tagAddRenderHook: Modify a tag prior to rendering

Description

Adds a hook to call on a tag() object when it is is rendered as HTML (with, for example, print(), renderTags(), as.tags(), etc).

Usage

tagAddRenderHook(tag, func, replace = FALSE)

Value

A tag() object with a .renderHooks field containing a list of functions (e.g. func). When the return value is rendered (such as with as.tags()), these functions will be called just prior to writing the HTML.

Arguments

tag: A tag() object.
func: A function (hook) to call when the tag is rendered. This function should have at least one argument (the tag) and return anything that can be converted into tags via as.tags().
replace: If TRUE, the previous hooks will be removed. If FALSE, func is appended to the previous hooks.

Details

The primary motivation for tagAddRenderHook() is to create tags that can change their attributes (e.g., change CSS classes) depending upon the context in which they're rendered (e.g., use one set of CSS classes in one a page layout, but a different set in another page layout). In this situation, tagAddRenderHook() is preferable to tagFunction() since the latter is more a "black box" in the sense that you don't know anything about the tag structure until it's rendered.

Examples

Run this code

# Have a place holder div and return a span instead
obj <- div("example", .renderHook = function(x) {
  x$name <- "span"
  x
})
obj$name # "div"
print(obj) # Prints as a `span`

# Add a class to the tag
# Should print a `span` with class `"extra"`
spanExtra <- tagAddRenderHook(obj, function(x) {
  tagAppendAttributes(x, class = "extra")
})
spanExtra

# Replace the previous render method
# Should print a `div` with class `"extra"`
divExtra <- tagAddRenderHook(obj, replace = TRUE, function(x) {
  tagAppendAttributes(x, class = "extra")
})
divExtra

# Add more child tags
spanExtended <- tagAddRenderHook(obj, function(x) {
  tagAppendChildren(x, " ", tags$strong("bold text"))
})
spanExtended

# Add a new html dependency
newDep <- tagAddRenderHook(obj, function(x) {
  fa <- htmlDependency(
    "font-awesome", "4.5.0", c(href="shared/font-awesome"),
    stylesheet = "css/font-awesome.min.css")
  attachDependencies(x, fa, append = TRUE)
})
# Also add a jqueryui html dependency
htmlDependencies(newDep) <- htmlDependency(
  "jqueryui", "1.11.4", c(href="shared/jqueryui"),
  script = "jquery-ui.min.js")
# At render time, both dependencies will be found
renderTags(newDep)$dependencies

# Ignore the original tag and return something completely new.
newObj <- tagAddRenderHook(obj, function(x) {
  tags$p("Something else")
})
newObj