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:

1. Output markup (denoted by {{ }}): Used to output content.
2. 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 string
• downcase: Converts a string to lowercase
• upcase: Converts a string to uppercase
• date: 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 statements
• unless: 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:

1. Locale parameter in date filter:

   Liquid

   {{ order_date | date: "%B %d, %Y", locale: "fr" }}
   

2. Localize (l) or translate (t) filters:

   Liquid

   {{ order_date | l: "date.formats.long" }}
   

3. System-wide locale setting:

   Liquid

   {{ order_date | date: "long" }}
   

4. Locale-aware time zones:

   Liquid

   {{ 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 currency
• money_with_currency: Formats a number as currency and includes the currency symbol or code

Usage examples:

1. Basic currency formatting:

   Liquid

   {{ product.price | money }}
   

   This might output: "$10.00"

2. Currency formatting with symbol:

   Liquid

   {{ product.price | money_with_currency }}
   

   This might output: "$10.00 USD"

3. Locale-specific currency formatting:

   Liquid

   {{ product.price | money: locale: "fr" }}
   

   This might output: "10,00 €"

4. Specifying a different currency:

   Liquid

   {{ product.price | money: currency: "EUR" }}
   

   This might output: "€10.00"

5. Combining locale and currency:

   Liquid

   {{ 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 array
• break: Exit a loop
• continue: Skip the current iteration

Usage example:

Your recent purchases:
{% for product in customer.recent_purchases limit:3 %}
  - {{ product.name }}
{% endfor %}

Best Practices

1. Always test your templates with sample data before sending.
2. Use meaningful variable names for clarity.
3. Implement fallback content for missing data:
   Liquid

   {{ customer.first_name | default: "Valued Customer" }}
   

4. Keep your templates simple and readable.
5. Use comments to explain complex logic:
   Liquid

   {% comment %}Check if customer is eligible for discount{% endcomment %}
   

6. Be mindful of different locales when formatting dates and currencies.
7. Use appropriate error handling to prevent broken personalization:
   Liquid

   {% if customer.first_name %}Hello {{ customer.first_name }}{% else %}Hello there{% endif %}
   

Examples

1. Personalized Email Greeting:

   Liquid

   Dear {{ customer.first_name | default: "Valued Customer" }},
   

2. Conditional Content based on Purchase History:

   Liquid

   {% 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 %}
   

3. Product Recommendations with Price:

   Liquid

   Based on your interests, we recommend:
   {% for product in recommended_products limit:3 %}
     - {{ product.name }}: {{ product.price | money_with_currency }}
   {% endfor %}
   

4. Abandoned Cart Reminder with Total:

   Liquid

   {% 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 %}
   

5. Event Countdown with Localized Date:

   Liquid

   {% 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 }}
   

6. International Pricing:

   Liquid

   Our new product is now available!
   Price in your region: {{ product.price | money_with_currency: locale: customer.locale }}