insightsengineering · donyunardi · Sep 27, 2022 · Sep 5, 2022 · Sep 5, 2022 · Sep 6, 2022
diff --git a/.gitignore b/.gitignore
@@ -1,29 +1,31 @@
-*.Rcheck
-*.html
-*.rprof
-*.sas.txt
-*~
-.DS_Store
-.RData
-.Rhistory
-.Rproj.user
-.Ruserdata
-.httr-oauth
-.project
-.settings/**
-/.project
-Meta
-coverage.*
-devel/*
-doc
-docs
-inst/outputs/*
-logs
-packrat/lib*/
-temp
-temp_w
-templates/
-tmp.*
-vignettes/*.R
-vignettes/*.html
-vignettes/*.md
+*.Rcheck
+*.html
+*.rprof
+*.sas.txt
+*~
+.DS_Store
+.RData
+.Rhistory
+.Rproj.user
+.Ruserdata
+.httr-oauth
+.project
+.settings/**
+/.project
+Meta
+coverage.*
+devel/*
+doc
+docs
+inst/outputs/*
+logs
+packrat/lib*/
+temp
+temp_w
+templates/
+tmp.*
+vignettes/*.R
+vignettes/*.html
+vignettes/*.md
+/doc/
+/Meta/
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -41,6 +41,7 @@ Imports:
     teal.slice (>= 0.1.1),
     utils
 Suggests:
+    bslib,
     covr,
     dplyr,
     knitr,

diff --git a/R/module_teal.R b/R/module_teal.R
@@ -91,6 +91,7 @@ ui_teal <- function(id,
 
   res <- fluidPage(
     title = title,
+    theme = get_teal_bs_version(),
     include_teal_css_js(),
     tags$header(header),
     tags$hr(class = "my-2"),

diff --git a/R/utils.R b/R/utils.R
@@ -19,3 +19,17 @@ get_client_timezone <- function(ns) {
   shinyjs::runjs(script) # function does not return anything
   return(invisible(NULL))
 }
+
+#' Resolve the expected bootstrap version
+#' @keywords internal
+get_teal_bs_version <- function() {
+  bs_theme <- getOption("teal.bs_theme")
+  if (is.null(bs_theme)) {
+    NULL
+  } else if (!inherits(bs_theme, "bs_theme")) {
+    warning("teal.bs_theme has to be of a bslib::bs_theme class, the default shiny bootstrap is used.")
+    NULL
+  } else {
+    bs_theme
+  }
+}
diff --git a/inst/css/custom.css b/inst/css/custom.css
@@ -60,3 +60,7 @@ footer {
   font-size: 0.8em;
   opacity: 0.6;
 }
+
+#teal_secondary_col .well {
+  margin: 0  0 15px 0;
+}
diff --git a/man/get_teal_bs_version.Rd b/man/get_teal_bs_version.Rd
diff --git a/vignettes/teal-bs-themes.Rmd b/vignettes/teal-bs-themes.Rmd
@@ -0,0 +1,127 @@
+---
+title: "Teal and Bootstrap Themes"
+author: "Coredev"
+date: "2022-09-08"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Teal and Bootstrap Themes}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Introduction
+
+We offer the easy application of a custom bootstrap theme to a `teal::init` app. 
+Teal is a consumer of the `bslib` R package which provides tools for customizing Bootstrap themes e.g. of Shiny apps.
+
+## Usage
+
+Teal users take the benefit of custom bootstrap themes by specifying the `teal.bs_theme` R  option, which has to be set to `bslib::bs_theme` object.
+The `bslib::bs_theme(...)` function creates a Bootstrap theme object, where you should specify the (major) Bootstrap version (default or one of 3, 4 or 5).
+Optionally you could choose a **Bootswatch theme** and **customize the app css** with functions like `bslib::bs_add_rules`.
+Please read more about custom themes in [the bslib getting started vignette](https://rstudio.github.io/bslib/articles/bslib.html).
+The `teal.bs_theme` R option has to be specified at the top of the code script.
+
+Please install `bslib` package if not already installed
+
+### `teal.bs_theme` R option
+
+```
+options("teal.bs_theme" = bslib::bs_theme("Custom Options"))
+
+#######################
+# teal::init() app code
+#######################
+```
+
+### bootstrap version and themes
+
+The best way to **explore** the bootstrap themes is to use `bslib::run_with_themer(shinyApp(app$ui, app$server))` or `bslib::bs_theme_preview()`,
+both functions offer an interactive explore mode.
+Please, remember that the interactive theming for Bootstrap 3 is not supported.
+The `bslib::bs_theme_preview()` is recommended when the end user does not have any shiny app yet. 
+When you already have a shiny app and want to test different bootstrap themes (and css styling) then `bslib::run_with_themer(shinyApp(app$ui, app$server))` is recommended.
+
+Available bootstrap versions could be checked with `bslib::versions()` and bootstrap themes (bootswatch) with `bslib::bootswatch_themes()`.
+
+```
+# bslib::bootswatch_themes()
+# bslib::versions()
+options("teal.bs_theme" = bslib::bs_theme(version = "5", bootswatch = "lux")
+# or
+options("teal.bs_theme" = bslib::bs_theme_update(bslib::bs_theme(version = "5"), bootswatch = "lux"))
+```
+
+### custom teal css
+
+The most important `teal` html tags have a proper id/class, so they could be directly styled.
+The `bslib::bs_add_rules` function could be used around the `bslib::bs_theme` object to apply custom css rules.
+
+```
+library(magrittr)
+options("teal.bs_theme" = bslib::bs_theme(version = "5") %>% bslib::bs_add_rules("Anything understood by sass::as_sass()"))
+```
+
+Other `bslib::bs_add_*` family functions could be used to specify low-level bootstrap elements.
+
+### reset the bs theme
+
+Please use the `options("teal.bs_theme" = NULL)` call to return to the default shiny bootstrap for teal apps.
+
+### theme not updated
+
+One reason the theme is not updated could be the problem that a browser caches the previous one, especially when we run different themes one after another.
+Please, use the Cmd+Shift+r (Mac) or Ctrl+F5 (Windows) to hard refresh the webpage.
+
+### regular fluidPage
+
+If you want to update the theme in the regular `shiny::fluidPage` like app, you do not need the `teal.bs_theme` option. Then simply provide the `bslib::bs_theme` directly to the `shiny::fluidPage(theme = bslib::bs_theme(...), ...)`. 
+
+### Examples
+
+With `bslib::run_with_themer` to explore different themes.
+Please, remember that the interactive theming for Bootstrap 3 isn't supported.
+
+
+```{r, message=FALSE}
+options("teal.bs_theme" = bslib::bs_theme(version = "5"))
+library(teal)
+
+app <- init(
+  data = teal_data(
+    dataset("IRIS", iris),
+    dataset("MTCARS", mtcars)
+  ),
+  modules = modules(example_module(), example_module()),
+  header = "My first teal application"
+)
+
+if (interactive()) {
+  # Run with themer
+  bslib::run_with_themer(shinyApp(app$ui, app$server))
+}
+```
+
+Apply the already chosen theme with `options("teal.bs_theme" = bslib::bs_theme(...))`, in this example the `lux` theme from Boostrap version 5.
+
+```{r, message=FALSE}
+options("teal.bs_theme" = bslib::bs_theme(version = "5", bootswatch = "lux"))
+library(teal)
+
+app <- init(
+  data = teal_data(
+    dataset("IRIS", iris),
+    dataset("MTCARS", mtcars)
+  ),
+  modules = modules(example_module(), example_module()),
+  header = "My first teal application"
+)
+
+if (interactive()) {
+  shinyApp(app$ui, app$server)
+}
+```
+
+## Sources
+
+- https://rstudio.github.io/bslib/
diff --git a/vignettes/teal-options.Rmd b/vignettes/teal-options.Rmd
@@ -75,7 +75,7 @@ This specifies the list of arguments passed to every call to `rtables::basic_tab
 
 Default: `teal.widgets::basic_table_args()`.
 
-### `teal.ggplot2_args`
+### `teal.ggplot2_args` (`ggplot2_args` object)
 This option allows modifying labels and themes of all `ggplot2` plots in a `teal` application. See the documentation of `teal.widgets::ggplot2_args` for more information.
 
 Default: `teal.widgets::ggplot2_args()`.
@@ -84,3 +84,9 @@ Default: `teal.widgets::ggplot2_args()`.
 This option controls the dots per inch of the graphs rendered and downloaded when using `plot_with_settings`. 
 
 Default: 72
+
+### `teal.bs_theme` (`bslib::bs_theme` object)
+This option controls the bootstrap theme and version used in the teal apps. Achieve better UX with the customized UI of an app.
+Please visit the `vignette("teal-bs-themes", package = "teal")` to read more about the functionality.
+
+Default: `NULL`
-Original file line number
+Diff line change
@@ Expand Up / @@ -41,6 +41,7 @@ Imports: @@
         teal.slice (>= 0.1.1),
         utils
     Suggests:
+        bslib,
         covr,
         dplyr,
         knitr,
@@ Expand Down @@