Merge pull request #19 from eodaGmbH/feature/pkgdown

Feature/pkgdown

.Rbuildignore

@@ -9,3 +9,4 @@ _NAMESPACE
 ^docs$
 ^pkgdown$
 ^\.github$
+images/

DESCRIPTION

@@ -1,15 +1,19 @@
 Package: rtabulator
 Type: Package
 Title: R Bindings for Tabulator JS
-Version: 0.1.0
-Date: 2024-09-08
+Version: 0.1.1
+Date: 2024-09-13
 Authors@R: c(
   person("Stefan", "Kuethe", email = "[email protected]", role = c("aut", "cre")),
   person("Nico", "Friess", email = "[email protected]", role = c("aut"))
   )
 Maintainer: Stefan Kuethe <[email protected]>
 Description: Provides R bindings for 'Tabulator JS' <https://tabulator.info/>.
   Makes it a breeze to create beautiful interactive tables.
+URL:
+  https://github.com/eodaGmbH/rtabulator
+  https://eodagmbh.github.io/rtabulator/
+BugReports: https://github.com/eodaGmbH/rtabulator/issues
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true

NAMESPACE

@@ -6,6 +6,7 @@ export(delete_selected_rows)
 export(list_to_data_frame)
 export(redo)
 export(renderTabulator)
+export(set_column_editor)
 export(set_formatter_color)
 export(set_formatter_datetime)
 export(set_formatter_html)
@@ -19,6 +20,8 @@ export(set_formatter_textarea)
 export(set_formatter_tick_cross)
 export(set_formatter_toggle_switch)
 export(set_formatter_traffic_light)
+export(set_header_filter)
+export(set_multi_column_header)
 export(tabulator)
 export(tabulatorContext)
 export(tabulatorOutput)

NEWS.md

@@ -1,3 +1,12 @@
+# rtabulator 0.1.1
+
+* Update docs
+* Add pkgdown site
+* Add function to create multi column headers
+* Add a lot of examples
+* Update README
+* Make `devtools::check()` pass 🚀
+
 # rtabulator 0.1.0
 
 * Add NEWS.md to track changes.

R/columns.R

@@ -1,4 +1,4 @@
-#' Create columns definition from data
+#' Create column definitions from data
 #' @param data (data.frame) data
 #' @param editor (bool): Whether to make columns editable.
 #' @param filter (bool): Whether to add a header filter to the columns.
