Use webshot to generate images of HTML tables (#257)

* Add the `gt_save_webshot()` function

* Modify roxygen documentation

* Modify switch statement

* Modify stop message

* Modify roxygen documentation

* Update help file using roxygen

* Modify `stop()` message

* Use the `gt_save_html()` fn with default options

* Remove jpeg options from `gtsave()`

* Add linebreaks to function signatures

* Add `zoom` and `expand` arguments to `gt_save_webshot()`

* Reverse slashes on Windows filesystems

* Add extra slash for file URI

* Modify the call to `webshot()`

* Modify roxygen documentation

* Refactor `switch()` statement

* Refactor conditional statement

* Modify `stop()` message

* Update help file using roxygen

* Pass `...` to saving methods

R/gtsave.R

@@ -2,18 +2,22 @@
 #'
 #' The `gtsave()` function makes it easy to save a \pkg{gt} table to a file. The
 #' function guesses the file type by the extension provided in the output
-#' filename, producing either an HTML, LaTeX, or RTF file.
+#' filename, producing either an HTML, LaTeX, RTF, PNG, or PDF file.
 #'
 #' Output filenames with either the `.html` or `.htm` extensions will produce an
 #' HTML document. In this case, we can pass a `TRUE` or `FALSE` value to the
 #' `inline_css` option to obtain an HTML document with inlined CSS styles (the
 #' default is `FALSE`). More details on CSS inlining are available at
 #' [as_raw_html()].
 #'
-#' If the output filename is either of `.tex`, `.ltx`, or `.rnw`, a LaTeX
-#' document is produced. An output filename of `.rtf` will generate an RTF
+#' If the output filename extension is either of `.tex`, `.ltx`, or `.rnw`, a
+#' LaTeX document is produced. An output filename of `.rtf` will generate an RTF
 #' document. The LaTeX and RTF saving function don't have any options to pass to
-#' `...`.
+#' the triple-dots.
+#'
+#' We can create an image file based on the HTML version of the `gt` table. With
+#' the filename extension `.png`, we get a PNG image file. A PDF document can be
+#' generated by using the `.pdf` extension.
 #'
 #' @param data A table object that is created using the [gt()] function.
 #' @param filename The file name to create on disk. Ensure that an extension
@@ -23,7 +27,9 @@
 #' @param ... All other options passed to the appropriate internal saving
 #'   function.
 #' @export
-gtsave <- function(data, filename, ...) {
+gtsave <- function(data,
+                   filename,
+                   ...) {
 
   # Input object validation
   stop_if_not_gt(data)
@@ -34,20 +40,26 @@ gtsave <- function(data, filename, ...) {
   # Stop function if a file extension is not provided
   if (file_ext == "") {
 
-    stop("A file extension is required in the provided filename.\n",
-         " * We can use `", filename, "` + either of `.html`/`.htm`, `.tex`/`.ltx`/`.rnw`, or `.rtf`",
+    stop("A file extension is required in the provided filename. We can use:\n",
+         " * `.html`/`.htm` (HTML file)\n",
+         " * `.tex`/`.ltx`/`.rnw` (LaTeX file)\n",
+         " * `.rtf` (RTF file)\n",
+         " * `.png` (PNG file)\n",
+         " * `.pdf` (PDF file)",
          call. = FALSE)
   }
 
   # Use the appropriate save function based
   # on the filename extension
   switch(file_ext,
-         htm = gt_save_html(data, filename, ...),
+          htm = ,
          html = gt_save_html(data, filename, ...),
-         ltx = gt_save_latex(data, filename, ...),
-         rnw = gt_save_latex(data, filename, ...),
-         tex = gt_save_latex(data, filename, ...),
-         rtf = gt_save_rtf(data, filename, ...),
+          ltx = ,
+          rnw = ,
+          tex = gt_save_latex(data, filename, ...),
+          rtf = gt_save_rtf(data, filename, ...),
+          png = ,
+          pdf = gt_save_webshot(data, filename, ...),
          {
            stop("The file extension used (`.", file_ext, "`) doesn't have an ",
                 "associated saving function.\n",
@@ -61,27 +73,73 @@ gtsave <- function(data, filename, ...) {
 #'
 #' @importFrom htmltools as.tags save_html HTML
 #' @noRd
-gt_save_html <- function(data, filename, ..., inline_css = FALSE) {
+gt_save_html <- function(data,
+                         filename,
+                         ...,
+                         inline_css = FALSE) {
 
   if (inline_css) {
 
     data %>%
       as_raw_html(inline_css = inline_css) %>%
       htmltools::HTML() %>%
-      htmltools::save_html(filename)
+      htmltools::save_html(filename, ...)
 
   } else {
 
     data %>%
       htmltools::as.tags() %>%
-      htmltools::save_html(filename)
+      htmltools::save_html(filename, ...)
+  }
+}
+
+#' Saving function for an image file via the webshot package
+#'
+#' @noRd
+gt_save_webshot <- function(data,
+                            filename,
+                            ...,
+                            zoom = 2,
+                            expand = 5) {
+
+  # Create a temporary file with the `html` extension
+  tempfile_ <- tempfile(fileext = ".html")
+
+  # Reverse slashes on Windows filesystems
+  tempfile_ <-
+    tempfile_ %>%
+    tidy_gsub("\\\\", "/")
+
+  # Save gt table as HTML using the `gt_save_html()` function
+  data %>% gt_save_html(filename = tempfile_)
+
+  # Saving an image requires the webshot package; if it's
+  # not present, stop with a message
+  if (!requireNamespace("webshot", quietly = TRUE)) {
+
+    stop("The `webshot` package is required for saving images of gt tables.",
+         call. = FALSE)
+
+  } else {
+
+    # Save the image in the working directory
+    webshot::webshot(
+      url = paste0("file:///", tempfile_),
+      file = filename,
+      selector = "table",
+      zoom = zoom,
+      expand = expand,
+      ...
+    )
   }
 }
 
 #' Saving function for a LaTeX file
 #'
 #' @noRd
-gt_save_latex <- function(data, filename, ...) {
+gt_save_latex <- function(data,
+                          filename,
+                          ...) {
 
   data %>%
     as_latex() %>%
@@ -91,14 +149,16 @@ gt_save_latex <- function(data, filename, ...) {
 #' Saving function for an RTF file
 #'
 #' @noRd
-gt_save_rtf <- function(data, filename, ...) {
+gt_save_rtf <- function(data,
+                        filename,
+                        ...) {
 
   data %>%
     as_rtf() %>%
     writeLines(con = filename)
 }
 
-#' Get the file extension from an input filename
+#' Get the lowercase extension from a filename
 #'
 #' @importFrom tools file_ext
 #' @noRd