,
Alex Shum [ctb],
Emerson Berry [ctb]| Title: | Adds Functionality to the R Markdown + Shiny Bootstrap Framework |
|---|---|
| Description: | The Bootstrap framework lets you add some JavaScript functionality to your web site by adding attributes to your HTML tags - Bootstrap takes care of the JavaScript <https://getbootstrap.com/docs/3.3/javascript/>. If you are using R Markdown or Shiny, you can use these functions to create collapsible sections, accordion panels, modals, tooltips, popovers, and an accordion sidebar framework (not described at Bootstrap site). Please note this package was designed for Bootstrap 3.3. |
| Authors: | Ian Lyttle [aut, cre] ,
Alex Shum [ctb],
Emerson Berry [ctb] |
| Maintainer: | Ian Lyttle <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.3.9002 |
| Built: | 2024-09-09 04:26:06 UTC |
| Source: | https://github.com/ijlyttle/bsplus |
An accordion is a set of collapsible panels where, at most, one panel-body is visible.
bs_accordion(id) ## S3 method for class 'bsplus_accordion' bs_append(tag, title, content, ...) ## S3 method for class 'bsplus_accordion' bs_set_opts(tag, panel_type = "primary", use_heading_link = TRUE, ...)bs_accordion(id) ## S3 method for class 'bsplus_accordion' bs_append(tag, title, content, ...) ## S3 method for class 'bsplus_accordion' bs_set_opts(tag, panel_type = "primary", use_heading_link = TRUE, ...)
id |
character, unique id for accordion |
tag |
|
title |
character (HTML) or |
content |
character (HTML) or |
... |
other arguments (not used) |
panel_type |
character, one of the standard Bootstrap types
|
use_heading_link |
logical, indicates whether to make the entire panel heading clickable. |
All of these functions return a bsplus_accordion object
(which is also an htmltools::[tag][htmltools::tag], <div/>), so you can
compose an accordion by piping. There are three parts to this system:
A constructor function for the accordion, bs_accordion()
A function to set options for subsequent panels, bs_set_opts()
A function to append a panel to the group, bs_append()
The verb append is used to signify that you can append an arbitrary number of panels to an accordion.
For the constructor, bs_accordion(),
it is your responsibility to ensure that id is unique
among HTML elements in your page. If you have non-unique id's, strange things may
happen to your page.
bsplus_accordion object (htmltools::[tag][htmltools::tag],
<div/>)
https://getbootstrap.com/docs/3.3/javascript/#collapse-example-accordion
bs_accordion(id = "meet_the_beatles") %>% bs_set_opts(panel_type = "success", use_heading_link = TRUE) %>% bs_append(title = "John Lennon", content = "Rhythm guitar, vocals") %>% bs_set_opts(panel_type = "info") %>% bs_append(title = "Paul McCartney", content = "Bass guitar, vocals")bs_accordion(id = "meet_the_beatles") %>% bs_set_opts(panel_type = "success", use_heading_link = TRUE) %>% bs_append(title = "John Lennon", content = "Rhythm guitar, vocals") %>% bs_set_opts(panel_type = "info") %>% bs_append(title = "Paul McCartney", content = "Bass guitar, vocals")
Combines Bootstrap accordion with
the functionality of shiny::[sidebarLayout][shiny::sidebarLayout],
allowing you to add another dimension to your shiny apps.
bs_accordion_sidebar( id, spec_side = c(width = 4, offset = 0), spec_main = c(width = 8, offset = 0), position = c("left", "right") ) use_bs_accordion_sidebar() ## S3 method for class 'bsplus_accordion_sidebar' bs_append(tag, title_side, content_side, content_main, ...) ## S3 method for class 'bsplus_accordion_sidebar' bs_set_opts( tag, panel_type_active = "success", panel_type_inactive = "primary", use_main_enclosure = TRUE, ... )bs_accordion_sidebar( id, spec_side = c(width = 4, offset = 0), spec_main = c(width = 8, offset = 0), position = c("left", "right") ) use_bs_accordion_sidebar() ## S3 method for class 'bsplus_accordion_sidebar' bs_append(tag, title_side, content_side, content_main, ...) ## S3 method for class 'bsplus_accordion_sidebar' bs_set_opts( tag, panel_type_active = "success", panel_type_inactive = "primary", use_main_enclosure = TRUE, ... )
id |
character, unique id for accordion-sidebar |
spec_side |
numeric, column specification for sidebar panels |
spec_main |
numeric, column specification for main panels |
position |
character, indicates where to put the sidebar panels with respect to the main panels |
tag |
|
title_side |
character (HTML) or |
content_side |
character (HTML) or |
content_main |
character (HTML) or |
... |
other arguments (not used) |
panel_type_active |
character, indicated bootstrap type for active-panel header,
one of |
panel_type_inactive |
character, indicated bootstrap type for inactive-panel header,
one of |
use_main_enclosure |
logical, indicates if main content is to be wrapped in a Bootstrap panel |
If you use a bs_accordion_sidebar(), you will have to call the function
use_bs_accordion_sidebar() somewhere in your UI. This attaches some
JavaScript needed for your accordion sidebar to work properly.
All of these functions return a bsplus_accsidebar object,
(which is also an htmltools::[tag][htmltools::tag], <div/>), so you can
compose an accordion sidebar by piping. There are three parts to this system:
A constructor function for the accordion-sidebar, bs_accordion_sidebar()
A function to set options for subsequent panels, bs_set_opts()
A function to append a panel-set to an accordion-sidebar, bs_append()
The verb append is used to signify that you can append an arbitrary number of panels-sets to an accordion-sidebar.
For the constructor, bs_accordion_sidebar(),
it is your responsibility to ensure that id is unique
among HTML elements in your page. If you have non-unique id's, strange things may
happen to your page.
bsplus_accsidebar object (htmltools::[tag][htmltools::tag],
<div/>)
bs_accordion_sidebar(id = "meet_the_beatles") %>% bs_append( title_side = "John Lennon", content_side = "Rhythm guitar, vocals", content_main = "Dear Prudence" ) %>% bs_append( title_side = "Paul McCartney", content_side = "Bass guitar, vocals", content_main = "Blackbird" ) ## Not run: use_bs_accordion_sidebar() ## End(Not run)bs_accordion_sidebar(id = "meet_the_beatles") %>% bs_append( title_side = "John Lennon", content_side = "Rhythm guitar, vocals", content_main = "Dear Prudence" ) %>% bs_append( title_side = "Paul McCartney", content_side = "Bass guitar, vocals", content_main = "Blackbird" ) ## Not run: use_bs_accordion_sidebar() ## End(Not run)
A carousel is used to enclose a set of (typically) images, providing controls to move slides back-and-forth.
## S3 method for class 'bsplus_carousel' bs_append(tag, content, caption = NULL, ...) bs_carousel(id, use_indicators = FALSE, use_controls = TRUE)## S3 method for class 'bsplus_carousel' bs_append(tag, content, caption = NULL, ...) bs_carousel(id, use_indicators = FALSE, use_controls = TRUE)
tag |
|
content |
character (HTML) or |
caption |
character (HTML) or |
... |
other args (not used) |
id |
character, unique id for accordion |
use_indicators |
logical, denotes use of slide-position indicators (dots) |
use_controls |
logical, denotes use of controls (chevrons at sides) |
All of these functions return a bsplus_carousel object
(which is also an htmltools::[tag][htmltools::tag], <div/>), so you can
compose a carousel by piping. There are two parts to this system:
A constructor function for the carousel, bs_carousel()
A function to append a slide to the carousel, bs_append()
The verb append is used to signify that you can append an arbitrary number of slides to a carousel.
For the constructor, bs_carousel(),
it is your responsibility to ensure that id is unique
among HTML elements in your page. If you have non-unique id's, strange things may
happen to your page.
bsplus_carousel object (htmltools::[tag][htmltools::tag],
<div/>)
https://getbootstrap.com/docs/3.3/javascript/#carousel,
bs_carousel_image(), bs_carousel_caption()
bs_carousel(id = "with_the_beatles") %>% bs_append(content = bs_carousel_image(src = "img/john.jpg")) %>% bs_append(content = bs_carousel_image(src = "img/paul.jpg")) %>% bs_append(content = bs_carousel_image(src = "img/george.jpg")) %>% bs_append(content = bs_carousel_image(src = "img/ringo.jpg"))bs_carousel(id = "with_the_beatles") %>% bs_append(content = bs_carousel_image(src = "img/john.jpg")) %>% bs_append(content = bs_carousel_image(src = "img/paul.jpg")) %>% bs_append(content = bs_carousel_image(src = "img/george.jpg")) %>% bs_append(content = bs_carousel_image(src = "img/ringo.jpg"))
This function makes it a little easier to make Bootstrap-friendly buttons;
it wraps htmltools::tags for buttons.
bs_button( label, button_type = c("default", "primary", "success", "info", "warning", "danger"), button_size = c("default", "large", "small", "extra-small"), ... )bs_button( label, button_type = c("default", "primary", "success", "info", "warning", "danger"), button_size = c("default", "large", "small", "extra-small"), ... )
label |
character (HTML), button label |
button_type |
character, one of the standard Bootstrap types |
button_size |
character, size of the button |
... |
attributes (named arguments) and children (unnamed arguments) of the button, passed to |
Object with S3 class, shiny.tag, <button/>.
https://getbootstrap.com/docs/3.3/css/#buttons
bs_button("Click me", button_type = "primary", button_size = "small")bs_button("Click me", button_type = "primary", button_size = "small")
Helper function to generate HTML for a carousel caption.
bs_carousel_caption(title = NULL, body = NULL)bs_carousel_caption(title = NULL, body = NULL)
title |
character, caption title |
body |
character, caption body |
htmltools::[tag][htmltools::tag] <div/> for carousel caption
Helper function to generate HTML for a carousel image.
bs_carousel_image(...)bs_carousel_image(...)
... |
additional arguments passed to
|
This function wraps htmltools::[tag][htmltools::tag]$img,
but adding a class to center the image in the carousel.
htmltools::[tag][htmltools::tag], </img>
This is useful for content that you may wish to be hidden when the page is initialized, but that can be revealed (and subsequently hidden) by clicking a button or a link.
bs_collapse(id, content = NULL, show = FALSE) bs_attach_collapse(tag, id_collapse)bs_collapse(id, content = NULL, show = FALSE) bs_attach_collapse(tag, id_collapse)
id |
character, unique id for the collapsible |
content |
character (HTML) or
|
show |
logical, indicates if collapsible |
tag |
|
id_collapse |
character, |
There are two parts to this system:
A collapsible <div/>, created using bs_collapse()
At least one button (<button/>) or link (<a/>)
to which the id of the collapsible <div/> is attached,
using bs_attach_collapse()
The verb attach is used to signify that we are attaching the
id of our collapsible
<div/> to the tag in question (a button or a link).
Note that you can attach the id of a collapsible
<div/> to more than one button or link.
It is your responsibility to ensure that id is unique
among HTML elements in your page. If you have non-unique id's,
strange things may happen to your page.
bs_collapse()htmltools::[tag][htmltools::tag],
<div/>
bs_attach_collapse()htmltools::[tag][htmltools::tag],
modified copy of tag (button or link)
https://getbootstrap.com/docs/3.3/javascript/#collapse
library("htmltools") bs_collapse(id = "id_yeah", "Yeah Yeah Yeah") bs_button("She Loves You", button_type = "primary") %>% bs_attach_collapse("id_yeah")library("htmltools") bs_collapse(id = "id_yeah", "Yeah Yeah Yeah") bs_button("She Loves You", button_type = "primary") %>% bs_attach_collapse("id_yeah")
A popover can be a useful way to add a somewhat-verbose explanation to a tag.
bs_embed_popover(tag, title = NULL, content = NULL, placement = "top", ...) use_bs_popover()bs_embed_popover(tag, title = NULL, content = NULL, placement = "top", ...) use_bs_popover()
tag |
|
title |
character, title for the popover, generally text |
content |
character, content for the popover body, can be HTML |
placement |
character, placement of the popover with respect to |
... |
other named arguments, passed to |
To activate the use of popovers in your page, you will need to call
the use_bs_popover() function somewhere.
The verb embed is used to signify that you are embedding information
into a tag. This implies that you can embed, at most, one "thing"
into a particular tag. You should not, for example, expect to embed both a tooltip
and a popover into a tag.
htmltools::[tag][htmltools::tag], modified copy of tag
bs_embed_tooltip(),
https://getbootstrap.com/docs/3.3/javascript/#popovers
library("htmltools") bs_button("A button") %>% bs_embed_popover(title = "I'm a popover", content = "Really!")library("htmltools") bs_button("A button") %>% bs_embed_popover(title = "I'm a popover", content = "Really!")
A tooltip can be a useful way to add a few words of explanation to a tag.
bs_embed_tooltip(tag, title = "", placement = "top", ...) use_bs_tooltip()bs_embed_tooltip(tag, title = "", placement = "top", ...) use_bs_tooltip()
tag |
|
title |
character, title for the tooltip |
placement |
character, placement of the tooltip with respect to |
... |
other named arguments, passed to |
To activate the use of tooltips in your page, you will need to call
the use_bs_tooltip() function somewhere.
The verb embed is used to signify that you are embedding information
into a tag. This implies that you can embed, at most, one "thing"
into a particular tag. You should not, for example, expect to embed both a tooltip
and a popover into a tag.
htmltools::[tag][htmltools::tag], modified copy of tag
bs_embed_popover(), https://getbootstrap.com/docs/3.3/javascript/#tooltips
library("htmltools") bs_button("I'm a button") %>% bs_embed_tooltip(title = "I'm a tooltip")library("htmltools") bs_button("I'm a button") %>% bs_embed_tooltip(title = "I'm a tooltip")
Modal windows are useful to make detailed explanations, and are typically attached to buttons or links. Thus, there are two parts to this system:
bs_modal( id, title, body, footer = bs_modal_closebutton(label = "Close"), size = c("medium", "large", "small") ) bs_modal_closebutton(label = "Close", title) bs_attach_modal(tag, id_modal)bs_modal( id, title, body, footer = bs_modal_closebutton(label = "Close"), size = c("medium", "large", "small") ) bs_modal_closebutton(label = "Close", title) bs_attach_modal(tag, id_modal)
id |
character, unique id for the modal window |
title |
character, title for the modal window (this argument is deprecated
for |
body |
character (HTML) or |
footer |
character (HTML) or |
size |
character, size of the modal window |
label |
character (HTML), label for the close-button |
tag |
|
id_modal |
character, unique id of modal window to attach |
A modal window, created using bs_modal()
At least one button or link to which the id of the
modal window is attached, using bs_attach_modal()
The verb attach is used to signify that we are attaching the id of our
modal window to the tag in question (generally a button or a link). This implies that
you can attach the id of a modal window to more than one button or link.
It is your responsibility to ensure that id is unique
among HTML elements in your page. If you have non-unique id's, strange things may
happen to your page.
Your code may be cleaner if you can import the content for the modal body from
an external source. Here, the function shiny::[includeMarkdown][shiny::includeMarkdown]
be useful.
If you want to compose your own footer for the modal window, the function
bs_modal_closebutton() can be useful.
bs_modal()htmltools::[tag][htmltools::tag], <div/>
bs_attach_modal()htmltools::[tag][htmltools::tag],
modified copy of tag
bs_modal_closebutton()htmltools::[tag][htmltools::tag], <button/>
shiny::[includeMarkdown][shiny::includeMarkdown]
library("htmltools") # also needs `markdown` package library("shiny") bs_modal(id = "modal", title = "I'm a modal", body = "Yes, I am.") bs_button("Click for modal") %>% bs_attach_modal(id_modal = "modal") bs_modal( id = "modal_large", title = "I'm a modal", size = "large", body = includeMarkdown(system.file("markdown", "modal.md", package = "bsplus")) ) bs_button("Click for modal") %>% bs_attach_modal(id_modal = "modal_large")library("htmltools") # also needs `markdown` package library("shiny") bs_modal(id = "modal", title = "I'm a modal", body = "Yes, I am.") bs_button("Click for modal") %>% bs_attach_modal(id_modal = "modal") bs_modal( id = "modal_large", title = "I'm a modal", size = "large", body = includeMarkdown(system.file("markdown", "modal.md", package = "bsplus")) ) bs_button("Click for modal") %>% bs_attach_modal(id_modal = "modal_large")
This function makes it a little easier to make Bootstrap-friendly panels;
it wraps htmltools::tags for panels
bs_panel( id = NULL, panel_type = c("default", "primary", "success", "info", "warning", "danger"), heading = NULL, body = NULL, ..., footer = NULL )bs_panel( id = NULL, panel_type = c("default", "primary", "success", "info", "warning", "danger"), heading = NULL, body = NULL, ..., footer = NULL )
id |
character, unique identifier |
panel_type |
character, one of the standard Bootstrap types |
heading |
character (HTML) or htmltools::tagList(), content for the heading |
body |
character (HTML) or htmltools::tagList(), content for the body |
... |
character (HTML) or htmltools::tagList(), other content |
footer |
character (HTML) or htmltools::tagList(), content for the footer |
Object with S3 class, shiny.tag, <div/>
https://getbootstrap.com/docs/3.3/css/#panels
library("htmltools") bs_panel( panel_type = "primary", heading = tags$h3("title"), body = tags$p("Some very important content") )library("htmltools") bs_panel( panel_type = "primary", heading = tags$h3("title"), body = tags$p("Some very important content") )
Helper function to manage attributes for Bootstrap's JavaScript components.
bs_set_data(tag, ...) bs_set_aria(tag, ...)bs_set_data(tag, ...) bs_set_aria(tag, ...)
tag |
|
... |
named arguments used to set the attributes of |
One of the mechanisms used by the API for Boostrap JavaScript-components is
an html elements' attributes. These attribute names are prefixed with
"data-" or "aria-", depending on the function.
When expressed in html, attributes themselves have the properties:
Logical values are expressed as "true" or "false".
Time durations are expressed as number of milliseconds.
Vector (non scalar) values are expressed in a space-delimited list.
The purpose of this function is to let you express these values in ways familiar to you as an R user. For example:
Logical values can be expressed as logicals: TRUE or FALSE.
Time durations can be expressed using lubridate durations.
Vector (non scalar) values can be expressed as vectors.
Note that this returns a modified copy of the tag sent to it, so it is pipeable.
htmltools::[tag][htmltools::tag], modified copy of tag
Bootstrap JavaScript Components
library("htmltools") library("lubridate") tags$div() %>% bs_set_data( target = "#foobar", delay = dseconds(1), placement = c("right", "auto") ) %>% bs_set_aria(expanded = FALSE)library("htmltools") library("lubridate") tags$div() %>% bs_set_data( target = "#foobar", delay = dseconds(1), placement = c("right", "auto") ) %>% bs_set_aria(expanded = FALSE)
This is a wrapper around the rmarkdown::[render][rmarkdown::render]
function. The principal difference is that the function is designed to
return an HTML fragment (rather than writing to a file). This function is
useful to populate the content of a modal window.
render_html_fragment(input, output_format = rmarkdown::html_fragment(), ...)render_html_fragment(input, output_format = rmarkdown::html_fragment(), ...)
input |
character, path to input file |
output_format |
rmarkdown output format, provided so you can specify arguments |
... |
other arguments passed to
|
This function is being deprecated in favor of
shiny::[includeMarkdown][shiny::includeMarkdown]
htmltools::[tag][htmltools::tag]
## Not run: my_file <- system.file("markdown", "modal.md", package = "bsplus") render_html_fragment(my_file) ## End(Not run)## Not run: my_file <- system.file("markdown", "modal.md", package = "bsplus") render_html_fragment(my_file) ## End(Not run)
You can use this helper function to wrap link element
around a shiny::[icon][shiny::icon].
It may be useful to attach a modal window to
(or embed a popover into) into such a link.
shiny_iconlink(name = "info-circle", id = NULL, ...)shiny_iconlink(name = "info-circle", id = NULL, ...)
name |
character, name of the icon, passed to |
id |
character, option ID for the link |
... |
other arguments passed to |
htmltools::[tag][htmltools::tag], <a/>
shinyInput_label_embed(),
shiny::[icon][shiny::icon], bs_attach_modal(),
bs_embed_popover(), bs_embed_tooltip()
shiny_iconlink() shiny_iconlink() %>% bs_embed_popover(title = "Help!", content = "I need somebody")shiny_iconlink() shiny_iconlink() %>% bs_embed_popover(title = "Help!", content = "I need somebody")
The element embedded into the Shiny input will be pulled to the right edge of the label.
shinyInput_label_embed(tag, element)shinyInput_label_embed(tag, element)
tag |
Shiny input, such as |
element |
|
To promote consistency, the following convention is proposed:
For links (activated by clicking), embed a shiny::icon("info-circle");
this is the default for shiny_iconlink(). For elements activated
by hovering, embed a shiny::icon("info").
Shiny input, modified copy of tag
library("shiny") numericInput(inputId = "foo", label = "Enter a number", value = 0) %>% shinyInput_label_embed( shiny_iconlink() %>% bs_embed_popover(title = "Number", content = "Not a complex number") )library("shiny") numericInput(inputId = "foo", label = "Enter a number", value = 0) %>% shinyInput_label_embed( shiny_iconlink() %>% bs_embed_popover(title = "Number", content = "Not a complex number") )