Adopt an organisation brand from a PowerPoint or Word template

Reads the colour and font theme out of your organisation's .pptx / .docx template and makes it the session default for everything ezrsurvey produces: charts pick up the brand accent colours and body font, and the template file itself becomes the default reference document for report_new(), report_deck() and scaffold_report(). One call, and analysis output is on-brand.

Usage

use_brand(template = NULL, colors = NULL, fonts = NULL, quiet = FALSE)

Arguments

template: Path to a .pptx or .docx file. Its OOXML theme (accent colours, heading/body typefaces) is extracted, and the file is registered as the default reference document for reports of the matching format. NULL to set colours/fonts directly without a template.
colors: Optional character vector of hex colours overriding the extracted accents. A single colour sets only the primary; a vector sets the full accent palette (first entry = primary). Invalid entries are dropped with a warning.
fonts: Optional character vector overriding the extracted typefaces: either a single body font, or c(major = "...", minor = "...").
quiet: If TRUE, suppress the confirmation message.

Value

Invisibly a ezrsurvey_brand list (see brand_info()).

Details

Extraction reads theme1.xml inside the template (requires the suggested xml2 package): accent colours 1-6 become brand_colors (first accent = brand_color_primary, the default fill of plot_bars()), and the minor (body) typeface becomes the default base_family of theme_ezrsurvey() – but only when that font is actually installed on this machine, so charts never render with substituted glyph boxes. Set ezrsurvey_options(brand_fonts_enabled = FALSE) to keep brand colours but ignore brand fonts.

A brand font also needs a graphics device that reads the machine's fonts. The pdf and postscript devices do not: they carry their own short list of families, and a chart printed to one fails with "invalid font type". That is the default device in a plain Rscript run, so use_brand() says so when it sets a font there. Charts written with save_plot() are unaffected, because it saves through a device that does read system fonts.

Everything lands in ordinary ezrsurvey_options() (brand_* keys), so you can equally set the values by hand or persist them in a YAML profile; a later use_brand() call simply overwrites them. Semantic palettes (pal_rating, pal_nps) deliberately keep their meaning-carrying colours and are not rebranded. Use clear_brand() to return to the neutral look.

Examples

tmp <- tempfile(fileext = ".pptx")
print(officer::read_pptx(), target = tmp)
use_brand(tmp, quiet = TRUE)
brand_info()
#> ezrsurvey brand
#>   colors:   #4F81BD #C0504D #9BBB59 #8064A2 #4BACC6 #F79646
#>   primary:  #4F81BD
#>   fonts:    Calibri / Calibri
#>   pptx ref: /tmp/RtmpjqnV9l/file1b131df8cb39.pptx
clear_brand()
# Or set brand values directly, no template needed:
use_brand(colors = c("#0B5394", "#E69138"), fonts = "Georgia", quiet = TRUE)
clear_brand()