In djnavarro/bs4cards: Generate Bootstrap Cards

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(tibble)

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:

slides <- data.frame(
  messy_title = c("Starting R markdown", "Starting ggplot2", "Starting programming"),
  clean_title = c("starting-rmarkdown", "starting-ggplot2", "starting-programming"),
  description = c("An introduction to R markdown. The target audience is a novice R user with no previous experience with markdown.", "An introduction to ggplot2. The target audience is a novice user with no previous experience with R or ggplot2.", text = "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.")
  )

bs4cards::cards(
    data = slides,
    title = messy_title,
    text = description,
    link = paste0("https://slides.djnavarro.net/", clean_title),
    image = paste0("https://slides.djnavarro.net/index_img/", clean_title, ".png"),
    width = 3
  )

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

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,
    link = gallery_url,
    image = image_url,
    footer = paste("posted:", date)
  )

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
  )