Handlebars is a templating mechanism that provides the ability to define a template with placeholders for expected data elements. At runtime, the actual values for those data elements are substituted into the template to create an output.
Handlebars utilizes Mustache which is a logicless template engine. Mustache was originally created to allow building more dynamic HTML pages, but it can be used for any text-based output that can be created from a template.
Use cases
Handlebars can address a wide variety of needs, including:
- Generating formatted emails
- Creating files or text in a required format, such as the body of an HTTP POST request
- Processing complex JSON payloads, such as those that have nested arrays
Handlebars commands
There are two commands for the Handlebars connector:
- Render file template: This command is used to create large (>32k characters) outputs. It produces a physical file that can be used by subsequent chain commands that require file input. One option to store a file template in Workiva is file resources.
- Render text template: This command is used to create small to medium outputs. It generates a text-based output which cannot be used in subsequent commands that require a physical file.
In turn, each of these commands have two primary components:
- Template: The text that is updated when the command runs. The text is rendered exactly as specified, including any indenting or carriage returns.
- Variables: The values that will be replaced in the template when the command runs. Individual variables can be specified, such as the row count output of a command like advanced query.
Example configuration
The following is a sample configuration using a render text template:
In the template section of the command, there are several things worth noting:
This template renders plain and json variables.
- This text is indented and renders the Row Count: {{rows}}
Below are the list of priorities in the JSON object
{{#each priorities}}
+{{Priority}}
{{/each}}
- The first line of the template is purely text and does not use any variables.
- The second line is indented and uses the rows variable.
- The third line is blank because of a carriage return.
- Lines 4-6 are used to process the JSON variable called priorities.
- Line 4 is the beginning of a loop through the JSON variable called priorities.
- Line 5 returns the value from the JSON key-value pair for the key called Priority. Note that key names are case sensitive -- a plus sign (+) was added to the line to display how plain text and variable values can usually be combined.
- Line 6 closes the loop through the priorities JSON object.
In the variables section of the command:
- A variable named rows is defined as the Record Count output from a previous command.
- A JSON variable named priorities is defined as the JSON File output of a previous command.
In this example, the JSON object is the following:
[
{"Priority":"Medium"},
{"Priority":"High"},
{"Priority":"Low"}
]
The resulting rendered text from the Handlebars command is below:
Note: Additional information about Handlebar functions and how they can be used to construct a template can be found in our Handlebars functions article.
Things to know
Variable placeholders are defined by double ({{Variable_Name}}) or triple ({{{Variable_Name}}}) curly braces. Triple curly braces are used when a variable value contains HTML special characters that need to be rendered as the character, as opposed to the HTML code associated with the character.
For example, the greater than character (>) is an HTML special character. With double braces, a variable value containing this character would render the HTML code (>) while triple braces would render the greater than (>) character.