Update URL in browser's location bar — updateQueryString

v1.9.0|Source: R/bookmark-state.R

Description

This function updates the client browser's query string in the location bar. It typically is called from an observer. Note that this will not work in Internet Explorer 9 and below.

updateQueryString(
  queryString,
  mode = c("replace", "push"),
  session = getDefaultReactiveDomain()
)

Arguments

queryString

The new query string to show in the location bar.

mode

When the query string is updated, should the current history entry be replaced (default), or should a new history entry be pushed onto the history stack? The former should only be used in a live bookmarking context. The latter is useful if you want to navigate between states using the browser's back and forward buttons. See Examples.

session

A Shiny session object.

Details

For mode = "push", only three updates are currently allowed:

1. the query string (format: ?param1=val1&param2=val2)

2. the hash (format: #hash)

3. both the query string and the hash (format: ?param1=val1&param2=val2#hash)

In other words, if mode = "push", the queryString must start with either ? or with #.

A technical curiosity: under the hood, this function is calling the HTML5 history API (which is where the names for the mode argument come from). When mode = "replace", the function called is window.history.replaceState(null, null, queryString). When mode = "push", the function called is window.history.pushState(null, null, queryString).

See also

enableBookmarking(), getQueryString()

Examples

## Only run these examples in interactive sessions
if (interactive()) {

  ## App 1: Doing "live" bookmarking
  ## Update the browser's location bar every time an input changes.
  ## This should not be used with enableBookmarking("server"),
  ## because that would create a new saved state on disk every time
  ## the user changes an input.
  enableBookmarking("url")
  shinyApp(
    ui = function(req) {
      fluidPage(
        textInput("txt", "Text"),
        checkboxInput("chk", "Checkbox")
      )
    },
    server = function(input, output, session) {
      observe({
        # Trigger this observer every time an input changes
        reactiveValuesToList(input)
        session$doBookmark()
      })
      onBookmarked(function(url) {
        updateQueryString(url)
      })
    }
  )

  ## App 2: Printing the value of the query string
  ## (Use the back and forward buttons to see how the browser
  ## keeps a record of each state)
  shinyApp(
    ui = fluidPage(
      textInput("txt", "Enter new query string"),
      helpText("Format: ?param1=val1&param2=val2"),
      actionButton("go", "Update"),
      hr(),
      verbatimTextOutput("query")
    ),
    server = function(input, output, session) {
      observeEvent(input$go, {
        updateQueryString(input$txt, mode = "push")
      })
      output$query <- renderText({
        query <- getQueryString()
        queryText <- paste(names(query), query,
                       sep = "=", collapse=", ")
        paste("Your query string is:\n", queryText)
      })
    }
  )
}