Skip to content

Commit 212d1f7

Browse files
gadenbuiecpsievert
gadenbuie
and
cpsievert
authored
docs(pkgdown): Re-organize and add descriptions to reference index (#842)
Co-authored-by: Carson Sievert <[email protected]>
1 parent 8c7d1c9 commit 212d1f7

22 files changed

+680
-219
lines changed

‎R/fill.R‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
#' non-tag objects that have a [as.tags] method (e.g., htmlwidgets), they return
1616
#' the "tagified" version of that object.
1717
#'
18-
#' @examplesIf interactive()
18+
#' @examplesIf rlang::is_interactive()
1919
#' library(shiny)
2020
#' shinyApp(
2121
#' page_fillable(

‎R/input-switch.R‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
#'
66
#' Create an on-off style switch control for specifying logical values.
77
#'
8-
#' @examplesIf interactive()
8+
#' @examplesIf rlang::is_interactive()
99
#' library(shiny)
1010
#' library(bslib)
1111
#'

‎R/layout.R‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
#' A grid-like, column-first, layout
1+
#' Column-first uniform grid layouts
22
#'
33
#' @description
44
#' `r lifecycle::badge("experimental")`
@@ -110,7 +110,7 @@ layout_column_wrap <- function(
110110
)
111111
}
112112

