Floating table

NEWS.md

@@ -1,5 +1,7 @@
 # gt (development version)
 
+* PDF output now defaults to a full-width floating environment using `tabular*` (@AronGullickson, #1588). Float position can be controlled by the `latex.tbl.pos` argument in `tab_options`. Quarto users can alternatively use the `tbl-pos` argument to control positioning. To use a `longtable` environment instead, use `tab_option(latex.use.longtable = TRUE)`.
+
 # gt 0.11.0
 
 ## New features

R/dt_options.R

@@ -252,4 +252,6 @@ dt_options_tbl <-
     "page_footer_height",                FALSE,  "page",             "value",   "0.5in",
     "quarto_disable_processing",         FALSE,  "quarto",           "logical", FALSE,
     "quarto_use_bootstrap",              FALSE,  "quarto",           "logical", FALSE,
+    "latex_use_longtable",               FALSE,  "latex",            "logical", FALSE,
+    "latex_tbl_pos",                     FALSE,  "latex",            "value",   "!t",
   )[-1, ]

R/export.R

@@ -702,7 +702,7 @@ as_latex <- function(data) {
   footer_component <- create_footer_component_l(data = data)
 
   # Create a LaTeX fragment for the ending tabular statement
-  table_end <- create_table_end_l()
+  table_end <- create_table_end_l(data = data)
 
   # If the `rmarkdown` package is available, use the
   # `latex_dependency()` function to load latex packages
@@ -718,25 +718,48 @@ as_latex <- function(data) {
   # Allow user to set a font-size
   fontsize_statement <- create_fontsize_statement_l(data = data)
 
+  # create wrapping environment
+  wrap_start_statement <- create_wrap_start_l(data = data)
+  wrap_end_statement <- create_wrap_end_l(data = data)
+
 
   # Compose the LaTeX table
-  knitr::asis_output(
-    paste0(
-      "\\begingroup\n",
-      table_width_statement,
-      fontsize_statement,
-      table_start,
-      heading_component,
-      columns_component,
-      body_component,
-      table_end,
-      footer_component,
-      "\\endgroup\n",
-      collapse = ""
-    ),
-    meta = latex_packages
-  )
-}
+  if (dt_options_get_value(data = data, option = "latex_use_longtable")) {
+    knitr::asis_output(
+      paste0(
+        wrap_start_statement,
+        table_width_statement,
+        fontsize_statement,
+        table_start,
+        heading_component,
+        columns_component,
+        body_component,
+        table_end,
+        footer_component,
+        wrap_end_statement,
+        collapse = ""
+      ),
+      meta = latex_packages
+    )
+  } else {
+    knitr::asis_output(
+      paste0(
+        wrap_start_statement,
+        heading_component,
+        table_width_statement,
+        fontsize_statement,
+        table_start,
+        columns_component,
+        body_component,
+        table_end,
+        footer_component,
+        wrap_end_statement,
+        collapse = ""
+      ),
+      meta = latex_packages
+    )
+  }
+  }
 
 #' Output a **gt** object as RTF
 #'

R/tab_create_modify.R

