Add vertical and horizontal padding options (#882)

* Update gt_styles_default.scss * Add new `opt_*()` fns for padding * Update NAMESPACE * Update help files using roxygen * Update SCSS styles * Update dt_options.R * Simplify padding functions * Add several `*.padding.horizontal` args * Update helper-gt_attr_expectations.R * Update tab_options.Rd * Update documentation * Update documentation * Update _pkgdown.yml * Update documentation * Simplify steps interpretation * Make changes based on code review Co-authored-by: Joe Cheng <[email protected]>
rstudio · Feb 11, 2022 · 8a30632 · 8a30632
1 parent 2d77df6
commit 8a30632
Show file tree

Hide file tree

Showing 20 changed files with 477 additions and 36 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -85,10 +85,12 @@ export(opt_align_table_header)
 export(opt_all_caps)
 export(opt_css)
 export(opt_footnote_marks)
+export(opt_horizontal_padding)
 export(opt_row_striping)
 export(opt_table_font)
 export(opt_table_lines)
 export(opt_table_outline)
+export(opt_vertical_padding)
 export(pct)
 export(px)
 export(random_id)

diff --git a/R/dt_options.R b/R/dt_options.R
@@ -84,6 +84,7 @@ dt_options_tbl <-
     "heading_subtitle_font_size",         TRUE,  "heading",          "px",      "85%",
     "heading_subtitle_font_weight",       TRUE,  "heading",          "value",   "initial",
     "heading_padding",                    TRUE,  "heading",          "px",      "4px",
+    "heading_padding_horizontal",         TRUE,  "heading",          "px",      "5px",
     "heading_border_bottom_style",        TRUE,  "heading",          "value",   "solid",
     "heading_border_bottom_width",        TRUE,  "heading",          "px",      "2px",
     "heading_border_bottom_color",        TRUE,  "heading",          "value",   "#D3D3D3",
@@ -95,6 +96,7 @@ dt_options_tbl <-
     "column_labels_font_weight",          TRUE,  "column_labels",    "value",   "normal",
     "column_labels_text_transform",       TRUE,  "column_labels",    "value",   "inherit",
     "column_labels_padding",              TRUE,  "column_labels",    "px",      "5px",
+    "column_labels_padding_horizontal",   TRUE,  "column_labels",    "px",      "5px",
     "column_labels_vlines_style",         TRUE,  "table_body",       "value",   "none",
     "column_labels_vlines_width",         TRUE,  "table_body",       "px",      "1px",
     "column_labels_vlines_color",         TRUE,  "table_body",       "value",   "#D3D3D3",
@@ -113,6 +115,7 @@ dt_options_tbl <-
     "row_group_font_weight",              TRUE,  "row_group",        "value",   "initial",
     "row_group_text_transform",           TRUE,  "row_group",        "value",   "inherit",
     "row_group_padding",                  TRUE,  "row_group",        "px",      "8px",
+    "row_group_padding_horizontal",       TRUE,  "row_group",        "px",      "5px",
     "row_group_border_top_style",         TRUE,  "row_group",        "value",   "solid",
     "row_group_border_top_width",         TRUE,  "row_group",        "px",      "2px",
     "row_group_border_top_color",         TRUE,  "row_group",        "value",   "#D3D3D3",
@@ -140,6 +143,7 @@ dt_options_tbl <-
     "table_body_border_bottom_width",     TRUE,  "table_body",       "px",      "2px",
     "table_body_border_bottom_color",     TRUE,  "table_body",       "value",   "#D3D3D3",
     "data_row_padding",                   TRUE,  "data_row",         "px",      "8px",
+    "data_row_padding_horizontal",        TRUE,  "data_row",         "px",      "5px",
     "stub_background_color",              TRUE,  "stub",             "value",   NA_character_,
     "stub_font_size",                     TRUE,  "stub",             "px",      "100%",
     "stub_font_weight",                   TRUE,  "stub",             "value",   "initial",
@@ -155,19 +159,22 @@ dt_options_tbl <-
     "stub_row_group_border_width",        TRUE,  "stub",             "px",      "2px",
     "stub_row_group_border_color",        TRUE,  "stub",             "value",   "#D3D3D3",
     "summary_row_padding",                TRUE,  "summary_row",      "px",      "8px",
+    "summary_row_padding_horizontal",     TRUE,  "summary_row",      "px",      "5px",
     "summary_row_background_color",       TRUE,  "summary_row",      "value",   NA_character_,
     "summary_row_text_transform",         TRUE,  "summary_row",      "value",   "inherit",
     "summary_row_border_style",           TRUE,  "summary_row",      "value",   "solid",
     "summary_row_border_width",           TRUE,  "summary_row",      "px",      "2px",
     "summary_row_border_color",           TRUE,  "summary_row",      "value",   "#D3D3D3",
     "grand_summary_row_padding",          TRUE,  "grand_summary_row", "px",     "8px",
+    "grand_summary_row_padding_horizontal",TRUE, "grand_summary_row", "px",     "5px",
     "grand_summary_row_background_color", TRUE,  "grand_summary_row", "value",  NA_character_,
     "grand_summary_row_text_transform",   TRUE,  "grand_summary_row", "value",  "inherit",
     "grand_summary_row_border_style",     TRUE,  "grand_summary_row", "value",  "double",
     "grand_summary_row_border_width",     TRUE,  "grand_summary_row", "px",     "6px",
     "grand_summary_row_border_color",     TRUE,  "grand_summary_row", "value",  "#D3D3D3",
     "footnotes_font_size",                TRUE,  "footnotes",        "px",      "90%",
     "footnotes_padding",                  TRUE,  "footnotes",        "px",      "4px",
+    "footnotes_padding_horizontal",       TRUE,  "footnotes",        "px",      "5px",
     "footnotes_background_color",         TRUE,  "footnotes",        "value",   NA_character_,
     "footnotes_margin",                   TRUE,  "footnotes",        "px",      "0px",
     "footnotes_border_bottom_style",      TRUE,  "footnotes",        "value",   "none",
@@ -180,6 +187,7 @@ dt_options_tbl <-
     "footnotes_multiline",               FALSE,  "footnotes",        "logical", TRUE,
     "footnotes_sep",                     FALSE,  "footnotes",        "value",   " ",
     "source_notes_padding",               TRUE,  "source_notes",     "px",      "4px",
+    "source_notes_padding_horizontal",    TRUE,  "source_notes",     "px",      "5px",
     "source_notes_background_color",      TRUE,  "source_notes",     "value",   NA_character_,
     "source_notes_font_size",             TRUE,  "source_notes",     "px",      "90%",
     "source_notes_border_bottom_style",   TRUE,  "source_notes",     "value",   "none",

diff --git a/R/opts.R b/R/opts.R
@@ -224,6 +224,196 @@ opt_align_table_header <- function(data,
   )
 }
 
