Skip to content

Personalizing messages

FreeMarker can be used in the subject and body of email campaigns. FreeMarker is a templating engine, a Java library for generating textual output. With FreeMarker, you can manage the content of emails.

Link to full FreeMarker documentation - https://freemarker.apache.org/docs

Defining and Setting Variables

Creating a variable and assigning a value to it:

  • <#assign positionSum = 4200000> - creates a numeric variable
  • <#assign subscriberTitle = "Attention"> - creates a string variable
  • ${positionSum} or ${subscriberTitle} - outputs the created variable

If it is necessary to display subscriber data stored in the address book, then the variable name is formed as the reserved word "contact." plus the field name (fields.name) from contact base.

  • ${contact.name} - displays the contact details, in this case the "Name" column
  • ${contact.birthdate} - displays contact details, in this case the column "Date of birth"

Mathematical operations

Can be used to:

  • calculate the size of the discount in rubles,
  • calculate the amount of the discount as a percentage,
  • calculate how many points a subscriber needs to accumulate to move to the next step of the loyalty program,
  • recalculate prices taking into account personal discounts.

Examples:

  • ${positionSum * 0.50}
  • ${positionSum * 0.25 / 100}%
  • <p class="sale">${(product.oldPrice-product.price)/product.oldPrice*100}%</p>

Rounding

Information

The methods described below only round to whole number. If you need to display a number, leaving a few digits after the comma, then see the paragraph "Output Formats"

Rounding methods:

  • round: round to nearest whole number (if there is 5 or more after the decimal point, then the number is rounded up, otherwise - down)
  • floor: rounds the number always down
  • ceiling: rounds the number always up

Examples:

  • For example, let's take price = 12.534721
    • ${price?round} - will show 13
    • ${price?floor} - will show 12
    • ${price?ceiling} - will show 13
  • For example, let's take price = 48.2521
    • ${price?round} - will show 48
    • ${price?floor} - will show 48
    • ${price?ceiling} - will show 49

Output formats

This is output conversion and rounding.

For example, if you want to display the discount amount with one decimal place in order not to get the value 12.23472100012%.

  • For example, let's take price = 12.234721
    • ${price?string["0"]} - will show 12
    • ${price?string["0.#"]} - will show 12.2
    • ${price?string["0.##"]} - will show 12.23
    • ${price?string["0.###"]} - will show 12.235
    • ${price?string["0.####"]} - will show 12.2347

Work with text

If the names of the goods are generated in different ways, then the method of changing the case of strings - capitalize - is suitable to bring all the names to a single style.

In order not to break the layout of the product card, you can use:

  • using the length method to determine the length of the string
  • using the truncate method to truncate a line and/or add an ellipsis at the end.

You can apply several methods in a row to variables

For example, let's take product.name = "Women shoes".

  • Change case of strings
    • ${product.name?capitalize} - a string where all words start with a capital letter
      • ${" women shoes"?capitalize} - will show " Women Shoes"
      • ${"WoMen Shoes"?capitalize} - will show "Women Shoes"
    • ${product.name?lower_case} - the whole string is lowercase
      • ${"WoMen Shoes"?lower_case} - will show "women shoes"
    • ${product.name?upper_case} - the whole string is uppercase
      • ${"WoMen Shoes"?upper_case} - will show "WOMEN SHOES"
  • Calculate string length
    • ${product.name?length} - 11
  • Truncate string
    • in the brackets of the truncate method, you need to specify the length, taking into account all additional characters
    • ${product.name?truncate(10)} - will show "Women[...]", because this function in after trimming the string adds [...]
    • ${product.name?truncate(5, '---')} - will show "Wo---", because this function allows you to set those characters that will be added at the end of the line
  • Apply multiple methods
    • ${product.name?capitalize?truncate(13)} - will show "Women Sh[...]"

Logical conditions

The following logical constructions are allowed:

<#if condition>
  ...
<#elseif condition2>
  ...
<#elseif condition3>
  ...
...
<#else>
  ...
</#if>

Example with a blank subscriber name

For example, if you need to display the name of a subscriber, you can display it like this: "Hello, ${contact.name}!"

If the subscriber does not have a name, he will see the text with extra commas and spaces "Hello, !"

Suitable options:

  • "Hello<#if (contact.name?length>1)>, ${contact.name?capitalize}<!--#if-->!"
  • "Hello<#if contact.name??>, ${contact.name?capitalize}<!--#if-->!"
  • "Hello<#if contact.name?has_content>, ${contact.name?capitalize}<!--#if-->!"

Example with displaying/hiding a block for subscribers by condition

The letter of the pet supply store must contain 3 banners. The dog owner does not need to show a banner that suits the cat or parrot owner.

If you do not specify the conditions:

<a href=”#”><img src=”/banner-dog.png” /></a><br />
<a href=”#”><img src=”/banner-cat.png” /></a><br />
<a href=”#”><img src=”/banner-bird.png” /></a>

With the condition:

<#if ${contact.pet}="собака">
    <a href=”#”><img src=”/banner-dog.png” /></a>
<#else>
    <a href=”#”><img src=”/banner-cat.png” /></a>
    <a href=”#”><img src=”/banner-bird.png” /></a>
</#if>

Loops

Example of displaying an array of products for triggers

The layout designer draws up the code of one product card, which can be multiplied using a cycle by the number of products selected for display in the letter.

<#list eventInfos as event>
    <div class=”product”>
        <a href=”${event.productURL}”><img src="${event.productImg}" /></a>
        <p class=”product-title”><a href=”${event.productURL}”>${event.productName}</a></p>
        <p class=”product-price”><a href=”${event.productURL}”>Price ${event.productPrice} euro</a></p>
    </div>
</#list>

Example of a filter in a loop

The client decides not to show subscribers products that are cheaper than 20 euro.

<#list eventInfos as event>
    <#if ${event.productPrice}<20 ><#continue></#if>
    <div class=”product”><a href=”${event.productURL}”><img src="${event.productImg}" /></a>
    <p class=”product-title”><a href=”${event.productURL}”>${event.productName}</a></p>
    <p class=”product-price”><a href=”${event.productURL}”>Price ${event.productPrice}} euro</a></p>
</#list>

An example of checking for the presence of values in a loop

If the loop is empty, display a message stating that there are no products.

<#list eventInfos as event>
    <div class=”product”><a href=”${event.productURL}”><img src="${event.productImg}" /></a>
    <p class=”product-title”><a href=”${event.productURL}”>${event.productName}</a></p>
    <p class=”product-price”><a href=”${event.productURL}”>Price ${event.productPrice}} euro</a></p>
    <#else>
    No products
</#list>

An example of adding a separator between loop elements

To add a separator between loop elements, you can use the <#sep> directive, which will add code after each loop element except the last.

<#list eventInfos as event>
    <p class=”categoryTitle”><a href=”${event.categoryUrl}”>${event.categoryTitle}</a></p>
    <#sep>, </#sep>
</#list>