Skip to main content

Liquid Templating

Overview​

Liquid is a lightweight, safe, and extensible templating language originally created by Shopify. It is designed to load dynamic content into templates while preventing unsafe operations. Liquid is widely used for generating HTML, emails, configuration files, and dynamic text based on structured data.

Liquid focuses on simplicity, security, and predictability, making it suitable for both developers and non-technical users.

info

You can find the full documentation of the liquid engine here : LiquidJS Documentation

Liquid Usage in Insurgate​

Liquid templating is used extensively across Insurgate to generate dynamic content based on contextual data.

Email Generation​

Liquid is used in all generated emails, whether they are:

  • Basic emails with simple dynamic fields
  • Advanced emails based on full templates

This allows emails to adapt their content dynamically depending on the request, user, or workflow context.

Request Title Templating​

Liquid is also used to generate the request title.
The title itself is a Liquid template that is interpreted at runtime, enabling titles to include dynamic data such as identifiers, names, dates, or other contextual values.

This makes request titles both descriptive and automatically generated.

Library Usage​

Finally, Liquid is used within the library, following a defined format, to generate dynamic content consistently across the platform.

Important Notes About Rendering Engines​

Be aware that the Liquid rendering engine is not exactly the same in all contexts:

  • Emails are generated by the backend, using a Ruby Liquid engine
  • Library rendering is handled by the frontend, using a JavaScript Liquid engine

Because of this, small differences may occur between the two renderers.

Key points to watch out for:

  • In Ruby Liquid, whitespace handling can be more strict
  • Ensure spacing and syntax are consistent across templates
  • If a template works in one context but not the other, the issue is often due to subtle differences between the Ruby and JavaScript rendering engines

When troubleshooting, always compare how the template is interpreted by each engine.

Core Concepts​

Liquid templates are built around three main elements:

  • Objects: Output data
  • Tags: Control logic and flow
  • Filters: Transform data

Syntax Basics​

Output (Objects)​

Objects are wrapped in double curly braces and are used to display data.

{{ user.name }}
{{ order.total }}

If a value is missing or undefined, Liquid outputs an empty string instead of throwing an error.

Tags (Logic & Control Flow)​

Tags are wrapped in {% %} and control the behavior of the template.

Conditionals​

{% if user.logged_in %}
  Welcome back, {{ user.name }}!
{% else %}
  Please log in.
{% endif %}

Loops​

{% for item in cart.items %}
  {{ item.name }} - {{ item.price }}
{% endfor %}

Assignments​

{% assign total = order.subtotal %}

Filters​

Filters modify the output of objects. They are applied using the pipe (|) symbol.

{{ user.name | upcase }}
{{ price | round: 2 }}
{{ description | truncate: 50 }}

Filters can be chained:

{{ title | strip | capitalize }}

Common Built-in Filters​

FilterDescription
upcaseConverts text to uppercase
downcaseConverts text to lowercase
capitalizeCapitalizes the first letter
truncateShortens text with ellipsis
replaceReplaces a substring
defaultProvides a fallback value

Example:

{{ user.email | default: "[email protected]" }}

Arrays and Collections​

Accessing Elements​

{{ products[0].name }}

Loop Helpers​

{% for product in products %}
  {{ forloop.index }} - {{ product.name }}
{% endfor %}

Available helpers:

  • forloop.index
  • forloop.first
  • forloop.last
  • forloop.length

Whitespace Control​

Liquid allows trimming whitespace using hyphens.

{{- value -}}
{% if condition -%}

This is useful for generating clean HTML or compact outputs.

Comments​

{% comment %}
This is a comment and will not appear in the output
{% endcomment %}

Safety and Limitations​

Liquid is intentionally limited:

  • No direct code execution
  • No access to system or runtime environment
  • No arbitrary function calls

This makes Liquid safe for user-generated templates and controlled rendering environments.

Example: Full Template​

<h1>Hello {{ user.name | capitalize }}</h1>

{% if user.orders.size > 0 %}
  <ul>
    {% for order in user.orders %}
      <li>Order #{{ order.id }} - {{ order.total }} €</li>
    {% endfor %}
  </ul>
{% else %}
  <p>No orders found.</p>
{% endif %}

Conclusion​

Liquid is a powerful yet constrained templating language that balances flexibility and security. Its simple syntax and predictable behavior make it an excellent choice for dynamic content generation across many platforms.