spsComps (version 0.3.3.0)

addLoader: Add CSS loaders from server

Description

Add/remove CSS loaders from server to any Shiny/HTML component. It is useful to indicate busy status when some code is running in the server and when it finishes, remove the loader to indicate clear status.

Value

CSS load in R6 class

Methods

Public methods

• addLoader$new()

• addLoader$show()

• addLoader$hide()

• addLoader$destroy()

• addLoader$recreate()

• addLoader$clone()

---

Method new()

create a loader object

Usage

addLoader$new(
  target_selector = "",
  isID = TRUE,
  type = "default",
  src = "",
  id = "",
  height = NULL,
  width = height,
  color = "#337ab7",
  opacity = 1,
  method = "replace",
  block = TRUE,
  center = TRUE,
  bg_color = "#eee",
  footer = NULL,
  z_index = 2000,
  alert = FALSE,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

target_selector

string, which Shiny component you want to add the loader to? a shiny component ID or a valid CSS selector if isID = FLASE. for example, you have a button and want to add animation to it:

actionButton(inputId = "btn")

This function is used in server only, so if you are in shiny module, use ns() for ID on UI but DO NOT add the ns() wrapper on server.

UI

actionButton(inputId = ns("btn"))

server

addLoader$new(target_selector = "btn", ...)

isID

bool, is your selector an ID?

type

string, one of "circle", "dual-ring", "facebook", "heart", "ring", "roller", "default", "ellipsis", "grid", "hourglass", "ripple", "spinner", "gif", default is "default".

src

string, online URL or local path of the gif animation file if you would like to upload your own loader.

id

string, the unqiue ID for the loader, if not provided, a random ID will be given. If you are using shiny modules, DO NOT use session$ns('YOUR_ID') to wrap it. Loaders live on the top level of the document.

height

string, (r)em, "1.5rem", "1.5em", or pixel, like "10px". Default is NULL, will be automatically calculated based on the target component. It is recommend to use NULL for "replace" and "inline" method to let it automatically be calculated, but required for "full_screen" method.

width

string, default is the same as height to make it square.

color

string, any valid CSS color name, or hex color code

opacity

number, between 0-1

method

one of "replace", "inline", "full_screen", see details

block

bool, for some input components, once the loader starts, it can also block user interaction with the component, very useful for "inline" method, eg. prevent users from clicking the button while some process is still running.

center

bool, try to place the load to the center of the target for "inline" and "replace" and center of the screen for "full_screen".

bg_color

string, any valid CSS color name, or hex color code. Only works for "full_screen" method.

footer

Additional Shiny/HTML component to add below the loader, like a title h1("load title"). inline method does not have a footer.

z_index

number, only works for "full_screen" method, what CSS layer should the overlay be places. In HTML, all elements have the default of 0.

alert

bool, should alert if target cannot be found or other javascript errors? mainly for debugging

session

shiny session

Details

Methods

• replace: use a HTML div with the same CSS styles to replace the original target, but add the loader inside and remove original content inside. When the loader is hide, show the original div and hide this loader div. Height and width is the original div's height unless specially specified. Good example of this will be some plot outputs.

• inline: append the loader as the first child of target HTML container. loader's height and width is the original div's height unless specially specified. In addition, this methods will disable all inputs and buttons inside the target container, so this method can be useful on some buttons.

• full_screen: Do not change anything of the target HTML container, add an overlay to cover the whole page when show and hide the overlay when hide. This method requires the height to be specified manually. Under this method, bg_color and z_index can also be changed.

New container

addLoader$new() method only stores the loader information, the loader is add to your docuement upon the first time addLoader$show() is called.

Required javascript and css files

Since spsComps 0.3.1 all dependencies will be added automatically. If you don't see them working, try to manually add spsDepend('addLoader') or spsDepend('css-loader') (old name) somewhere in your UI to add the dependency.

Returns

A R6 loader object

---

Method show()

show the loader

Usage

addLoader$show(alert = FALSE)

Arguments

alert

bool, if the target selector or loader is not found, alert on UI? For debugging purposes.

Details

Make sure your target element is visible when the time you call this show method, otherwise, you will not get it if height and width is rely on auto-calculation for "replace" and "inline" method. "full_screen" method is not affected.

---

Method hide()

hide the loader

Usage

addLoader$hide(alert = FALSE)

Arguments

alert

bool, if the target selector or loader is not found, alert on UI? For debugging purposes.

---

Method destroy()

Destroy current loader

Usage

addLoader$destroy(alert = FALSE)

Arguments

alert

bool, if the target selector or loader is not found, alert on UI? For debugging purposes.

Details

hide and remove current loader from the current document

---

Method recreate()

recreate the loader

Usage

addLoader$recreate(
  type = "default",
  src = NULL,
  id = "",
  height = NULL,
  width = height,
  color = "#337ab7",
  opacity = 1,
  method = "replace",
  block = TRUE,
  center = TRUE,
  bg_color = "#eee",
  footer = NULL,
  z_index = 2000,
  alert = FALSE
)

Arguments

type

string, one of "circle", "dual-ring", "facebook", "heart", "ring", "roller", "default", "ellipsis", "grid", "hourglass", "ripple", "spinner", "gif", default is "default".

src

string, online URL or local path of the gif animation file if you would like to upload your own loader.

id

string, the unqiue ID for the loader, if not provided, a random ID will be given. If you are using shiny modules, DO NOT use session$ns('YOUR_ID') to wrap it. Loaders live on the top level of the document.

height

string, (r)em, "1.5rem", "1.5em", or pixel, like "10px". Default is NULL, will be automatically calculated based on the target component. It is recommend to use NULL for "replace" and "inline" method to let it automatically be calculated, but required for "full_screen" method.

width

string, default is the same as height to make it square.

color

string, any valid CSS color name, or hex color code

opacity

number, between 0-1

method

one of "replace", "inline", "full_screen", see details

block

bool, for some input components, once the loader starts, it can also block user interaction with the component, very useful for "inline" method, eg. prevent users from clicking the button while some process is still running.

center

bool, try to place the load to the center of the target for "inline" and "replace" and center of the screen for "full_screen".

bg_color

string, any valid CSS color name, or hex color code. Only works for "full_screen" method.

footer

Additional Shiny/HTML component to add below the loader, like a title h1("load title"). inline method does not have a footer.

z_index

number, only works for "full_screen" method, what CSS layer should the overlay be places. In HTML, all elements have the default of 0.

alert

bool, should alert if target cannot be found or other javascript errors? mainly for debugging

Details

This method will first disable then destroy (remove) current loader, and finally store new information of the new loader.

Note:: this method only refresh loader object on the server, the loader is not recreated until the next time show method is called.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

addLoader$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

if (interactive()){
  ui <- fluidPage(
    h4("Use buttons to show and hide loaders with different methods"),
    spsDepend("addLoader"), # optional
    tags$b("Replace"), br(),
    actionButton("b_re_start", "Replace"),
    actionButton("b_re_stop", "stop replace"),
    br(), tags$b("Inline"), br(),
    actionButton("b_in_start", "Inline"),
    actionButton("b_in_stop", "stop inline"),
    br(), tags$b("Full screen"), br(),
    actionButton("b_fs_start", "Full screen 2s"), br(),
    h4("Add loaders to a big HTML chunk"),
    actionButton("chunk_start", "Chunk loader"),
    actionButton("chunk_stop", "Stop"), br(),
    column(6,
           id = "chunk",
           style = "background-color: #eee",
           h5("Here is some text 12345"),
           tags$hr(),
           icon("house"),
           p("blablablablablablablablablablablablablablablablablablablabla"),
           p("blablablablablablablablablablablablablablablablablablablabla"),
           p("blablablablablablablablablablablablablablablablablablablabla"),
           p("blablablablablablablablablablablablablablablablablablablabla")
    )
  )

  server <- function(input, output, session) {
    # Init loaders
    loader_replace <- addLoader$new("b_re_start", type = "facebook")
    loader_inline <- addLoader$new("b_in_start", color = "green", method = "inline")
    loader_fs <- addLoader$new(
      "b_fs_start", color = "pink", method = "full_screen",
      bg_color = "#eee", height = "30rem", type = "heart"
    )
    loader_chunk <- addLoader$new(
      "chunk", type = "spinner", color = "orange",
      footer = h5("chunk loader")
    )

    # toggle loaders
    ## replace
    observeEvent(input$b_re_start, {
      loader_replace$show()
    })
    observeEvent(input$b_re_stop, {
      loader_replace$hide()
    })
    ## inline
    observeEvent(input$b_in_start, {
      loader_inline$show()
    })
    observeEvent(input$b_in_stop, {
      loader_inline$hide()
    })
    ## full screen
    observeEvent(input$b_fs_start, {
      loader_fs$show()
      Sys.sleep(2)
      loader_fs$hide()
    })
    ## chunk
    observeEvent(input$chunk_start, {
      loader_chunk$show()
    })
    observeEvent(input$chunk_stop, {
      loader_chunk$hide()
    })

  }

  shinyApp(ui, server)
}

if (interactive()){
  ui <- bootstrapPage(
    spsDepend("addLoader"), # optional
    h4("Add loaders to Shiny `render` events"),
    tags$b("Replace"), br(),
    selectizeInput(inputId = "n_re",
                   label = "Change this to render the following plot",
                   choices = c(10, 20, 35, 50)),
    plotOutput(outputId = "p_re"),
    br(), tags$b("Full screen"), br(),
    selectInput(inputId = "n_fs",
                label = "Change this to render the following plot",
                choices = c(10, 20, 35, 50)),
    plotOutput(outputId = "p_fs")
  )

  server <- function(input, output, session) {
    # create loaders
    l_re <- addLoader$new("p_re")
    l_fs <- addLoader$new(
      "p_fs", color = "pink", method = "full_screen",
      bg_color = "#eee", height = "30rem", type = "grid",
      footer = h4("Replotting...")
    )
    # use loaders in rednering
    output$p_re <- renderPlot({
      on.exit(l_re$hide())
      # to make it responsive
      # (always create a new one by calculating the new height and width)
      l_re$recreate()$show()
      Sys.sleep(1)
      hist(faithful$eruptions,
           probability = TRUE,
           breaks = as.numeric(input$n_re),
           xlab = "Duration (minutes)",
           main = "Geyser eruption duration")
    })
    output$p_fs <- renderPlot({
      on.exit(l_fs$hide())
      l_fs$show()

      Sys.sleep(1)
      hist(faithful$eruptions,
           probability = TRUE,
           breaks = as.numeric(input$n_fs),
           xlab = "Duration (minutes)",
           main = "Geyser eruption duration")
    })
  }
  shinyApp(ui, server)
}