Add Dynamic Content Using Liquid
This guide provides an overview of the Liquid template language, focusing on features relevant for personalizing messages in Engage+.
Introduction to Liquid
Liquid is a templating language used to add dynamic content. It allows you to personalize your messages based on user data, making your communications more relevant and engaging.
Note
By default, the Liquid language is not enabled. You need to raise a Jira ticket to the sustenance team and enable the LiquidFeature config.
Basic Syntax
Liquid uses two types of markup:
- Output markup (denoted by {{ }}): Used to output content.
- Tag markup (denoted by {% %}): Used for logic and control flow.
Variables
Variables allow you to insert dynamic content into your templates. Common variables might include:
{{ customer.first_name }}
: The customer's first name{{ customer.email }}
: The customer's email address{{ customer.total_purchases }}
: The total number of purchases made by the customer
Usage example:
Hello {{ customer.first_name }},
Variable Formatting
Formatting modify the output of Liquid objects. They are used with the pipe character ( | ).
Common filters include:
capitalize
: Capitalizes the first letter of a stringdowncase
: Converts a string to lowercaseupcase
: Converts a string to uppercasedate
: Formats a date (see Date Formatting section)money
: Formats a number as currency (see Currency Formatting section)
Usage example:
Welcome back, {{ customer.first_name | capitalize }}!
Your last purchase was on {{ customer.last_purchase_date | date: "%B %d, %Y" }}.
Control Flow
Control flow tags create conditions that decide whether blocks of Liquid code should be executed.
Common control flow tags:
if
,elsif
,else
: Conditional statementsunless
: Negative conditional statement
Usage example:
{% if customer.vip_status == true %}
Enjoy your exclusive VIP offer!
{% elsif customer.total_purchases > 5 %}
Thanks for being a loyal customer!
{% else %}
Check out our latest products!
{% endif %}
Date Formatting
Dates can be formatted using the date
filter. Here are some common format specifiers:
%B
: Full month name (e.g., "January")%b
: Abbreviated month name (e.g., "Jan")%d
: Day of the month, zero-padded (01-31)%e
: Day of the month (1-31)%Y
: Four-digit year (e.g., 2024)%y
: Two-digit year (e.g., 24)%H
: Hour in 24-hour format (00-23)%I
: Hour in 12-hour format (01-12)%M
: Minute (00-59)%S
: Second (00-59)%p
: AM/PM
Example:
{{ order_date | date: "%B %d, %Y at %I:%M %p" }}
This might output: "September 26, 2024 at 02:30 PM"
Locale-Specific Date Formatting
For international audiences, you may need to format dates according to specific locales here are some common approaches:
-
Locale parameter in date filter:
{{ order_date | date: "%B %d, %Y", locale: "fr" }}
-
Localize (
l
) or translate (t
) filters:{{ order_date | l: "date.formats.long" }}
-
System-wide locale setting:
{{ order_date | date: "long" }}
-
Locale-aware time zones:
{{ event_date | date: "%B %d, %Y at %I:%M %p %Z", locale: "de" }}
Currency Formatting
Liquid typically provides filters for formatting monetary values according to different currencies and locales.
Common currency filters include:
money
: Formats a number as currencymoney_with_currency
: Formats a number as currency and includes the currency symbol or code
Usage examples:
-
Basic currency formatting:
{{ product.price | money }}
This might output: "$10.00"
-
Currency formatting with symbol:
{{ product.price | money_with_currency }}
This might output: "$10.00 USD"
-
Locale-specific currency formatting:
{{ product.price | money: locale: "fr" }}
This might output: "10,00 €"
-
Specifying a different currency:
{{ product.price | money: currency: "EUR" }}
This might output: "€10.00"
-
Combining locale and currency:
{{ product.price | money_with_currency: currency: "JPY", locale: "ja" }}
This might output: "¥1,000 JPY"
Loops
Loops are used to iterate over collections like arrays or hashes.
Common loop tags:
for
: Iterate over an arraybreak
: Exit a loopcontinue
: Skip the current iteration
Usage example:
Your recent purchases:
{% for product in customer.recent_purchases limit:3 %}
- {{ product.name }}
{% endfor %}
Best Practices
- Always test your templates with sample data before sending.
- Use meaningful variable names for clarity.
- Implement fallback content for missing data:
{{ customer.first_name | default: "Valued Customer" }}
- Keep your templates simple and readable.
- Use comments to explain complex logic:
{% comment %}Check if customer is eligible for discount{% endcomment %}
- Be mindful of different locales when formatting dates and currencies.
- Use appropriate error handling to prevent broken personalization:
{% if customer.first_name %}Hello {{ customer.first_name }}{% else %}Hello there{% endif %}
Examples
-
Personalized Email Greeting:
Dear {{ customer.first_name | default: "Valued Customer" }},
-
Conditional Content based on Purchase History:
{% if customer.total_purchases > 10 %} As a loyal customer, enjoy 20% off your next purchase! {% elsif customer.total_purchases > 5 %} Thanks for your continued support. Here's 10% off your next order! {% else %} Shop now and start earning rewards! {% endif %}
-
Product Recommendations with Price:
Based on your interests, we recommend: {% for product in recommended_products limit:3 %} - {{ product.name }}: {{ product.price | money_with_currency }} {% endfor %}
-
Abandoned Cart Reminder with Total:
{% if customer.abandoned_cart %} Don't forget about the items in your cart: {% for item in customer.abandoned_cart.items %} - {{ item.name }}: {{ item.price | money }} {% endfor %} Total: {{ customer.abandoned_cart.total | money_with_currency }} {% endif %}
-
Event Countdown with Localized Date:
{% assign days_until_event = event_date | date: "%s" | minus: "now" | date: "%s" | divided_by: 86400 %} Only {{ days_until_event }} days until our big sale! Mark your calendar: {{ event_date | date: "long", locale: customer.locale }}
-
International Pricing:
Our new product is now available! Price in your region: {{ product.price | money_with_currency: locale: customer.locale }}
Updated 2 days ago