Query and modify HTML tags

Source: R/tag_query.R

[Experimental]

tagQuery() provides a jQuery inspired interface for querying and modifying tag() (and tagList()) objects.

tagQuery(tags)

Arguments

tags

A tag(), tagList(), or list() of tags.

Value

A class with methods that are described below. This class can't be used directly inside other tag() or a renderTags() context, but underlying HTML tags may be extracted via $allTags() or $selectedTags().

Altered Tag structure

For performance reasons, the input tag structure to tagQuery() will be altered into a consistently expected shape.

Some alterations include:

  • tags flattening their $children fields into a single list()

  • tags relocating any attribute html_dependency() to be located in $children`

  • tagList()-like structures relocating any attribute html dependency to be a entry in its list structure.

While the resulting tag shape has possibly changed, tagQuery()'s' resulting tags will still render to the same HTML value (ex: renderTags()) and HTML dependencies (ex: findDependencies()).

Vignette

To get started with using tagQuery(), visit https://rstudio.github.io/htmltools/articles/tagQuery.html.

Methods

Unless otherwise stated, tagQuery() methods accept a character vector as input.

Query methods

Query methods identify particular subsets of the root tag using CSS selectors (or R functions).

Children

  • $find(cssSelector): Get the descendants of each selected tag, filtered by a cssSelector.

  • $children(cssSelector = NULL): Get the direct children of each selected tag, optionally filtered by a cssSelector.

Siblings

  • siblings(cssSelector = NULL): Get the siblings of each selected tag, optionally filtered by a cssSelector.

Parents

  • $parent(cssSelector = NULL): Get the parent of each selected tag, optionally filtered by a cssSelector.

  • $parents(cssSelector = NULL): Get the ancestors of each selected tag, optionally filtered by a cssSelector.

  • $closest(cssSelector = NULL): For each selected tag, get the closest ancestor tag (including itself) satisfying a cssSelector. If cssSelector = NULL, it is equivalent to calling $selectedTags().

Custom filter

  • $filter(fn): Filter the selected tags to those for which fn(x, i) returns TRUE. In addition to an R function with two arguments (the selected tag x and the index i), fn may also be a valid CSS selector.

Length

  • $length(): Number of tags that have been selected.

Reset

  • $resetSelected(): Reset selected tags to the $allTags() tag. Useful in combination with $replaceWith() since it empties the selection.

Modify methods

Unlike query methods, modify methods modify the tagQuery() object.

Attributes

  • $addClass(class): Adds class(es) to each selected tag.

  • $removeClass(class): Removes class(es) to each selected tag.

  • $toggleClass(class): Adds class(es) that don't already exist and removes class(es) that do already exist (for each selected tag).

  • $hasClass(class): Does each selected tag have all the provided class(es)?

  • $addAttrs(...): Add a set of attributes to each selected tag.

  • $removeAttrs(attrs): Remove a set of attributes from each selected tag.

  • $hasAttrs(attr): Do each selected tags have all of the attributes?

Children

  • $append(...): For each selected tag, insert ... after any existing children.

  • $prepend(...): For each selected tag, insert ... before any existing children.

Siblings

  • $after(...): Add all ... objects as siblings after each of the selected tags.

  • $before(...): Add all ... objects as siblings before each of the selected tags.

Custom

  • $each(fn): Modify each selected tag with a function fn. fn should accept two arguments: the first is the selected tag and second is the selected tags position index. Since the selected tag is a reference, any modifications to it will also modify the tagQuery() object.

Replace methods

  • $replaceWith(...): Replace all selected tags with ... in the root tag and clear the selection.

  • $remove(...): Remove all selected tags from the root tag and clear the current selection.

  • $empty(): Remove any children of each selected tag. Use this method before calling $append(...) to replace the children of each selected tag, with other content.

Extract HTML tags

  • $allTags(): Return the (possibly modified) root tags.

  • $selectedTags(): Return a tagList() of the currently selected tags.

Examples

tagQ <- tagQuery(div(a()))
tagQ$find("a")$addClass("foo")
#> `$allTags()`:
#> <div>
#>   <a class="foo"></a>
#> </div>
#> 
#> `$selectedTags()`:
#> [[1]]
#> <a class="foo"></a>
#> 
tagQ
#> `$allTags()`:
#> <div>
#>   <a class="foo"></a>
#> </div>
#> 
#> `$selectedTags()`: `$allTags()`

# To learn more, visit https://rstudio.github.io/htmltools/articles/tagQuery.html