Basics of Personalization in MessageGears (Using FreeMarker)

Overview

Please note that before starting that MessageGears uses Apache FreeMarker (version 2.3.23) for both Content Templates and SQL templates. For more detailed information on FreeMarker, the official handbook from Apache can be found by clicking on the following link. This document will cover some of the more basic examples of FreeMarker uses for your Campaign. You can find additional information on building Campaigns with MessageGears, in the FreeMarker Intermediate and Advanced sections.

Table of Contents

FreeMarker Basics

Using Merge Tags from a MessageGears Audience

Conditional Statements

Supplement Conditional Statements

Operators in Conditional Statements

Creating and using Variables

FreeMarker Basics

FreeMarker is an open-source templating language. This means that it uses placeholder text, also called variables, to create dynamic content. This templating language, along with Audience Data and Context Data used in Accelerator, means that personalized content can easily be created within MessageGears Templates.

For example, if your Audience has a field called “first_name”, then using the variable ${Recipient.first_name} inputs the first name of the listed recipient of your email for the Recipient. This allows you to change the first name for each different contact with very little effort and almost instantly. This is a type of Personalized Attribute in the Templates that is commonly referred to as a Merge Tag. 

Using Merge Tags from a MessageGears Audience

A helpful feature of Merge Tags is that while they can be manually entered into Templates, they do not need to be manually entered. By using either the Drag-and-Drop method or an HTML Editor, Merge Tags can be selectable from a pre-generated list.

Examples of Merge Tags

Recipient Merge Tags from Audience Data allow you to use a reference from the field name within the Recipient Object. The following Merge Tag will allow you to use your Recipient's first name (from your data source) in your template:

${Recipient.first_name}

An example of this Merge Tag being used in a Template is the following:

Hello, ${Recipient.first_name}, and welcome to the City & Glory Membership Program. Your new account number is ${Recipient.acct_num} and can be used in any of the City & Glory stores.

In this case, the message included in the template will now automatically contain the first name of the Recipient when the message is sent.

When adding a Merge Tag using HTML, the Recipient Data must be surrounded by a dollar sign $ and curly brackets {}. When referencing Recipient Data within FreeMarker directives, such as an <#if> tag or an <#assign> tag (both covered below), then the Recipient Data does not need to be surrounded by the dollar sign and curly brackets. This is referred to as FreeMarker Expression Mode.

Conditional Statements

Condition Statements are a powerful part of the FreeMarker templating language. Conditional Statements are used to handle content that should only display if one or more conditions are met. There are a number of different Conditional Statements that are available to users, and a broader list of examples can be found by clicking on the following link.

The most common way to use Conditional Statements is within an IF statement. The content within an IF statement is only displayed if the condition is met. An example of one of these statements is below:

<#if Recipient.state == "CA">
  Your account can be removed by clicking this link.
</#if>

In this example, a piece of content will only be rendered within the Template IF the Recipient’s state within the Audience Data is "CA." IF this condition is not met, THEN the content is not rendered within the Template.

Multiple conditions can be included using the following logical operators: AND, OR, NOT

An example of the logical operators:

The AND Operator:

<#if Recipient.state == "CA" && Recipient.age == 21 >

The OR Operator:

<#if Recipient.state == "CA" || Recipient.state == "AZ">

The NOT Operator:

<#if !Recipient.state == "CA">

<#if Recipient.state != "CA">

Supplement Conditional Statements

In addition, there is also an ELSE statement. This statement can be used with an IF statement to allow a default piece of content to be used if the IF statement condition is not met. For example:

<#if Recipient.state == "CA">
  Your account can be removed by clicking this link.
<#else>
  Your account can be deactivated by clicking this link.
</#if>

The last type of basic Conditional Statements is the ELSEIF statement. The ELSEIF statement is meant to be used after the first IF statement, but before the default ELSE statement. This is used if multiple entries within the Conditional Statements need conditions applied. For example:

<#if Recipient.state == "CA">
  Your account can be removed by clicking this link.
<#elseif Recipient.state == "AZ">
  Your account can be deactivated by clicking this link.
<#else>
  To turn off email notifications, click here.
<#/if>

Conditional Statements can also be embedded within each other, creating an IF statement within an IF statement. An example of this:

<#if Recipient.acct_tier == "Platinum">
  <#if Recipient.days_since_last_purchase gte 10>
    We miss you! Check out the new deals in store.
  </#if>
  <#else>
    More deals than before! Check out the new deals in store.
</#if>

Operators in Conditional Statements

When evaluating integer values, many different operators can be used. Some of these operators work in similar ways to other programming languages.

When evaluating if values are equal:

<#if x == 4>

When evaluating if values are not equal:

<#if x != 4>
Or
<#if !x == 4>

Greater than and lesser than values work differently in FreeMarker compared to other programming languages. Because FreeMarker is contained within an HTML tag, the angled brackets cannot be used in the operation because the HTML tag may be closed.

When evaluating a greater than or lesser than value:

Greater Than - <#if x gt 4>
Less Than - <#if x lt 4>

Greater Than Or Equal To - <#if x gte 4>
Less Than Or Equal To - <#if x lte 4>

Creating and using Variables

Variables are established in FreeMarker using the Assign tag. Assigning variables can be done within one line of code, or broken into multiple lines to establish multiple variables at the same time.

When building a MessageGears Template, it is a best practice to use Snippets to organize variable assignments into one place. Snippets are configured for each Template individually and are commonly used to handle data management or advanced properties in a separate location than an HTML Template. Instead of coding everything within one file, a Snippet allows the organization of data and is referenced in the final product. 

There are a few different ways to assign variables:

<#assign x = 4>

<#assign x = 4 y = 5>

<#assign
x = 4
y = 5
>

Within an Assign tag, multiple variables can be established. These variables do not have to all be the same data type.

<#assign
x = 4
first_name = "John"
seq = ["Doe", 123, "Variables"]
>

Variables can also be assigned Recipient data or Context Data:

<#assign first_name = Recipient.first_name>

This is useful if data from the Audience or Context Data must be processed or altered before use within the Template.