+#' Option to expand or contract vertical padding
+#'
+#' @description
+#' Increase or decrease the vertical padding throughout all locations of a
+#' **gt** table by use of a `scale` factor, which here is defined by a real
+#' number between `0` and `3`. This function serves as a shortcut for setting
+#' the following eight options in [tab_options()]:
+#'
+#' - `heading.padding`
+#' - `column_labels.padding`
+#' - `data_row.padding`
+#' - `row_group.padding`
+#' - `summary_row.padding`
+#' - `grand_summary_row.padding`
+#' - `footnotes.padding`
+#' - `source_notes.padding`
+#'
+#' @inheritParams fmt_number
+#' @param scale A scale factor by which the vertical padding will be adjusted.
+#'   Must be a number between `0` and `3`.
+#'
+#' @return An object of class `gt_tbl`.
+#'
+#' @examples
+#' # Use `exibble` to create a gt table with
+#' # a number of table parts added; contract
+#' # the vertical padding across the entire
+#' # table with `opt_vertical_padding()`
+#' tab_1 <-
+#'   exibble %>%
+#'   gt(rowname_col = "row", groupname_col = "group") %>%
+#'   summary_rows(
+#'     groups = "grp_a",
+#'     columns = c(num, currency),
+#'     fns = list(
+#'       min = ~min(., na.rm = TRUE),
+#'       max = ~max(., na.rm = TRUE)
+#'     )) %>%
+#'   grand_summary_rows(
+#'     columns = currency,
+#'     fns = list(
+#'       total = ~sum(., na.rm = TRUE)
+#'     )) %>%
+#'   tab_source_note(source_note = "This is a source note.") %>%
+#'   tab_footnote(
+#'     footnote = "This is a footnote.",
+#'     locations = cells_body(columns = 1, rows = 1)
+#'   ) %>%
+#'   tab_header(
+#'     title = "The title of the table",
+#'     subtitle = "The table's subtitle"
+#'   ) %>%
+#'   opt_vertical_padding(scale = 0.25)
+#'
+#' @section Figures:
+#' \if{html}{\figure{man_opt_vertical_padding_1.png}{options: width=100\%}}
+#'
+#' @family Table Option Functions
+#' @section Function ID:
+#' 9-4
+#'
+#' @export
+opt_vertical_padding <- function(data,
+                                 scale = 1) {
+
+  option_value_list <-
+    get_padding_option_value_list(
+      scale = scale,
+      type = "vertical"
+    )
+
+  tab_options_multi(
+    data = data,
+    options = option_value_list
+  )
+}
+
+#' Option to expand or contract horizontal padding
+#'
+#' @description
+#' Increase or decrease the horizontal padding throughout all locations of a
+#' **gt** table by use of a `scale` factor, which here is defined by a real
+#' number between `0` and `3`. This function serves as a shortcut for setting
+#' the following eight options in [tab_options()]:
+#'
+#' - `heading.padding.horizontal`
+#' - `column_labels.padding.horizontal`
+#' - `data_row.padding.horizontal`
+#' - `row_group.padding.horizontal`
+#' - `summary_row.padding.horizontal`
+#' - `grand_summary_row.padding.horizontal`
+#' - `footnotes.padding.horizontal`
+#' - `source_notes.padding.horizontal`
+#'
+#' @inheritParams fmt_number
+#' @param scale A scale factor by which the horizontal padding will be adjusted.
+#'   Must be a number between `0` and `3`.
+#'
+#' @return An object of class `gt_tbl`.
+#'
+#' @examples
+#' # Use `exibble` to create a gt table with
+#' # a number of table parts added; expand
+#' # the horizontal padding across the entire
+#' # table with `opt_horizontal_padding()`
+#' tab_1 <-
+#'   exibble %>%
+#'   gt(rowname_col = "row", groupname_col = "group") %>%
+#'   summary_rows(
+#'     groups = "grp_a",
+#'     columns = c(num, currency),
+#'     fns = list(
+#'       min = ~min(., na.rm = TRUE),
+#'       max = ~max(., na.rm = TRUE)
+#'     )) %>%
+#'   grand_summary_rows(
+#'     columns = currency,
+#'     fns = list(
+#'       total = ~sum(., na.rm = TRUE)
+#'     )) %>%
+#'   tab_source_note(source_note = "This is a source note.") %>%
+#'   tab_footnote(
+#'     footnote = "This is a footnote.",
+#'     locations = cells_body(columns = 1, rows = 1)
+#'   ) %>%
+#'   tab_header(
+#'     title = "The title of the table",
+#'     subtitle = "The table's subtitle"
+#'   ) %>%
+#'   opt_horizontal_padding(scale = 3)
+#'
+#' @section Figures:
+#' \if{html}{\figure{man_opt_horizontal_padding_1.png}{options: width=100\%}}
+#'
+#' @family Table Option Functions
+#' @section Function ID:
+#' 9-5
+#'
+#' @export
+opt_horizontal_padding <- function(data,
+                                   scale = 1) {
+
+  option_value_list <-
+    get_padding_option_value_list(
+      scale = scale,
+      type = "horizontal"
+    )
+
+  tab_options_multi(
+    data = data,
+    options = option_value_list
+  )
+}
+
+get_padding_option_value_list <- function(scale, type) {
+
+  # Stop if `scale` is beyond an acceptable range
+  if (scale < 0 | scale > 3) {
+    stop(
+      "The value provided for `scale` (", scale, ") must be between `0` and `3`.",
+      call. = FALSE
+    )
+  }
+
+  pattern <- if (type == "vertical") "_padding" else  "_padding_horizontal"
+
+  # Get the padding parameters from `dt_options_tbl` that relate
+  # to the `type` (either vertical or horizontal padding)
+  padding_params <-
+    dt_options_tbl %>%
+    dplyr::filter(grepl(paste0(pattern, "$"), parameter)) %>%
+    dplyr::pull(parameter)
+
+  padding_options <-
+    dt_options_tbl %>%
+    dplyr::filter(parameter %in% padding_params) %>%
+    dplyr::select(parameter, value) %>%
+    dplyr::mutate(
+      parameter = gsub(pattern, gsub("_", ".", pattern, fixed = TRUE), parameter, fixed = TRUE)
+    ) %>%
+    dplyr::mutate(value = unlist(value)) %>%
+    dplyr::mutate(px = as.numeric(gsub("px", "", value))) %>%
+    dplyr::mutate(px = px * scale)
+
+  create_option_value_list(
+    padding_options$parameter,
+    paste0(padding_options$px, "px")
+  )
+}
+
 #' Option to use all caps in select table locations
 #'
 #' @description
