From 5d53c53befb031ec821b9e501010cbddeff4e99f Mon Sep 17 00:00:00 2001 From: Carson Date: Thu, 5 Oct 2023 16:45:41 -0500 Subject: [PATCH 1/8] Make save_html() an S3 generic method --- NAMESPACE | 1 + R/html_print.R | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/NAMESPACE b/NAMESPACE index 8f91cb8e..957d86d4 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -30,6 +30,7 @@ S3method(print,shiny.tag) S3method(print,shiny.tag.env) S3method(print,shiny.tag.list) S3method(print,shiny.tag.query) +S3method(save_html,default) S3method(str,shiny.tag.env) export("htmlDependencies<-") export(HTML) diff --git a/R/html_print.R b/R/html_print.R index c257514f..a5142b1d 100644 --- a/R/html_print.R +++ b/R/html_print.R @@ -71,6 +71,11 @@ html_print <- function(html, background = "white", viewer = getOption("viewer", #' #' @export save_html <- function(html, file, background = "white", libdir = "lib", lang = "en") { + UseMethod("save_html") +} + +#' @export +save_html.default <- function(html, file, background = "white", libdir = "lib", lang = "en") { force(html) force(background) force(libdir) From de30ded0b02f127b3b551d5665f25b85e5821019 Mon Sep 17 00:00:00 2001 From: Carson Date: Fri, 6 Oct 2023 10:26:52 -0500 Subject: [PATCH 2/8] Make the generic...more generic --- R/html_print.R | 9 +++++---- man/save_html.Rd | 5 ++++- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/R/html_print.R b/R/html_print.R index a5142b1d..7371b86e 100644 --- a/R/html_print.R +++ b/R/html_print.R @@ -59,21 +59,22 @@ html_print <- function(html, background = "white", viewer = getOption("viewer", #' Save an HTML object to a file #' -#' Save the specified HTML object to a file, copying all of it's -#' dependencies to the directory specified via `libdir`. +#' An S3 generic method for saving an HTML-like object to a file. The default +#' method copies dependency files to the directory specified via `libdir`. #' #' @param html HTML content to print -#' @param background Background color for web page #' @param file File path or connection. If a file path containing a #' sub-directory, the sub-directory must already exist. +#' @param background Background color for web page #' @param libdir Directory to copy dependencies to #' @param lang Value of the `` `lang` attribute #' #' @export -save_html <- function(html, file, background = "white", libdir = "lib", lang = "en") { +save_html <- function(html, file, ...) { UseMethod("save_html") } +#' @rdname save_html #' @export save_html.default <- function(html, file, background = "white", libdir = "lib", lang = "en") { force(html) diff --git a/man/save_html.Rd b/man/save_html.Rd index 526b0767..a2861c32 100644 --- a/man/save_html.Rd +++ b/man/save_html.Rd @@ -2,9 +2,12 @@ % Please edit documentation in R/html_print.R \name{save_html} \alias{save_html} +\alias{save_html.default} \title{Save an HTML object to a file} \usage{ -save_html(html, file, background = "white", libdir = "lib", lang = "en") +save_html(html, file, ...) + +\method{save_html}{default}(html, file, background = "white", libdir = "lib", lang = "en") } \arguments{ \item{html}{HTML content to print} From 47b03a12b8c2d61618ce96b19ce6165c5300b7b4 Mon Sep 17 00:00:00 2001 From: cpsievert Date: Fri, 6 Oct 2023 15:30:05 +0000 Subject: [PATCH 3/8] `devtools::document()` (GitHub Actions) --- man/save_html.Rd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/man/save_html.Rd b/man/save_html.Rd index a2861c32..c96a97f8 100644 --- a/man/save_html.Rd +++ b/man/save_html.Rd @@ -22,6 +22,6 @@ sub-directory, the sub-directory must already exist.} \item{lang}{Value of the \verb{} \code{lang} attribute} } \description{ -Save the specified HTML object to a file, copying all of it's -dependencies to the directory specified via \code{libdir}. +An S3 generic method for saving an HTML-like object to a file. The default +method copies dependency files to the directory specified via \code{libdir}. } From 5ae307ef4461fb75e0bc0f13a263d2f8f63c57fe Mon Sep 17 00:00:00 2001 From: Carson Date: Fri, 6 Oct 2023 10:48:20 -0500 Subject: [PATCH 4/8] Bump version; update news --- DESCRIPTION | 2 +- NEWS.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 4e840f43..1b3b6ce9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: htmltools Title: Tools for HTML -Version: 0.5.6.9000 +Version: 0.5.6.9001 Authors@R: c( person("Joe", "Cheng", , "joe@posit.co", role = "aut"), person("Carson", "Sievert", , "carson@posit.co", role = c("aut", "cre"), diff --git a/NEWS.md b/NEWS.md index 36f5bb78..e5d5eeca 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,9 @@ # htmltools (development version) +## New Features + +* `save_html()` is now an S3 generic, allowing for HTML-like objects to be saved as an HTML file. (#411) + ## Improvements * Fill items no longer set `overflow: auto` or `width: 100%` by default. (#401) From 5df5bbf688e45d02e8e8c519a2820df67963842d Mon Sep 17 00:00:00 2001 From: Carson Date: Fri, 6 Oct 2023 14:57:46 -0500 Subject: [PATCH 5/8] Add ... to method signature (and throw if they're non-empty) --- R/html_print.R | 4 +++- tests/testthat/test-print.R | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/R/html_print.R b/R/html_print.R index 7371b86e..d4eb7d19 100644 --- a/R/html_print.R +++ b/R/html_print.R @@ -76,7 +76,9 @@ save_html <- function(html, file, ...) { #' @rdname save_html #' @export -save_html.default <- function(html, file, background = "white", libdir = "lib", lang = "en") { +save_html.default <- function(html, file, background = "white", libdir = "lib", lang = "en", ...) { + rlang::check_dots_empty() + force(html) force(background) force(libdir) diff --git a/tests/testthat/test-print.R b/tests/testthat/test-print.R index 88d2fa7e..3239dbf6 100644 --- a/tests/testthat/test-print.R +++ b/tests/testthat/test-print.R @@ -99,3 +99,13 @@ test_that("save_html() can write to a file connection", { grepl("

Howdy

", paste(readLines(f), collapse = " ")) ) }) + +test_that("save_html.default() throws when undefined arguments are provided", { + expect_error( + save_html(div(), tempfile(), foo = "bar") + ) + + expect_error( + save_html(div(), tempfile(), background = "white", libdir = "lib", lang = "en", "bar") + ) +}) From e45010418e42e1c3728c306c31b7990e91e9bb64 Mon Sep 17 00:00:00 2001 From: cpsievert Date: Fri, 6 Oct 2023 20:02:18 +0000 Subject: [PATCH 6/8] `devtools::document()` (GitHub Actions) --- man/save_html.Rd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/save_html.Rd b/man/save_html.Rd index c96a97f8..a572d6fd 100644 --- a/man/save_html.Rd +++ b/man/save_html.Rd @@ -7,7 +7,7 @@ \usage{ save_html(html, file, ...) -\method{save_html}{default}(html, file, background = "white", libdir = "lib", lang = "en") +\method{save_html}{default}(html, file, background = "white", libdir = "lib", lang = "en", ...) } \arguments{ \item{html}{HTML content to print} From f5caf7ebd751111685d57e2c19b56edcd87738fd Mon Sep 17 00:00:00 2001 From: Carson Date: Fri, 6 Oct 2023 15:07:11 -0500 Subject: [PATCH 7/8] Clean Rd docs --- R/html_print.R | 9 +++++---- man/save_html.Rd | 10 ++++++---- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/R/html_print.R b/R/html_print.R index d4eb7d19..c6943953 100644 --- a/R/html_print.R +++ b/R/html_print.R @@ -62,12 +62,10 @@ html_print <- function(html, background = "white", viewer = getOption("viewer", #' An S3 generic method for saving an HTML-like object to a file. The default #' method copies dependency files to the directory specified via `libdir`. #' -#' @param html HTML content to print +#' @param html HTML content to print. #' @param file File path or connection. If a file path containing a #' sub-directory, the sub-directory must already exist. -#' @param background Background color for web page -#' @param libdir Directory to copy dependencies to -#' @param lang Value of the `` `lang` attribute +#' @param ... Further arguments passed to other methods. #' #' @export save_html <- function(html, file, ...) { @@ -75,6 +73,9 @@ save_html <- function(html, file, ...) { } #' @rdname save_html +#' @param background Background color for web page. +#' @param libdir Directory to copy dependencies to. +#' @param lang Value of the `` `lang` attribute. #' @export save_html.default <- function(html, file, background = "white", libdir = "lib", lang = "en", ...) { rlang::check_dots_empty() diff --git a/man/save_html.Rd b/man/save_html.Rd index a572d6fd..00ed4839 100644 --- a/man/save_html.Rd +++ b/man/save_html.Rd @@ -10,16 +10,18 @@ save_html(html, file, ...) \method{save_html}{default}(html, file, background = "white", libdir = "lib", lang = "en", ...) } \arguments{ -\item{html}{HTML content to print} +\item{html}{HTML content to print.} \item{file}{File path or connection. If a file path containing a sub-directory, the sub-directory must already exist.} -\item{background}{Background color for web page} +\item{...}{Further arguments passed to other methods.} -\item{libdir}{Directory to copy dependencies to} +\item{background}{Background color for web page.} -\item{lang}{Value of the \verb{} \code{lang} attribute} +\item{libdir}{Directory to copy dependencies to.} + +\item{lang}{Value of the \verb{} \code{lang} attribute.} } \description{ An S3 generic method for saving an HTML-like object to a file. The default From 35cb74246cd0d27fb06893d5c16fbe6b99d47d37 Mon Sep 17 00:00:00 2001 From: Carson Sievert Date: Fri, 6 Oct 2023 15:09:37 -0500 Subject: [PATCH 8/8] Update NEWS.md --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index e5d5eeca..0f0f51d4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,7 @@ ## New Features -* `save_html()` is now an S3 generic, allowing for HTML-like objects to be saved as an HTML file. (#411) +* `save_html()` is now an S3 generic, allowing for more customization over how certain classes are saved to an HTML file. (#411) ## Improvements