Merge pull request #1051 from billdenney/fix-1048

Add `tab_caption()`

NAMESPACE

@@ -102,6 +102,7 @@ export(pct)
 export(px)
 export(random_id)
 export(render_gt)
+export(rm_caption)
 export(rm_footnotes)
 export(rm_header)
 export(rm_source_notes)
@@ -116,6 +117,7 @@ export(sub_small_vals)
 export(sub_values)
 export(sub_zero)
 export(summary_rows)
+export(tab_caption)
 export(tab_footnote)
 export(tab_header)
 export(tab_options)

R/dt_options.R

@@ -41,7 +41,7 @@ dt_options_tbl <-
     "container_overflow_x",              FALSE,  "container",        "overflow","auto",
     "container_overflow_y",              FALSE,  "container",        "overflow","auto",
     "table_id",                          FALSE,  "table",            "value",   NA_character_,
-    "table_caption",                     FALSE,  "table",            "value",   NULL,
+    "table_caption",                     FALSE,  "table",            "value",   NA_character_,
     "table_width",                        TRUE,  "table",            "px",      "auto",
     "table_layout",                       TRUE,  "table",            "value",   "fixed",
     "table_margin_left",                  TRUE,  "table",            "px",      "auto",

R/gt.R

@@ -30,8 +30,8 @@
 #'   group labels for generation of stub row groups. If the input `data` table
 #'   has the `grouped_df` class (through use of the [dplyr::group_by()] function
 #'   or associated `group_by*()` functions) then any input here is ignored.
-#' @param caption An optional table caption to use for cross-referencing
-#'   in R Markdown documents and **bookdown** book projects.
+#' @param caption An optional table caption to use for cross-referencing in R
+#'   Markdown, Quarto, or **bookdown**.
 #' @param rownames_to_stub An option to take rownames from the input `data`
 #'   table as row captions in the display table stub.
 #' @param auto_align Optionally have column data be aligned depending on the
@@ -182,11 +182,7 @@ gt <- function(
       )
   }
 
-  # Add any user-defined table caption to the `table_id` parameter
-  # TODO: consider whether this might take a string or a logical (to say that
-  # we'll use the header from `tab_header` as the table caption); this might
-  # require some more thought still because a `caption` arg might also be
-  # sensible in `tab_header`
+  # Add any user-defined table caption to the `table_caption` parameter
   if (!is.null(caption)) {
 
     data <-

R/tab_create_modify.R

@@ -1379,6 +1379,62 @@ tab_source_note <- function(
   )
 }
 
+#' Add a table caption
+#'
+#' @description
+#' Add a caption to a **gt** table, which is handled specially for a table
+#' within an R Markdown, Quarto, or **bookdown** context. The addition of
+#' captions makes tables cross-referencing across the containing document. The
+#' caption location (i.e., top, bottom, margin) is handled at the document level
+#' in each of these system.
+#'
+#' @inheritParams fmt_number
+#' @param caption The table caption to use for cross-referencing in R Markdown,
+#'   Quarto, or **bookdown**.
+#'
+#' @return An object of class `gt_tbl`.
+#'
+#' @section Examples:
+#'
+#' Use [`gtcars`] to create a **gt** table. Add a header part with the
+#' [tab_header()] function, and, add a caption as well with `tab_caption()`.
+#'
+#' ```r
+#' gtcars %>%
+#'   dplyr::select(mfr, model, msrp) %>%
+#'   dplyr::slice(1:5) %>%
+#'   gt() %>%
+#'   tab_header(
+#'     title = md("Data listing from **gtcars**"),
+#'     subtitle = md("`gtcars` is an R dataset")
+#'   ) %>%
+#'   tab_caption(caption = md("**gt** table example."))
+#' ```
+#'
+#' \if{html}{\out{
+#' `r man_get_image_tag(file = "man_tab_caption_1.png")`
+#' }}
+#'
+#' @family part creation/modification functions
+#' @section Function ID:
+#' 2-9
+#'
+#' @export
+tab_caption <- function(
+    data,
+    caption
+) {
+
+  # Perform input object validation
+  stop_if_not_gt(data = data)
+
+  dt_options_set_value(
+    data = data,
+    option = "table_caption",
+    value = caption
+  )
+}
+
 #' Add custom styles to one or more cells
 #'
 #' @description
