htmltools (version 0.5.8.1)

tagQuery: Query and modify HTML tags

Description

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

Usage

tagQuery(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().

Arguments

tags

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

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")
tagQ

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