@@ -7,4 +7,284 @@ vignette: >
77 %\VignetteEncoding{UTF-8}
88---
99
10- # TODO: add content
10+ ## Use bslib with Golem
11+
12+ When you create a new Golem application, ` app_ui.R ` is created with the ` shiny::fluidPage() ` function.
13+
14+ By default, the ` fluidPage() ` function uses ** Bootstrap 3** .
15+
16+ It is possible to use ** Bootstrap 4** or ** Bootstrap 5** with the ` bslib ` package.
17+
18+ First make sure you have the ` bslib ` package installed:
19+
20+ ``` r
21+ install.packages(" bslib"
22+ ```
23+
24+ Then, we need to modify the ` app_ui.R ` file to use ` bslib ` .
25+
26+ ### Modify the ` app_ui.R ` file
27+
28+ In the ` app_ui.R ` file, create a new function:
29+
30+ ``` {r eval=FALSE}
31+ #' @import bslib
32+ #' @noRd
33+ my_application_theme <- function(version = bslib::version_default()) {
34+ bs_theme(
35+ version = version
36+ )
37+ }
38+ ```
39+
40+ Then, modify the ` fluidPage() ` function to use the ` my_application_theme() ` function:
41+
42+ ``` {r eval=FALSE}
43+ #' The application User-Interface
44+ #'
45+ #' @param request Internal parameter for `{shiny}`.
46+ #' DO NOT REMOVE.
47+ #' @import shiny
48+ #' @noRd
49+ app_ui <- function(request) {
50+ tagList(
51+ # Leave this function for adding external resources
52+ golem_add_external_resources(),
53+ # Your application UI logic
54+ fluidPage(
55+ theme = my_application_theme(),
56+ h1("Hello"),
57+ h2("This is a h2 title"),
58+ actionButton(
59+ inputId = "go",
60+ label = "Click me"
61+ )
62+ )
63+ )
64+ }
65+ ```
66+
67+ ::: {.callout .callout-note}
68+ ::: {.callout-body}
69+ Note that we remove the ` golem::golem_welcome_page() ` function to add some content to the ` fluidPage() ` function.
70+
71+ :::
72+ :::
73+
74+ Now your application uses ` bslib ` with the default version.
75+
76+ If you want to use specifically Bootstrap 5, you can modify the ` my_application_theme() ` function:
77+
78+ ``` {r eval=FALSE}
79+ my_application_theme <- function() {
80+ bs_theme(
81+ version = 5
82+ )
83+ }
84+ ```
85+
86+ We also recomand to use the ` bslib ` page fluid function:
87+
88+ ``` {r eval=FALSE}
89+ app_ui <- function(request) {
90+ tagList(
91+ # Leave this function for adding external resources
92+ golem_add_external_resources(),
93+ # Your application UI logic
94+ bslib::page_fluid(
95+ theme = my_application_theme(),
96+ h1("Hello"),
97+ h2("This is a h2 title"),
98+ actionButton(
99+ inputId = "go",
100+ label = "Click me"
101+ )
102+ )
103+ )
104+ }
105+ ```
106+
107+ More information about ` bslib ` page layout can be found [ here] ( https://rstudio.github.io/bslib/reference/page.html ) .
108+
109+
110+ ## Change the theme of your application
111+
112+ Once you have set up ` bslib ` , you can change the theme of your application by modifying the ` my_application_theme() ` function.
113+
114+ For example, to use the ` cerulean ` theme:
115+
116+ ``` {r eval=FALSE}
117+ my_application_theme <- function(version = bslib::version_default()) {
118+ bs_theme(
119+ version = version,
120+ bootswatch = "sketchy"
121+ )
122+ }
123+ ```
124+
125+ ``` {r, echo=FALSE, fig.align="center", out.width="100%"}
126+ knitr::include_graphics("sketchy_theme.png")
127+ ```
128+
129+ You can find the list of available themes with ` bslib::bootswatch_themes() ` or on the bootswatch website: < https://bootswatch.com/ > .
130+
131+ ## Customize your application with your own variables
132+
133+ You can also use your own variables with ` bslib ` .
134+
135+ For example, to use a custom color:
136+
137+ ``` {r eval=FALSE}
138+ my_application_theme <- function(version = bslib::version_default()) {
139+ bs_theme(
140+ version = version,
141+ bootswatch = "sketchy",
142+ bg = "#dedede",
143+ fg = "#eca72b",
144+ primary = "#e91e63"
145+ )
146+ }
147+ ```
148+
149+ We modify the ` actionButton ` function to use the ` btn-primary ` class:
150+
151+ ``` {r eval=FALSE}
152+ app_ui <- function(request) {
153+ tagList(
154+ # Leave this function for adding external resources
155+ golem_add_external_resources(),
156+ # Your application UI logic
157+ bslib::page_fluid(
158+ theme = my_application_theme(),
159+ h1("Hello"),
160+ h2("This is a h2 title"),
161+ actionButton(
162+ inputId = "go",
163+ label = "Click me",
164+ class = "btn-primary"
165+ )
166+ )
167+ )
168+ }
169+ ```
170+
171+ ``` {r, echo=FALSE, fig.align="center", out.width="100%"}
172+ knitr::include_graphics("sketchy_theme_custom.png")
173+ ```
174+
175+ ::: {.callout .callout-note}
176+ ::: {.callout-body}
177+ Use a bootswatch theme is not mandatory, you can use your own variables to fully customize your application.
178+
179+ More details about Bootstrap variables can be found [ here] ( https://rstudio.github.io/bslib/articles/bs5-variables/index.html ) .
180+ :::
181+ :::
182+
183+ ## Use a dark theme
184+
185+ To use a dark theme, you can modify the ` my_application_theme() ` function:
186+
187+ ``` {r eval=FALSE}
188+ my_application_theme <- function(
189+ version = bslib::version_default(),
190+ dark = FALSE) {
191+ if (dark) {
192+ bslib::bs_theme(
193+ version = version,
194+ bootswatch = "sketchy",
195+ bg = "#2c2c2c",
196+ fg = "#ffffff",
197+ primary = "#db5ddb"
198+ )
199+ } else {
200+ bs_theme(
201+ version = version,
202+ bootswatch = "sketchy",
203+ bg = "#dedede",
204+ fg = "#eca72b",
205+ primary = "#e91e63"
206+ )
207+ }
208+ }
209+ ```
210+
211+ We added a ` dark ` argument to the ` my_application_theme() ` function.
212+
213+ To see the dark theme, you can modify the ` app_ui ` function:
214+
215+ ``` {r eval=FALSE}
216+ app_ui <- function(request) {
217+ tagList(
218+ # Leave this function for adding external resources
219+ golem_add_external_resources(),
220+ # Your application UI logic
221+ bslib::page_fluid(
222+ theme = my_application_theme(dark = TRUE),
223+ h1("Hello"),
224+ h2("This is a h2 title"),
225+ actionButton(
226+ inputId = "go",
227+ label = "Click me",
228+ class = "btn-primary"
229+ )
230+ )
231+ )
232+ }
233+ ```
234+
235+ ``` {r, echo=FALSE, fig.align="center", out.width="100%"}
236+ knitr::include_graphics("sketchy_theme_dark.png")
237+ ```
238+
239+ Now, we'd like to be able to switch between the light and dark theme. We can add a ` switchInput ` to the UI:
240+
241+ They are several ways to do this. Here some of them:
242+
243+ ### Using bslib toggle input
244+
245+ In the ` app_ui ` function, we add a ` bslib::input_dark_mode ` function:
246+
247+ ``` {r eval=FALSE}
248+ app_ui <- function(request) {
249+ tagList(
250+ # Leave this function for adding external resources
251+ golem_add_external_resources(),
252+ # Your application UI logic
253+ bslib::page_fluid(
254+ theme = my_application_theme(dark = TRUE),
255+ bslib::input_dark_mode(),
256+ h1("Hello"),
257+ h2("This is a h2 title"),
258+ actionButton(
259+ inputId = "go",
260+ label = "Click me",
261+ class = "btn-primary"
262+ )
263+ )
264+ )
265+ }
266+ ```
267+
268+ ``` {r, echo=FALSE, fig.align="center", out.width="100%"}
269+ knitr::include_graphics("bslib_input_dark_mode.gif")
270+ ```
271+
272+ ### Using your own button
273+
274+ It's also possible to switch between the light and dark theme with your own button.
275+
276+ Choose where you want to place the button (or any other input) in your UI. Then, in the server side, you can swith the theme with the ` bslib::toggle_dark_mode() ` function:
277+
278+ ``` {r eval=FALSE}
279+ app_server <- function(input, output, session) {
280+ # Your application server logic
281+
282+ observeEvent(input$go, {
283+ bslib::toggle_dark_mode()
284+ })
285+ }
286+ ```
287+
288+ ``` {r, echo=FALSE, fig.align="center", out.width="100%"}
289+ knitr::include_graphics("bslib_toggle_dark.gif")
290+ ```
0 commit comments