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

@@ -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)

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()

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()
 }

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

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)

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) {