From 1a17e8acbfec8bc933bc2fb4ce05fc74e061d38f Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Wed, 8 May 2019 16:01:08 -0400
Subject: [PATCH] Have the table ID be settable, random, or absent in `gt()`
 (#286)

* Add `table_id` param to `gt_options_default()`

* Add a `random_id()` util function

* Add the `table_id` argument to `gt()`

* Add the `table_id` value to `opts_df`

* Modify setting of `opts_df` attr

* Get the table ID from the `opts_df` attr

* Add roxygen @param statement

* Update help file using roxygen

* Use the `opts_df_get()` fcn

* Rename `random_id()` to `id_random()`

* Modify name of function call

* Add to NAMESPACE

* Update help files using roxygen

* Move `id_random()` to a different file

* Update help files using roxygen

* Modify roxygen title

* Rename function and add `n` arg

* Modify use of renamed function

* Update roxygen documentation

* Modify NAMESPACE
---
 NAMESPACE                    |  1 +
 R/gt.R                       | 19 ++++++++++++++++---
 R/gt_options_default.R       |  4 +++-
 R/helpers.R                  | 14 ++++++++++++++
 R/print.R                    | 12 ++++++++++--
 R/utils.R                    |  3 +--
 man/cells_styles.Rd          |  3 ++-
 man/escape_latex.Rd          |  3 ++-
 man/gt.Rd                    |  8 ++++++--
 man/gt_latex_dependencies.Rd |  3 ++-
 man/html.Rd                  |  3 ++-
 man/md.Rd                    |  3 ++-
 man/pct.Rd                   |  3 ++-
 man/px.Rd                    |  3 ++-
 man/random_id.Rd             | 23 +++++++++++++++++++++++
 15 files changed, 88 insertions(+), 17 deletions(-)
 create mode 100644 man/random_id.Rd

diff --git a/NAMESPACE b/NAMESPACE
index b3967bbe25..677982a243 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -61,6 +61,7 @@ export(md)
 export(one_of)
 export(pct)
 export(px)
+export(random_id)
 export(render_gt)
 export(row_group_order)
 export(starts_with)
diff --git a/R/gt.R b/R/gt.R
index 990bea060e..b1a746db2d 100644
--- a/R/gt.R
+++ b/R/gt.R
@@ -15,7 +15,7 @@
 #' (perhaps unique across the entire table or unique within groups).
 #'
 #' Row groups can also be created by passing a `grouped_df` to `gt()` by using
-#' the `dplyr::group_by()` function on the table data. In this way, two or more
+#' the [dplyr::group_by()] function on the table data. In this way, two or more
 #' columns of categorical data can be used to make row groups. The
 #' `stub_group.sep` argument allows for control in how the row group label will
 #' appear in the display table.
@@ -27,6 +27,9 @@
 #'   group labels for generation of stub row groups.
 #' @param rownames_to_stub An option to take rownames from the input `data`
 #'   table as row captions in the display table stub.
+#' @param id The table ID. By default, this will be a random ID as generated by
+#'   the [random_id()] function. If set to `NULL` then no table ID will be
+#'   applied.
 #' @param stub_group.sep The separator to use between consecutive group names (a
 #'   possibility when providing `data` as a `grouped_df` with multiple groups)
 #'   in the displayed stub row group label.
@@ -71,8 +74,18 @@ gt <- function(data,
                rowname_col = "rowname",
                groupname_col = "groupname",
                rownames_to_stub = FALSE,
+               id = random_id(),
                stub_group.sep = getOption("gt.stub_group.sep", " - ")) {
 
+  opts_df <- gt_options_default()
+
+  # Add the table ID to the `id` parameter
+  if (!is.null(id)) {
+
+    opts_df <- opts_df_set(
+      opts_df, "table_id", id)
+  }
+
   # If the option to place rownames in the stub
   # is taken, then the `stub_df` data frame will
   # be pre-populated with rownames in the `rowname`
@@ -230,8 +243,8 @@ gt <- function(data,
   # Apply the input data table as an attribute
   attr(data_tbl, "data_df") <- data
 
-  # Apply the default theme options data frame as an attribute
-  attr(data_tbl, "opts_df") <- gt_options_default()
+  # Apply the `opts_df` data frame as an attribute
+  attr(data_tbl, "opts_df") <- opts_df
 
   # Apply an empty `formats` list as an attribute
   attr(data_tbl, "formats") <- list()
diff --git a/R/gt_options_default.R b/R/gt_options_default.R
index c78d622baa..104d10ed53 100644
--- a/R/gt_options_default.R
+++ b/R/gt_options_default.R
@@ -2,6 +2,7 @@ gt_options_default <- function() {
 
   dplyr::tribble(
     ~parameter,                           ~scss, ~category,             ~value,
+    "table_id",                          FALSE,  "table",               NA_character_,
     "table_font_size",                    TRUE,  "table",               "16px",
     "table_background_color",             TRUE,  "table",               "#FFFFFF",
     "table_width",                        TRUE,  "table",               "auto",
@@ -47,6 +48,7 @@ gt_options_default <- function() {
     "footnote_font_size",                 TRUE,  "footnote",            "90%",
     "footnote_padding",                   TRUE,  "footnote",            "4px",
     "sourcenote_font_size",               TRUE,  "sourcenote",          "90%",
-    "sourcenote_padding",                 TRUE,  "sourcenote",          "4px") %>%
+    "sourcenote_padding",                 TRUE,  "sourcenote",          "4px",
+    ) %>%
     as.data.frame()
 }
diff --git a/R/helpers.R b/R/helpers.R
index a8fb71a37a..835da5e015 100644
--- a/R/helpers.R
+++ b/R/helpers.R
@@ -682,6 +682,20 @@ px <- function(x) {
   paste0(x, "px")
 }
 
+#' Helper for creating a random `id` for a \pkg{gt} table
+#'
+#' This helper function is to be used with `id` argument of the [gt()] function.
+#' The `id` option in [gt()] uses `random_id()` by default however we can
+#' optionally supply a custom `id` value, or, use `NULL` for no ID at all.
+#'
+#' @param n The number of lowercase letters to use for the random ID.
+#' @family helper functions
+#' @export
+random_id <- function(n = 10) {
+
+  paste(sample(letters, n, replace = TRUE), collapse = "")
+}
+
 #' Perform LaTeX escaping
 #'
 #' Text may contain several characters with special meanings in LaTeX. This
diff --git a/R/print.R b/R/print.R
index 0339e5cda1..540100fc0f 100644
--- a/R/print.R
+++ b/R/print.R
@@ -43,8 +43,16 @@ as.tags.gt_tbl <- function(x, ...) {
   # Generate the HTML table
   html_table <- render_as_html(data = x)
 
-  # Create a random `id` tag
-  id <- paste(sample(letters, 10, 10), collapse = "")
+  # Extract the `opts_df` data frame object from `x`
+  opts_df <- attr(x, "opts_df", exact = TRUE)
+
+  # Get the table ID from `opts_df`
+  id <- opts_df_get(opts_df, option = "table_id")
+
+  # If the ID hasn't been set, set `id` as NULL
+  if (is.na(id)) {
+    id <- NULL
+  }
 
   # Compile the SCSS as CSS
   css <- compile_scss(data = x, id = id)
diff --git a/R/utils.R b/R/utils.R
index 926354c989..6fd927bdd1 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -933,8 +933,7 @@ stop_if_not_gt <- function(data) {
   }
 }
 
-
-#' Expand a path using fs::path_ex
+#' Expand a path using fs::path_expand
 #' @noRd
 path_expand <- function(file) {
 
diff --git a/man/cells_styles.Rd b/man/cells_styles.Rd
index 41fd56ae95..ae22443b04 100644
--- a/man/cells_styles.Rd
+++ b/man/cells_styles.Rd
@@ -61,6 +61,7 @@ also define several styles within a single call of \code{cells_styles} and
 \seealso{
 Other helper functions: \code{\link{escape_latex}},
   \code{\link{gt_latex_dependencies}}, \code{\link{html}},
-  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}}
+  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/escape_latex.Rd b/man/escape_latex.Rd
index b071f5b433..b12ea78d59 100644
--- a/man/escape_latex.Rd
+++ b/man/escape_latex.Rd
@@ -18,6 +18,7 @@ LaTeX tables.
 \seealso{
 Other helper functions: \code{\link{cells_styles}},
   \code{\link{gt_latex_dependencies}}, \code{\link{html}},
-  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}}
+  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/gt.Rd b/man/gt.Rd
index 2c2fe9b9eb..fad3c41429 100644
--- a/man/gt.Rd
+++ b/man/gt.Rd
@@ -5,7 +5,7 @@
 \title{Create a \pkg{gt} table object}
 \usage{
 gt(data, rowname_col = "rowname", groupname_col = "groupname",
-  rownames_to_stub = FALSE,
+  rownames_to_stub = FALSE, id = random_id(),
   stub_group.sep = getOption("gt.stub_group.sep", " - "))
 }
 \arguments{
@@ -20,6 +20,10 @@ group labels for generation of stub row groups.}
 \item{rownames_to_stub}{An option to take rownames from the input \code{data}
 table as row captions in the display table stub.}
 
+\item{id}{The table ID. By default, this will be a random ID as generated by
+the \code{\link[=random_id]{random_id()}} function. If set to \code{NULL} then no table ID will be
+applied.}
+
 \item{stub_group.sep}{The separator to use between consecutive group names (a
 possibility when providing \code{data} as a \code{grouped_df} with multiple groups)
 in the displayed stub row group label.}
@@ -44,7 +48,7 @@ of data in a table and the data in the \code{rowname_col} are unique labels
 (perhaps unique across the entire table or unique within groups).
 
 Row groups can also be created by passing a \code{grouped_df} to \code{gt()} by using
-the \code{dplyr::group_by()} function on the table data. In this way, two or more
+the \code{\link[dplyr:group_by]{dplyr::group_by()}} function on the table data. In this way, two or more
 columns of categorical data can be used to make row groups. The
 \code{stub_group.sep} argument allows for control in how the row group label will
 appear in the display table.
diff --git a/man/gt_latex_dependencies.Rd b/man/gt_latex_dependencies.Rd
index 9580081e6b..91e3af5c05 100644
--- a/man/gt_latex_dependencies.Rd
+++ b/man/gt_latex_dependencies.Rd
@@ -45,6 +45,7 @@ exibble %>% gt()
 \seealso{
 Other helper functions: \code{\link{cells_styles}},
   \code{\link{escape_latex}}, \code{\link{html}},
-  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}}
+  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/html.Rd b/man/html.Rd
index de978a5a55..825b04189a 100644
--- a/man/html.Rd
+++ b/man/html.Rd
@@ -40,6 +40,7 @@ tab_1 <-
 Other helper functions: \code{\link{cells_styles}},
   \code{\link{escape_latex}},
   \code{\link{gt_latex_dependencies}}, \code{\link{md}},
-  \code{\link{pct}}, \code{\link{px}}
+  \code{\link{pct}}, \code{\link{px}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/md.Rd b/man/md.Rd
index 4464d09bf5..0915b27b9b 100644
--- a/man/md.Rd
+++ b/man/md.Rd
@@ -39,6 +39,7 @@ tab_1 <-
 Other helper functions: \code{\link{cells_styles}},
   \code{\link{escape_latex}},
   \code{\link{gt_latex_dependencies}}, \code{\link{html}},
-  \code{\link{pct}}, \code{\link{px}}
+  \code{\link{pct}}, \code{\link{px}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/pct.Rd b/man/pct.Rd
index 1433a9511c..ac5c228815 100644
--- a/man/pct.Rd
+++ b/man/pct.Rd
@@ -18,6 +18,7 @@ Helper for providing a numeric value as percentage
 Other helper functions: \code{\link{cells_styles}},
   \code{\link{escape_latex}},
   \code{\link{gt_latex_dependencies}}, \code{\link{html}},
-  \code{\link{md}}, \code{\link{px}}
+  \code{\link{md}}, \code{\link{px}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/px.Rd b/man/px.Rd
index 027f7e2281..21e4404445 100644
--- a/man/px.Rd
+++ b/man/px.Rd
@@ -18,6 +18,7 @@ Helper for providing a numeric value as pixels value
 Other helper functions: \code{\link{cells_styles}},
   \code{\link{escape_latex}},
   \code{\link{gt_latex_dependencies}}, \code{\link{html}},
-  \code{\link{md}}, \code{\link{pct}}
+  \code{\link{md}}, \code{\link{pct}},
+  \code{\link{random_id}}
 }
 \concept{helper functions}
diff --git a/man/random_id.Rd b/man/random_id.Rd
new file mode 100644
index 0000000000..22b3ab5852
--- /dev/null
+++ b/man/random_id.Rd
@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/helpers.R
+\name{random_id}
+\alias{random_id}
+\title{Helper for creating a random \code{id} for a \pkg{gt} table}
+\usage{
+random_id(n = 10)
+}
+\arguments{
+\item{n}{The number of lowercase letters to use for the random ID.}
+}
+\description{
+This helper function is to be used with \code{id} argument of the \code{\link[=gt]{gt()}} function.
+The \code{id} option in \code{\link[=gt]{gt()}} uses \code{random_id()} by default however we can
+optionally supply a custom \code{id} value, or, use \code{NULL} for no ID at all.
+}
+\seealso{
+Other helper functions: \code{\link{cells_styles}},
+  \code{\link{escape_latex}},
+  \code{\link{gt_latex_dependencies}}, \code{\link{html}},
+  \code{\link{md}}, \code{\link{pct}}, \code{\link{px}}
+}
+\concept{helper functions}