From 8d3e5fc160c2be89dd51129b835bd9435e7c1c46 Mon Sep 17 00:00:00 2001 From: Winston Chang Date: Fri, 10 Jun 2016 10:11:55 -0500 Subject: [PATCH] Refinements --- NAMESPACE | 1 - R/save-state.R | 50 +++++++++++++++++++++++++++++-------- man/configureBookmarking.Rd | 6 +++++ man/restoreInput.Rd | 17 +++++++++++++ man/saveStateQueryString.Rd | 3 +++ man/updateQueryString.Rd | 17 +++++++++++++ man/urlModal.Rd | 22 ++++++++++++++++ 7 files changed, 105 insertions(+), 11 deletions(-) create mode 100644 man/restoreInput.Rd create mode 100644 man/updateQueryString.Rd create mode 100644 man/urlModal.Rd diff --git a/NAMESPACE b/NAMESPACE index c4cf94cfe..34ade3bcd 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -61,7 +61,6 @@ export(dataTableOutput) export(dateInput) export(dateRangeInput) export(dblclickOpts) -export(decodeStateQueryString) export(dialogViewer) export(div) export(downloadButton) diff --git a/R/save-state.R b/R/save-state.R index 6ac9ef381..3d578c8e8 100644 --- a/R/save-state.R +++ b/R/save-state.R @@ -8,8 +8,14 @@ #' @param input The session's input object. #' @param exclude A character vector of input names that should not be #' bookmarked. +#' @param values Any additional values that should be saved or encoded. This +#' must be either NULL or a list. #' @export saveStateQueryString <- function(input, exclude = NULL, values = NULL) { + if (!is.null(values) && !is.list(values)) { + stop("'values' must be either NULL or a list.") + } + id <- createUniqueId(8) saveInterface <- getShinyOption("save.interface", default = saveInterfaceLocal) @@ -29,7 +35,7 @@ saveStateQueryString <- function(input, exclude = NULL, values = NULL) { paste0("_state_id=", encodeURIComponent(id)) } - +# Counterpart to saveStateQueryString loadStateQueryString <- function(queryString) { values <- parseQueryString(queryString, nested = TRUE) id <- values[["_state_id"]] @@ -55,11 +61,12 @@ loadStateQueryString <- function(queryString) { res } + #' @rdname saveStateQueryString #' @export encodeStateQueryString <- function(input, exclude = NULL, values = NULL) { - if (!is.list(values)) { - stop("'values' must be a list.") + if (!is.null(values) && !is.list(values)) { + stop("'values' must be either NULL or a list.") } inputVals <- serializeReactiveValues(input, exclude, stateDir = NULL) @@ -98,8 +105,7 @@ encodeStateQueryString <- function(input, exclude = NULL, values = NULL) { res } - -#' @export +# Counterpart to encodeStateQueryString decodeStateQueryString <- function(queryString) { if (grepl("_values_", queryString)) { splitStr <- strsplit(queryString, "_values_", fixed = TRUE)[[1]] @@ -273,6 +279,13 @@ getCurrentRestoreContext <- function() { ctx } +#' Restore an input value +#' +#' This restores an input value from the current restore context.. +#' +#' @param id Name of the input value to restore. +#' @param default A default value to use, if there's no value to restore. +#' #' @export restoreInput <- function(id, default) { if (!isTRUE(getShinyOption("restorable")) || !hasCurrentRestoreContext()) @@ -286,13 +299,26 @@ restoreInput <- function(id, default) { } } - +#' Update URL query string in browser's location bar +#' +#' @param queryString The new query string to show in the location bar. +#' @param session A Shiny session object. #' @export updateQueryString <- function(queryString, session = getDefaultReactiveDomain()) { session$updateQueryString(queryString) } +#' Generate a modal dialog that displays a URL +#' +#' The modal dialog generated by \code{urlModal} will display the URL in a +#' textarea input, and the URL text will be selected so that it can be easily +#' copied. The result from \code{urlModal} should be passed to the +#' \code{\link{showModal}} function to display it in the browser. +#' +#' @param url A URL to display in the dialog box. +#' @param title A title for the dialog box. +#' @param subtitle Text to display underneath URL. #' @export urlModal <- function(url, title = "Share link", subtitle = NULL) { @@ -346,13 +372,17 @@ urlModal <- function(url, title = "Share link", subtitle = NULL) { #' encodes all of the relevant values in a URL, or \code{"disable"}, which #' disables any previously-enabled bookmarking. #' @param exclude Input values to exclude from bookmarking. +#' @param onBookmark A function to call before saving state. This function should +#' return a list, which will be saved as \code{values}. +#' @param onRestore A function to call when a session is restored. It will be +#' passed one argument, a restoreContext object. #' @param onBookmarked A callback function to invoke after the bookmarking has #' been done. #' @param session A Shiny session object. #' @export configureBookmarking <- function(eventExpr, type = c("save", "encode", "disable"), exclude = NULL, - onSave = NULL, onRestore = NULL, onBookmarked = NULL, + onBookmark = NULL, onRestore = NULL, onBookmarked = NULL, session = getDefaultReactiveDomain()) { @@ -391,10 +421,10 @@ configureBookmarking <- function(eventExpr, event.quoted = TRUE, { values <- NULL - if (!is.null(onSave)) - values <- onSave() + if (!is.null(onBookmark)) + values <- onBookmark() if (!is.null(values) && !is.list(values)) - stop("The value returned by onSave() must be NULL or a list.") + stop("The value returned by onBookmark() must be NULL or a list.") if (type == "save") { url <- saveStateQueryString(session$input, exclude, values) diff --git a/man/configureBookmarking.Rd b/man/configureBookmarking.Rd index da4cc06b8..a2db1f587 100644 --- a/man/configureBookmarking.Rd +++ b/man/configureBookmarking.Rd @@ -18,6 +18,12 @@ disables any previously-enabled bookmarking.} \item{exclude}{Input values to exclude from bookmarking.} +\item{onSave}{A function to call before saving state. This function should +return a list, which will be saved as \code{values}.} + +\item{onRestore}{A function to call when a session is restored. It will be +passed one argument, a restoreContext object.} + \item{onBookmarked}{A callback function to invoke after the bookmarking has been done.} diff --git a/man/restoreInput.Rd b/man/restoreInput.Rd new file mode 100644 index 000000000..d9f5a21cd --- /dev/null +++ b/man/restoreInput.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/save-state.R +\name{restoreInput} +\alias{restoreInput} +\title{Restore an input value} +\usage{ +restoreInput(id, default) +} +\arguments{ +\item{id}{Name of the input value to restore.} + +\item{default}{A default value to use, if there's no value to restore.} +} +\description{ +This restores an input value from the current restore context.. +} + diff --git a/man/saveStateQueryString.Rd b/man/saveStateQueryString.Rd index 2bdefa1f9..b45d099d7 100644 --- a/man/saveStateQueryString.Rd +++ b/man/saveStateQueryString.Rd @@ -14,6 +14,9 @@ encodeStateQueryString(input, exclude = NULL, values = NULL) \item{exclude}{A character vector of input names that should not be bookmarked.} + +\item{values}{Any additional values that should be saved or encoded. This +must be either NULL or a list.} } \description{ Shiny applications can have their state \emph{encoded} in a URL or diff --git a/man/updateQueryString.Rd b/man/updateQueryString.Rd new file mode 100644 index 000000000..9c91d90a1 --- /dev/null +++ b/man/updateQueryString.Rd @@ -0,0 +1,17 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/save-state.R +\name{updateQueryString} +\alias{updateQueryString} +\title{Update URL query string in browser's location bar} +\usage{ +updateQueryString(queryString, session = getDefaultReactiveDomain()) +} +\arguments{ +\item{queryString}{The new query string to show in the location bar.} + +\item{session}{A Shiny session object.} +} +\description{ +Update URL query string in browser's location bar +} + diff --git a/man/urlModal.Rd b/man/urlModal.Rd new file mode 100644 index 000000000..3d4185144 --- /dev/null +++ b/man/urlModal.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/save-state.R +\name{urlModal} +\alias{urlModal} +\title{Generate a modal dialog that displays a URL} +\usage{ +urlModal(url, title = "Share link", subtitle = NULL) +} +\arguments{ +\item{url}{A URL to display in the dialog box.} + +\item{title}{A title for the dialog box.} + +\item{subtitle}{Text to display underneath URL.} +} +\description{ +The modal dialog generated by \code{urlModal} will display the URL in a +textarea input, and the URL text will be selected so that it can be easily +copied. The result from \code{urlModal} should be passed to the +\code{\link{showModal}} function to display it in the browser. +} +