With ROI Emails, users can swap out content in emails based on the recipient’s attributes. This article describes the commands for writing dynamic content in ROI emails.


What is Freemarker?
ROI uses the industry standard Freemarker, a generic language you can use to create dynamic changes in an email. For example, if you wanted to included targeted content based on whether a recipient is male or female, you could use Freemarker to accomplish this. Freemarker script must be entered directly into the HTML source code of the email. You will use the same personalization fields you are already familiar with.


Note: Not all features and functionality of Freemarker are supported in ROI. Only the items listed below can be used in ROI


Simple Examples

Hello, 
<#if ${Contacts.Gender} == “female”>
  Mrs.
<#else>
  Mr.
</#if>
${Contacts.LastName}

In this example, the script will display “Mrs. Doe” if the recipient is female, or “Mr. Doe” otherwise.

<#if ${Contacts.FirstName?length} == 0>

Hello

<#else>

${Contacts.FirstName}

</#if>


In this example, the script will display the the first name data in the Contacts Table unless the first name field is blank then the script will display "Hello".


As you can see, the personalization fields are the same whether you are using them inside Freemaker tags or in the body of the email.


Let’s take a look at another example:

Hello, 
<#if ${Contacts.City} == “Indianapolis”>
  Welcome, Pacers fans! Go blue & yellow! 
<#else>
  Welcome, basketball fans!
</#if>

The content inside the Freemarker tags doesn’t have to be simple text content. It can hyperlinks, bold-ed or other HTML-rich content.

if, elseif, else
The if statement is the main decision making statement in Freemarker script. Here is the general syntax of the if statement:


<#if condition>
<#elseif condition>
<#elseif condition>
<#else>
</#if>

Every if statement must start with an <#if … > tag. The opening if tag can be followed by any number of <#elseif … > tags. An if statement may also contain an <#else> tag. Finally, the if statement is always ended with an </#if> tag. These will all be explained in detail after this example:

<#if ${Contacts.City} == “Indianapolis”>
    Hello Neighbor!
<#elseif ${Contacts.City} == “Chicago”>
    Sure is windy out today.
<#elseif ${Contacts.City} == “Miami”>
    Time to hit the beach!
<#else>
    I don’t know where you are located.
</#if>


This if statement contains one if tag, two elseif tags, and an else tag. The English translation of this if statement would be something like this:


If a contact’s city is set to “Indianapolis”, they will see the message “Hello Neighbor”.
Otherwise, if a contact’s city is set to “Chicago”, they will see the message “Sure is windy today”.
Otherwise, if a contacts city is set to “Miami”, they will see the message “Time to hit the beach!”
Otherwise, they will see the message “I don’t know where you are located”.


Remember, the <#elseif … > and <#else> tags are optional, so the following are all valid if statements:

  1. An if statement without any elseif or else tags:

    <#if ${Contacts.City} == “Indianapolis”>
    Hello Neighbor!
    </#if>
  2. An if statement with elseif tags, but no else tag:

    <#if ${Contacts.City} == “Indianapolis”>
    Hello Neighbor!
    <#elseif ${Contacts.City} == “Chicago”>
    Sure is windy out today.
    </#if>
    In this example, if you were in a city other than Indianapolis and Chicago no message will be displayed for you
  3. An if statement with just an else tag:

    <#if ${Contacts.City} == “Indianapolis”>
    Hello Neighbor!
    <#else>
    I don’t know where you are located.
    </#if>

An if statement is evaluated from the top down. Once one condition is met, the rest of the statement is skipped.


Comparison Operators
The examples you’ve seen so far have only been testing for equality, but that’s not the only way you can compare values. This section will list the comparison operators available to you and provide an example for each.


Equality, Inequality
As you’ve seen in the previous examples, the equals symbol (==) is used to test two values for equality. To test if two values are not equal, use the inequality symbol (!=). Here is an example:

<#if ${Contacts.Country} != “United States”>
    Ask us about our emerging market discounts!
</#if>

Helper Operators
There are numerous helper operators that are built into Freemarker that you can use in your emails. This table lists them, their description, and an example:

Operator Description Example
?cap_first Converts the first letter of a string to uppercase.
${Contacts.FirstName?cap_first}
?upper_case Converts an entire string to uppercase characters.
${Contacts.JobTitle?upper_case}
?lower_case Converts an entire string to lowercase characters.
${Company.Wesbsite?lower_case}
?trim Trims whitespace off of both ends of a string.
${Contacts.LastName}
?html Converts a string to an HTML safe output.
${“Tom & Jerry”?html}


The Helper operators can be chained together, for example:


${“       iT wAs ThE bEsT oF tImEs; It WaS tHe WoRsT oF tImEs.”?trim?lower_case?cap_first?html}


Would result in the output of: “It was the best of times; it was the worst of times.”