Add documentation for the new parameter onChange (rte-antares-rpackag…

…e#16)

R/add_minicharts.R

@@ -58,9 +58,54 @@
 #' @param initialTime This argument can be used to set the initial time step
 #'   shown when the map is created. It is used only when argument \code{time} is
 #'   set.
-#' @param onChange (Advanced usage) Javascript function that is called each time
-#'   a minichart is modified. This function can take as parameter an object
-#'   containing all options that are modified.
+#' @param onChange (For power users who know javascript) A character string
+#'   containing javascript code that is exexuted each time a chart is updated.
+#'   See the details section to understand why and how to use this parameter.
+#'
+#' @details
+#' Since version 0.5, the parameter \code{onChange} can be used to execute
+#' some arbitrary javascript code each time a chart is updated (with
+#' \code{updateMinicharts()} or when time step changes). A typical use case
+#' would be to change the color of a polygon added with
+#' \code{\link[leaflet]{addPolygons}} based on the data of the chart. It is even
+#' possible to create an invisible chart and use it to manage the color and the
+#' popup of a polygon. Here is a sample code that do that:
+#'
+#' \preformatted{
+#'   leaflet() \%>\% addTiles() \%>\%
+#'     addPolygons(data = myPolygons, layerId = myPolygons$myIds) \%>\%
+#'     addMinicharts(
+#'       mydata$lon, mydata$lat,
+#'       time = mydata^time
+#'       fillColor = mydata$color,
+#'       layerId = mydata$myIds,
+#'       width = 0, height = 0,
+#'       onChange = "
+#'         var s = this._map.layerManager.getLayer("shape", this.layerId);
+#'         s.bindPopup(popup);
+#'         if (opts.fillColor) {
+#'           d3.select(s._path)
+#'           .transition()
+#'           .duration(750)
+#'           .attr("fill", opts.fillColor);
+#'         }"
+#'     )
+#'
+#' }
+#'
+#' The following objects are available when executing the javascript code:
+#' \describe{
+#'   \item{this}{The current minichart object. See
+#'   \url{https://rte-antares-rpackage.github.io/leaflet.minichart/-_L.Minichart_.html}
+#'   for more information.
+#'   }
+#'   \item{opts}{The current options passed to the current minichart object.}
+#'   \item{popup}{Popup html.}
+#'   \item{d3}{The D3 module.}
+#' }
+#'
+#' Here is a toy example
+#'
 #'
 #' @return
 #' The modified leaflet map object. \code{addMinicharts} add new minicharts to
@@ -110,7 +155,7 @@ addMinicharts <- function(map, lng, lat, chartdata = 1, time = NULL, maxValues =
                     transitionTime = transitionTime, fillColor = fillColor)
   )
 
-  args <- .prepareArgs(options, chartdata, popup)
+  args <- .prepareArgs(options, chartdata, popup, onChange)
 
   if (is.null(maxValues)) maxValues <- args$maxValues
 
@@ -126,7 +171,7 @@ addMinicharts <- function(map, lng, lat, chartdata = 1, time = NULL, maxValues =
 
   map <- invokeMethod(map, data = leaflet::getMapData(map), "addMinicharts",
                       args$options, args$chartdata, maxValues, colorPalette,
-                      I(timeLabels), initialTime, args$popupArgs, JS(onChange))
+                      I(timeLabels), initialTime, args$popupArgs, args$onChange)
 
   if (legend && length(args$legendLab) > 0 && args$ncol > 1) {
     legendCol <- colorPalette[(seq_len(args$ncols)-1) %% args$ncols + 1]
@@ -173,7 +218,7 @@ updateMinicharts <- function(map, layerId, chartdata = NULL, time = NULL, maxVal
                     fillColor = fillColor)
   )
 
-  args <- .prepareArgs(options, chartdata, popup)
+  args <- .prepareArgs(options, chartdata, popup, onChange)
 
   # Update legend if required
   if (!is.null(args$chartdata)) {
@@ -200,7 +245,7 @@ updateMinicharts <- function(map, layerId, chartdata = NULL, time = NULL, maxVal
   map %>%
     invokeMethod(leaflet::getMapData(map), "updateMinicharts",
                  args$options, args$chartdata, unname(maxValues), colorPalette,
-                 I(timeLabels), initialTime, args$popupArgs, args$legendLab, JS(onChange))
+                 I(timeLabels), initialTime, args$popupArgs, args$legendLab, args$onChange)
 }
 
 #' @rdname addMinicharts

R/prepare_args.R

@@ -1,4 +1,4 @@
-.prepareArgs <- function(options, chartdata, popupArgs,
+.prepareArgs <- function(options, chartdata, popupArgs, onChange = NULL,
                          static = c("layerId", "lat", "lat0", "lat1", "lng", "lng0", "lng1")) {
 
   staticOptions <- options$staticOptions
@@ -104,12 +104,19 @@
     popupArgs$supLabels <- I(popupArgs$supLabels)
   }
 
+  # Prepare onChange argument
+  if (!is.null(onChange)) {
+    onChange <- sprintf("(function(opts, popup, d3){%s})", onChange)
+    onChange <- JS(onChange)
+  }
+
   list(
     options = options,
     chartdata = chartdata,
     maxValues = maxValues,
     ncols = ncols,
     popupArgs = popupArgs,
-    legendLab = I(legendLab)
+    legendLab = I(legendLab),
+    onChange = onChange
   )
 }