---
title: "rbranding"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rbranding}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, include = FALSE}
library(rbranding)
```

# 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`](https://posit-dev.github.io/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'](https://quarto.org/docs/authoring/brand.html), 'Shiny' and 'RMarkdown' through [`bslib`](https://pkgs.rstudio.com/bslib/articles/brand-yml/index.html), 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:

``` r
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.

```{r}
# Temp directory
tmpdir <- file.path(tempdir(), "rbranding_example")
# Initializes the brand files in the current working directory
brand_init(install_path = tmpdir)

cat(readLines(file.path(tmpdir, "_brand.yml")), sep = "\n")

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

# Check the contents of the _brand.yml file
cat(readLines(file.path(tmpdir, "_brand.yml")), sep = "\n")
```

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

``` r
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

```{r cleanup, include = FALSE}
unlink(tmpdir, recursive = TRUE)
```