htmltools/0000755000176200001440000000000014111445212012272 5ustar liggesusershtmltools/NAMESPACE0000644000176200001440000000514714106770125013530 0ustar liggesusers# Generated by roxygen2: do not edit by hand S3method(as.character,html) S3method(as.character,shiny.tag) S3method(as.character,shiny.tag.env) S3method(as.character,shiny.tag.list) S3method(as.character,shiny.tag.query) S3method(as.tags,character) S3method(as.tags,default) S3method(as.tags,html) S3method(as.tags,html_dependency) S3method(as.tags,list) S3method(as.tags,shiny.tag) S3method(as.tags,shiny.tag.env) S3method(as.tags,shiny.tag.function) S3method(as.tags,shiny.tag.list) S3method(as.tags,shiny.tag.query) S3method(format,html) S3method(format,htmltools.selector) S3method(format,htmltools.selector.list) S3method(format,shiny.tag) S3method(format,shiny.tag.env) S3method(format,shiny.tag.list) S3method(format,shiny.tag.query) S3method(print,html) S3method(print,html_dependency) S3method(print,htmltools.selector) S3method(print,htmltools.selector.list) S3method(print,shiny.tag) S3method(print,shiny.tag.env) S3method(print,shiny.tag.list) S3method(print,shiny.tag.query) S3method(str,shiny.tag.env) export("htmlDependencies<-") export(HTML) export(a) export(as.tags) export(attachDependencies) export(br) export(browsable) export(capturePlot) export(code) export(copyDependencyToDir) export(css) export(defaultPngDevice) export(div) export(doRenderTags) export(em) export(extractPreserveChunks) export(findDependencies) export(h1) export(h2) export(h3) export(h4) export(h5) export(h6) export(hr) export(htmlDependencies) export(htmlDependency) export(htmlEscape) export(htmlPreserve) export(htmlTemplate) export(html_print) export(img) export(includeCSS) export(includeHTML) export(includeMarkdown) export(includeScript) export(includeText) export(is.browsable) export(is.singleton) export(knit_print.html) export(knit_print.shiny.tag) export(knit_print.shiny.tag.list) export(makeDependencyRelative) export(p) export(parseCssColors) export(plotTag) export(pre) export(renderDependencies) export(renderDocument) export(renderTags) export(resolveDependencies) export(restorePreserveChunks) export(save_html) export(singleton) export(span) export(strong) export(subtractDependencies) export(suppressDependencies) export(surroundSingletons) export(tag) export(tagAddRenderHook) export(tagAppendAttributes) export(tagAppendChild) export(tagAppendChildren) export(tagFunction) export(tagGetAttribute) export(tagHasAttribute) export(tagInsertChildren) export(tagList) export(tagQuery) export(tagSetChildren) export(tags) export(takeSingletons) export(urlEncodePath) export(validateCssUnit) export(withTags) import(digest) import(rlang) import(utils) importFrom(fastmap,fastmap) importFrom(fastmap,faststack) useDynLib(htmltools, .registration = TRUE) htmltools/man/0000755000176200001440000000000014062147721013056 5ustar liggesusershtmltools/man/htmlPreserve.Rd0000644000176200001440000000443214047273610016030 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{htmlPreserve} \alias{htmlPreserve} \alias{extractPreserveChunks} \alias{restorePreserveChunks} \title{Preserve HTML regions} \usage{ htmlPreserve(x) extractPreserveChunks(strval) restorePreserveChunks(strval, chunks) } \arguments{ \item{x}{A character vector of HTML to be preserved.} \item{strval}{Input string from which to extract/restore chunks.} \item{chunks}{The \code{chunks} element of the return value of \code{extractPreserveChunks}.} } \value{ \code{htmlPreserve} returns a single-element character vector with "magic" HTML comments surrounding the original text (unless the original text was empty, in which case an empty string is returned). \code{extractPreserveChunks} returns a list with two named elements: \code{value} is the string with the regions replaced, and \code{chunks} is a named character vector where the names are the IDs and the values are the regions that were extracted. \code{restorePreserveChunks} returns a character vector with the chunk IDs replaced with their original values. } \description{ Use "magic" HTML comments to protect regions of HTML from being modified by text processing tools. } \details{ Text processing tools like markdown and pandoc are designed to turn human-friendly markup into common output formats like HTML. This works well for most prose, but components that generate their own HTML may break if their markup is interpreted as the input language. The \code{htmlPreserve} function is used to mark regions of an input document as containing pure HTML that must not be modified. This is achieved by substituting each such region with a benign but unique string before processing, and undoing those substitutions after processing. } \examples{ # htmlPreserve will prevent "" # from getting an tag inserted in the middle markup <- paste(sep = "\n", "This is *emphasized* text in markdown.", htmlPreserve(""), "Here is some more *emphasized text*." ) extracted <- extractPreserveChunks(markup) markup <- extracted$value # Just think of this next line as Markdown processing output <- gsub("\\\\*(.*?)\\\\*", "\\\\1", markup) output <- restorePreserveChunks(output, extracted$chunks) output } htmltools/man/html_print.Rd0000644000176200001440000000135114047273610015525 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_print.R \name{html_print} \alias{html_print} \title{Implementation of the print method for HTML} \usage{ html_print( html, background = "white", viewer = getOption("viewer", utils::browseURL) ) } \arguments{ \item{html}{HTML content to print} \item{background}{Background color for web page} \item{viewer}{A function to be called with the URL or path to the generated HTML page. Can be \code{NULL}, in which case no viewer will be invoked.} } \value{ Invisibly returns the URL or path of the generated HTML page. } \description{ Convenience method that provides an implementation of the \code{\link[base:print]{base::print()}} method for HTML content. } htmltools/man/makeDependencyRelative.Rd0000644000176200001440000000210414047273610017752 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_dependency.R \name{makeDependencyRelative} \alias{makeDependencyRelative} \title{Make an absolute dependency relative} \usage{ makeDependencyRelative(dependency, basepath, mustWork = TRUE) } \arguments{ \item{dependency}{A single HTML dependency with an absolute path.} \item{basepath}{The path to the directory that \code{dependency} should be made relative to.} \item{mustWork}{If \code{TRUE} and \code{dependency} does not point to a directory on disk (but rather a URL location), an error is raised. If \code{FALSE} then non-disk dependencies are returned without modification.} } \value{ The dependency with its \code{src} value updated to the new location's relative path. If \code{baspath} did not appear to be a parent directory of the dependency's directory, an error is raised (regardless of the value of \code{mustWork}). } \description{ Change a dependency's absolute path to be relative to one of its parent directories. } \seealso{ \code{\link[=copyDependencyToDir]{copyDependencyToDir()}} } htmltools/man/tagList.Rd0000644000176200001440000000070514062147721014756 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{tagList} \alias{tagList} \title{Create a list of tags} \usage{ tagList(...) } \arguments{ \item{...}{A collection of \link{tag}s.} } \description{ Create a \code{list()} of \link{tag}s with methods for \code{\link[=print]{print()}}, \code{\link[=as.character]{as.character()}}, etc. } \examples{ tagList( h1("Title"), h2("Header text"), p("Text here") ) } htmltools/man/save_html.Rd0000644000176200001440000000131414047273610015326 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_print.R \name{save_html} \alias{save_html} \title{Save an HTML object to a file} \usage{ save_html(html, file, background = "white", libdir = "lib", lang = "en") } \arguments{ \item{html}{HTML content to print} \item{file}{File path or connection. If a file path containing a sub-directory, the sub-directory must already exist.} \item{background}{Background color for web page} \item{libdir}{Directory to copy dependencies to} \item{lang}{Value of the \verb{} \code{lang} attribute} } \description{ Save the specified HTML object to a file, copying all of it's dependencies to the directory specified via \code{libdir}. } htmltools/man/validateCssUnit.Rd0000644000176200001440000000235314047273610016452 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{validateCssUnit} \alias{validateCssUnit} \title{Validate proper CSS formatting of a unit} \usage{ validateCssUnit(x) } \arguments{ \item{x}{The unit to validate. Will be treated as a number of pixels if a unit is not specified.} } \value{ A properly formatted CSS unit of length, if possible. Otherwise, will throw an error. } \description{ Checks that the argument is valid for use as a CSS unit of length. } \details{ \code{NULL} and \code{NA} are returned unchanged. Single element numeric vectors are returned as a character vector with the number plus a suffix of \code{"px"}. Single element character vectors must be \code{"auto"}, \code{"fit-content"} or \code{"inherit"}, a number, or a length calculated by the \code{"calc"} CSS function. If the number has a suffix, it must be valid: \code{px}, \verb{\\\%}, \code{ch}, \code{em}, \code{rem}, \code{pt}, \verb{in}, \code{cm}, \code{mm}, \code{ex}, \code{pc}, \code{vh}, \code{vw}, \code{vmin}, or \code{vmax}. If the number has no suffix, the suffix \code{"px"} is appended. Any other value will cause an error to be thrown. } \examples{ validateCssUnit("10\%") validateCssUnit(400) #treated as '400px' } htmltools/man/renderTags.Rd0000644000176200001440000000335614051530603015443 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{renderTags} \alias{renderTags} \alias{doRenderTags} \title{Render tags into HTML} \usage{ renderTags(x, singletons = character(0), indent = 0) doRenderTags(x, indent = 0) } \arguments{ \item{x}{Tag object(s) to render} \item{singletons}{A list of \link{singleton} signatures to consider already rendered; any matching singletons will be dropped instead of rendered. (This is useful (only?) for incremental rendering.)} \item{indent}{Initial indent level, or \code{FALSE} if no indentation should be used.} } \value{ \code{renderTags} returns a list with the following variables: \itemize{ \item \code{head}: An \code{\link[=HTML]{HTML()}} string that should be included in \verb{}. \item \code{singletons}: Character vector of singleton signatures that are known after rendering. \item \code{dependencies}: A list of \link[=resolveDependencies]{resolved} \code{\link[=htmlDependency]{htmlDependency()}} objects. \item \code{html}: An \code{\link[=HTML]{HTML()}} string that represents the main HTML that was rendered. } \code{doRenderTags} returns a simple \code{\link[=HTML]{HTML()}} string. } \description{ Renders tags (and objects that can be converted into tags using \code{\link[=as.tags]{as.tags()}}) into HTML. (Generally intended to be called from web framework libraries, not directly by most users--see \code{\link[=print.html]{print.html()}} for higher level rendering.) } \details{ \code{doRenderTags} is intended for very low-level use; it ignores render hooks, singletons, head, and dependency handling, and simply renders the given tag objects as HTML. Please use \code{renderTags()} if \code{x} has not already handled its dependencies and render hooks. } htmltools/man/tagFunction.Rd0000644000176200001440000000162614051530603015624 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{tagFunction} \alias{tagFunction} \title{Tag function} \usage{ tagFunction(func) } \arguments{ \item{func}{a function with no arguments that returns HTML tags and/or dependencies.} } \description{ Create 'lazily' rendered HTML \link{tags} (and/or \code{\link[=htmlDependencies]{htmlDependencies()}}). } \details{ When possible, use \code{\link[=tagAddRenderHook]{tagAddRenderHook()}} to provide both a tag structure and utilize a render function. } \examples{ myDivDep <- tagFunction(function() { if (isTRUE(getOption("useDep", TRUE))) { htmlDependency( name = "lazy-dependency", version = "1.0", src = "" ) } }) myDiv <- attachDependencies(div(), myDivDep) renderTags(myDiv) withr::with_options(list(useDep = FALSE), renderTags(myDiv)) } \seealso{ \code{\link[=tagAddRenderHook]{tagAddRenderHook()}} } htmltools/man/findDependencies.Rd0000644000176200001440000000104314047273610016572 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{findDependencies} \alias{findDependencies} \title{Collect attached dependencies from HTML tag object} \usage{ findDependencies(tags, tagify = TRUE) } \arguments{ \item{tags}{A tag-like object to search for dependencies.} \item{tagify}{Whether to tagify the input before searching for dependencies.} } \value{ A list of \code{\link[=htmlDependency]{htmlDependency()}} objects. } \description{ Walks a hierarchy of tags looking for attached dependencies. } htmltools/man/htmlEscape.Rd0000644000176200001440000000077113546657312015447 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_escape.R \name{htmlEscape} \alias{htmlEscape} \title{Escape HTML entities} \usage{ htmlEscape(text, attribute = FALSE) } \arguments{ \item{text}{Text to escape} \item{attribute}{Escape for use as an attribute value} } \value{ Character vector with escaped text. } \description{ Escape HTML entities contained in a character vector so that it can be safely included as text or an attribute value within an HTML document } htmltools/man/include.Rd0000644000176200001440000000245614047273610014777 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{include} \alias{include} \alias{includeHTML} \alias{includeText} \alias{includeMarkdown} \alias{includeCSS} \alias{includeScript} \title{Include Content From a File} \usage{ includeHTML(path) includeText(path) includeMarkdown(path) includeCSS(path, ...) includeScript(path, ...) } \arguments{ \item{path}{The path of the file to be included. It is highly recommended to use a relative path (the base path being the Shiny application directory), not an absolute path.} \item{...}{Any additional attributes to be applied to the generated tag.} } \description{ Load HTML, text, or rendered Markdown from a file and turn into HTML. } \details{ These functions provide a convenient way to include an extensive amount of HTML, textual, Markdown, CSS, or JavaScript content, rather than using a large literal R string. } \note{ \code{includeText} escapes its contents, but does no other processing. This means that hard breaks and multiple spaces will be rendered as they usually are in HTML: as a single space character. If you are looking for preformatted text, wrap the call with \code{\link[=pre]{pre()}}, or consider using \code{includeMarkdown} instead. The \code{includeMarkdown} function requires the \code{markdown} package. } htmltools/man/browsable.Rd0000644000176200001440000000164714047273610015335 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_print.R \name{browsable} \alias{browsable} \alias{is.browsable} \title{Make an HTML object browsable} \usage{ browsable(x, value = TRUE) is.browsable(x) } \arguments{ \item{x}{The object to make browsable or not.} \item{value}{Whether the object should be considered browsable.} } \value{ \code{browsable} returns \code{x} with an extra attribute to indicate that the value is browsable. \code{is.browsable} returns \code{TRUE} if the value is browsable, or \code{FALSE} if not. } \description{ By default, HTML objects display their HTML markup at the console when printed. \code{browsable} can be used to make specific objects render as HTML by default when printed at the console. } \details{ You can override the default browsability of an HTML object by explicitly passing \code{browse = TRUE} (or \code{FALSE}) to the \code{print} function. } htmltools/man/renderDependencies.Rd0000644000176200001440000000166114047273610017137 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_dependency.R \name{renderDependencies} \alias{renderDependencies} \title{Create HTML for dependencies} \usage{ renderDependencies( dependencies, srcType = c("href", "file"), encodeFunc = urlEncodePath, hrefFilter = identity ) } \arguments{ \item{dependencies}{A list of \code{htmlDependency} objects.} \item{srcType}{The type of src paths to use; valid values are \code{file} or \code{href}.} \item{encodeFunc}{The function to use to encode the path part of a URL. The default should generally be used.} \item{hrefFilter}{A function used to transform the final, encoded URLs of script and stylesheet files. The default should generally be used.} } \value{ An \code{\link[=HTML]{HTML()}} object suitable for inclusion in the head of an HTML document. } \description{ Create the appropriate HTML markup for including dependencies in an HTML document. } htmltools/man/plotTag.Rd0000644000176200001440000000554514106770125014767 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/images.R \name{plotTag} \alias{plotTag} \title{Capture a plot as a self-contained \verb{} tag} \usage{ plotTag( expr, alt, device = defaultPngDevice(), width = 400, height = 400, pixelratio = 2, mimeType = "image/png", deviceArgs = list(), attribs = list(), suppressSize = c("none", "x", "y", "xy") ) } \arguments{ \item{expr}{A plotting expression that generates a plot (or yields an object that generates a plot when printed, like a ggplot2).} \item{alt}{A single-element character vector that contains a text description of the image. This is used by accessibility tools, such as screen readers for vision impaired users.} \item{device}{A graphics device function; by default, this will be either \code{\link[grDevices:png]{grDevices::png()}}, \code{\link[ragg:agg_png]{ragg::agg_png()}}, or \code{\link[Cairo:Cairo]{Cairo::CairoPNG()}}, depending on your system and configuration. See \code{\link[=defaultPngDevice]{defaultPngDevice()}}.} \item{width, height}{The width/height that the generated tag should be displayed at, in logical (browser) pixels.} \item{pixelratio}{Indicates the ratio between physical and logical units of length. For PNGs that may be displayed on high-DPI screens, use \code{2}; for graphics devices that express width/height in inches (like \code{\link[grDevices:cairo]{grDevices::svg()}}, try \code{1/72} or \code{1/96}.} \item{mimeType}{The MIME type associated with the \code{device}. Examples are \code{image/png}, \code{image/tiff}, \code{image/svg+xml}.} \item{deviceArgs}{A list of additional arguments that should be included when the \code{device} function is invoked.} \item{attribs}{A list of additional attributes that should be included on the generated \verb{} (e.g. \code{id}, \code{class}).} \item{suppressSize}{By default, \code{plotTag} will include a \code{style} attribute with \code{width} and \code{height} properties specified in pixels. If you'd rather specify the image size using other methods (like responsive CSS rules) you can use this argument to suppress width (\code{"x"}), height (\code{"y"}), or both (\code{"xy"}) properties.} } \value{ A \code{\link[=browsable]{browsable()}} HTML \verb{} tag object. Print it at the console to preview, or call \code{\link[=as.character]{as.character()}} on it to view the HTML source. } \description{ Capture a plot as a self-contained \verb{} tag } \examples{ img <- plotTag({ plot(cars) }, "A plot of the 'cars' dataset", width = 375, height = 275) if (interactive()) img if (interactive() && capabilities("cairo")) { plotTag( plot(pressure), "A plot of the 'pressure' dataset", device = grDevices::svg, width = 375, height = 275, pixelratio = 1/72, mimeType = "image/svg+xml" ) } } \seealso{ \code{\link[=capturePlot]{capturePlot()}} saves plots as an image file. } htmltools/man/parseCssColors.Rd0000644000176200001440000000266714051530603016316 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/colors.R \name{parseCssColors} \alias{parseCssColors} \title{Parse CSS color strings} \usage{ parseCssColors(str, mustWork = TRUE) } \arguments{ \item{str}{CSS color strings} \item{mustWork}{If true, invalid color strings will cause an error; if false, then the result will contain \code{NA} for invalid colors.} } \value{ A vector of strings in \verb{#RRGGBB} or \verb{#RRGGBBAA} format (the latter is only used for colors whose alpha values are less than \code{FF}), or \code{NA} for invalid colors when \code{mustWork} is false. Such strings are suitable for use in plots, or parsing with \code{\link[=col2rgb]{col2rgb()}} (be sure to pass \code{alpha = TRUE} to prevent the alpha channel from being discarded). } \description{ Parses/normalizes CSS color strings, and returns them as strings in \code{"#RRGGBB"} and/or \code{"#RRGGBBAA"} format. Understands hex colors in 3, 4, 6, and 8 digit forms, \code{rgb()}/\code{rgba()}, \code{hsl()}/\code{hsla()}, and color keywords. } \details{ Note that \code{parseCssColors} may return colors in \verb{#RRGGBBAA} format. Such values are not understood by Internet Explorer, and must be converted to \code{rgba(red, green, blue, alpha)} format to be safe for the web. } \examples{ parseCssColors(c( "#0d6efd", "#DC35457F", "rgb(32,201,151)", " rgba( 23 , 162 , 184 , 0.5 ) ", "hsl(261, 51\%, 51\%)", "cornflowerblue" )) } htmltools/man/tagAppendAttributes.Rd0000644000176200001440000000347114051530603017315 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{tagAppendAttributes} \alias{tagAppendAttributes} \alias{tagHasAttribute} \alias{tagGetAttribute} \title{Append tag attributes} \usage{ tagAppendAttributes(tag, ..., .cssSelector = NULL) tagHasAttribute(tag, attr) tagGetAttribute(tag, attr) } \arguments{ \item{tag}{a \link{tag} object.} \item{...}{a collection of attributes.} \item{.cssSelector}{A character string containing a \href{https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors}{CSS selector} for targeting particular (inner) tags of interest. At the moment, only a combination of \href{https://www.w3.org/TR/CSS22/selector.html#type-selectors}{type} (e.g, \code{div}), \href{https://www.w3.org/TR/CSS22/selector.html#class-html}{class} (e.g., \code{.my-class}), \href{https://www.w3.org/TR/CSS22/selector.html#id-selectors}{id} (e.g., \verb{#myID}), and \href{https://www.w3.org/TR/CSS22/selector.html#universal-selector}{universal} (\code{*}) selectors within a given \href{https://www.w3.org/TR/CSS22/selector.html#selector-syntax}{simple selector} is supported. Note, if \code{.cssSelector} is used, the returned tags will have their \verb{$children} fields flattened to a single \code{list()} via \code{\link[=tagQuery]{tagQuery()}}.} \item{attr}{The name of an attribute.} } \description{ Append (\code{tagAppendAttributes()}), check existence (\code{tagHasAttribute()}), and obtain the value (\code{tagGetAttribute()}) of HTML attribute(s). } \examples{ html <- div(a()) tagAppendAttributes(html, class = "foo") tagAppendAttributes(html, .cssSelector = "a", class = "bar") tagHasAttribute(div(foo = "bar"), "foo") tagGetAttribute(div(foo = "bar"), "foo") } \seealso{ \code{\link[=tagAppendChildren]{tagAppendChildren()}}, \code{\link[=tagQuery]{tagQuery()}} } htmltools/man/defaultPngDevice.Rd0000644000176200001440000000124713743335230016561 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/images.R \name{defaultPngDevice} \alias{defaultPngDevice} \title{Determine the best PNG device for your system} \usage{ defaultPngDevice() } \value{ A graphics device function. } \description{ Returns the best PNG-based graphics device for your system, in the opinion of the \code{htmltools} maintainers. On Mac, \code{\link[grDevices:png]{grDevices::png()}} is used; on all other platforms, either \code{\link[ragg:agg_png]{ragg::agg_png()}} or \code{\link[Cairo:Cairo]{Cairo::CairoPNG()}} are used if their packages are installed. Otherwise, \code{\link[grDevices:png]{grDevices::png()}} is used. } htmltools/man/singleton.Rd0000644000176200001440000000123014047273610015343 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{singleton} \alias{singleton} \alias{is.singleton} \title{Include content only once} \usage{ singleton(x, value = TRUE) is.singleton(x) } \arguments{ \item{x}{A \code{\link[=tag]{tag()}}, text, \code{\link[=HTML]{HTML()}}, or list.} \item{value}{Whether the object should be a singleton.} } \description{ Use \code{singleton} to wrap contents (tag, text, HTML, or lists) that should be included in the generated document only once, yet may appear in the document-generating code more than once. Only the first appearance of the content (in document order) will be used. } htmltools/man/tagQuery.Rd0000644000176200001440000001257214051530606015151 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tag_query.R \name{tagQuery} \alias{tagQuery} \title{Query and modify HTML tags} \usage{ tagQuery(tags) } \arguments{ \item{tags}{A \code{\link[=tag]{tag()}}, \code{\link[=tagList]{tagList()}}, or \code{\link[=list]{list()}} of tags.} } \value{ A class with methods that are described below. This class can't be used directly inside other \code{\link[=tag]{tag()}} or a \code{\link[=renderTags]{renderTags()}} context, but underlying HTML tags may be extracted via \verb{$allTags()} or \verb{$selectedTags()}. Note: The returned tags will have their \verb{$children} fields flattened to a single \code{list()}, which may not be the same shape that was provided to \code{tagQuery()}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}\cr\cr \code{tagQuery()} provides a \href{https://jquery.com/}{\code{jQuery}} inspired interface for querying and modifying \code{\link[=tag]{tag()}} (and \code{\link[=tagList]{tagList()}}) objects. } \section{Vignette}{ To get started with using \code{tagQuery()}, visit \url{https://rstudio.github.io/htmltools/articles/tagQuery.html}. } \section{Methods}{ Unless otherwise stated, \code{tagQuery()} methods accept a character vector as input. \subsection{Query methods}{ Query methods identify particular subsets of the root tag using CSS selectors (or R functions). \subsection{Children}{ \itemize{ \item \verb{$find(cssSelector)}: Get the descendants of each selected tag, filtered by a \code{cssSelector}. \item \verb{$children(cssSelector = NULL)}: Get the direct children of each selected tag, optionally filtered by a \code{cssSelector}. } } \subsection{Siblings}{ \itemize{ \item \code{siblings(cssSelector = NULL)}: Get the siblings of each selected tag, optionally filtered by a \code{cssSelector}. } } \subsection{Parents}{ \itemize{ \item \verb{$parent(cssSelector = NULL)}: Get the parent of each selected tag, optionally filtered by a \code{cssSelector}. \item \verb{$parents(cssSelector = NULL)}: Get the ancestors of each selected tag, optionally filtered by a \code{cssSelector}. \item \verb{$closest(cssSelector = NULL)}: For each selected tag, get the closest ancestor tag (including itself) satisfying a \code{cssSelector}. If \code{cssSelector = NULL}, it is equivalent to calling \verb{$selectedTags()}. } } \subsection{Custom filter}{ \itemize{ \item \verb{$filter(fn)}: Filter the selected tags to those for which \code{fn(x, i)} returns \code{TRUE}. In addition to an R function with two arguments (the selected tag \code{x} and the index \code{i}), \code{fn} may also be a valid CSS selector. } } \subsection{Length}{ \itemize{ \item \verb{$length()}: Number of tags that have been selected. } } \subsection{Reset}{ \itemize{ \item \verb{$resetSelected()}: Reset selected tags to the \verb{$root()} tag. Useful in combination with \verb{$replaceWith()} since it empties the selection. } } } \subsection{Modify methods}{ Unlike query methods, modify methods modify the \code{tagQuery()} object. \subsection{Attributes}{ \itemize{ \item \verb{$addClass(class)}: Adds class(es) to each selected tag. \item \verb{$removeClass(class)}: Removes class(es) to each selected tag. \item \verb{$toggleClass(class)}: Adds class(es) that don't already exist and removes class(es) that do already exist (for each selected tag). \item \verb{$hasClass(class)}: Does each selected tag have all the provided class(es)? \item \verb{$addAttrs(...)}: Add a set of attributes to each selected tag. \item \verb{$removeAttrs(attrs)}: Remove a set of attributes from each selected tag. \item \verb{$hasAttrs(attr)}: Do each selected tags have all of the attributes? } } \subsection{Children}{ \itemize{ \item \verb{$append(...)}: For each selected tag, insert \code{...} \strong{after} any existing children. \item \verb{$prepend(...)}: For each selected tag, insert \code{...} \strong{before} any existing children. } } \subsection{Siblings}{ \itemize{ \item \verb{$after(...)}: Add all \code{...} objects as siblings after each of the selected tags. \item \verb{$before(...)}: Add all \code{...} objects as siblings before each of the selected tags. } } \subsection{Custom}{ \itemize{ \item \verb{$each(fn)}: Modify each selected tag with a function \code{fn}. \code{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 \code{tagQuery()} object. } } } \subsection{Replace methods}{ \itemize{ \item \verb{$replaceWith(...)}: Replace all selected tags with \code{...} in the root tag and clear the selection. \item \verb{$remove(...)}: Remove all selected tags from the root tag and clear the current selection. \item \verb{$empty()}: Remove any children of each selected tag. Use this method before calling \verb{$append(...)} to replace the children of each selected tag, with other content. } } \subsection{Extract HTML tags}{ \itemize{ \item \verb{$allTags()}: Return the (possibly modified) root \code{tags}. \item \verb{$selectedTags()}: Return a \code{\link[=tagList]{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/man/singleton_tools.Rd0000644000176200001440000000237214047273610016573 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{singleton_tools} \alias{singleton_tools} \alias{surroundSingletons} \alias{takeSingletons} \title{Singleton manipulation functions} \usage{ surroundSingletons(ui) takeSingletons(ui, singletons = character(0), desingleton = TRUE) } \arguments{ \item{ui}{Tag object or lists of tag objects. See \link{builder} topic.} \item{singletons}{Character vector of singleton signatures that have already been encountered (i.e. returned from previous calls to \code{takeSingletons}).} \item{desingleton}{Logical value indicating whether singletons that are encountered should have the singleton attribute removed.} } \value{ \code{surroundSingletons} preprocesses a tag object by changing any singleton X into \verb{X'} where sig is the sha1 of X, and X' is X minus the singleton attribute. \code{takeSingletons} returns a list with the elements \code{ui} (the processed tag objects with any duplicate singleton objects removed) and \code{singletons} (the list of known singleton signatures). } \description{ Functions for manipulating \code{\link[=singleton]{singleton()}} objects in tag hierarchies. Intended for framework authors. } htmltools/man/css.Rd0000644000176200001440000000323314047273610014136 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{css} \alias{css} \title{CSS string helper} \usage{ css(..., collapse_ = "") } \arguments{ \item{...}{Named style properties, where the name is the property name and the argument is the property value. See Details for conversion rules.} \item{collapse_}{(Note that the parameter name has a trailing underscore character.) Character to use to collapse properties into a single string; likely \code{""} (the default) for style attributes, and either \code{"\\n"} or \code{NULL} for style blocks.} } \description{ Convenience function for building CSS style declarations (i.e. the string that goes into a style attribute, or the parts that go inside curly braces in a full stylesheet). } \details{ CSS uses \code{'-'} (minus) as a separator character in property names, but this is an inconvenient character to use in an R function argument name. Instead, you can use \code{'.'} (period) and/or \code{'_'} (underscore) as separator characters. For example, \code{css(font.size = "12px")} yields \code{"font-size:12px;"}. To mark a property as \code{!important}, add a \code{'!'} character to the end of the property name. (Since \code{'!'} is not normally a character that can be used in an identifier in R, you'll need to put the name in double quotes or backticks.) Argument values will be converted to strings using \code{paste(collapse = " ")}. Any property with a value of \code{NULL} or \code{""} (after paste) will be dropped. } \examples{ padding <- 6 css( font.family = "Helvetica, sans-serif", margin = paste0(c(10, 20, 10, 20), "px"), "padding!" = if (!is.null(padding)) padding ) } htmltools/man/urlEncodePath.Rd0000644000176200001440000000064214047273610016104 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/html_dependency.R \name{urlEncodePath} \alias{urlEncodePath} \title{Encode a URL path} \usage{ urlEncodePath(x) } \arguments{ \item{x}{A character vector.} } \description{ Encode characters in a URL path. This is the same as \code{\link[utils:URLencode]{utils::URLencode()}} with \code{reserved = TRUE} except that \code{/} is preserved. } htmltools/man/builder.Rd0000644000176200001440000000726014062147721015000 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/tags.R \name{builder} \alias{builder} \alias{tags} \alias{p} \alias{h1} \alias{h2} \alias{h3} \alias{h4} \alias{h5} \alias{h6} \alias{a} \alias{br} \alias{div} \alias{span} \alias{pre} \alias{code} \alias{img} \alias{strong} \alias{em} \alias{hr} \alias{tag} \title{Create HTML tags} \usage{ tags p(..., .noWS = NULL, .renderHook = NULL) h1(..., .noWS = NULL, .renderHook = NULL) h2(..., .noWS = NULL, .renderHook = NULL) h3(..., .noWS = NULL, .renderHook = NULL) h4(..., .noWS = NULL, .renderHook = NULL) h5(..., .noWS = NULL, .renderHook = NULL) h6(..., .noWS = NULL, .renderHook = NULL) a(..., .noWS = NULL, .renderHook = NULL) br(..., .noWS = NULL, .renderHook = NULL) div(..., .noWS = NULL, .renderHook = NULL) span(..., .noWS = NULL, .renderHook = NULL) pre(..., .noWS = NULL, .renderHook = NULL) code(..., .noWS = NULL, .renderHook = NULL) img(..., .noWS = NULL, .renderHook = NULL) strong(..., .noWS = NULL, .renderHook = NULL) em(..., .noWS = NULL, .renderHook = NULL) hr(..., .noWS = NULL, .renderHook = NULL) tag(`_tag_name`, varArgs, .noWS = NULL, .renderHook = NULL) } \arguments{ \item{...}{Tag attributes (named arguments) and children (unnamed arguments). A named argument with an \code{NA} value is rendered as a boolean attributes (see example). Children may include any combination of: \itemize{ \item Other tags objects \item \code{\link[=HTML]{HTML()}} strings \item \code{\link[=htmlDependency]{htmlDependency()}}s \item Single-element atomic vectors \item \code{list()}s containing any combination of the above }} \item{.noWS}{Character vector used to omit some of the whitespace that would normally be written around this tag. Valid options include \code{before}, \code{after}, \code{outside}, \code{after-begin}, and \code{before-end}. Any number of these options can be specified.} \item{.renderHook}{A function (or list of functions) to call when the \code{tag} is rendered. This function should have at least one argument (the \code{tag}) and return anything that can be converted into tags via \code{\link[=as.tags]{as.tags()}}. Additional hooks may also be added to a particular \code{tag} via \code{\link[=tagAddRenderHook]{tagAddRenderHook()}}.} \item{_tag_name}{A character string to use for the tag name.} \item{varArgs}{List of tag attributes and children.} } \value{ A \code{list()} with a \code{shiny.tag} class that can be converted into an HTML string via \code{as.character()} and saved to a file with \code{save_html()}. } \description{ Create an R object that represents an HTML tag. For convenience, common HTML tags (e.g., \verb{
}) can be created by calling for their tag name directly (e.g., \code{div()}). To create less common HTML5 (or SVG) tags (e.g., \verb{
}), use the \code{tags} list collection (e.g., \code{tags$article()}). To create other non HTML/SVG tags, use the lower-level \code{tag()} constructor. } \examples{ tags$html( tags$head( tags$title('My first page') ), tags$body( h1('My first heading'), p('My first paragraph, with some ', strong('bold'), ' text.'), div( id = 'myDiv', class = 'simpleDiv', 'Here is a div with some attributes.' ) ) ) # html5