teal - bs345

.gitignore

@@ -1,29 +1,29 @@
-*.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

DESCRIPTION

@@ -41,6 +41,7 @@ Imports:
     teal.slice (>= 0.1.1),
     utils
 Suggests:
+    bslib,
     covr,
     dplyr,
     knitr,

NEWS.md

@@ -1,5 +1,9 @@
 # teal 0.11.1.9023
 
+### New features
+
+* Added the support for custom `bslib` bootstrap themes in `teal::init` apps, please read more in the new `teal-bs-themes` vignette.
+
 ### Enhancements
 
 * Added option to choose which variables can be filtered in the filter panel by using the `filterable` attributes for the per-dataset lists in the `filter` argument of `init`. 

R/module_teal.R

@@ -91,6 +91,7 @@ ui_teal <- function(id,
 
   res <- fluidPage(
     title = title,
+    theme = get_teal_bs_theme(),
     include_teal_css_js(),
     tags$header(header),
     tags$hr(class = "my-2"),

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 theme
+#' @keywords internal
+get_teal_bs_theme <- 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
+  }
+}

_pkgdown.yml

@@ -21,6 +21,7 @@ articles:
   - creating-custom-modules
   - adding-support-for-reporting
   - teal-options
+  - teal-bs-themes
 
 reference:
   - title: Teal Core Functions

inst/WORDLIST

@@ -4,6 +4,8 @@ ADTTE
 ADaM
 CDISC
 CSR
+Cmd
+Ctrl
 DDL
 Datanames
 Github
@@ -14,6 +16,7 @@ RSConnect
 UI
 UIs
 Ui
+UX
 anl
 bookmarkable
 cdisc
@@ -30,6 +33,7 @@ reproducibility
 schemas
 submodule
 tabsetted
+theming
 ui
 repo
 Forkers

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;
+}

tests/testthat/test-utils.R

@@ -0,0 +1,12 @@
+testthat::test_that("get_teal_bs_theme", {
+  testthat::expect_true(is.null(get_teal_bs_theme()))
+  withr::with_options(list("teal.bs_theme" = bslib::bs_theme(version = "5")), {
+    testthat::expect_s3_class(get_teal_bs_theme(), "bs_theme")
+  })
+  withr::with_options(list("teal.bs_theme" = 1), {
+    testthat::expect_warning(get_teal_bs_theme(), "the default shiny bootstrap is used")
+  })
+  withr::with_options(list("teal.bs_theme" = "bs_theme"), {
+    testthat::expect_warning(get_teal_bs_theme(), "the default shiny bootstrap is used")
+  })
+})

vignettes/teal-bs-themes.Rmd

@@ -0,0 +1,156 @@
+---
+title: "Teal and Bootstrap Themes"
+author: "NEST 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 have 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 before you run the code below.
+
+### `teal.bs_theme` R option
+
+```
+options("teal.bs_theme" = bslib::bs_theme("Custom Options"))
+
+#######################
+# teal::init() app code
+#######################
+```
+
+### bootstrap version and themes
+
+The best and recommended ways to **explore** the bootstrap themes are to use `bslib::run_with_themer(shinyApp(app$ui, app$server))` or `bslib::bs_theme_preview()`,
+both functions offer an interactive explore mode.
+Note 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 you 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(version = "5")`.
+
+```
+# bslib::versions()
+# bslib::bootswatch_themes(version = "5")
+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"))
+```
+
+Specifying only the bootstrap theme in many scenarios is not enough, please read the next section "Default bootstrap theme".
+
+### Default bootstrap theme
+
+When using the default `bslib` theme for any version (3, 4 or 5) its styling might not be as expected.
+Please run the interactive `themer` (recommended) or apply a custom theme to explore all the theme options. **In many scenarios updating only the theme might not be enough and e.g. font color and other specifications should be updated too.**
+
+```
+# instead of
+options("teal.bs_theme" =  bslib::bs_theme(version = "5"))
+# try non-default themes
+options("teal.bs_theme" = bslib::bs_theme(version = "5", bootswatch = "THEME NAME". ...))
+# or run the app inside bslib::run_with_themer
+```
+
+### Reset the bootstrap 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.
+
+### 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.
+
+### Bootstrap NULL vs 3
+
+It is important to note the difference between `options("teal.bs_theme" = NULL)` and `options("teal.bs_theme" = bslib::bs_theme(version = "3")`.
+The small differences could comes from the `bslib` approximation of the default shiny bootstrap for version 3.
+An important difference is that when using `bslib::bs_theme(version = "3", bootswatch = "THEME NAME")` we could apply the custom bootstrap theme.
+Another difference is that the usage of `bslib::bs_theme(version = "3")` requires the installation of the newest `shinyWidgets` package from the main branch, see below.
+
+```
+# Downloading the newest shinyWidgets
+# needed only when bslib::bs_theme(version = "3", ...) is used
+remotes::install_github("https://github.com/dreamRs/shinyWidgets@main")
+```
+
+### Regular `shiny::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 is not 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 `bootstrap` 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/

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`