input_task_button
is a button that can be used in conjuction with
shiny::bindEvent()
(or the older shiny::eventReactive()
and
shiny::observeEvent()
functions) to trigger actions or recomputation.
It is similar to shiny::actionButton()
, except it prevents the user from
clicking when its operation is already in progress.
Upon click, it automatically displays a customizable progress message and disables itself; and after the server has dealt with whatever reactivity is triggered from the click, the button automatically reverts to its original appearance and re-enables itself.
Usage
input_task_button(
id,
label,
...,
icon = NULL,
label_busy = "Processing...",
icon_busy = rlang::missing_arg(),
type = "primary",
auto_reset = TRUE
)
update_task_button(id, ..., state = NULL, session = get_current_session())
Arguments
- id
The
input
slot that will be used to access the value.- label
The label of the button while it is in ready (clickable) state; usually a string.
- ...
In
input_task_button()
, named arguments become attributes to include on the<button>
element, e.g.class
or data attributes. Unnamed arguments can provide additional states for the button, see the "Custom states" section.In
update_task_button()
,...
are ignored and must be empty. The task button only supports changing between pre-defined states.- icon
An optional icon to display next to the label while the button is in ready state. See
fontawesome::fa_i()
.- label_busy
The label of the button while it is busy.
- icon_busy
The icon to display while the button is busy. By default,
fontawesome::fa_i("refresh", class = "fa-spin", "aria-hidden" = "true")
is used, which displays a spinning "chasing arrows" icon. You can create spinning icons out of other Font Awesome icons by using the same expression, but replacing"refresh"
with a different icon name. Seefontawesome::fa_i()
.- type
One of the Bootstrap theme colors (
"primary"
,"default"
,"secondary"
,"success"
,"danger"
,"warning"
,"info"
,"light"
,"dark"
), orNULL
to leave off the Bootstrap-specific button CSS classes altogether.- auto_reset
If
TRUE
(the default), automatically put the button back in "ready" state after its click is handled by the server.- state
If
"busy"
, put the button into busy/disabled state. If"ready"
, put the button into ready/enabled state.- session
The
session
object; using the default is recommended.
Manual button reset
In some advanced use cases, it may be necessary to keep a task button in its
busy state even after the normal reactive processing has completed. Calling
update_task_button(id, state = "busy")
from the server will opt out of any
currently pending reset for a specific task button. After doing so, the
button can be re-enabled by calling update_task_button(id, state = "ready")
after each click's work is complete.
You can also pass an explicit auto_reset = FALSE
to input_task_button()
,
which means that button will never be automatically re-enabled and will
require update_task_button(id, state = "ready")
to be called each time.
Note that, as a general rule, Shiny's update
family of functions do not
take effect at the instant that they are called, but are held until the end
of the current reactive cycle. So if you have many different reactive
calculations and outputs, you don't have to be too careful about when you
call update_task_button(id, state = "ready")
, as the button on the client
will not actually re-enable until the same moment that all of the updated
outputs simultaneously sent to the client.
Custom states
The task button is designed to automatically switch between two states: the
"ready" state, where the button is clickable and displays the label
and
icon
; and the "busy" state, where the button is disabled and displays
label_busy
and icon_busy
.
In advanced use cases, you can include additional states by adding an
htmltools::div()
with a slot
attribute naming the state and the icon and
label as the first and second children, respectively.
input_task_button(
label = "Ring home",
icon = fontawesome::fa_i("phone"),
div(slot = "ringing", fontawesome::fa_i("bell"), "Ringing..."),
div(
slot = "voice-mail",
fontawesome::fa_i("voicemail"),
"Leaving a message..."
)
)
You can move between these states by calling update_task_button()
and
passing the slot name to the state
argument, e.g. state="ringing"
. See
the section above on manual button resetting, which you will likely need to
use in conjunction with custom states.
Server value
An integer of class "shinyActionButtonValue"
. This class differs from
ordinary integers in that a value of 0 is considered "falsy". This implies
two things:
Event handlers (e.g.,
shiny::observeEvent()
,shiny::eventReactive()
) won't execute on initial load.Input validation (e.g.,
shiny::req()
,shiny::need()
) will fail on initial load.
Examples
if (FALSE) { # interactive()
library(shiny)
library(bslib)
ui <- page_sidebar(
sidebar = sidebar(
open = "always",
input_task_button("resample", "Resample"),
),
verbatimTextOutput("summary")
)
server <- function(input, output, session) {
sample <- eventReactive(input$resample, ignoreNULL=FALSE, {
Sys.sleep(2) # Make this artificially slow
rnorm(100)
})
output$summary <- renderPrint({
summary(sample())
})
}
shinyApp(ui, server)
}