Fix renderOptions and sorters params, fix documentation, add documentation, add examples

R/rpivotTable.R

@@ -4,19 +4,20 @@
 #' htmlwidget.
 #'
 #' @param data data.frame or data.table (R>=1.9.6 for safety) with data to use in the pivot table
-#' @param rows String name of the column in the data.frame to prepopulate
+#' @param rows String or Array of Strings name(s) of the column(s) in the data.frame to prepopulate
 #'              the \strong{rows} of the pivot table.
-#' @param cols String name of the column in the data.frame to prepopulate
+#' @param cols String or Array of Strings name(s) of the column(s) in the data.frame to prepopulate
 #'              the \strong{columns} of the pivot table.
 #' @param aggregatorName String name of the pivottable.js aggregator to prepopulate the pivot table.
-#' @param vals String name of the column in the data.frame to use with \code{aggregatorName}. Must be additive (i.e a number).
-#' @param rendererName List name of the renderer selected, e.g. Table, Heatmap, Treemap etc.
-#' @param sorter String name this allows to implement a javascript function to specify the ad hoc sorting of certain values. See vignette for an example.
+#' @param vals String or Array of Strings name(s) of the column(s) in the data.frame to use with \code{aggregatorName}. Must be additive (i.e., a number).
+#' @param rendererName String name of the renderer selected, e.g. Table, Heatmap, Treemap etc.
+#' @param rendererOptions List of \href{https://github.com/nicolaskruchten/pivottable/wiki/Renderers}{options} passed to the renderers.
+#' @param sorters String this allows to implement a javascript function to specify the ad hoc sorting of certain values. See vignette for an example.
 #'              It is especially useful with time divisions like days of the week or months of the year (where the alphabetical order does not work).
 #' @param inclusions List this optional parameter allows to filter the members of a particular dimension "by inclusion".
 #'              Using the 'Titanic' example, to display only the "Crew" member in the "Class" dimension, it is convenient to filter by inclusion using `inclusions=list(Class="Crew")`.
 #'              Please note that this only pre-selects the visible filter(s) on the pivot table: the other dimension members are still availabe for selection if needed.
-#' @param exclusions String this optional parameter allows to filter the members of a particular dimension "by exclusion".
+#' @param exclusions List this optional parameter allows to filter the members of a particular dimension "by exclusion".
 #'              Using the 'Titanic' example, to display only the "1st", "2nd" and "3rd" members in the "Class" dimension, it is convenient to filter by exclusion using `exclusions=list(Class="Crew")`.
 #'              Please note that this only pre-selects the visible filter(s) on the pivot table: the other dimension members are still availabe for selection if needed.
 #' @param locale \code{character} of locale to use.  Valid locale options are
@@ -40,7 +41,7 @@
 #' @param height height parameter
 #' @param elementId String valid CSS selector id for the rpivotTable container.
 #'
-#' @param ... list other \href{https://github.com/nicolaskruchten/pivottable/wiki/Parameters}{parameters} that
+#' @param ... List other \href{https://github.com/nicolaskruchten/pivottable/wiki/Parameters}{parameters} that
 #'            can be passed to \code{pivotUI}. See Nicolas's Wiki for more details.
 #'            A further example of parameter is onRefresh. This parameters (shiny-only) introduces a JS function that allows to get back server side the list of parameters selected by the user.
 #'            An example is: onRefresh=htmlwidgets::JS("function(config) { Shiny.onInputChange('myPivotData', config); }")
@@ -99,7 +100,8 @@ rpivotTable <- function(
     aggregatorName = NULL,
     vals = NULL,
     rendererName = NULL,
-    sorter = NULL,
+    rendererOptions = NULL,
+    sorters = NULL,
     exclusions = NULL,
     inclusions = NULL,
     locale = "en",
@@ -123,7 +125,7 @@ rpivotTable <- function(
       aggregatorName = aggregatorName,
       vals = vals,
       rendererName = rendererName,
-      sorter = sorter,
+      sorters = sorters,
       ...
     )
 
@@ -136,8 +138,9 @@ rpivotTable <- function(
       }
       , params
     )
-    # exlusions & inclusions need to be "excluded" from auto_boxing
+    # rendererOptions, exlusions & inclusions need to be "excluded" from auto_boxing
     par <- list(
+           rendererOptions = rendererOptions,
            exclusions = exclusions,
            inclusions = inclusions
          )

inst/examples/customizePlot.R

@@ -0,0 +1,17 @@
+library(rpivotTable)
+
+MyColors <- c(rgb(186,150,155, maxColorValue=255), rgb(238,221,130, maxColorValue=255),
+                      rgb(205,150,205, maxColorValue=255))
+
+c3RenderOptions <- list(size = list(height=525, width=900),# change the size of the barchart
+                  zoom = list(enabled=T), # add zooming
+                  # use a custom color scheme
+                  color = list(pattern=as.list(MyColors)))
+
+rpivotTable(Titanic,
+            rows = "Survived",
+            cols = c("Sex"),
+            rendererName = "Bar Chart",
+            # pass options to the c3 renderer to customize the barchart
+            rendererOptions = list(c3 = c3RenderOptions)
+            )

inst/examples/drilldown.R

