Overview

The templating framework Dispatch utilizes is called Freemarker. Dispatch evaluates the text provided in templates and a few other communication fields to do variable replacement, expression evaluation, includes, and some other basic template operations. This is not meant to be a definitive guide to Freemarker, but rather a quick reference to the most commonly used functions. See the Freemarker Manual for a full list of its capabilities.

Printing variables

Variables from your population are available to Freemarker as top-level variables that you can print. All populations should contain the values: toAddress and toName. Depending upon your population data source, those variables may come across as lower or upper case (Oracle queries should return variable names as uppercase). All variables are case-sensitive. Freemarker will yell at you if it can't locate a variable.

For more information, see Freemarker manual reference

${toAddress}

if/else/elseif

For more info, see Freemarker manual reference

<#if condition == "abc">
     ...
<#elseif condition2 == "def">
     ...
<#elseif condition3 == "ghi">
     ...
     ...
<#else>
     ...
</#if>

Check for null

If you are not sure a variable is available in your population, you can check to see if it exists and then print it.

<#if userName??>
    Hi ${userName}, How are you?
</#if>

Lists

Using lists in Dispatch templates is tricky because Dispatch basically expects each member in a population to just have a series of String key/value pairs as attributes. There are two somewhat hacky ways to get a list to work. For our example, let's assume you have a series items you want to list out in a template such as a person with a list of known addresses.

Example 1: lists, assign and eval

Your population could contain fields like: toName, address_1, address_2, address_3 and using Freemarker's list, assign and eval functions you could effectively list out the addresses. It's not the most elegant solution, but it works.

<#list 0..1000 as i>
    <#assign var = "address_${i}">
    <#if var?eval??>
        ${var?eval}
    <#else>
        <#break>
    </#if>
</#list>

Example 2: Delimited lists

Your population could contain fields like: to_name, addresses where the field "addresses" contains a delimited string with a list of values like "Home Address:123 Main St.; Work Address 999 1st Ave.". You could then loop through that list using the semicolon as a delimiter and splitting the address string. This solution doesn't feel as hacky, but it is limiting.

<#list addresses?trim?substring(0,(addresses?trim?length))?split(";") as address>
    ${address?replace(':', ': <strong>')}</strong><br />
</#list>

If your delimited list always ends in the delimiter, you'll need to adjust the second argument of the substring function to trim off the last character. Assuming a slightly different list like: "Home Address:123 Main St.; Work Address 999 1st Ave.;".

<#list addresses?trim?substring(0,(addresses?trim?length-1))?split(";") as address>
    ${address?replace(':', ': <strong>')}</strong><br />
</#list>

include

You can dynamically load content using Freemarker's include tag. The path to template you want to include is just the template's name. Note: the Quick Preview function from the tempalte error will not render the include.

For additional information, see Freemarker manual reference.

Example 1: include a common footer

This example shows a template some unique content and then we include an additional Dispatch template titled "footer".

This is my unique content

<#include "footer">

Example 2: dynamically change template based on member attribute

You could have a scenario where you have multitudes of templates with quite varying content and you want to switch between them in a single communication. To accomplish this you communication would have a very simple template like such:

<#include "${template}">

You population would then include a member attribute (templateName) indicating which template should be used for that particular member.

Related topics: