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: 4

For 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 and Blood    ash        2021… Simu… ggplot2      https://… https://ar…
#> 2 Ghosts on Marble Paper ghosts     2021… Abst… ambient      https://… https://ar…
#> 3 Ice Floes              ice-floes  2021… Abst… ambient      https://… https://ar…
#> 4 Native Flora           native-fl… 2021… Coll… ggplot2; fl… https://… https://ar…
#> 5 Silhouettes            silhouett… 2021… Tree… ggplot2; rc… https://… https://ar…
#> 6 Track Marks            track-mar… 2020… Voro… ggplot2; rc… https://… https://ar…
#> 7 Viewports              viewports  2021… Simp… ggplot2; fl… https://… https://ar…

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:

galleries %>%
cards(
title = long_name,
image = image_url,
footer = paste("posted:", date)
)

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,
image = image_url,
tags = paste("all;", paintbrushes),
footer = paintbrushes,
layout = "label-right",
width = 4,
)

##### 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.