When creating R markdown pages and websites it can be useful to organise content into a grid of links and image, sometimes known as “cards”. To design a course website you may want something like this:
Starting R markdown
An introduction to R markdown. The target audience is a novice R user with no previous experience with markdown.
Starting ggplot2
An introduction to ggplot2. The target audience is a novice user with no previous experience with R or ggplot2.
Starting programming
This is primarily a tutorial on making generative art in R, but in doing so introduces core programming constructs and data structures. It is assumed the user has some previous experience with ggplot2.
Enabling bootstrap 4
The first step in using the package is to make sure that your R markdown document uses version 4 of bootstrap. The default behaviour of R markdown when creating HTML documents is to use bootstrap version 3, so this setting needs to be altered. To ensure that you are using bootstrap 4, you need to edit the YAML header for your document to specify which version of bootstrap you want to use. For a plain R markdown document or website (i.e., one where the output format is html_document) here is the relevant section of YAML you might use:
output:
html_document:
theme:
version: 4For other kinds of R markdown documents, see the enabling bootstrap article.
The galleries data
The main function in bs4cards is cards(). It takes a data frame as the first argument, generally the data set from which the bootstrap cards are to be constructed. The package comes with a data set galleries that I’ll use to create the grids
library(bs4cards)
galleries
#> # A tibble: 7 × 7
#> long_name short_name date blurb paintbrushes image_url gallery_url
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Ash Cloud… ash 2021-… Simulate… ggplot2 https://bs… https://art.…
#> 2 Ghosts on… ghosts 2021-… Abstract… ambient https://bs… https://art.…
#> 3 Ice Floes ice-floes 2021-… Abstract… ambient https://bs… https://art.…
#> 4 Native Fl… native-flo… 2021-… Collecti… ggplot2; fl… https://bs… https://art.…
#> 5 Silhouett… silhouettes 2021-… Trees ge… ggplot2; rc… https://bs… https://art.…
#> 6 Track Mar… track-marks 2020-… Voronoi … ggplot2; rc… https://bs… https://art.…
#> 7 Viewports viewports 2021-… Simple m… ggplot2; fl… https://bs… https://art.…Each row in this data corresponds to one card in the grid. The columns contain information that is useful for constructing the cards.
Basic usage
For example to create the card grid shown at the start of the vignette, I needed to the title for each card, the text printed below it, the image decorating the card, and the URL to which the title and image in each card should link. Each of these is an argument to cards(), and for each argument you can pass an expression that will be evaluated using the data input:
Additional example
The cards() function supports a variety of different layouts and customisation options, discussed in the next article. To give a flavour of what’s possible, here’s another example based on the same data:
galleries %>%
cards(
title = long_name,
text = blurb,
link = gallery_url,
image = image_url,
tags = paste("all;", paintbrushes),
footer = paintbrushes,
layout = "label-right",
width = 4,
border_radius = 5
)
Ash Cloud and Blood
Simulated watercolours in ggplot2 using the transparent polygon method
Ghosts on Marble Paper
Abstract landscapes generated using ambient
Ice Floes
Abstract icebergs generated using ambient
Native Flora
Collections of small flametrees that resemble branching plants
Silhouettes
Trees generated in flametree with random walk backgrounds
Track Marks
Voronoi tessellations with seed points sampled from an iterated function system
Viewports
Simple masks with ggfx using flametree-generated textures
Where to next?
If you’re interested in using the bs4cards package, check out the articles page.