@@ -283,7 +473,7 @@ opt_align_table_header <- function(data,
 #'
 #' @family Table Option Functions
 #' @section Function ID:
-#' 9-4
+#' 9-6
 #'
 #' @export
 opt_all_caps <- function(data,
@@ -385,7 +575,7 @@ opt_all_caps <- function(data,
 #'
 #' @family Table Option Functions
 #' @section Function ID:
-#' 9-5
+#' 9-7
 #'
 #' @export
 opt_table_lines <- function(data,
@@ -475,7 +665,7 @@ opt_table_lines <- function(data,
 #'
 #' @family Table Option Functions
 #' @section Function ID:
-#' 9-6
+#' 9-8
 #'
 #' @export
 opt_table_outline <- function(data,
@@ -613,7 +803,7 @@ opt_table_outline <- function(data,
 #'
 #' @family Table Option Functions
 #' @section Function ID:
-#' 9-7
+#' 9-9
 #'
 #' @export
 opt_table_font <- function(data,
@@ -737,7 +927,7 @@ opt_table_font <- function(data,
 #'
 #' @family Table Option Functions
 #' @section Function ID:
-#' 9-8
+#' 9-10
 #'
 #' @export
 opt_css <- function(data,

diff --git a/R/tab_create_modify.R b/R/tab_create_modify.R
@@ -1482,6 +1482,14 @@ set_style.cells_source_notes <- function(loc, data, style) {
 #'   (`data_row.padding`), in summary rows (`summary_row.padding` or
 #'   `grand_summary_row.padding`), or in the footnotes and source notes
 #'   (`footnotes.padding` and `source_notes.padding`).
+#' @param heading.padding.horizontal,column_labels.padding.horizontal,data_row.padding.horizontal,row_group.padding.horizontal,summary_row.padding.horizontal,grand_summary_row.padding.horizontal,footnotes.padding.horizontal,source_notes.padding.horizontal
+#'   The amount of horizontal padding to incorporate in the `heading` (title and
+#'   subtitle), the `column_labels` (this includes the column spanners), the row
+#'   group labels (`row_group.padding.horizontal`), in the body/stub rows
+#'   (`data_row.padding`), in summary rows (`summary_row.padding.horizontal` or
+#'   `grand_summary_row.padding.horizontal`), or in the footnotes and source
+#'   notes (`footnotes.padding.horizontal` and
+#'   `source_notes.padding.horizontal`).
 #' @param table.border.top.style,table.border.top.width,table.border.top.color,table.border.right.style,table.border.right.width,table.border.right.color,table.border.bottom.style,table.border.bottom.width,table.border.bottom.color,table.border.left.style,table.border.left.width,table.border.left.color
 #'   The style, width, and color properties of the table's absolute top and
 #'   absolute bottom borders.
@@ -1720,6 +1728,7 @@ tab_options <- function(data,
                         heading.subtitle.font.size = NULL,
                         heading.subtitle.font.weight = NULL,
                         heading.padding = NULL,
+                        heading.padding.horizontal = NULL,
                         heading.border.bottom.style = NULL,
                         heading.border.bottom.width = NULL,
                         heading.border.bottom.color = NULL,
@@ -1731,6 +1740,7 @@ tab_options <- function(data,
                         column_labels.font.weight = NULL,
                         column_labels.text_transform = NULL,
                         column_labels.padding = NULL,
+                        column_labels.padding.horizontal = NULL,
                         column_labels.vlines.style = NULL,
                         column_labels.vlines.width = NULL,
                         column_labels.vlines.color = NULL,
@@ -1749,6 +1759,7 @@ tab_options <- function(data,
                         row_group.font.weight = NULL,
                         row_group.text_transform = NULL,
                         row_group.padding = NULL,
+                        row_group.padding.horizontal = NULL,
                         row_group.border.top.style = NULL,
                         row_group.border.top.width = NULL,
                         row_group.border.top.color = NULL,
@@ -1789,21 +1800,25 @@ tab_options <- function(data,
                         stub_row_group.border.width = NULL,
                         stub_row_group.border.color = NULL,
                         data_row.padding = NULL,
+                        data_row.padding.horizontal = NULL,
                         summary_row.background.color = NULL,
                         summary_row.text_transform = NULL,
                         summary_row.padding = NULL,
+                        summary_row.padding.horizontal = NULL,
                         summary_row.border.style = NULL,
                         summary_row.border.width = NULL,
                         summary_row.border.color = NULL,
                         grand_summary_row.background.color = NULL,
                         grand_summary_row.text_transform = NULL,
                         grand_summary_row.padding = NULL,
+                        grand_summary_row.padding.horizontal = NULL,
                         grand_summary_row.border.style = NULL,
                         grand_summary_row.border.width = NULL,
                         grand_summary_row.border.color = NULL,
                         footnotes.background.color = NULL,
                         footnotes.font.size = NULL,
                         footnotes.padding = NULL,
+                        footnotes.padding.horizontal = NULL,
                         footnotes.border.bottom.style = NULL,
                         footnotes.border.bottom.width = NULL,
                         footnotes.border.bottom.color = NULL,
@@ -1816,6 +1831,7 @@ tab_options <- function(data,
                         source_notes.background.color = NULL,
                         source_notes.font.size = NULL,
                         source_notes.padding = NULL,
+                        source_notes.padding.horizontal = NULL,
                         source_notes.border.bottom.style = NULL,
                         source_notes.border.bottom.width = NULL,
                         source_notes.border.bottom.color = NULL,

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -173,6 +173,8 @@ reference:
     - opt_footnote_marks
     - opt_row_striping
     - opt_align_table_header
+    - opt_vertical_padding
+    - opt_horizontal_padding
     - opt_all_caps
     - opt_table_lines
     - opt_table_outline