Skip to contents

rbranding

Source: vignettes/rbranding.qmd

Introduction to rbranding

The rbranding package provides a set of tools to help you create and maintain consistent branding across your R projects. It is powered by _brand.yml, a configuration file that defines your brand’s visual identity, including colors, fonts, logos, and other design elements. _brand.yml is supported by various R-based platforms, including Shiny, Quarto, and R Markdown.

The rbranding package provides functions for setting up the branding files, updating them from remote sources, and applying them to your projects. It also includes templates for various project types, making it easy to get started with a branded project. The package supports ‘Quarto’, ‘Shiny’ and ‘RMarkdown’ through bslib, and integrates with ‘ggplot2’ and ‘plotly’ for producing branded graphics and visualizations.

Finally, the rbranding package provides guidelines and support for accessibility, ensuring that your branded content is usable by all audiences.

Initialization

Use brand_init() to initialize the branding setup:

brand_init(brand_url = "your_brand_file_url_here", install_path = ".")

This function generates two files:

  • rbranding_config.yml: Contains configuration settings for the updating your _brand.yml file, specifically the URL of your brand file (brand_url) and the path to your local _brand.yml file (based on install_path). Essentially, this file saves the parameters you used when calling brand_init(), allowing you to easily update your branding files in the future without needing to remember or re-enter these details.
  • _brand.yml: Your local brand configuration file. After calling brand_init(), this file contains placeholder text and will need to be updated by get_brand_*(), which we describe in the next section.

Note: Both brand_url and install_path are optional parameters. If not provided, brand_init() will set brand_url to a _brand.yml hosted on the rbranding GitHub page. install_path defaults to the current working directory (".").

brand_init() is intended to be run once per project. It sets up the necessary configuration for managing your brand files, but does not need to be run again unless you want to change the brand_url or install_path.

Updating Your Brand File

Now that you’ve initialized the branding setup with brand_init(), you can use the get_brand_*() functions to download or update your local _brand.yml file from a remote source.

You’ll need to do this at least once after calling brand_init(), since the _brand.yml file generated by that function contains placeholder text. However, these functions can also be used to update your local _brand.yml file whenever changes are made to the remote brand file.

There are currently two get_brand_*() functions available, depending on where your brand file is hosted:

  • get_brand_public(): Use this function if your brand file is hosted publicly, such as on a public GitHub repository or a web server.
  • get_brand_private_github(): Use this function if your brand file is hosted in a private GitHub repository. It requires a GitHub personal access token (PAT) with appropriate permissions to access the repository.

get_brand_*() functions both download the brand file from the URL specified in your rbranding_config.yml file and saves it to the local file path specified there (typically the current working directory). By default this function runs interactively, but this can be disabled by setting run_interactive = FALSE. You can also specify a backup file, so the previous version of your _brand.yml file is saved before being overwritten.

Again, call this function whenever you want to update your local _brand.yml file with the latest version from the remote source.

Example Usage

Below is a simple example using the default brand file hosted on the rbranding GitHub page.

# Temp directory
tmpdir <- file.path(tempdir(), "rbranding_example")
# Initializes the brand files in the current working directory
brand_init(install_path = tmpdir)
#> Created files '/tmp/RtmpX2TxHJ/rbranding_example/rbranding_config.yml' and placeholder '_brand.yml' in /tmp/RtmpX2TxHJ/rbranding_example

cat(readLines(file.path(tmpdir, "_brand.yml")), sep = "\n")
#> Update this file with rbranding::get_brand_public() (or another `get_brand_*` function)

# Downloads the public brand file from the rbranding GitHub page
# and saves it as _brand.yml in the current working directory
get_brand_public(
  config_file = file.path(tmpdir, "rbranding_config.yml"),
  run_interactive = FALSE
)
#> Checking remote version...
#> Local branding file overwritten with remote file

# Check the contents of the _brand.yml file
cat(readLines(file.path(tmpdir, "_brand.yml")), sep = "\n")
#> meta:
#>   name: rbranding
#>   links:
#>     docs: https://epiforesite.github.io/rbranding/
#>     github: https://github.com/EpiForeSITE/rbranding/
#> 
#> logo:
#>   images:
#>     icon:
#>       path: icon.png
#>       alt: "Company icon with abstract shapes"
#>     logo:
#>       path: logo.png
#>       alt: "Full company logo with tagline"
#>   small: icon
#> 
#> 
#> 
#> color:
#>   palette:
#>     orange: "#FF6F20"
#>     pink: "#FF3D7F"
#>     green: "#28A745"
#>     yellow: "#FFC107"
#>   primary: orange
#>   success: green
#>   warning: yellow
#>   danger: pink
#> 
#> typography:
#>   fonts:
#>     - family: Open Sans
#>       source: google
#>     - family: IBM Plex Mono
#>       source: google
#>     - family: Rubik
#>       source: google
#>   base:
#>     family: Open Sans
#>     line-height: 1.6
#>   headings:
#>     family: Rubik
#>     weight: normal
#>   link:
#>     color: purple
#>   monospace:
#>     family: IBM Plex Mono
#>     size: 1em
#> 
#> defaults:
#>   quarto:
#>     format:
#>       # basic format-specific settings
#>   shiny:
#>     # shiny specific settings

Using Templates

The rbranding package includes several templates to help you get started with branded projects. You can use the get_template() function to download and set up a template:

get_template(template_name = "shiny_complex")

This will copy the contents of the shiny_complex template into your current working directory. This template provides ready-to-use Shiny app files with branding support. You can specify other templates by changing the template_name argument to get_template(). Available templates include:

  • ggplot2: R script using ggplot2
  • quarto_ggplot2: Quarto Report with Branded ggplot2 Figures
  • quarto_website: Simple Quarto Website Template
  • rmarkdown: R Markdown document
  • shiny_basic: Simple Histogram Visualization Shiny App
  • shiny_complex: Complex Histogram Visualization Shiny App
  • shiny_kmeans: Simple K-means Clustering Visualization Shiny App
  • shiny_wastewater: Complex Wasterwater Data Visualization Shiny App