@@ -4409,6 +4409,24 @@ set_style.cells_source_notes <- function(loc, data, style) {
 #'   deactivated with `quarto.disable_processing = TRUE` (this option is `FALSE`
 #'   by default).
 #'
+#' @param latex.use.longtable
+#'
+#'   *Use longtable latex environment*
+#'
+#'   By default, tables produced using latex code will be embedded in the
+#'   `table` floating environment. Setting this parameter to `TRUE` will instead
+#'   use the `longtable` environment which will not float and may span multiple
+#'   pages.
+#'
+#' @param latex.tbl.pos
+#'
+#'   *Specify latex floating position*
+#'
+#'   The latex position indicator for a floating environment (e.g. "!t", "H"). It
+#'   should be specified without square brackets. Quarto users should instead
+#'   set the floating position within the code chunk argument `tbl-pos`. Table
+#'   will only float if longtable environment is set to `FALSE`.
+#'
 #' @return An object of class `gt_tbl`.
 #'
 #' @section Examples:
@@ -4726,7 +4744,9 @@ tab_options <- function(
     page.header.height = NULL,
     page.footer.height = NULL,
     quarto.use_bootstrap = NULL,
-    quarto.disable_processing = NULL
+    quarto.disable_processing = NULL,
+    latex.use.longtable = NULL,
+    latex.tbl.pos = NULL
 ) {
 
   # Perform input object validation

R/utils_render_latex.R

@@ -129,6 +129,20 @@ latex_group_row <- function(
   )
 }
 
+#' @noRd
+create_wrap_start_l <- function(data) {
+  tbl_pos = ifelse(check_quarto(),
+                   "",
+                   paste0("[",
+                          dt_options_get_value(data = data,
+                                               option = "latex_tbl_pos"),
+                          "]"))
+
+  ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
+         "\\begingroup\n",
+         paste0("\\begin{table}", tbl_pos, "\n"))
+}
+
 #' @noRd
 create_table_start_l <- function(data, colwidth_df) {
 
@@ -213,11 +227,41 @@ create_table_start_l <- function(data, colwidth_df) {
   if (dt_options_get_value(data = data, option = "table_width") != "auto")
     extra_sep <- "@{\\extracolsep{\\fill}}"
 
+  # determine string for table width if using tabular* environment
+  hdr_tabular <- ""
+  if(!dt_options_get_value(data = data, option = "latex_use_longtable")) {
+
+    # we need to use the extracolsep here for tabular* regardless of width
+    extra_sep <- '@{\\extracolsep{\\fill}}'
+    table_width <- dt_options_get_value(data = data, 'table_width')
+
+    if (endsWith(table_width, "%")) {
+
+      tw <- as.numeric(gsub('%', '', table_width))
+      hdr_tabular <- paste0("\\begin{tabular*}{", tw/100, "\\linewidth}{")
+
+    } else if (endsWith(table_width, "px")) {
+
+      width_in_pt <- 0.75 * convert_to_px(table_width)
+      hdr_tabular <- paste0("\\begin{tabular*}{", width_in_pt, "pt}{")
+
+    } else {
+
+      hdr_tabular <- "\\begin{tabular*}{\\linewidth}{"
+
+    }
+
+  }
+
   # Generate setup statements for table including default left
   # alignments and vertical lines for any stub columns
   paste0(
-    longtable_post_length,
-    "\\begin{longtable}{",
+    ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
+           longtable_post_length,
+           ""),
+    ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
+           "\\begin{longtable}{",
+           hdr_tabular),
     extra_sep,
     paste(col_defs, collapse = ""),
     "}\n",
@@ -295,9 +339,14 @@ create_heading_component_l <- function(data) {
     subtitle_row <- ""
   }
 
-  paste_between(
-    paste0(title_row, subtitle_row),
-    x_2 = c("\\caption*{\n", "\n} \\\\ \n")
+  paste0(
+    paste_between(
+      paste0(title_row, subtitle_row),
+      x_2 = c("\\caption*{\n", "\n}")
+    ),
+    ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
+           " \\\\ \n",
+           " \n")
   )
 }
 
@@ -922,15 +971,24 @@ summary_rows_for_group_l <- function(
 }
 
 #' @noRd
-create_table_end_l <- function() {
+create_table_end_l <- function(data) {
 
   paste0(
     "\\bottomrule\n",
-    "\\end{longtable}\n",
+    ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
+           "\\end{longtable}\n",
+           "\\end{tabular*}\n"),
     collapse = ""
   )
 }
 
+#' @noRd
+create_wrap_end_l <- function(data) {
+  ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
+         "\\endgroup\n",
+         "\\end{table}\n")
+}
+
 #' @noRd
 create_footer_component_l <- function(data) {
 
@@ -1275,7 +1333,9 @@ derive_table_width_statement_l <- function(data) {
   table_width <- dt_options_get_value(data = data, 'table_width')
 
   # Bookends are not required if a table width is not specified
-  if (table_width == 'auto') {
+  # of if using floating table
+  if (table_width == 'auto' ||
+      !dt_options_get_value(data = data, option = "latex_use_longtable")) {
 
     statement <- ''
 

tests/gt-examples/03-latex/latex-01-iris.Rmd

@@ -26,5 +26,6 @@ gt(iris) %>%
   ) %>%
   tab_source_note(
     source_note = md("The data were collected by *Anderson* (1935).")
-  )
+  ) %>%
+  tab_options(latex.use.longtable = TRUE)
 ```

tests/gt-examples/03-latex/latex-06-mtcars.Rmd

@@ -99,5 +99,6 @@ gt(mtcars, rownames_to_stub = TRUE) %>%
   cols_label(
     hp = md("*HP*"),
     qsec = "QMT, seconds"
-  )
+  ) %>%
+  tab_options(latex.use.longtable = TRUE)
 ```

tests/gt-examples/03-latex/latex-13-adding_footnotes.Rmd

@@ -35,7 +35,7 @@ gt(
   data = tbl,
   groupname_col = "date"
 ) %>%
-  tab_header(title = "The Table Title", subtitle = "The subtitle.") %>%
+  #tab_header(title = "The Table Title", subtitle = "The subtitle.") %>%
   tab_spanner(
     label = "values",
     columns = starts_with("value")
@@ -75,5 +75,6 @@ gt(
   tab_footnote(
     footnote = md("The `subtitle` can likewise get a footnote."),
     locations = cells_title(groups = "subtitle")
-  )
+  ) %>%
+  tab_options(latex.use.longtable = TRUE)
 ```