From 91c2c5ea9d4eefbfb196d9fe40f7461729bad9be Mon Sep 17 00:00:00 2001
From: Stefan Kuethe <stefan.kuethe@eoda.de>
Date: Fri, 13 Sep 2024 18:48:28 +0200
Subject: [PATCH] Add helper for spreadsheet def and update docs

---
 NAMESPACE                         |  1 +
 R/spreadsheet.R                   | 10 ++++++++
 _pkgdown.yml                      |  1 +
 man/spreadsheet_def.Rd            | 19 ++++++++++++++
 vignettes/articles/rtabulator.Rmd | 42 +++++++++++++++++++++++++------
 5 files changed, 66 insertions(+), 7 deletions(-)
 create mode 100644 man/spreadsheet_def.Rd

diff --git a/NAMESPACE b/NAMESPACE
index ee40f28..a3b3f31 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -22,6 +22,7 @@ export(set_formatter_toggle_switch)
 export(set_formatter_traffic_light)
 export(set_header_filter)
 export(set_multi_column_header)
+export(spreadsheet_def)
 export(tabulator)
 export(tabulatorContext)
 export(tabulatorOutput)
diff --git a/R/spreadsheet.R b/R/spreadsheet.R
index eec92ed..a9b0fc8 100644
--- a/R/spreadsheet.R
+++ b/R/spreadsheet.R
@@ -1,3 +1,13 @@
+#' Create a spreadsheet definition
+#' @param title (character): The name of the spreadsheet.
+#' @param key (character): Optional unique key of the spreadsheet.
+#' @param data (list) The initial data of the spreadsheet.
+#'  Set to \code{NULL} to create an empty spreadsheet.
+#' @export
+spreadsheet_def <- function(title, key = NULL, data = NULL) {
+  return(compact(as.list(environment())))
+}
+
 ## #' @export
 # TODO: Is this useful?
 set_spreadsheet_mode <- function(
diff --git a/_pkgdown.yml b/_pkgdown.yml
index 448e27e..88f9aea 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -35,6 +35,7 @@ reference:
     desc: >
       Utitily functions
     contents:
+      - spreadsheet_def
       - list_to_data_frame
       - create_columns
 
diff --git a/man/spreadsheet_def.Rd b/man/spreadsheet_def.Rd
new file mode 100644
index 0000000..6d187a3
--- /dev/null
+++ b/man/spreadsheet_def.Rd
@@ -0,0 +1,19 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/spreadsheet.R
+\name{spreadsheet_def}
+\alias{spreadsheet_def}
+\title{Create a spreadsheet definition}
+\usage{
+spreadsheet_def(title, key = NULL, data = NULL)
+}
+\arguments{
+\item{title}{(character): The name of the spreadsheet.}
+
+\item{key}{(character): Optional unique key of the spreadsheet.}
+
+\item{data}{(list) The initial data of the spreadsheet.
+Set to \code{NULL} to create an empty spreadsheet.}
+}
+\description{
+Create a spreadsheet definition
+}
diff --git a/vignettes/articles/rtabulator.Rmd b/vignettes/articles/rtabulator.Rmd
index 3927663..b55b265 100644
--- a/vignettes/articles/rtabulator.Rmd
+++ b/vignettes/articles/rtabulator.Rmd
@@ -11,7 +11,7 @@ knitr::opts_chunk$set(
 
 rtabulator provides R bindings for [Tabulator JS](https://tabulator.info/).
 
-The goal of rtabulator is to make it easy to create elegant and interactive tables in markdown documents and [Shiny](https://shiny.posit.co/) applications. Furthermore, it support creating spreadsheets with multiple sheets.
+The goal of rtabulator is to make it easy to create elegant and interactive tables in markdown documents and [Shiny](https://shiny.posit.co/) applications. Furthermore, it supports creating spreadsheets with multiple sheets.
 
 ```{r setup}
 library(rtabulator)
@@ -19,7 +19,7 @@ library(rtabulator)
 
 ## Basic Usage
 
-To render a table just pass a data frame to the `tabulator` function:
+To render a table just pass a data frame to `tabulator()`:
 
 ```{r}
 tabulator(airquality)
@@ -30,7 +30,7 @@ character columns is set to _left_  while numeric columns are aligned _right_.
 
 ## Setup Options
 
-With `tabulator_options` you can customize your table (or spreadsheet):
+With `tabulator_options()` you can customize your table (or spreadsheet):
 
 ```{r}
 setup <- tabulator_options(
@@ -44,7 +44,7 @@ tabulator(USArrests, setup)
 
 ## Column Formatters
 
-To customize your columns the easiest way is to use the `set_formatter_*` functions: 
+To customize your columns, the easiest way is to use the `set_formatter_*` functions like `set_formatter_progress()` and others: 
 
 ```{r}
 tabulator(airquality) |>
@@ -54,7 +54,7 @@ tabulator(airquality) |>
 
 ## Multi Column headers
 
-You can create multi column headers with `set_multi_column_header`:
+You can create multi column headers with `set_multi_column_header()`:
 
 ```{r}
 headers <- list(
@@ -68,9 +68,37 @@ tabulator(iris) |>
 
 ## Spreadsheets
 
-To create an empty spreadsheet just pass an empty list as `data` parameter and `spreadsheet = TRUE`
-to the `tabulator` function:
+To create an empty spreadsheet just pass an empty list as `data` parameter and `spreadsheet = TRUE` to `tabulator()`:
 
 ```{r}
 tabulator(data = list(), spreadsheet = TRUE)
 ```
+
+The data format for spreadsheets is a list of lists or vectors where each entry represents a row in the spreadsheet:
+
+```{r}
+spreadsheet_data <- list(
+  c(1, 2, 3),
+  c(2, 3, 4)
+)
+```
+
+To use multiple sheets pass a list of sheets created with`spreadsheet_def()`. In this case, data is passed with the `data` parameter of the sheet definitions:
+
+```{r}
+sheets <- list(
+  spreadsheet_def(title = "Lee", data = spreadsheet_data),
+  spreadsheet_def(title = "Morgan", data = list()) # Empty spreadsheet
+)
+setup = tabulator_options(
+  spreadsheet = TRUE,
+  spreadsheet_sheets = sheets,
+  spreadsheet_sheet_tabs = TRUE,
+  edit_trigger_event = "click"
+)
+
+tabulator(NULL, setup)
+```
+## Next Steps
+
+Check the [API Reference](../reference/index.html) for details.