Articles in this section

Creating Dynamic Links with FreeMarker

Overview

Using FreeMarker, we can populate dynamic, recipient-specific variables into the content of your emails to customize content for that recipient. It's a great way to add a personalized touch to emails and increase engagement. One way to track this increased engagement, and even pre-populate or personalize web content after a link click, is by including FreeMarker values in links. By including values like name or a unique ID related to a recipient and having a way to capture those unique values on your site, you can track their engagement with your website. Tools like Google Analytics capture UTM parameters attached to links to enable you to see how individuals are getting to your site, how long they stay, the pages they view, etc.

In this article, we're going to show you how to best populate your links with a FreeMarker variable while including a backup default value, just in case a recipient is missing the primary data. The benefit to having a default value option to present when the full name is unavailable is that trying to access missing values can cause errors, and having a default value allows you to avoid errors and potentially identify gaps in your data.

For our example here, the goal is to add the recipient's full name to the URL as a query string.

The way to express a value with a backup default value if the original can't be populated is ${unsafe_value!default_value}, so it follows that we could express the recipient's full name using ${Recipient.contact.fullname!"noname"}.

When adding this to a link, it's tempting to do this:

Incorrect:
<a href="http://www.domain.com?${Recipient.contact.fullname!'noname'}" rel="link">Link</a>

The issue with this is the single quotes ('') inside of the link's double quotes (""). Having single quotes inside of the double quotes here will cause syntax errors with the sent email.

In order to make this work, we need to remove the single quotes from inside the link href="..." area. We'll avoid this issue by using the <#assign> method in Freemarker to simplify what is contained in our link code.

Expression

There are two ways to use <#assign> to accomplish our goal: make the assignment for the full expression, or just for the backup value.

Full expression:
<#assign contactName>${Recipient.contact.fullname!'noname'}</#assign>
<a href="http://www.domain.com?${contactName}" rel="link">Link</a>

This is a good option if you want to use the same ${unsafe_value!default_value} combination in multiple places. It simplifies the content of the actual link by assigning a value to the full expression.

Default value:
<#assign backupValue>noname</#assign>
<a href="http://www.domain.com?${Recipient.contact.fullname!backupValue}" rel="link">Link</a>

This option is beneficial if you want to use the same default value with different primary (unsafe) values.

 

Placement

Just as there are two different ways to create an assignment for our goal, there are two different areas of the template code where the assignment can be placed.

In HTML body:
<html>
<body>
<#assign contactName>${Recipient.contact.fullname!'noname'}</#assign>
<a href="http://www.domain.com?${contactName}" rel="link">Link</a>
</body>
</html>

In this option, the assignment will function within the code following the assignment, but the same assignment won't be functional in content above that line. This is beneficial if you want the assignment to apply to a very narrow area of the email content, so keeping the code close together here helps to understand what ${contactName} references specifically.

Above all HTML content:
<#assign contactName>${Recipient.contact.fullname!'noname'}</#assign>
<html>
<head></head>
<body>
<a href="http://www.domain.com?${contactName}" rel="link">Link</a>
</body>
</html>

This second option is a good one for cases where you want to use the assignment to express the value in multiple places in the email content. By placing it outside of the <html> tags, the assignment will be available to the full content of the email.

For more about expressing a default value option in FreeMarker, check the link here

For more about Assignment operators in FreeMarker, check the link here

Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Article is closed for comments.