[pt] add wb_add_timeline() (#1017)

NAMESPACE

@@ -76,6 +76,7 @@ export(wb_add_slicer)
 export(wb_add_sparklines)
 export(wb_add_style)
 export(wb_add_thread)
+export(wb_add_timeline)
 export(wb_add_worksheet)
 export(wb_clean_sheet)
 export(wb_clone_sheet_style)

NEWS.md

@@ -8,6 +8,8 @@
 
 * Initial support for pivot table timelines. [1016](https://github.com/JanMarvin/openxlsx2/pull/1016)
 
+* Add `wb_add_timeline()` and extend `wb_add_slicer()`. [1017](https://github.com/JanMarvin/openxlsx2/pull/1017)
+
 ## Fixes
 
 * Fixed an issue with non consecutive dims, where columns or rows were silently dropped. [1015](https://github.com/JanMarvin/openxlsx2/pull/1015)

R/class-workbook-wrappers.R

@@ -414,7 +414,7 @@ wb_add_data_table <- function(
 #' @param fun A vector of functions to be used with `data`. See **Details** for the list of available options.
 #' @param params A list of parameters to modify pivot table creation. See **Details** for available options.
 #' @param pivot_table An optional name for the pivot table
-#' @param slicer Any additional column name(s) of `x` used as slicer
+#' @param slicer,timeline Any additional column name(s) of `x` used as slicer/timeline
 #' @seealso [wb_data()]
 #' @examples
 #' wb <- wb_workbook() %>% wb_add_worksheet() %>% wb_add_data(x = mtcars)
@@ -446,17 +446,19 @@ wb_add_pivot_table <- function(
     fun,
     params,
     pivot_table,
-    slicer
+    slicer,
+    timeline
 ) {
   assert_workbook(wb)
-  if (missing(filter))      filter <- substitute()
-  if (missing(rows))        rows   <- substitute()
-  if (missing(cols))        cols   <- substitute()
-  if (missing(data))        data   <- substitute()
-  if (missing(fun))         fun    <- substitute()
-  if (missing(params))      params <- substitute()
+  if (missing(filter))      filter      <- substitute()
+  if (missing(rows))        rows        <- substitute()
+  if (missing(cols))        cols        <- substitute()
+  if (missing(data))        data        <- substitute()
+  if (missing(fun))         fun         <- substitute()
+  if (missing(params))      params      <- substitute()
   if (missing(pivot_table)) pivot_table <- substitute()
-  if (missing(slicer))      slicer <- substitute()
+  if (missing(slicer))      slicer      <- substitute()
+  if (missing(timeline))    timeline    <- substitute()
 
   wb$clone()$add_pivot_table(
     x           = x,
@@ -469,48 +471,108 @@ wb_add_pivot_table <- function(
     fun         = fun,
     params      = params,
     pivot_table = pivot_table,
-    slicer      = slicer
+    slicer      = slicer,
+    timeline    = timeline
   )
 
 }
 
-#' Add a slicer to a pivot table
+#' Add a slicer/timeline to a pivot table
 #'
-#' Add a slicer to a previously created pivot table. This function is still experimental and might be changed/improved in upcoming releases.
+#' Add a slicer/timeline to a previously created pivot table. This function is still experimental and might be changed/improved in upcoming releases.
 #'
 #' @details
-#' This assumes that the slicer variable initialization has happened before. Unfortunately, it is unlikely that we can guarantee this for loaded workbooks, and we *strictly* discourage users from attempting this. If the variable has not been initialized properly, this may cause the spreadsheet software to crash.
+#' This assumes that the slicer/timeline variable initialization has happened before. Unfortunately, it is unlikely that we can guarantee this for loaded workbooks, and we *strictly* discourage users from attempting this. If the variable has not been initialized properly, this may cause the spreadsheet software to crash.
+#' Although it is documented that slicers should use "TimelineStyleLight\[1-6\]" and "TimelineStyleDark\[1-6\]" they use slicer styles.
 #'
-#' Possible `params` arguments are listed below.
+#' Possible `params` arguments for slicers are listed below.
 #' * edit_as: "twoCell" to place the slicer into the cells
-#' * style: "SlicerStyleLight2"
 #' * column_count: integer used as column count
-#' * caption: string used for a caption
 #' * sort_order: "descending" / "ascending"
 #' * choose: select variables in the form of a named logical vector like
 #'  `c(agegp = 'x > "25-34"')` for the `esoph` dataset.
+#' * locked_position
+#' * start_item
+#'
+#' Possible `params` arguments for timelines are listed below.
+#' * beg_date/end_date: dates when the timeline should begin or end
+#' * choose_beg/choose_end: dates when the selection should begin or end
+#' * scroll_position
+#' * show_selection_label
+#' * show_time_level
+#' * show_horizontal_scrollbar
+#'
+#' Possible common `params`:
+#' * caption: string used for a caption
+#' * style: "SlicerStyleLight\[1-6\]", "SlicerStyleDark\[1-6\]" only for slicer "SlicerStyleOther\[1-2\]"
+#' * level: the granularity of the slicer (for timeline 0 = year, 1 = quarter, 2 = month)
+#' * show_caption: logical if caption should be shown or not
 #'
-#' @param wb A Workbook object containing a #' worksheet.
+#' @param wb A Workbook object containing a worksheet.
 #' @param x A `data.frame` that inherits the [`wb_data`][wb_data()] class.
-#' @param sheet A worksheet containing a #'
+#' @param sheet A worksheet
 #' @param dims The worksheet cell where the pivot table is placed
-#' @param pivot_table The name of a pivot table on the selected sheet
-#' @param slicer A variable used as slicer for the pivot table
+#' @param pivot_table The name of a pivot table
+#' @param slicer,timeline A variable used as slicer/timeline for the pivot table
 #' @param params A list of parameters to modify pivot table creation. See **Details** for available options.
 #' @family workbook wrappers
 #' @family worksheet content functions
 #' @examples
-#' wb <- wb_workbook() %>%
-#'   wb_add_worksheet() %>% wb_add_data(x = mtcars)
+#' # prepare data
+#' df <- data.frame(
+#'   AirPassengers = c(AirPassengers),
+#'   time = seq(from = as.Date("1949-01-01"), to = as.Date("1960-12-01"), by = "month"),
+#'   letters = letters[1:4]
+#' )
 #'
-#' df <- wb_data(wb, sheet = 1)
+#' # create workbook
+#' wb <- wb_workbook()$
+#'   add_worksheet("pivot")$
+#'   add_worksheet("data")$
+#'   add_data(x = df)
+#'
+#' # get pivot table data source
+#' df <- wb_data(wb, sheet = "data")
+#'
+#' # create pivot table
+#' wb$add_pivot_table(
+#'   df,
+#'   sheet = "pivot",
+#'   rows = "time",
+#'   cols = "letters",
+#'   data = "AirPassengers",
+#'   pivot_table = "airpassengers",
+#'   params = list(
+#'     compact = FALSE, outline = FALSE, compact_data = FALSE,
+#'     row_grand_totals = FALSE, col_grand_totals = FALSE)
+#' )
 #'
-#' wb <- wb %>%
-#'   wb_add_pivot_table(
-#'     df, dims = "A3", slicer = "vs", rows = "cyl", cols = "gear", data = "disp",
-#'     pivot_table = "mtcars"
-#'   ) %>%
-#'   wb_add_slicer(x = df, slicer = "vs", pivot_table = "mtcars")
+#' # add slicer
+#' wb$add_slicer(
+#'   df,
+#'   dims = "E1:I7",
+#'   sheet = "pivot",
+#'   slicer = "letters",
+#'   pivot_table = "airpassengers",
+#'   params = list(choose = c(letters = 'x %in% c("a", "b")'))
+#' )
+#'
+#' # add timeline
+#' wb$add_timeline(
+#'   df,
+#'   dims = "E9:I14",
+#'   sheet = "pivot",
+#'   timeline = "time",
+#'   pivot_table = "airpassengers",
+#'   params = list(
+#'     beg_date = as.Date("1954-01-01"),
+#'     end_date = as.Date("1961-01-01"),
+#'     choose_beg = as.Date("1957-01-01"),
+#'     choose_end = as.Date("1958-01-01"),
+#'     level = 0,
+#'     style = "TimeSlicerStyleLight2"
+#'   )
+#' )
 #' @export
 wb_add_slicer <- function(
     wb,
@@ -535,6 +597,31 @@ wb_add_slicer <- function(
 
 }
 
+#' @rdname wb_add_slicer
+#' @export
+wb_add_timeline <- function(
+    wb,
+    x,
+    dims        = "A1",
+    sheet       = current_sheet(),
+    pivot_table,
+    timeline,
+    params
+) {
+  assert_workbook(wb)
+  if (missing(params)) params <- substitute()
+
+  wb$clone()$add_timeline(
+    x           = x,
+    sheet       = sheet,
+    dims        = dims,
+    pivot_table = pivot_table,
+    timeline    = timeline,
+    params      = params
+  )
+
+}
+
 #' Add a formula to a cell range in a worksheet
 #'
 #' This function can be used to add a formula to a worksheet.