tagQuery: Query and modify HTML tags
In htmltools: Tools for HTML
tagQuery R Documentation
Query and modify HTML tags
Description
![[Experimental]](../help/figures/lifecycle-experimental.svg)
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 May 29, 2024, 5:19 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| tagQuery | R Documentation |
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 |
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
$childrenfields into a singlelist()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 acssSelector. -
$children(cssSelector = NULL): Get the direct children of each selected tag, optionally filtered by acssSelector.
Siblings
-
siblings(cssSelector = NULL): Get the siblings of each selected tag, optionally filtered by acssSelector.
Parents
-
$parent(cssSelector = NULL): Get the parent of each selected tag, optionally filtered by acssSelector. -
$parents(cssSelector = NULL): Get the ancestors of each selected tag, optionally filtered by acssSelector. -
$closest(cssSelector = NULL): For each selected tag, get the closest ancestor tag (including itself) satisfying acssSelector. IfcssSelector = NULL, it is equivalent to calling$selectedTags().
Custom filter
-
$filter(fn): Filter the selected tags to those for whichfn(x, i)returnsTRUE. In addition to an R function with two arguments (the selected tagxand the indexi),fnmay 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 functionfn.fnshould 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 thetagQuery()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) roottags. -
$selectedTags(): Return atagList()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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.