From 2a26d1fce3bc9f01e29238eebb57006b9c247067 Mon Sep 17 00:00:00 2001 From: Carson Sievert Date: Fri, 6 Oct 2023 15:19:06 -0500 Subject: [PATCH] Make `save_html()` an S3 generic method (#411) Co-authored-by: cpsievert --- DESCRIPTION | 2 +- NAMESPACE | 1 + NEWS.md | 4 ++++ R/html_print.R | 23 ++++++++++++++++------- man/save_html.Rd | 19 ++++++++++++------- tests/testthat/test-print.R | 10 ++++++++++ 6 files changed, 44 insertions(+), 15 deletions(-) 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/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/NEWS.md b/NEWS.md index 36f5bb78..0f0f51d4 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 more customization over how certain classes are saved to an HTML file. (#411) + ## Improvements * Fill items no longer set `overflow: auto` or `width: 100%` by default. (#401) diff --git a/R/html_print.R b/R/html_print.R index c257514f..c6943953 100644 --- a/R/html_print.R +++ b/R/html_print.R @@ -59,18 +59,27 @@ 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 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 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, background = "white", libdir = "lib", lang = "en") { +save_html <- function(html, file, ...) { + UseMethod("save_html") +} + +#' @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() + force(html) force(background) force(libdir) diff --git a/man/save_html.Rd b/man/save_html.Rd index 526b0767..00ed4839 100644 --- a/man/save_html.Rd +++ b/man/save_html.Rd @@ -2,23 +2,28 @@ % 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} +\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{background}{Background color for web page.} -\item{libdir}{Directory to copy dependencies to} +\item{libdir}{Directory to copy dependencies to.} -\item{lang}{Value of the \verb{} \code{lang} attribute} +\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}. } 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") + ) +})