htmltools::tag() and varArgs not documented

[JosiahParry]

I am trying to understand how to create a custom tag for a component library. However the tag() function does not have an example. It is unclear what the structure of varArgs argument should be.

htmltools/R/tags.R

Lines 639 to 667 in 038ef7b

	#' tags$html(
	#' tags$head(
	#' tags$title('My first page')
	#' ),
	#' tags$body(
	#' h1('My first heading'),
	#' p('My first paragraph, with some ', strong('bold'), ' text.'),
	#' div(
	#' id = 'myDiv', class = 'simpleDiv',
	#' 'Here is a div with some attributes.'
	#' )
	#' )
	#' )
	#'
	#' # html5 <audio> with boolean control attribute
	#' # https://www.w3.org/TR/html5/infrastructure.html#sec-boolean-attributes
	#' tags$audio(
	#' controls = NA,
	#' tags$source(
	#' src = "myfile.wav",
	#' type = "audio/wav"
	#' )
	#' )
	#'
	#' # suppress the whitespace between tags
	#' tags$span(
	#' tags$strong("I'm strong", .noWS="outside")
	#' )
	#'

[JosiahParry]

I also noticed that varArgs argument might be out of date or could benefit from better input checking

"List of tag attributes and children."

htmltools::tag("hello-world", list(c("a", "b", "c")))
#> Error in writeImpl(text): Text to be written must be a length-one character vector

[gadenbuie]

Agreed, we could definitely improve both the docs to add an example and the error message.

varArgs should be a list where the primary restriction is that any character items in the list must be scalar. In other words list("a", "b", "c") or list("a b c") will work but list(c("a", "b", "c")) will not. So Text to be written must be a length-one character vector is accurate but not very helpful.

The hard part in making the error message better is that it happens at a much lower level than where varArgs is provided and it's discovered as a part of a recursive walk of the varArgs list.

library(htmltools)

tag("hello-world", list("a", "b", "c"))
#> <hello-world>
#> a
#> b
#> c
#> </hello-world>

tag("hello-world", list(div("a", "b"), span("c")))
#> <hello-world>
#> <div>
#> a
#> b
#> </div>
#> <span>c</span>
#> </hello-world>