htmlDependency: Define an HTML dependency

In htmltools: Tools for HTML

Define an HTML dependency

Description

Define an HTML dependency (i.e. CSS and/or JavaScript bundled in a directory). HTML dependencies make it possible to use libraries like jQuery, Bootstrap, and d3 in a more composable and portable way than simply using script, link, and style tags.

Usage

htmlDependency(
  name,
  version,
  src,
  meta = NULL,
  script = NULL,
  stylesheet = NULL,
  head = NULL,
  attachment = NULL,
  package = NULL,
  all_files = TRUE
)

Arguments

name	Library name
version	Library version
src	Unnamed single-element character vector indicating the full path of the library directory. Alternatively, a named character string with one or more elements, indicating different places to find the library; see Details.
meta	Named list of meta tags to insert into document head
script	Script(s) to include within the document head (should be specified relative to the src parameter).
stylesheet	Stylesheet(s) to include within the document (should be specified relative to the src parameter).
head	Arbitrary lines of HTML to insert into the document head
attachment	Attachment(s) to include within the document head. See Details.
package	An R package name to indicate where to find the src directory when src is a relative path (see resolveDependencies()).
all_files	Whether all files under the src directory are dependency files. If FALSE, only the files specified in script, stylesheet, and attachment are treated as dependency files.

Details

Each dependency can be located on the filesystem, at a relative or absolute URL, or both. The location types are indicated using the names of the src character vector: file for filesystem directory, href for URL. For example, a dependency that was both on disk and at a URL might use src = c(file=filepath, href=url).

script can be given as one of the following:

• a character vector specifying various scripts to include relative to the value of src. Each is expanded into its own ⁠<script>⁠ tag

• A named list with any of the following fields:

  • src,

  • integrity, &

  • crossorigin,

  • any other valid ⁠<script>⁠ attributes.

  allowing the use of SRI to ensure the integrity of packages downloaded from remote servers. Eg: script = list(src = "min.js", integrity = "hash")

• An unnamed list, containing a combination of named list with the fields mentioned previously, and strings. Eg:

  • script = list(list(src = "min.js"), "util.js", list(src = "log.js"))

  • script = "pkg.js" is equivalent to

  • script = list(src = "pkg.js").

attachment can be used to make the indicated files available to the JavaScript on the page via URL. For each element of attachment, an element ⁠<link id="DEPNAME-ATTACHINDEX-attachment" rel="attachment" href="...">⁠ is inserted, where DEPNAME is name. The value of ATTACHINDEX depends on whether attachment is named or not; if so, then it's the name of the element, and if not, it's the 1-based index of the element. JavaScript can retrieve the URL using something like ⁠document.getElementById(depname + "-" + index + "-attachment").href⁠. Note that depending on the rendering context, the runtime value of the href may be an absolute, relative, or data URI.

htmlDependency should not be called from the top-level of a package namespace with absolute paths (or with paths generated by system.file()) and have the result stored in a variable. This is because, when a binary package is built, R will run htmlDependency and store the path from the building machine's in the package. This path is likely to differ from the correct path on a machine that downloads and installs the binary package. If there are any absolute paths, instead of calling htmlDependency at build-time, it should be called at run-time. This can be done by wrapping the htmlDependency call in a function.

Value

An object that can be included in a list of dependencies passed to attachDependencies().

See Also

Use attachDependencies() to associate a list of dependencies with the HTML it belongs with. The shape of the htmlDependency object is described (in TypeScript code) here.

htmltools documentation built on May 29, 2024, 5:19 a.m.