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:

  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:

    {{ order_date | date: "%B %d, %Y", locale: "fr" }}
    
  2. Localize (l) or translate (t) filters:

    {{ order_date | l: "date.formats.long" }}
    
  3. System-wide locale setting:

    {{ order_date | date: "long" }}
    
  4. 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 currency
  • money_with_currency: Formats a number as currency and includes the currency symbol or code

Usage examples:

  1. Basic currency formatting:

    {{ product.price | money }}
    

    This might output: "$10.00"

  2. Currency formatting with symbol:

    {{ product.price | money_with_currency }}
    

    This might output: "$10.00 USD"

  3. Locale-specific currency formatting:

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

    This might output: "10,00 €"

  4. Specifying a different currency:

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

    This might output: "€10.00"

  5. 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 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:
    {{ customer.first_name | default: "Valued Customer" }}
    
  4. Keep your templates simple and readable.
  5. Use comments to explain complex logic:
    {% 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:
    {% if customer.first_name %}Hello {{ customer.first_name }}{% else %}Hello there{% endif %}
    

Examples

  1. Personalized Email Greeting:

    Dear {{ customer.first_name | default: "Valued Customer" }},
    
  2. 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 %}
    
  3. 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 %}
    
  4. 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 %}
    
  5. 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 }}
    
  6. International Pricing:

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