Export JSEvals (#381)

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

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)

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

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
 -------------------------------------------------------