EVOLUTION-MANAGER

Edit File: bs_dependency.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Themeable HTML components</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for bs_dependency {bslib}"><tr><td>bs_dependency {bslib}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Themeable HTML components</h2>

<h3>Description</h3>

<p>Themeable HTML components use Sass to generate CSS rules from Bootstrap Sass
variables, functions, and/or mixins (i.e., stuff inside of <code>theme</code>).
<code>bs_dependencies()</code> makes it a bit easier to create themeable components by
compiling <code><a href="../../sass/html/sass.html">sass::sass()</a></code> (<code>input</code>) together with Bootstrap Sass inside of a
<code>theme</code>, and packaging up the result into an <code><a href="../../htmltools/html/htmlDependency.html">htmlDependency()</a></code>.
</p>
<p>Themable components can also be  <em>dynamically</em> themed inside of Shiny (i.e.,
they may be themed in 'real-time' via <code><a href="run_with_themer.html">bs_themer()</a></code>, and more generally,
update their styles in response to <a href="../../shiny/html/session.html">shiny::session</a>'s <code>setCurrentTheme()</code>
method). Dynamically themeable components provide a &quot;recipe&quot; (i.e., a
function) to <code>bs_dependency_defer()</code>, describing how to generate new CSS
stylesheet(s) from a new <code>theme</code>. This function is called when the HTML page
is first rendered, and may be invoked again with a new <code>theme</code> whenever
<a href="../../shiny/html/session.html">shiny::session</a>'s <code>setCurrentTheme()</code> is called.
</p>

<h3>Usage</h3>

<pre>
bs_dependency(
  input = list(),
  theme,
  name,
  version,
  cache_key_extra = NULL,
  .dep_args = list(),
  .sass_args = list()
)

bs_dependency_defer(func, memoise = TRUE)
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>input</code></td>
<td>
<p>Sass rules to compile, using <code>theme</code>.</p>
</td></tr>
<tr valign="top"><td><code>theme</code></td>
<td>
<p>A <code><a href="bs_theme.html">bs_theme()</a></code> object.</p>
</td></tr>
<tr valign="top"><td><code>name</code></td>
<td>
<p>Library name</p>
</td></tr>
<tr valign="top"><td><code>version</code></td>
<td>
<p>Library version</p>
</td></tr>
<tr valign="top"><td><code>cache_key_extra</code></td>
<td>
<p>Extra information to add to the sass cache key. It is
useful to add the version of your package.</p>
</td></tr>
<tr valign="top"><td><code>.dep_args</code></td>
<td>
<p>A list of additional arguments to pass to
<code><a href="../../htmltools/html/htmlDependency.html">htmltools::htmlDependency()</a></code>. Note that <code>package</code> has no effect and
<code>script</code> must be absolute path(s).</p>
</td></tr>
<tr valign="top"><td><code>.sass_args</code></td>
<td>
<p>A list of additional arguments to pass to
<code><a href="../../sass/html/sass_partial.html">sass::sass_partial()</a></code>.</p>
</td></tr>
<tr valign="top"><td><code>func</code></td>
<td>
<p>a <em>non-anonymous</em> function, with a <em>single</em> argument.
This function should accept a <code><a href="bs_theme.html">bs_theme()</a></code> object and return a single
<code><a href="../../htmltools/html/htmlDependency.html">htmlDependency()</a></code>, a list of them, or <code>NULL</code>.</p>
</td></tr>
<tr valign="top"><td><code>memoise</code></td>
<td>
<p>whether or not to memoise (i.e., cache) <code>func</code> results for a
short period of time. The default, <code>TRUE</code>, can have large performance
benefits when many instances of the same themable widget are rendered. Note
that you may want to avoid memoisation if <code>func</code> relies on side-effects
(e.g., files on-disk) that need to change for each themable widget
instance.</p>
</td></tr>
</table>

<h3>Value</h3>

<p><code>bs_dependency()</code> returns an <code><a href="../../htmltools/html/htmlDependency.html">htmltools::htmlDependency()</a></code> and
<code>bs_dependency_defer()</code> returns an <code><a href="../../htmltools/html/tagFunction.html">htmltools::tagFunction()</a></code>
</p>

<h3>References</h3>

<p><a href="https://rstudio.github.io/bslib/articles/custom-components.html">https://rstudio.github.io/bslib/articles/custom-components.html</a>
</p>

<h3>Examples</h3>

<pre>

## Not run:

myWidgetVersion &lt;- "1.2.3"

myWidgetDependency &lt;- function() {
  list(
    bs_dependency_defer(myWidgetCss),
    htmlDependency(
      name = "mywidget-js",
      version = myWidgetVersion,
      src = system.file(package = "mypackage", "js"),
      script = "mywidget.js"
    )
  )
}

myWidgetCSS &lt;- function(theme) {
  if (!is_bs_theme(theme)) {
    return(
      htmlDependency(
        name = "mywidget-css",
        version = myWidgetVersion,
        src = system.file(package = "mypackage", "css"),
        stylesheet = "mywidget.css"
      )
    )
  }

# Compile mywidget.scss using the variables and defaults from the theme
  # object.
  sass_input &lt;- sass::sass_file(system.file(package = "mypackage", "scss/mywidget.scss"))

bs_dependency(
    input = sass_input,
    theme = theme,
    name = "mywidget",
    version = myWidgetVersion,
    cache_key_extra = utils::packageVersion("mypackage")
  )
}

# Note that myWidgetDependency is not defined inside of myWidget. This is so
# that, if `myWidget()` is called multiple times, Shiny can tell that the
# function objects are identical and deduplicate them.
myWidget &lt;- function(id) {
  div(
    id = id,
    span("myWidget"),
    myWidgetDependency()
  )
}

## End(Not run)

</pre>

<hr /><div style="text-align: center;">[Package <em>bslib</em> version 0.4.0 <a href="00Index.html">Index</a>]</div>
</body></html>