113-
#' Responsive column-based grid layouts
113+
#' Responsive 12-column grid layouts
114114
#'
115115
#' Create responsive, column-based grid layouts, based on a 12-column grid.
116116
#'
@@ -146,7 +146,7 @@ layout_column_wrap <- function(
146146
#'
147147
#' @export
148148
#' @seealso [breakpoints()] for more information on breakpoints.
149-
#' @examplesIf interactive()
149+
#' @examplesIf rlang::is_interactive()
150150
#'
151151
#'
152152
#' x <- card("A simple card")

‎R/page.R‎

Lines changed: 171 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
# page constructors from shiny so folks can create static
33
# pages without a shiny dependency.
44

5-
#' Create a Bootstrap page
5+
#' Modern Bootstrap page layouts
66
#'
77
#' These functions are small wrappers around shiny's page constructors (i.e.,
88
#' [shiny::fluidPage()], [shiny::navbarPage()], etc) that differ in two ways:
@@ -12,7 +12,10 @@
1212
#' @inheritParams shiny::bootstrapPage
1313
#' @param ... UI elements for the page. Named arguments become HTML attributes.
1414
#' @param theme A [bslib::bs_theme()] object.
15-
#' @seealso [page_sidebar()]
15+
#'
16+
#' @seealso Dashboard-style pages: [page_sidebar()], [page_navbar()],
17+
#' [page_fillable()].
18+
#'
1619
#' @export
1720
page <- function(..., title = NULL, theme = bs_theme(), lang = NULL) {
1821
# Wrap ... in <body> since bootstrapPage() passes ... to tagList(),
@@ -51,8 +54,14 @@ page_fixed <- function(..., title = NULL, theme = bs_theme(), lang = NULL) {
5154
)
5255
}
5356

54-
#' @describeIn page `r lifecycle::badge("experimental")` A Bootstrap-based page
55-
#' layout whose contents fill the full height and width of the browser window.
57+
#' A screen-filling page layout
58+
#'
59+
#' @description
60+
#' `r lifecycle::badge("experimental")`
61+
#'
62+
#' A Bootstrap-based page layout whose contents fill the full height and width
63+
#' of the browser window.
64+
#'
5665
#' @param padding Padding to use for the body. This can be a numeric vector
5766
#' (which will be interpreted as pixels) or a character vector with valid CSS
5867
#' lengths. The length can be between one and four. If one, then that value
@@ -65,8 +74,89 @@ page_fixed <- function(..., title = NULL, theme = bs_theme(), lang = NULL) {
6574
#' height on mobile devices (i.e., narrow windows).
6675
#' @param gap A [CSS length unit][htmltools::validateCssUnit()] defining the
6776
#' `gap` (i.e., spacing) between elements provided to `...`.
77+
#' @inheritParams page
78+
#'
6879
#' @export
69-
page_fillable <- function(..., padding = NULL, gap = NULL, fillable_mobile = FALSE, title = NULL, theme = bs_theme(), lang = NULL) {
80+
#' @family Dashboard page layouts
81+
#'
82+
#' @seealso [layout_columns()] and [layout_column_wrap()] for laying out content
83+
#' into rows and columns.
84+
#' @seealso [layout_sidebar()] for 'floating' sidebar layouts.
85+
#' @seealso [accordion()] for grouping related input controls in the `sidebar`.
86+
#' @seealso [card()] for wrapping outputs in the 'main' content area.
87+
#' @seealso [value_box()] for highlighting values.
88+
#'
89+
#' @references
90+
#' * [Filling Layouts](https://rstudio.github.io/bslib/articles/filling/index.html)
91+
#' on the bslib website.
92+
#' * [Getting Started with Dashboards](https://rstudio.github.io/bslib/articles/dashboards/index.html)
93+
#' on the bslib website.
94+
#'
95+
#' @examplesIf rlang::is_interactive()
96+
#'
97+
#' library(shiny)
98+
#' library(ggplot2)
99+
#'
100+
#' ui <- page_fillable(
101+
#' h1("Example", code("mtcars"), "dashboard"),
102+
#' layout_columns(
103+
#' card(
104+
#' full_screen = TRUE,
105+
#' card_header("Number of forward gears"),
106+
#' plotOutput("gear")
107+
#' ),
108+
#' card(
109+
#' full_screen = TRUE,
110+
#' card_header("Number of carburetors"),
111+
#' plotOutput("carb")
112+
#' )
113+
#' ),
114+
#' card(
115+
#' full_screen = TRUE,
116+
#' card_header("Weight vs. Quarter Mile Time"),
117+
#' layout_sidebar(
118+
#' sidebar = sidebar(
119+
#' varSelectInput("var_x", "Compare to qsec:", mtcars[-7], "wt"),
120+
#' varSelectInput("color", "Color by:", mtcars[-7], "cyl"),
121+
#' position = "right"
122+
#' ),
123+
#' plotOutput("var_vs_qsec")
124+
#' )
125+
#' )
126+
#' )
127+
#'
128+
#' server <- function(input, output) {
129+
#' for (var in c("cyl", "vs", "am", "gear", "carb")) {
130+
#' mtcars[[var]] <- as.factor(mtcars[[var]])
131+
#' }
132+
#'
133+
#' output$gear <- renderPlot({
134+
#' ggplot(mtcars, aes(gear)) + geom_bar()
135+
#' })
136+
#'
137+
#' output$carb <- renderPlot({
138+
#' ggplot(mtcars, aes(carb)) + geom_bar()
139+
#' })
140+
#'
141+
#' output$var_vs_qsec <- renderPlot({
142+
#' req(input$var_x, input$color)
143+
#'
144+
#' ggplot(mtcars) +
145+
#' aes(y = qsec, x = !!input$var_x, color = !!input$color) +
146+
#' geom_point()
147+
#' })
148+
#' }
149+
#'
150+
#' shinyApp(ui, server)
151+
page_fillable <- function(
152+
...,
153+
padding = NULL,
154+
gap = NULL,
155+
fillable_mobile = FALSE,
156+
title = NULL,
157+
theme = bs_theme(),
158+
lang = NULL
159+
) {
70160
page(
71161
title = title,
72162
theme = theme,
@@ -96,20 +186,27 @@ validateCssPadding <- function(padding = NULL) {
96186
#'
97187
#' Create a dashboard layout with a full-bleed header (`title`) and [sidebar()].
98188
#'
99-
#' @inheritParams layout_sidebar
100-
#' @inheritParams page_fillable
101189
#' @param ... UI elements to display in the 'main' content area (i.e., next to
102190
#' the `sidebar`). These arguments are passed to `layout_sidebar()`, which has
103191
#' more details.
104192
#' @param title A string, number, or [htmltools::tag()] child to display as the
105193
#' title (just above the `sidebar`).
194+
#' @inheritParams layout_sidebar
195+
#' @inheritParams page_fillable
196+
#' @inheritParams page_navbar
106197
#'
107198
#' @export
108-
#' @seealso [layout_sidebar()] for 'floating' sidebar layouts.
199+
#' @family Dashboard page layouts
200+
#'
201+
#' @seealso [layout_columns()] and [layout_column_wrap()] for laying out content
202+
#' into rows and columns.
109203
#' @seealso [accordion()] for grouping related input controls in the `sidebar`.
110204
#' @seealso [card()] for wrapping outputs in the 'main' content area.
111205
#' @seealso [value_box()] for highlighting values.
112206
#'
207+
#' @references [Getting Started with Dashboards](https://rstudio.github.io/bslib/articles/dashboards/index.html)
208+
#' on the bslib website.
209+
#'
113210
#' @examplesIf rlang::is_interactive()
114211
#'
115212
#' library(shiny)
@@ -135,8 +232,16 @@ validateCssPadding <- function(padding = NULL) {
135232
#'
136233
#' shinyApp(ui, server)
137234
#'
138-
page_sidebar <- function(..., sidebar = NULL, title = NULL, fillable = TRUE, fillable_mobile = FALSE, theme = bs_theme(), window_title = NA, lang = NULL) {
139-
235+
page_sidebar <- function(
236+
...,
237+
sidebar = NULL,
238+
title = NULL,
239+
fillable = TRUE,
240+
fillable_mobile = FALSE,
241+
theme = bs_theme(),
242+
window_title = NA,
243+
lang = NULL
244+
) {
140245
if (rlang::is_bare_character(title) || rlang::is_bare_numeric(title)) {
141246
title <- h1(title, class = "bslib-page-title")
142247
}
@@ -161,17 +266,70 @@ page_sidebar <- function(..., sidebar = NULL, title = NULL, fillable = TRUE, fil
161266
}
162267

163268

164-
#' @rdname page
165-
#' @inheritParams navset_bar
166-
#' @seealso [shiny::navbarPage()]
269+
#' Multi-page app with a top navigation bar
270+
#'
271+
#' @description
272+
#' Create a page that contains a top level navigation bar that can be used to
273+
#' toggle a set of [nav_panel()] elements. Use this page layout to create the
274+
#' effect of a multi-page app, where your app's content is broken up into
275+
#' multiple "pages" that can be navigated to via the top navigation bar.
276+
#'
167277
#' @param fillable_mobile Whether or not `fillable` pages should fill the viewport's
168278
#' height on mobile devices (i.e., narrow windows).
169279
#' @param underline Whether or not to add underline styling to page links when
170280
#' active or focused.
171281
#' @param window_title the browser window title. The default value, `NA`, means
172282
#' to use any character strings that appear in `title` (if none are found, the
173283
#' host URL of the page is displayed by default).
284+
#' @inheritParams navset_bar
285+
#' @inheritParams page
286+
#'
174287
#' @export
288+
#' @family Dashboard page layouts
289+
#'
290+
#' @seealso [nav_panel()], [nav_menu()], and [nav_item()] for adding content
291+
#' sections and organizing or creating items in the navigation bar.
292+
#' @seealso [layout_columns()] and [layout_column_wrap()] for laying out content
293+
#' into rows and columns.
294+
#' @seealso [card()] for wrapping outputs in the 'main' content area.
295+
#' @seealso [value_box()] for highlighting values.
296+
#' @seealso [accordion()] for grouping related input controls in the `sidebar`.
297+
#'
298+
#' @references [Getting Started with Dashboards](https://rstudio.github.io/bslib/articles/dashboards/index.html)
299+
#' on the bslib website.
300+
#'
301+
#' @examplesIf rlang::is_interactive()
302+
#' library(shiny)
303+
#' library(bslib)
304+
#'
305+
#' link_shiny <- tags$a(
306+
#' shiny::icon("github"), "Shiny",
307+
#' href = "https://github.com/rstudio/shiny",
308+
#' target = "_blank"
309+
#' )
310+
#' link_posit <- tags$a(
311+
#' shiny::icon("r-project"), "Posit",
312+
#' href = "https://posit.co",
313+
#' target = "_blank"
314+
#' )
315+
#'
316+
#' ui <- page_navbar(
317+
#' title = "My App",
318+
#' nav_panel(title = "One", p("First page content.")),
319+
#' nav_panel(title = "Two", p("Second page content.")),
320+
#' nav_panel("Three", p("Third page content.")),
321+
#' nav_spacer(),
322+
#' nav_menu(
323+
#' title = "Links",
324+
#' align = "right",
325+
#' nav_item(link_shiny),
326+
#' nav_item(link_posit)
327+
#' )
328+
#' )
329+
#'
330+
#' server <- function(...) { } # not used in this example
331+
#'
332+
#' shinyApp(ui, server)
175333
page_navbar <- function(
176334
...,
177335
title = NULL,

‎R/popover.R‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,8 @@
7070
#' @references <https://getbootstrap.com/docs/5.3/components/popovers/>
7171
#' @export
7272
#' @seealso [tooltip()]
73-
#' @examplesIf interactive()
73+
#'
74+
#' @examplesIf rlang::is_interactive()
7475
#'
7576
#' popover(
7677
#' shiny::actionButton("btn", "A button"),

‎R/sidebar.R‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,7 @@ toggle_sidebar <- function(id, open = NULL, session = get_current_session()) {
293293
}
294294

295295
#' @describeIn sidebar An alias for [toggle_sidebar()].
296+
#' @keywords internal
296297
#' @export
297298
sidebar_toggle <- toggle_sidebar
298299

‎R/tooltip.R‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
#' @references <https://getbootstrap.com/docs/5.3/components/tooltips/>
6060
#' @export
6161
#' @seealso [popover()]
62-
#' @examplesIf interactive()
62+
#' @examplesIf rlang::is_interactive()
6363
#'
6464
#' tooltip(
6565
#' shiny::actionButton("btn", "A button"),

‎R/value-box.R‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -56,21 +56,19 @@
5656
#' @inheritParams card
5757
#' @param theme_color `r lifecycle::badge("deprecated")` Use `theme` instead.
5858
#'
59-
#' @examples
59+
#' @examplesIf rlang::is_interactive()
6060
#' library(htmltools)
6161
#'
62-
#' if (interactive()) {
63-
#' value_box(
64-
#' "KPI Title",
65-
#' h1(HTML("$1 <i>Billion</i> Dollars")),
66-
#' span(
67-
#' bsicons::bs_icon("arrow-up"),
68-
#' " 30% VS PREVIOUS 30 DAYS"
69-
#' ),
70-
#' showcase = bsicons::bs_icon("piggy-bank"),
71-
#' theme = "success"
72-
#' )
73-
#' }
62+
#' value_box(
63+
#' "KPI Title",
64+
#' h1(HTML("$1 <i>Billion</i> Dollars")),
65+
#' span(
66+
#' bsicons::bs_icon("arrow-up"),
67+
#' " 30% VS PREVIOUS 30 DAYS"
68+
#' ),
69+
#' showcase = bsicons::bs_icon("piggy-bank"),
70+
#' theme = "success"
71+
#' )
7472
#'
7573
#' @seealso [card()]
7674
#' @export

0 commit comments

Comments
 (0)