FreeMarker: Syntax and Interpolations

The basic element of FreeMarker is the interpolation. This is basically a statement that is used to reference and display a specific piece of information.

Goals

• Learn how to interpret the syntax of a FreeMarker statement
• Learn how to write your own FreeMarker 

Understanding FreeMarker

A FreeMarker template consists of one of at least three elements:

1. Interpolations: ${...} These sections will be replaced with a calculated value in the output. Interpolations are delimited by ${ and }
   
   
2. FTL Tags; #if, #else, #list, etc. FTL tags are a bit similar to HTML tags, but they are instructions to FreeMarker and will not be printed to the output.
   
   
3. Comments: <#-- and --> Comments are similar to HTML comments, but they are delimited by <#-- and -->. Comments will be ignored by FreeMarker, and will not be written to the output.

Anything that is not an Interpolation, FTL Tag, or Comment is considered static text and will not be interpreted by FreeMarker.  It will be printed to the output as-is.

Interpolations: ${...}

FreeMarker will replace an interpolation in the output (i.e. the actual email) with the actual value of the expression inside the curly brackets.

For this example: ${Recipient.contact.firstname[0]!""} is referencing the value of a field directly on the Contact record.

In this interpolation, the expression is telling FreeMarker to replace the interpolation with the data in the recipient's Contact record's "First Name" field.

So that this in the email template editor: Hello ${Recipient.contact.firstname[0]!"Valued Customer"}

Becomes this in the final email that the recipient (named Susan) sees: Hello Susan

The text within the quotation marks is backup text that will be displayed if there is no value in the specified field on the recipient’s Lead/Contact/Account record. So, if the recipient’s record does not have a First Name value, the final email will display "Hello Valued Customer".

Code Your Own

In many situations you will need to write out your own FreeMarker, rather than use the Personalization Menu. Here is a breakdown of what each piece of a FreeMarker interpolation does:

${Recipient.contact.firstname} – this represents the entity from which data is being pulled. In this case, it is the contact that the email will be sent to. If it is referencing a Lead record, then this would be ${Recipient.lead.

${Recipient.contact.firstname} – this represents the schema name of the field on the contact record from which data will be pulled.  

Using FreeMarker with Lookup Fields

Freemarker can also be used to reference data from a record that is linked to the recipient via a lookup field. In this example, we are referencing a value found on a lookup field on the Contact's record.

• ${Recipient.contact.parentcustomerid.account.name} – this represents the entity through which we are accessing the lookup field to pull data from the related record. In this case, it is the contact that email will be sent to.
• ${Recipient.contact.parentcustomerid.account.name} – this represents the schema name of the lookup field, in this case the lookup to the parent account record
• ${Recipient.contact.parentcustomerid.account.name} – this represents the primary entity of the relationship in our case Account
• ${Recipient.contact.parentcustomerid.account.name} – this represents the field that we want to display in the email, in this case the Account Name.

This interpolation is attempting to pull information from the "Name" field of an Account record that the Contact is related to.

NOTE: FreeMarker can only reference data from records that are at most one level removed from the recipient. Like the example above, FreeMarker can be used to reference data from a contact's parent account, but it could not be used to reference data from the recipient's parent account's owning user because the user is two levels removed from the contact.