@@ -0,0 +1,33 @@
+library(rpivotTable)
+
+# This example demonstrates connecting a custom function to the double-click event
+# for table cells.
+
+# if not using the subtotals plugin, use the following rendererOptions synax
+rpivotTable(Titanic, 
+            rows = c("Survived"), 
+            cols = c("Sex"),
+            rendererOptions = list(
+                # these will be the rendering options passed to the "table" renderer
+                table = list(
+                # popup a list of the observations' genders associated with the cell that you double click on
+                clickCallback = htmlwidgets::JS('function(e, value, filters, pivotData) {
+                                             var names = [];
+                                             pivotData.forEachMatchingRecord(filters,
+                                             function(record){ names.push(record.Sex); });
+                                             alert(names.join(\"\\n\"));
+                                             }')))
+        )
+
+# if subtotals is true, then the rendererOptions's syntax should be the following 
+rpivotTable(Titanic, 
+            rows = c("Survived"), 
+            cols = c("Sex"),
+            rendererOptions = list(table = list(eventHandlers = list("click" = htmlwidgets::JS('function(e, value, filters, pivotData) {
+                                var names = [];
+                            pivotData.forEachMatchingRecord(filters,
+                                function(record){ names.push(record.Sex); });
+                            alert(names.join(\"\\n\"));
+                            }')
+                            ))),
+            subtotals = T)

vignettes/rpivotTableIntroduction.Rmd

@@ -62,6 +62,7 @@ For additional technical information please refer to the examples and explanatio
 * `aggregatorName` indicates the type of aggregation. Options here are numerous: Count, Count Unique Values, List Unique Values, Sum, Integer Sum, Average, Sum over Sum, 80% Upper Bound, 80% Lower Bound, Sum as Fraction of Total, Sum as Fraction of Rows, Sum as Fraction of Columns, Count as Fraction of Total, Count as Fraction of Rows, Count as Fraction of Columns
 * `vals` specifies the variable to use with `aggregatorName` (if any).
 * `renderers` dictates the type of graphic rendering used for display, like Table, Treemap etc.
+* `rendererOptions` provides the ability to customize the renderers' displays and behavior.
 * `sorters` allow to implement a javascript function to specify the ad hoc sorting of certain values. See vignette for an example. It is especially useful with time divisions like days of the week or months of the year (where the alphabetical order does not work)
 
 For example, to display a table with frequency of colour combinations of eyes and hair, you can specify:
@@ -92,20 +93,77 @@ This function could be useful for example to sort time divisions like months of
 You can also use the very visual new subtotals:
 
 ```{r, fig.show='hold'}
+library(rpivotTable)
 data(mtcars)
 rpivotTable(mtcars,rows="gear", cols=c("cyl","carb"),subtotals=TRUE, width="100%", height="400px")
 ```
 
-Or if you want to include it as part of your `dplyr` / `magrittr` pipeline, you can do that also.
+And even customize how the graphs are rendered:
+
+```{r, fig.show='hold'}
+library(rpivotTable)
+MyColors <- c(rgb(186,150,155, maxColorValue=255), rgb(238,221,130, maxColorValue=255),
+ rgb(205,150,205, maxColorValue=255))
+
+c3RenderOptions <- list(size = list(height=300, width=600),# change the size of the barchart
+ zoom = list(enabled=T), # add zooming
+ # use a custom color scheme
+ color = list(pattern=as.list(MyColors)))
+
+rpivotTable(Titanic,
+ rows = "Survived",
+ cols = c("Sex"),
+ rendererName = "Bar Chart",
+ # pass options to the c3 renderer to customize the barchart
+ rendererOptions = list(c3 = c3RenderOptions),
+ width="100%", height="400px"
+ )
+```
 
+As well as add drilldown functionality to table cells:
+
+```{r}
+library(rpivotTable)
+rpivotTable(Titanic, 
+ rows = c("Survived"), 
+ cols = c("Sex"),
+ rendererOptions = list(
+ # these will be the rendering options passed to the "table" renderer
+ table = list(
+ # popup a list of the observations' genders associated with the cell that you double click on
+ clickCallback = htmlwidgets::JS('function(e, value, filters, pivotData) {
+  var names = [];
+  pivotData.forEachMatchingRecord(filters,
+  function(record){ names.push(record.Sex); });
+  alert(names.join(\"\\n\"));
+  }'))),
+ width="100%", height="400px"
+ )
+```
+
+If you want to include it as part of your `dplyr` / `magrittr` pipeline, you can do that also.
 
 ```{r, fig.show='hold'}
-# suppressMessages(
+library(rpivotTable)
+suppressMessages(
   library(dplyr)
-  # )
+  )
 iris %>%
 tbl_df %>%
 filter( Sepal.Width > 3 & Sepal.Length > 5 ) %>%
-rpivotTable(rows="Sepal.Width",  rendererName="Treemap")
+rpivotTable(rows="Sepal.Width",  rendererName="Treemap", width="100%", height="400px")
+```
+
+#### Notes
+
+When embedding an rprivotTable into a knitr project (especially flexdashboard projects), it is recommended to include the following in your project's CSS file: 
+
+```{css}
+.rpivotTable
+    {
+    overflow-x: auto;
+    overflow-y: auto;
+    }
 ```
 
+This will ensure that the pivot table has scrollbars if its content is too tall or wide for its display area.