Introduction to Scriptlets - Templating Language for Document Studio
Document Studio supports Scriptlets, an email templating language that lets you include sophisticated logic with conditional operators. For instance, use the if/else filter to conditionally render some content if a specified condition is true. If the condition is false, no content is rendered or another block of content may be rendered.
You can also create dynamic content or reformat content using a simple syntax. For instance, respondents of a Google Form may enter their name in all lowercase format (e.g. "angus"), but you may want to display the names in their original format with the first letters capitalized (e.g. "Angus"). This is where Scriptlets come in.
Filters
Filters change the output of a scriptlet. They are delimited by {? and ?}. When the template is rendered, the filter is replaced with the evaluated value of the filter.
For instance, the following scriptlet will capitalize the first letter of the first word of the input text.
{? "angus" | capitalize ?}
// Output: Angus
Multiple filters can be used on one output, separated by the pipe(|) character, and are executed in the order they appear from left to right. The output of the previous filter will become the input of the next filter in the chaining.
For instance, the following scriptlet will round the input number to two decimal places and then prepend the output with custom text.
{? 183.929 | round: 2 | prepend: "The due amount is $" ?}
// Output: The due amount is $183.93
In the next example, the expression will replace all occurrences of the word color with colour in the output.
{? "My favorite color is blue" | replace: "color", "colour" ?}
// Output: My favorite colour is blue
| Filter Group | Available Filters |
|---|---|
| String Manipulation | default, append, prepend, slice, capitalize, upcase, downcase, truncate, truncatewords |
| Array Operations | size, split, join, concat, reverse, uniq, sort, sort_natural, first, last |
| Date Formats | now, today |
| Math Operations | round, times, abs, ceil, floor, plus, minus, divided_by, modulo, at_least, at_most |
| Replace & Remove | replace, replace_first, remove, remove_first, strip, rstrip, lstrip, strip_newlines |
| HTML Entities | escape, escape_once, url_encode, url_decode, newline_to_br |
Tags
Tags create the logic and control the flow for your scriptlets. They are delimited by {% and %}. Any text that is surrounded by {%...%} is treated as a tag and is not included in the output.
For instance, the scriptlet below takes a string containing a list of fruit names and prints the first two fruit names in separate lines.
{% assign fruitArray = "Apple, Orange, Mango" | split: ", " %}
{% for fruit in fruitArray limit:2 %}
{? fruit ?}
{% endfor %}
// Output: Apple Orange (two lines)
Tags can also be used to print conditional content. For instance, the following scriptlet will add the relevant salutation based on the answer entered by the respondent for the question Input your gender in the Google Form.
{% assign gender = "{{Input your gender}}" %}
{% assign lowergender = gender | downcase %}
{% if lowergender == "female" %}
Hello Ms {{First Name}}
{% else %}
Hello Mr {{First Name}}
{% endif %}
| Tag Group | Available Tags |
|---|---|
| Conditional Tags | if else, if elsif, switch case, unless |
| Control Loops | for in, limit, offset, break, continue, increment, decrement |
Dynamic Fields
The general syntax of any Scriptlet expression is {? <input text> | <filter 1> | <filter 2> | ... ?}. The text enclosed within the {?...?} delimiters becomes the output, after being acted upon by all filters in sequence.
The input text can also be replaced by dynamic fields (column headers) using the double curly bracket syntax.
For instance, if you have a column in your Google Sheet titled Full Name, you can use the following scriptlet to display the first name of each respondent prepended with a greeting.
Hello {? {{Full Name}} | split: " " | first | append: "!" ?}
// Output: Hello Angus!