The main purpose of
onbrand is to create an abstraction layer that allows for the same reporting workflow to be used with different document templates. In order to do this, the abstraction information (or mapping) needs to be provided in a
yaml configuration file. The process will be detailed below, but at a high level it involves the following steps:
The following sections describe this process in detail for both Word and PowerPoint documents. Before you get started, copy the provided examples into your current working directory. To do so, use the following code:
library(onbrand) file.copy(system.file(package="onbrand","examples","example.pptx"), ".", overwrite = TRUE) file.copy(system.file(package="onbrand","examples","example.docx"), ".", overwrite = TRUE) file.copy(system.file(package="onbrand","examples","example.yaml"), ".", overwrite = TRUE)
This will create the following files:
example.pptx- example PowerPoint template
example.docx- example Word template
yamlmapping file (shown at the bottom)
Before we start discussing how to create templates we need to talk a little bit about the
yaml file format (and it’s recursive nature). If you already understand this, feel free to skip ahead to the relevant section below.
onbrand utilizes the
yaml file as a method for describing information in a hierarchical manner using key/value pairs. To help understand this better, consider the following example where the colors of the different parts a tree are listed in a hierarchy based on where the parts are located on the tree:
tree colors: roots: - white - brown trunk: bark: brown crown: branches: leaves: green flowers: red
This example lays out
key: value pairs based on the formatting of the file. The key is followed by both a colon and a space (
:) which are, in turn, followed by the value.
The main key in the example above is
tree colors. This key has three values:
crown. One for each section of a tree. The hierarchy comes from the indentation. Each of the main sections of a tree are indented two spaces. Each of these values (
crown) are also keys themselves because they end with both a colon and a space - and are followed by still more values.
The color values associated with roots are
root hierarchy is complete.
trunk has value
bark. But, because
bark is also indented two spaces and is followed by both a colon and a space, it is also a key with value
brown. Which completes the
crown is indented two spaces and followed by both a colon and a space. Hence,
crown is a key with value
branches is indented and followed by both a colon and a space. Then,
branches is also a key with values:
flowers. Each of these are also indented and followed by by both a colon and a space. So the key
leaves has value
green. Similarly, key
flowers has value
red. This completes the
There is more that can go into a
yaml file, but this should be enough to help you understand how to create mapping files for
onbrand. For more details see (yaml.org)[yaml.org].
This section provides a detailed walk-through for each of the three steps in the Introduction. We recommend everyone walk through this process at least once.
A quick note about terminology. A slide master is the top slide in a hierarchy of slides that stores information about the theme and slide layouts of a presentation, including the background, color, fonts, effects, placeholder sizes, and positioning. The slide master is the largest slide image at the top of the slide thumbnail list.
To create your custom abstraction layer for PowerPoint, you start by reading in your master template. If you don’t already have one, create a PowerPoint template master slide with slide layouts for each of the different layouts you want to use. In this example, we have the
Office Theme Master Slide with two slide layouts:
Tip When you make slide layouts under a master, give each of them a descriptive name that will be easy to use when you are coding later. These names will be used to refer to them within scripts.
PowerPoint assigns read-only names to every placeholder within each slide layout. To reveal those read-only names, create an annotated slide deck using the
library(onbrand) = view_layout(template = "example.pptx", vlres output_file = "example_layout.pptx")
This will create the file
example_layout.pptx. It contains a slide for each slide layout (
two_col) under the master (
Office Theme) in the input template file (
example.pptx). On each slide, the names of both the slide layout and slide master will be indicated in the upper right corner. Each placeholder within the slide layout will be shown and is identified by the placeholder label (
ph_label). For each placeholder within each slide layout under a slide master,
onbrand::view_layout() produces three pieces of information:
index. Notice, there are plenty of duplicate placeholder names.
Before we get to the mapping, take a moment to locate and open the
example.yaml file we copied over at the start of this vignette. In the yaml file there will be a key for mapping PowerPoint templates (rows 1-39 in the file). This key is called
rpptx and it will have three values (which are also keys):
master- Holds the name of the master slide
templates- Has an element for each slide layout you want to use in the template
md_def- Default formatting for when markdown formatting is being used
Within the hierarchy of
rpptx: templates: there is a value for each slide layout:
Remember the tip in Step 1 about names? The name you provided becomes the key value in the
yaml. It’s used to reference the placeholders on the slide in your code.
example.yaml doesn’t contain all of the placeholders for either slide in the
example_layout.pptx. This is because those elements were inherited from the master slide and are not unique to either of the slide layouts.
yaml, each placeholder will have two value pairs below it. For example, the placeholder
sub_title in slide layout
title has both
ph_label maps to the ph_label from the annotated layout (in the
content_type should be either
list depending on whether the placeholder contains text or list data.
The figure below shows how the annotated layout relates to the
yaml mapping file.