Modify a tag prior to rendering

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

tagAddRenderHook(tag, func, replace = FALSE)

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.

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.

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.

See also

tagFunction()

Examples

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

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

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

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

# 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
#> [[1]]
#> List of 10
#>  $ name      : chr "jqueryui"
#>  $ version   : chr "1.11.4"
#>  $ src       :List of 1
#>   ..$ href: chr "shared/jqueryui"
#>  $ meta      : NULL
#>  $ script    : chr "jquery-ui.min.js"
#>  $ stylesheet: NULL
#>  $ head      : NULL
#>  $ attachment: NULL
#>  $ package   : NULL
#>  $ all_files : logi TRUE
#>  - attr(*, "class")= chr "html_dependency"
#> 
#> [[2]]
#> List of 10
#>  $ name      : chr "font-awesome"
#>  $ version   : chr "4.5.0"
#>  $ src       :List of 1
#>   ..$ href: chr "shared/font-awesome"
#>  $ meta      : NULL
#>  $ script    : NULL
#>  $ stylesheet: chr "css/font-awesome.min.css"
#>  $ head      : NULL
#>  $ attachment: NULL
#>  $ package   : NULL
#>  $ all_files : logi TRUE
#>  - attr(*, "class")= chr "html_dependency"
#> 

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