bootstraplib (version 0.1.0.9000)

bs_theme_new: Create a Bootstrap theme

Description

bs_theme_new() creates a new (global) Bootstrap Sass theme which bootstrap() (or bootstrap_sass()) can consume (their theme argument defaults to bs_theme_get(), which get the current global theme). Once a global theme has been created, use bs_theme_add_variables() to set Sass variable defaults and bs_theme_add() to add arbitrary Sass (via sass::sass_layer()s).

Usage

bs_theme_new(version = version_default(), bootswatch = NULL)
bs_theme_add_variables(
  ...,
  .where = "defaults",
  .default_flag = identical(.where, "defaults")
)
bs_theme_add(defaults = "", declarations = "", rules = "", ...)
bs_theme_get()
bs_theme_clear()
bs_theme_set(theme)

Arguments

version

The major version of Bootstrap to use. A value of '4+3' means Bootstrap 4, but with additional CSS/JS to support BS3 style markup in BS4. Other supported versions include 3 and 4.

bootswatch

The name of a bootswatch theme. See bootswatch_themes() to list possible names.

...

For bs_theme_add_variables(), these arguments define Sass variables; otherwise, these arguments are passed along to sass::sass_layer().

.where

whether to place the variable definitions before other Sass "defaults", after other Sass "declarations", or after other Sass "rules".

.default_flag

whether or not to add a !default flag (if missing) to variable expressions. It's recommended to keep this as TRUE when .where = "defaults".

defaults

Any sass::as_sass() input to place before Bootstrap's Sass.

declarations

Any sass::as_sass() input to place after Bootstrap's variables, functions, and mixins, but before Bootstrap's styling rules.

rules

Any sass::as_sass() input to place after Bootstrap's Sass imports.

theme

a theme object (i.e., the return value of bs_theme_get()).

References

https://getbootstrap.com/docs/4.4/getting-started/theming/

https://rstudio.github.io/sass/

Examples

# NOT RUN {
# Function to preview the styling a (primary) Bootstrap button
library(htmltools)
button <- tags$a(class = "btn btn-primary", href = "#", role = "button", "Hello")
preview_button <- function(x) {
  browsable(tags$body(x, button))
}

# To create a custom theme, you must start by calling bs_theme_new()
# Here we start with a theme based on a Bootswatch theme,
# then override some variable defaults
bs_theme_new(bootswatch = "sketchy")
bs_theme_add_variables(
  primary = "orange",
  "body-bg" = "#EEEEEE",
  "font-family-base" = "monospace",
  "font-size-base" = "1.4rem",
  "btn-padding-y" = ".16rem",
  "btn-padding-x" = "2rem",
  "border-radius" = 0,
  "border-radius-lg" = 0,
  "border-radius-sm" = 0
)
preview_button(bootstrap())

# If you need to set a variable based on another Bootstrap variable
bs_theme_add_variables(
  "body-color" = "$success",
  .where = "declarations"
)
preview_button(bootstrap())

# Start a new global theme and add some custom rules that
# use Bootstrap variables to define a custom styling for a
# 'person card'
bs_theme_new()
bs_theme_add(
  rules = sass::sass_file(
    system.file("custom", "person.scss", package = "bootstraplib")
  )
)
# Include custom CSS that leverages bootstrap Sass variables
person <- function(name, title, company) {
  tags$div(
    class = "person",
    h3(class = "name", name),
    div(class = "title", title),
    div(class = "company", company)
  )
}
browsable(tags$body(
  bootstrap(),
  person("Andrew Carnegie", "Owner", "Carnegie Steel Company"),
  person("John D. Rockefeller", "Chairman", "Standard Oil")
))


# Once a theme has been set, you can get it, and see which
# version/bootswatch was specified
bs_theme_new(bootswatch = "cosmo")
theme <- bs_theme_get()
theme_version(theme)
theme_bootswatch(theme)

# Themes are just sass_layer(), so you can work with them locally
# just like any other sass layer
# https://rstudio.github.io/sass/articles/sass.html#layers
class(theme)
layer <- sass::sass_layer("$primary: red")
theme <- sass::sass_layer_merge(theme, layer)
bs_theme_set(theme)

# }