htmltools/ 0000755 0001762 0000144 00000000000 14521223427 012301 5 ustar ligges users htmltools/NAMESPACE 0000644 0001762 0000144 00000005331 14521211174 013516 0 ustar ligges users # 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(save_html,default)
S3method(str,shiny.tag.env)
export("htmlDependencies<-")
export(HTML)
export(a)
export(as.tags)
export(attachDependencies)
export(bindFillRole)
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.html_dependency)
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)
importFrom(rlang,obj_address)
useDynLib(htmltools, .registration = TRUE)
htmltools/man/ 0000755 0001762 0000144 00000000000 14521211174 013050 5 ustar ligges users htmltools/man/htmlPreserve.Rd 0000644 0001762 0000144 00000004432 14510021165 016017 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001351 14510021165 015514 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000002104 14510021165 017741 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000000705 14510021165 014745 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001564 14521211174 015327 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/html_print.R
\name{save_html}
\alias{save_html}
\alias{save_html.default}
\title{Save an HTML object to a file}
\usage{
save_html(html, file, ...)
\method{save_html}{default}(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{...}{Further arguments passed to other methods.}
\item{background}{Background color for web page.}
\item{libdir}{Directory to copy dependencies to.}
\item{lang}{Value of the \verb{} \code{lang} attribute.}
}
\description{
An S3 generic method for saving an HTML-like object to a file. The default
method copies dependency files to the directory specified via \code{libdir}.
}
htmltools/man/validateCssUnit.Rd 0000644 0001762 0000144 00000002353 14510021165 016441 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000003356 14510021165 015441 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001626 14510021165 015622 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001043 14510021165 016561 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000000771 14510021165 015426 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000002456 14510021165 014766 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001647 14510021165 015324 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001661 14510021165 017126 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000005545 14510021165 014757 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000002667 14510021165 016314 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000003471 14510021165 017313 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001247 14510021165 016551 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000001230 14510021165 015332 0 ustar ligges users % 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/htmltools-package.Rd 0000644 0001762 0000144 00000002151 14510021165 016751 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htmltools-package.R
\docType{package}
\name{htmltools-package}
\alias{htmltools}
\alias{htmltools-package}
\title{htmltools: Tools for HTML}
\description{
\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}
Tools for HTML generation and output.
}
\seealso{
Useful links:
\itemize{
\item \url{https://github.com/rstudio/htmltools}
\item \url{https://rstudio.github.io/htmltools/}
\item Report bugs at \url{https://github.com/rstudio/htmltools/issues}
}
}
\author{
\strong{Maintainer}: Carson Sievert \email{carson@posit.co} (\href{https://orcid.org/0000-0002-4958-2844}{ORCID})
Authors:
\itemize{
\item Joe Cheng \email{joe@posit.co}
\item Barret Schloerke \email{barret@posit.co} (\href{https://orcid.org/0000-0001-9986-114X}{ORCID})
\item Winston Chang \email{winston@posit.co} (\href{https://orcid.org/0000-0002-1576-2126}{ORCID})
\item Yihui Xie \email{yihui@posit.co}
\item Jeff Allen
}
Other contributors:
\itemize{
\item Posit Software, PBC [copyright holder, funder]
}
}
\keyword{internal}
htmltools/man/tagQuery.Rd 0000644 0001762 0000144 00000013666 14510021165 015151 0 ustar ligges users % 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()}.
}
\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{Altered Tag structure}{
For performance reasons, the input tag structure to \code{tagQuery()} will be
altered into a consistently expected shape.
Some alterations include:
\itemize{
\item tags flattening their \verb{$children} fields into a single \code{list()}
\item tags relocating any attribute \verb{html_dependency() to be located in }$children`
\item \code{tagList()}-like structures relocating any attribute html dependency to
be a entry in its list structure.
}
While the resulting tag shape has possibly changed,
\code{tagQuery()}'s' resulting tags will still render
to the same HTML value (ex: \code{\link[=renderTags]{renderTags()}}) and
HTML dependencies (ex: \code{\link[=findDependencies]{findDependencies()}}).
}
\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{$allTags()} 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.Rd 0000644 0001762 0000144 00000002372 14510021165 016562 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000003233 14510021165 014125 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000000642 14510021165 016073 0 ustar ligges users % 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.Rd 0000644 0001762 0000144 00000007260 14510021165 014767 0 ustar ligges users % 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