tagQuery {htmltools}

Query and modify HTML tags

Description

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

Usage

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

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