@@ -1511,7 +1567,7 @@ tab_source_note <- function(
 #'
 #' @family part creation/modification functions
 #' @section Function ID:
-#' 2-9
+#' 2-10
 #'
 #' @seealso [cell_text()], [cell_fill()], and [cell_borders()] as helpers for
 #'   defining custom styles and [cells_body()] as one of many useful helper
@@ -2200,7 +2256,7 @@ set_style.cells_source_notes <- function(loc, data, style) {
 #'
 #' @family part creation/modification functions
 #' @section Function ID:
-#' 2-10
+#' 2-11
 #'
 #' @export
 tab_options <- function(

R/tab_remove.R

@@ -614,3 +614,74 @@ rm_source_notes <- function(
 
   data
 }
+
+
+#' Remove the stubhead label
+#'
+#' @description
+#' We can easily remove the caption text from a **gt** table with
+#' `rm_caption()`. The caption may exist if it were set through the [gt()]
+#' `caption` argument or via [tab_caption()].
+#'
+#' This function for removal is useful if you have received a **gt** table
+#' (perhaps through an API that returns **gt** objects) but would prefer that
+#' the table not have a caption at all. This function is safe to use even if
+#' there is no table caption set in the input `gt_tbl` object.
+#'
+#' @param data A table object of class `gt_tbl`.
+#'
+#' @return An object of class `gt_tbl`.
+#'
+#' @section Examples:
+#'
+#' Use [`gtcars`] to create a **gt** table. Add a header part with the
+#' [tab_header()] function, and, add a caption as well with [tab_caption()].
+#'
+#' ```r
+#' gt_tbl <-
+#'   gtcars %>%
+#'   dplyr::select(mfr, model, msrp) %>%
+#'   dplyr::slice(1:5) %>%
+#'   gt() %>%
+#'   tab_header(
+#'     title = md("Data listing from **gtcars**"),
+#'     subtitle = md("`gtcars` is an R dataset")
+#'   ) %>%
+#'   tab_caption(caption = md("**gt** table example."))
+#'
+#' gt_tbl
+#' ```
+#'
+#' \if{html}{\out{
+#' `r man_get_image_tag(file = "man_rm_caption_1.png")`
+#' }}
+#'
+#' If you decide that you don't want the caption in the `gt_tbl` object,
+#' it can be removed with the `rm_caption()` function.
+#'
+#' ```r
+#' rm_caption(data = gt_tbl)
+#' ```
+#'
+#' \if{html}{\out{
+#' `r man_get_image_tag(file = "man_rm_caption_2.png")`
+#' }}
+#'
+#' @family part removal functions
+#' @section Function ID:
+#' 6-6
+#'
+#' @export
+rm_caption <- function(data) {
+
+  # Perform input object validation
+  stop_if_not_gt(data = data)
+
+  # Reset the `table_caption` parameter value to an NA value inside
+  # the `_options` component of the `gt_tbl` object
+  dt_options_set_value(
+    data = data,
+    option = "table_caption",
+    value = NA_character_
+  )
+}

R/utils_render_html.R

@@ -153,7 +153,7 @@ create_caption_component_h <- function(data) {
   # Create the table caption if available
   table_caption <- dt_options_get_value(data = data, option = "table_caption")
 
-  if (!is.null(table_caption)) {
+  if (!all(is.na(table_caption))) {
 
     table_caption <- process_text(table_caption, context = "html")
 
@@ -179,7 +179,7 @@ create_caption_component_h <- function(data) {
       # <caption> tag, which bookdown searches for), and then resume protection.
 
       htmltools::HTML(paste0(
-        "<!--/html_preserve--><caption>",
+        "<!--/html_preserve--><caption class='gt_caption'>",
         table_caption,
         "</caption><!--html_preserve-->"
       ))

inst/css/gt_styles_default.scss

@@ -37,6 +37,11 @@
     border-right-color: $heading_border_lr_color; // heading.border.lr.color
   }
 
+  .gt_caption {
+    padding-top: 4px;
+    padding-bottom: 4px;
+  }
+
   .gt_title {
     color: font-color($heading_background_color);
     font-size: $heading_title_font_size; // heading.title.font.size