From 52bf8751d9efe974d4e4a4be193a32a3493c0ce0 Mon Sep 17 00:00:00 2001 From: Joe Cheng Date: Tue, 25 Aug 2020 14:08:47 -0700 Subject: [PATCH] Export JSEvals (#381) --- DESCRIPTION | 2 +- NAMESPACE | 1 + R/utils.R | 36 +++++++++++++++++++++++------------- inst/NEWS | 2 ++ man/JSEvals.Rd | 34 ++++++++++++++++++++++++++++++++++ man/htmlwidgets-shiny.Rd | 7 +++++-- 6 files changed, 66 insertions(+), 16 deletions(-) create mode 100644 man/JSEvals.Rd diff --git a/DESCRIPTION b/DESCRIPTION index b3d61d67..73857fd9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -25,4 +25,4 @@ Suggests: Enhances: shiny (>= 1.1) URL: https://github.com/ramnathv/htmlwidgets BugReports: https://github.com/ramnathv/htmlwidgets/issues -RoxygenNote: 7.0.2 +RoxygenNote: 7.1.1 diff --git a/NAMESPACE b/NAMESPACE index c37ce80f..160e645b 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -4,6 +4,7 @@ S3method(as.tags,htmlwidget) S3method(print,htmlwidget) S3method(print,suppress_viewer) export(JS) +export(JSEvals) export(appendContent) export(createWidget) export(getDependency) diff --git a/R/utils.R b/R/utils.R index 3a7de263..6d5a107c 100644 --- a/R/utils.R +++ b/R/utils.R @@ -128,19 +128,29 @@ JS <- function(...) { structure(x, class = unique(c("JS_EVAL", oldClass(x)))) } -# Creates a list of keys whose values need to be evaluated on the client-side. -# -# It works by transforming \code{list(foo = list(1, list(bar = -# I('function(){}')), 2))} to \code{list("foo.2.bar")}. Later on the JS side, we -# will split foo.2.bar to ['foo', '2', 'bar'] and evaluate the JSON object -# member. Note '2' (character) should have been 2 (integer) but it does not seem -# to matter in JS: x[2] is the same as x['2'] when all child members of x are -# unnamed, and ('2' in x) will be true even if x is an array without names. This -# is a little hackish. -# -# @param list a list in which the elements that should be evaluated as -# JavaScript are to be identified -# @author Yihui Xie +#' Creates a list of keys whose values need to be evaluated on the client-side +#' +#' It works by transforming \code{list(foo = list(1, list(bar = +#' I('function(){}')), 2))} to \code{list("foo.2.bar")}. Later on the JS side, +#' the \code{window.HTMLWidgets.evaluateStringMember} function is called with +#' the JSON object and the "foo.2.bar" string, which is split to \code{['foo', +#' '2', 'bar']}, and the string at that location is replaced \emph{in-situ} with +#' the results of evaluating it. Note '2' (character) should have been 2 +#' (integer) but it does not seem to matter in JS: x[2] is the same as x['2'] +#' when all child members of x are unnamed, and ('2' in x) will be true even if +#' x is an array without names. This is a little hackish. +#' +#' This function is intended mostly for internal use. There's generally no need +#' for widget authors or users to call it, as it's called automatically on the +#' widget instance data during rendering. It's exported in case other packages +#' want to add support for \code{\link{JS}} in contexts outside of widget +#' payloads. +#' +#' @param list a list in which the elements that should be evaluated as +#' JavaScript are to be identified +#' @author Yihui Xie +#' @keywords internal +#' @export JSEvals <- function(list) { # the `%||% list()` part is necessary as of R 3.4.0 (April 2017) -- if `evals` # is NULL then `I(evals)` results in a warning in R 3.4.0. This is circumvented diff --git a/inst/NEWS b/inst/NEWS index c2164906..8c90f28d 100644 --- a/inst/NEWS +++ b/inst/NEWS @@ -5,6 +5,8 @@ htmlwidgets 1.5.1.9000 * Added a `reportTheme` argument to `shinyWidgetOutput()`. If `TRUE`, CSS styles of the widget's output container are made available to `shiny::getCurrentOutputInfo()`, making it possible to provide 'smart' styling defaults in a `renderWidget()` context. (#361) +* Export the `JSEvals` function, allowing other packages to support `JS()` in non-widget contexts. + htmlwidgets 1.5.1 ------------------------------------------------------- diff --git a/man/JSEvals.Rd b/man/JSEvals.Rd new file mode 100644 index 00000000..210d76e7 --- /dev/null +++ b/man/JSEvals.Rd @@ -0,0 +1,34 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{JSEvals} +\alias{JSEvals} +\title{Creates a list of keys whose values need to be evaluated on the client-side} +\usage{ +JSEvals(list) +} +\arguments{ +\item{list}{a list in which the elements that should be evaluated as +JavaScript are to be identified} +} +\description{ +It works by transforming \code{list(foo = list(1, list(bar = +I('function(){}')), 2))} to \code{list("foo.2.bar")}. Later on the JS side, +the \code{window.HTMLWidgets.evaluateStringMember} function is called with +the JSON object and the "foo.2.bar" string, which is split to \code{['foo', +'2', 'bar']}, and the string at that location is replaced \emph{in-situ} with +the results of evaluating it. Note '2' (character) should have been 2 +(integer) but it does not seem to matter in JS: x[2] is the same as x['2'] +when all child members of x are unnamed, and ('2' in x) will be true even if +x is an array without names. This is a little hackish. +} +\details{ +This function is intended mostly for internal use. There's generally no need +for widget authors or users to call it, as it's called automatically on the +widget instance data during rendering. It's exported in case other packages +want to add support for \code{\link{JS}} in contexts outside of widget +payloads. +} +\author{ +Yihui Xie +} +\keyword{internal} diff --git a/man/htmlwidgets-shiny.Rd b/man/htmlwidgets-shiny.Rd index 659678bf..e641cfb3 100644 --- a/man/htmlwidgets-shiny.Rd +++ b/man/htmlwidgets-shiny.Rd @@ -33,8 +33,11 @@ string and have \code{"px"} appended.} \item{inline}{use an inline (\code{span()}) or block container (\code{div()}) for the output} -\item{reportSize}{Should the widget's container styles (e.g., background -/foreground color) be reported in the shiny session's client data?} +\item{reportSize}{Should the widget's container size be reported in the +shiny session's client data?} + +\item{reportTheme}{Should the widget's container styles (e.g., colors and fonts) +be reported in the shiny session's client data?} \item{expr}{An expression that generates an HTML widget (or a \href{https://rstudio.github.io/promises/}{promise} of an HTML widget).}