Liquid Templating

Liquid is a popular templating language originally created by Shopify and used throughout the web. MESA uses a specialized version of Liquid that makes it easy to use and modify text or variables within your workflows.

Liquid displays dynamic content by combining objects, tags, and filters.

Objects

In MESA, an object is created to contain the output for each step when the workflow is run. Each step has a unique key that can be referenced in later steps as a Liquid object. Objects and variables are displayed when enclosed in double curly braces: {{ and }}.

INPUT

{{shopify.customer.email}}

OUTPUT

jannette.parks@getmesa.com

In this case, Liquid is rendering the content of the customer.email property that contains the text jannette.parks@getmesa.com. MESA created the shopify object when a Shopify Order Created trigger with a unique key of shopify has been run.

Tags

Tags create the logic and control flow for templates. The curly brace percentage delimiters {% and %} and the text that they surround do not produce any visible output when the template is rendered.

INPUT

{% if shopify.customer.email %}
    The customer's email is {{shopify.customer.email}}
{% endif %}

OUTPUT

The customer's email is jannette.parks@getmesa.com

Basic operators

Liquid includes many logical and comparison operators. You can use operators to create logic with control flow tags.

==	equals
!=	does not equal
>	greater than
<	less than
>=	greater than or equal to
<=	less than or equal to
or	logical or
and	logical and

Contains

contains checks for the presence of a substring inside a string. contains can also check for the presence of a string in an array of strings. contains can only search strings. You cannot use it to check for an object in an array of objects.

If

Executes a block of code only if a certain condition is true.

INPUT

{% if shopify.customer.email == "jannette.parks@getmesa.com" %}
    Hey, I know her!
{% endif %}

OUTPUT

Hey, I know her!

Unless

The opposite of if – executes a block of code only if a certain condition is not met.

INPUT

{% unless shopify.customer.email contains "@getmesa.com" %}
    I don't know them :(
{% endunless %}

OUTPUT

I don't know them :(

Elsif / else

Adds more conditions within an if or unless block.

Case/when

Creates a switch statement to execute a particular block of code when a variable has a specified value. case initializes the switch statement, and when statements define the various conditions.

A when tag can accept multiple values. When multiple values are provided, the expression is returned when the variable matches any of the values inside of the tag. Provide the values as a comma-separated list, or separate them using an or operator.

An optional else statement at the end of the case provides code to execute if none of the conditions are met.

Whitespace Control

By including hyphens in your Liquid tag, you can strip any unneeded whitespace (extra spaces) that may appear. Here is how to make this adjustment:

{%- if shopify.customer.email -%}

    {{ shopify.customer.email }}

{%- endif -%}

Comment

Allows you to leave un-rendered code inside a Liquid template. Any text within the opening and closing comment blocks will not be printed, and any Liquid code within will not be executed.

Raw

Temporarily disables tag processing.

Assign

Creates a new named variable.

INPUT

{% assign ecomm_automation = "awesome" %}
Ecommerce automation is {{ ecomm_automation }}!

OUTPUT

Ecommerce automation is awesome!

For

Repeatedly executes a block of code.

INPUT

{% for tag in product.tags %}
  {{ tag }}
{% endfor %}

OUTPUT

apparel womens summer shirt sale

Else

Specifies a fallback case for a for loop which will run if the loop has zero length.

INPUT

{% for tag in product.tags %}
  {{ tag }}
{% else %}
  The product has no tags
{% endfor %}

OUTPUT

The product has no tags

Break

Causes the loop to stop iterating when it encounters the break tag.

Continue

Causes the loop to skip the current iteration when it encounters the continue tag.

Filters

Filters change the output of a Liquid object or variable. They are used within double curly braces {{ }} and are separated by a pipe character |. Multiple filters can be used on one output, and are applied from left to right.

INPUT

{{ "Ecommerce automation is " | append: "awesome!" }}

OUTPUT

Ecommerce automation is awesome!

abs

Returns the absolute value of a number. abs will also work on a string that only contains a number.

append

Adds the specified string to the end of another string. append can also accept a variable as its argument.

capitalize

Makes the first character of a string capitalized and converts the remaining characters to lowercase. Only the first character of a string is capitalized, so later words are not capitalized:

ceil

Rounds an input up to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.

date

Converts a timestamp into another date format.

INPUT

{{ order.created_at | date: "%A, %B %-d" }}

OUTPUT

Wednesday, July 3

To get the current time, pass the special word "now" to date. The store’s default timezone, which is set in Shopify, will be used.

INPUT

{{ "now" | date: "%Y-%m-%d %H:%M" }}

OUTPUT

2024-07-03 16:18

Modifiers can be added to now to get a specific time in the past or future:

Yesterday

INPUT

{{ "now -1 day" | date: "%Y-%m-%d" }}

Two months from now

INPUT

{{ "now +2 months" | date: "%Y-%m-%d" }}

Valid units of time: year, month, day, hour, minute, second.

Date formatting

