# Liquid Templating
[Liquid](https://shopify.github.io/liquid/) is a popular templating language originally created by [Shopify](https://www.shopify.com) 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 `}}`.
{% code title="INPUT" %}
```liquid
{{shopify.customer.email}}
```
{% endcode %}
{% code title="OUTPUT" %}
```
jannette.parks@getmesa.com
```
{% endcode %}
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.
{% code title="INPUT" %}
```liquid
{% if shopify.customer.email %}
The customer's email is {{shopify.customer.email}}
{% endif %}
```
{% endcode %}
{% code title="OUTPUT" %}
```
The customer's email is jannette.parks@getmesa.com
```
{% endcode %}
### 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`.
{% code title="INPUT" %}
```liquid
{% if shopify.customer.email == "jannette.parks@getmesa.com" %}
Hey, I know her!
{% endif %}
```
{% endcode %}
{% code title="OUTPUT" %}
```
Hey, I know her!
```
{% endcode %}
### Unless
The opposite of `if` – executes a block of code only if a certain condition is **not** met.
{% code title="INPUT" %}
```liquid
{% unless shopify.customer.email contains "@getmesa.com" %}
I don't know them :(
{% endunless %}
```
{% endcode %}
{% code title="OUTPUT" %}
```
I don't know them :(
```
{% endcode %}
### 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:
```liquid
{%- 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.
{% code title="INPUT" %}
```liquid
{% assign ecomm_automation = "awesome" %}
Ecommerce automation is {{ ecomm_automation }}!
```
{% endcode %}
{% code title="OUTPUT" %}
```liquid
Ecommerce automation is awesome!
```
{% endcode %}
### For
Repeatedly executes a block of code.
{% code title="INPUT" %}
```liquid
{% for tag in product.tags %}
{{ tag }}
{% endfor %}
```
{% endcode %}
{% code title="OUTPUT" %}
```liquid
apparel womens summer shirt sale
```
{% endcode %}
### Else
Specifies a fallback case for a `for` loop which will run if the loop has zero length.
{% code title="INPUT" %}
```liquid
{% for tag in product.tags %}
{{ tag }}
{% else %}
The product has no tags
{% endfor %}
```
{% endcode %}
{% code title="OUTPUT" %}
```liquid
The product has no tags
```
{% endcode %}
### 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.
{% code title="INPUT" %}
```liquid
{{ "Ecommerce automation is " | append: "awesome!" }}
```
{% endcode %}
{% code title="OUTPUT" %}
```
Ecommerce automation is awesome!
```
{% endcode %}
### 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.
{% code title="INPUT" %}
```liquid
{{ order.created_at | date: "%A, %B %-d" }}
```
{% endcode %}
{% code title="OUTPUT" %}
```liquid
Wednesday, July 3
```
{% endcode %}
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.
{% code title="INPUT" %}
```liquid
{{ "now" | date: "%Y-%m-%d %H:%M" }}
```
{% endcode %}
{% code title="OUTPUT" %}
```liquid
2024-07-03 16:18
```
{% endcode %}
Modifiers can be added to `now` to get a specific time in the past or future:
Yesterday
{% code title="INPUT" %}
```liquid
{{ "now -1 day" | date: "%Y-%m-%d" }}
```
{% endcode %}
Two months from now
{% code title="INPUT" %}
```liquid
{{ "now +2 months" | date: "%Y-%m-%d" }}
```
{% endcode %}
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 (`
`) 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.getmesa.com/workflow-builder/fields/liquid-templating.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.