These functions are for registering callbacks on Shiny session events. They should be called within an application's server function.
onBookmark registers a function that will be called just
before Shiny bookmarks state.
onBookmarked registers a function that will be called just
after Shiny bookmarks state.
onRestore registers a function that will be called when a
session is restored, after the server function executes, but before all
other reactives, observers and render functions are run.
onRestored registers a function that will be called after a
session is restored. This is similar to onRestore, but it will be
called after all reactives, observers, and render functions run, and
after results are sent to the client browser. onRestored
callbacks can be useful for sending update messages to the client
browser.
onBookmark(fun, session = getDefaultReactiveDomain())
onBookmarked(fun, session = getDefaultReactiveDomain())
onRestore(fun, session = getDefaultReactiveDomain())
onRestored(fun, session = getDefaultReactiveDomain())All of these functions return a function which can be called with no arguments to cancel the registration.
The callback function that is passed to these functions should take one
argument, typically named "state" (for onBookmark, onRestore,
and onRestored) or "url" (for onBookmarked).
For onBookmark, the state object has three relevant fields. The
values field is an environment which can be used to save arbitrary
values (see examples). If the state is being saved to disk (as opposed to
being encoded in a URL), the dir field contains the name of a
directory which can be used to store extra files. Finally, the state object
has an input field, which is simply the application's input
object. It can be read, but not modified.
For onRestore and onRestored, the state object is a list. This
list contains input, which is a named list of input values to restore,
values, which is an environment containing arbitrary values that were
saved in onBookmark, and dir, the name of the directory that
the state is being restored from, and which could have been used to save
extra files.
For onBookmarked, the callback function receives a string with the
bookmark URL. This callback function should be used to display UI in the
client browser with the bookmark URL. If no callback function is registered,
then Shiny will by default display a modal dialog with the bookmark URL.
These callbacks may also be used in Shiny modules. When used this way, the inputs and values will automatically be namespaced for the module, and the callback functions registered for the module will only be able to see the module's inputs and values.
enableBookmarking for general information on bookmarking.
## Only run these examples in interactive sessions
if (interactive()) {
# Basic use of onBookmark and onRestore: This app saves the time in its
# arbitrary values, and restores that time when the app is restored.
ui <- function(req) {
fluidPage(
textInput("txt", "Input text"),
bookmarkButton()
)
}
server <- function(input, output) {
onBookmark(function(state) {
savedTime <- as.character(Sys.time())
cat("Last saved at", savedTime, "\n")
# state is a mutable reference object, and we can add arbitrary values to
# it.
state$values$time <- savedTime
})
onRestore(function(state) {
cat("Restoring from state bookmarked at", state$values$time, "\n")
})
}
enableBookmarking("url")
shinyApp(ui, server)
ui <- function(req) {
fluidPage(
textInput("txt", "Input text"),
bookmarkButton()
)
}
server <- function(input, output, session) {
lastUpdateTime <- NULL
observeEvent(input$txt, {
updateTextInput(session, "txt",
label = paste0("Input text (Changed ", as.character(Sys.time()), ")")
)
})
onBookmark(function(state) {
# Save content to a file
messageFile <- file.path(state$dir, "message.txt")
cat(as.character(Sys.time()), file = messageFile)
})
onRestored(function(state) {
# Read the file
messageFile <- file.path(state$dir, "message.txt")
timeText <- readChar(messageFile, 1000)
# updateTextInput must be called in onRestored, as opposed to onRestore,
# because onRestored happens after the client browser is ready.
updateTextInput(session, "txt",
label = paste0("Input text (Changed ", timeText, ")")
)
})
}
# "server" bookmarking is needed for writing to disk.
enableBookmarking("server")
shinyApp(ui, server)
# This app has a module, and both the module and the main app code have
# onBookmark and onRestore functions which write and read state$values$hash. The
# module's version of state$values$hash does not conflict with the app's version
# of state$values$hash.
#
# A basic module that captializes text.
capitalizerUI <- function(id) {
ns <- NS(id)
wellPanel(
h4("Text captializer module"),
textInput(ns("text"), "Enter text:"),
verbatimTextOutput(ns("out"))
)
}
capitalizerServer <- function(input, output, session) {
output$out <- renderText({
toupper(input$text)
})
onBookmark(function(state) {
state$values$hash <- rlang::hash(input$text)
})
onRestore(function(state) {
if (identical(rlang::hash(input$text), state$values$hash)) {
message("Module's input text matches hash ", state$values$hash)
} else {
message("Module's input text does not match hash ", state$values$hash)
}
})
}
# Main app code
ui <- function(request) {
fluidPage(
sidebarLayout(
sidebarPanel(
capitalizerUI("tc"),
textInput("text", "Enter text (not in module):"),
bookmarkButton()
),
mainPanel()
)
)
}
server <- function(input, output, session) {
callModule(capitalizerServer, "tc")
onBookmark(function(state) {
state$values$hash <- rlang::hash(input$text)
})
onRestore(function(state) {
if (identical(rlang::hash(input$text), state$values$hash)) {
message("App's input text matches hash ", state$values$hash)
} else {
message("App's input text does not match hash ", state$values$hash)
}
})
}
enableBookmarking(store = "url")
shinyApp(ui, server)
}