@@ -107,7 +107,7 @@ set_formatter_money <- function(
     column,
     decimal = c(",", "."),
     thousand = c(".", ","),
-    symbol = "EUR",
+    symbol = "$", # "\U20AC"
     symbol_after = "p",
     negative_sign = "-",
     precision = FALSE,
@@ -211,7 +211,6 @@ set_formatter_star <- function(widget, column, number_of_stars, hoz_align = "cen
 #'  If set to \code{NA} the minimum value of the column is used.
 #' @param max (numeric): The maximum value for progress bar.
 #'  If set to \code{NA} the maximum value of the column is used.
-#' @param max description
 #' @param color (character): Either a single color or a vector of colors
 #' @param legend (character, \code{TRUE}, JavaScript function): If set to \code{TRUE} the value of the cell is displayed.
 #'  Set to \code{NA} to display no value at all.
@@ -300,7 +299,7 @@ set_formatter_toggle_switch <- function(
   modify_col_def(widget, column, col_update)
 }
 
-#' Datetime formatter
+#' Datetime Formatter
 #' @inheritParams set_formatter_html
 #' @param input_format (character): The datetime input format.
 #' @param output_format (character): The datetime output format.
@@ -314,8 +313,7 @@ set_formatter_datetime <- function(
     input_format = "yyyy-MM-dd hh:ss:mm",
     output_format = "yy/MM/dd",
     invalid_placeholder = "(invalid datetime)",
-    timezone = NA
-    ) {
+    timezone = NA) {
   # Body
   col_update <- list(
     formatter = "datetime",
@@ -340,6 +338,7 @@ set_formatter_color <- function(widget, column) {
 
 #' Traffic Light Formatter
 #' @inheritParams set_formatter_progress
+#' @example examples/formatters/formatter_traffic_light.R
 #' @export
 set_formatter_traffic_light <- function(
     widget,
@@ -349,9 +348,9 @@ set_formatter_traffic_light <- function(
     color = c("green", "orange", "red"),
     hoz_align = "center") {
   # Body
-  if (is.na(min)) min = min(widget$x$data[column])
+  if (is.na(min)) min <- min(widget$x$data[column])
 
-  if (is.na(max)) max = max(widget$x$data[column])
+  if (is.na(max)) max <- max(widget$x$data[column])
 
   col_update <- list(
     formatter = "traffic",
@@ -365,6 +364,44 @@ set_formatter_traffic_light <- function(
   modify_col_def(widget, column, col_update)
 }
 
+# Other
+
+#' Make columns editable
+#' @inheritParams set_formatter_html
+#' @param columns (character vector): Columns the editor is applied to.
+#' @param type (character): Either \code{input} or \code{number}.
+#' @example examples/formatters/column_editor.R
+#' @export
+set_column_editor <- function(widget, columns, type = c("input", "number")) {
+  col_update <- list(editor = match.arg(type))
+  for (column in columns) {
+    widget <- modify_col_def(widget, column, col_update)
+  }
+
+  return(widget)
+}
+
+#' Add header filter
+#' @inheritParams set_column_editor
+#' @param columns (character vector): Columns the editor is applied to.
+#'  If set to \code{NULL}, the editor is applied to all columns.
+#' @example examples/misc/header_filter.R
+#' @export
+set_header_filter <- function(widget, columns = NULL) {
+  if (is.null(columns)) {
+    columns <- colnames(widget$x$data)
+  }
+
+  col_update <- list(headerFilter = TRUE)
+  for (column in columns) {
+    widget <- modify_col_def(widget, column, col_update)
+  }
+
+  return(widget)
+}
+
+# Generics
+
 modify_col_def <- function(widget, column, col_update) {
   for (index in 1:length(widget$x$options$columns)) {
     if (widget$x$options$columns[[index]]$field == column) {

R/experimental.R

@@ -1,4 +1,33 @@
 # See example here: https://github.com/eodaGmbH/py-tabulator/blob/main/docs/examples/getting_started/shiny_core_multi_row_headers.py
+#' Multi Column Header
+#' @inheritParams set_formatter_html
+#' @param multi_columns (list): Multi column definitions
+#' @example examples/experimental/multi_column_header.R
+#' @export
 set_multi_column_header <- function(widget, multi_columns) {
+  res <- list()
+  for (key in names(multi_columns)) {
+    column_names <- multi_columns[[key]]
+    column_defs <- purrr::map(column_names, ~ find_column(widget, .x))
+    res <- append(res, list(list(title = key, columns = column_defs)))
+  }
 
+  # Add columns not used in multi_columns
+  used_cols <- unlist(multi_columns)
+  for (column_name in unlist(purrr::map(widget$x$options$columns, ~ .x$field))) {
+    if (!column_name %in% used_cols) res <- append(res, list(find_column(widget, column_name)))
+  }
+
+  # return(res)
+  widget$x$options$columns <- res
+  return(widget)
+}
+
+find_column <- function(widget, column) {
+  column_def <- NULL
+  for (item in widget$x$options$columns) {
+    if (item$field == column) column_def <- item
+  }
+
+  return(column_def)
 }

R/spreadsheet.R

@@ -0,0 +1,25 @@
+## #' @export
+# TODO: Is this useful?
+set_spreadsheet_mode <- function(
+    widget,
+    spreadsheet_rows = NULL,
+    spreadsheet_columns = NULL,
+    spreadsheet_column_definition = NULL,
+    spreadsheet_sheets = NULL,
+    spreadsheet_sheet_tabs = NULL,
+    ...) {
+  spreadsheet_options <- list(
+    spreadsheet = TRUE,
+    spreadsheetRows = spreadsheet_rows,
+    spreadsheetColumns = spreadsheet_columns,
+    spreadsheetColumnDefinition = spreadsheet_column_definition,
+    spreadsheetSheets = spreadsheet_sheets,
+    spreadsheetSheetTabs = spreadsheet_sheet_tabs,
+    ...
+  )
+  widget$x$options <- keys_to_camel_case(utils::modifyList(
+    utils::modifyList(widget$x$options, default_spreadsheet_options),
+    compact(spreadsheet_options)
+  ))
+  return(widget)
+}

R/tabulator.R

@@ -1,5 +1,6 @@
 #' Create a Tabulator Widget
 #'
+#' Dots in column names are replaced by underscores.
 #' @param data (data.frame, character or list): In spreadsheet mode data needs to be a list or \code{NULL}
 #'  for an empty spreadsheet.
 #' @param options (list): Setup options. See \code{\link{tabulator_options}}.
@@ -9,8 +10,9 @@
 #' @param theme (character): Theme to apply to the table.
 #' @param width Width of the widget.
 #' @param height Height of the widget.
-#' @param element_id description
+#' @param element_id The unique ID of the widget.
 #' @param ... Named arguments that are appended to the \code{options} parameter.
+#' @example examples/multiple_spreadsheets.R
 #' @import htmlwidgets
 #' @export
 tabulator <- function(
@@ -35,7 +37,7 @@ tabulator <- function(
   if (isTRUE(options$spreadsheet)) {
     # ...
     options <- utils::modifyList(default_spreadsheet_options, options)
-  } else {
+  } else if (is.data.frame(data)) {
     data <- fix_colnames(data)
     if (getOption("rtabulator.auto_columns", TRUE) && is.null(options$columns)) {
       options$columns <- create_columns(data, editor = editable)

R/tabulator_context.R

@@ -14,7 +14,8 @@ invoke_method <- function(widget, method_name, ...) {
   invisible(widget)
 }
 
-#' Create a Tabulator Context
+#' Create a Tabulator Context Object
+#' A \code{tabulatorContext} object makes it possible to update your widget in a Shiny app.
 #' @param output_id (character): A tabulator output id.
 #' @param session shiny session object
 #' @export

R/tabulator_options.R

@@ -15,19 +15,24 @@
 #' @param frozen_rows (numeric): Number of frozen rows.
 #' @param index (character): Field to be used as the unique index for each row.
 #' @param group_by (character): Field to group rows by.
-#' @param edit_trigger_event description
-#' @param selectable_rows description
-#' @param pagination (bool): description
-#' @param pagination_size (integer): description
-#' @param pagination_add_row (character): description
-#' @param spreadsheet (bool): description
-#' @param spreadsheet_rows (integer): description
-#' @param spreadsheet_columns (integer): description
-#' @param spreadsheet_column_definition description
-#' @param spreadsheet_sheets (list): description
-#' @param spreadsheet_sheet_tabs (bool): description
+#' @param edit_trigger_event (character): Event that triggers a cell edit.
+#' @param selectable_rows (character, bool, integer) Set to \code{FALSE} to disble row selection.
+#'  If set to \code{TRUE} you can select as many rows as you want.
+#'  If set to \code{"highlight"} rows are just highlighted but do not change state when clicked.
+#'  An integer value sets the maximum number of rows that can be selected.
+#' @param pagination (bool): Whether to enable pagination.
+#' @param pagination_size (integer): Number of rows on each page.
+#' @param pagination_size_selector (list): Add pagination size selector.
+#' @param pagination_add_row (character): Where to add rows to the table when pagination is enabled.
+#' @param spreadsheet (bool): Whether to enable spreadsheet mode.
+#' @param spreadsheet_rows (integer): Number of spreadsheet rows.
+#' @param spreadsheet_columns (integer): Number of spreadsheet columns.
+#' @param spreadsheet_column_definition Column definition used for all columns in the sheet.
+#' @param spreadsheet_sheets (list): List of sheet definitions.
+#' @param spreadsheet_sheet_tabs (bool): Whether to show sheet tabs in the footer.
 #' @param ... Further options.
 #' @seealso \url{https://tabulator.info/docs/6.2/options}
+#' @example examples/tabulator_setup.R
 #' @export
 tabulator_options <- function(
     # General
@@ -50,13 +55,14 @@ tabulator_options <- function(
     # Row Grouping
     group_by = NULL,
     # Editing
-    edit_trigger_event = "dblclick",
+    edit_trigger_event = c("dblclick", "click", "focus"),
     # Selection
     selectable_rows = "highlight", # 'highlight', bool or integer
     # Pagination
     pagination = FALSE,
     pagination_size = 10,
-    pagination_add_row = "page",
+    pagination_size_selector = FALSE,
+    pagination_add_row = c("page", "table"),
     # Spreadsheet
     spreadsheet = FALSE,
     spreadsheet_rows = NULL,
@@ -68,6 +74,8 @@ tabulator_options <- function(
   params <- as.list(environment())
   params$layout <- match.arg(layout)
   params$add_row_pos <- match.arg(add_row_pos)
+  params$edit_trigger_event <- match.arg(edit_trigger_event)
+  params$pagination_add_row <- match.arg(pagination_add_row)
   return(c(params, list(...)))
 }
 

README.Rmd

@@ -22,18 +22,54 @@ knitr::opts_chunk$set(
 The goal of rtabulator is to make it a breeze creating beautiful and reactive tables using
 [Tabulator JS](https://tabulator.info/)
 
+## Features
+
+* Filters
+* Grouping
+* Multiple column formatters (images, html, progress bar, ...)
+* Multiple themes
+* Multi column headers
+* Spreadsheet mode supporting multiple sheets
+* Cell editing supporting validation
+* Downloads (json, csv, xlsx)
+* Interactivity
+
 ## Installation
 
+Once on CRAN you can install rtabulator with:
+
+``` r
+install.packages("rtabulator")
+```
+
 You can install the development version of rtabulator like so:
 
 ``` r
 remotes::install_github("eodaGmbH/rtabulator")
 ```
 
-## Example
+## Basic Usage
 
-```r
+``` r
 library(rtabulator)
 
 tabulator(mtcars)
+
+# Set theme
+tabulator(iris, theme = "midnight")
+
+# Format columns
+tabulator(airquality) |>
+  set_formatter_progress(
+    column = "Temp",
+    legend = TRUE,
+    legend_align = "left"
+  )
+
+# Spreadsheet mode
+tabulator(data = list(), spreadsheet = TRUE)
 ```
+
+## Documentation
+
+[rtabulator docs](https://eodagmbh.github.io/rtabulator/)