Format character	Example	Description
%a	Sun	Weekday as locale’s abbreviated name.
%A	Sunday	Weekday as locale’s full name.
%w	0	Weekday as a decimal number, where 0 is Sunday and 6 is Saturday.
%d	08	Day of the month as a zero-padded decimal number.
%-d	8	Day of the month as a decimal number. (Platform specific)
%b	Sep	Month as locale’s abbreviated name.
%B	September	Month as locale’s full name.
%m	09	Month as a zero-padded decimal number.
%-m	9	Month as a decimal number. (Platform specific)
%y	13	Year without century as a zero-padded decimal number.
%Y	2013	Year with century as a decimal number.
%H	07	Hour (24-hour clock) as a zero-padded decimal number.
%-H	7	Hour (24-hour clock) as a decimal number. (Platform specific)
%I	07	Hour (12-hour clock) as a zero-padded decimal number.
%-I	7	Hour (12-hour clock) as a decimal number. (Platform specific)
%p	AM	Locale’s equivalent of either AM or PM.
%M	06	Minute as a zero-padded decimal number.
%-M	6	Minute as a decimal number. (Platform specific)
%S	05	Second as a zero-padded decimal number.
%-S	5	Second as a decimal number. (Platform specific)
%f	000000	Microsecond as a decimal number, zero-padded to 6 digits.
%z	+0000	UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive).
%Z	UTC	Time zone name (empty string if the object is naive).
%j	251	Day of the year as a zero-padded decimal number.
%-j	251	Day of the year as a decimal number. (Platform specific)
%U	36	Week number of the year (Sunday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0.
%-U	36	Week number of the year (Sunday as the first day of the week) as a decimal number. All days in a new year preceding the first Sunday are considered to be in week 0. (Platform specific)
%W	35	Week number of the year (Monday as the first day of the week) as a zero-padded decimal number. All days in a new year preceding the first Monday are considered to be in week 0.
%-W	35	Week number of the year (Monday as the first day of the week) as a decimal number. All days in a new year preceding the first Monday are considered to be in week 0. (Platform specific)
%c	Sun Sep 8 07:06:05 2013	Locale’s appropriate date and time representation.
%x	09/08/13	Locale’s appropriate date representation.
%X	07:06:05	Locale’s appropriate time representation.
%%	%	A literal ‘%’ character.

default

Sets a default value for any variable with no assigned value. default will show its value if the input is nil, false, or empty.

divided_by

Divides a number by another number.

downcase

Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.

escape

Escapes a string by replacing characters with escape sequences (so that the string can be used in a URL, for example). It doesn’t change strings that don’t have anything to escape.

escape_once

Escapes a string without changing existing escaped entities. It doesn’t change strings that don’t have anything to escape.

first

Returns the first item of an array.

floor

Rounds an input down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.

join

Combines the items in an array into a single string using the argument as a separator.

last

Returns the last item of an array.

lstrip

Removes all whitespace (tabs, spaces, and newlines) from the left side of a string. It does not affect spaces between words.

map

Creates an array of values by extracting the values of a named property from another object.

minus

Subtracts a number from another number.

modulo

Returns the remainder of a division operation.

newline_to_br

Inserts an HTML line break (<br />) in front of each newline () in a string.

plus

Adds a number to another number.

prepend

Adds the specified string to the beginning of another string.

remove

Removes every occurrence of the specified substring from a string.

remove_first

Removes only the first occurrence of the specified substring from a string.

replace

Replaces every occurrence of the first argument in a string with the second argument.

replace_first

Replaces only the first occurrence of the first argument in a string with the second argument.

reverse

Reverses the order of the items in an array. reverse cannot reverse a string.

round

Rounds a number to the nearest integer or, if a number is passed as an argument, to that number of decimal places.

rstrip

Removes all whitespace (tabs, spaces, and newlines) from the right side of a string. It does not affect spaces between words.

size

Returns the number of characters in a string or the number of items in an array.

slice

Returns a substring of one character or series of array items beginning at the index specified by the first argument. An optional second argument specifies the length of the substring or number of array items to be returned. String or array indices are numbered starting from 0. If the first argument is a negative number, the indices are counted from the end of the string.

sort

Sorts items in an array in case-sensitive order.

split

Divides a string into an array using the argument as a separator. split is commonly used to convert comma-separated items from a string to an array.

strip

Removes all whitespace (tabs, spaces, and newlines) from both the left and right sides of a string. It does not affect spaces between words.

strip_html

Removes any HTML tags from a string.

strip_newlines

Removes any newline characters (line breaks) from a string.

times

Multiplies a number by another number.

truncate

Shortens a string down to the number of characters passed as an argument. If the specified number of characters is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.

truncate takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default this is an ellipsis (…), but you can specify a different sequence.

truncatewords

Shortens a string down to the number of words passed as an argument. If the specified number of words is less than the number of words in the string, an ellipsis (…) is appended to the string.

truncatewords takes an optional second argument that specifies the sequence of characters to be appended to the truncated string. By default this is an ellipsis (…), but you can specify a different sequence.

uniq

Removes any duplicate items in an array.

upcase

Makes each character in a string uppercase. It has no effect on strings which are already all uppercase.

url_decode

Decodes a string that has been encoded as a URL.

url_encode

Converts any URL-unsafe characters in a string into percent-encoded characters. Note that url_encode will turn a space into a + sign instead of a percent-encoded character.

where

Creates an array including only the objects with a given property value, or any truthy value by default.