tagQuery: Query and modify HTML tags

View source: R/tag_query.R

tagQueryR Documentation

Query and modify HTML tags

Description

[Experimental]

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

htmltools documentation built on Nov. 3, 2023, 5:07 p.m.