...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Operators
TODO: gli operatori funzionano sui valori degli endpoint, da verificare sui campi dinamici (dynamicfields.)
...
It is possible use this operator with dynamic fields 'as is' only to compare strings.
Code Block | ||
---|---|---|
| ||
{% if dynamicfields.name == 'goofy' %}
goofy
{% elsif dynamicfields.name == 'mickey' %}
mickey
{% else %}
donald
{% endif %} |
In this case the check is case sensitive.
To compare numbers or data type different from string it is possible use the built in functions:
Code Block | ||
---|---|---|
| ||
{% assign c1 = dynamicfields.name| evaltext: 'equalTo', 'Jennifer' %} {% if c1 == true %} Text {% endif %} |
Code Block | ||
---|---|---|
| ||
{% assign c1 = dynamicfields.age | evalinteger: 'equalTo', '8' %} {% if c1 == true %} |
...
Introduction
The liquid is an open-source template language created by Shopify and written in Ruby. It is the backbone of Shopify themes and is used to load dynamic content on storefronts.
In MailUp Liquid is used as a markup language for the email messages that use Advanced content personalization.
The following guide describes how to use Liquid within MailUp and which statements are supported.
When talking about dynamics fields, we refer to the MailUp Recipient fields.
To retrieve a specific dynamic field value, you have to use the following syntax: dynamicfields.<dynamic field name>.
Note |
---|
In the liquid syntax, not all characters are supported in a variable name. To be sure to have a correct syntax when using MailUp dynamic field, we recommend using only:
|
Basics
Operators
Operator | Meaning | Work | Syntax | |||||
---|---|---|---|---|---|---|---|---|
== | equals | This operator can be used with dynamic fields 'as is' only to compare strings.
|
|
|
|
|
|
|
In this case, the check is case-sensitive. To compare numbers or data |
types different from a string it is possible to use the built-in functions:
|
|
|
| ||||||||
!= | does not equal | It is possible to use this operator with dynamic fields 'as is' only to compare strings.
|
|
|
|
|
|
|
In this case, the check is case-sensitive. To compare numbers or data |
types different from a string it is possible to use the built-in functions:
|
|
|
|
the operator to check if the dynamic field is empty or contains a value.
|
|
|
|
|
|
In this case the check is case sensitive.
To compare numbers or data type different from string it is possible use the builtIt is possible do the same using the built-in functions:
|
|
|
|
> |
language | xml |
---|
{% assign c1 = dynamicfields.age | evalinteger: 'lessThan', '8' %} {% if c1 == true %}
greater than | It is possible to use this operator with dynamic fields 'as is' only to compare strings.
|
|
|
|
|
|
|
In this case, the check is case-sensitive. To compare numbers or data |
types different from a string it is possible to use the built-in functions:
|
|
|
| |
< | less than |
It is possible to use this operator with dynamic fields 'as is' only to compare strings.
|
|
|
|
|
|
|
In this case |
To compare numbers or data type different from string it is possible use the built in functions:
Code Block | ||
---|---|---|
| ||
{% assign c1 = dynamicfields.name| evaltext: 'equalOrLessThan', 'Jennifer' %} {% if c1 == true %} Text {% endif %} |
Code Block | ||
---|---|---|
| ||
{% assign c1 = dynamicfields.age | evalinteger: 'equalOrLessThan', '8' %} {% if c1 == true %} |
Example
Code Block |
---|
{% if product.title == "Awesome Shoes" %}
These shoes are awesome!
{% endif %} |
Code Block |
---|
{% if product.type == "Shirt" or product.type == "Shoes" %}
This is a shirt or a pair of shoes.
{% endif %} |
Truthy and falsy
TBD
Types
TBD
TAGS
Comment
Operator | Meaning | Work | Syntax |
---|---|---|---|
comment | Any text within the opening and closing comment blocks will not be output, and any Liquid code within will not be executed | Yes | {% comment %} Text {% endcomment %} |
Control flow
TBD
Operator | Meaning | Work | Syntax |
---|---|---|---|
if | Executes a block of code only if a certain condition is | Yes | {% assign c1 = dynamicfields.name| evaltext: 'equalTo', 'Jennifer' %} {% if c1 == true %} Text {% endif %} |
unless | Executes a block of code only if a certain condition is not me | Yes | {% assign c1 = dynamicfields.name| evaltext: 'equalTo', 'Jennifer' %} {% unless c1 == true %} Text {% endunless %} |
elsif/else | Adds more conditions within an if or unless block. | ||
case/when | Creates a switch statement to compare a variable with different values |
Iteration
TBD
Variable
TBD
Filters
TBD
Returns the absolute value of a number.
Concatenates two strings and returns the concatenated value.
Code Block | ||
---|---|---|
| ||
{{ "Hello " | append: "Carl" }}
|
Code Block | ||
---|---|---|
| ||
Hello Carl |
Code Block | ||
---|---|---|
| ||
{{ "Welcome" | append: dynamicfields.name }} |
Code Block | ||
---|---|---|
| ||
Welcome Luke |
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.name | append: " welcome!"}} |
Code Block | ||
---|---|---|
| ||
Luke welcome! |
Limits a number to a minimum value.
Limits a number to a maximum value.
Makes the first character of a string capitalized.
Code Block | ||
---|---|---|
| ||
{{ "my great title" | capitalize }} |
Code Block | ||
---|---|---|
| ||
My great title |
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.nome | capitalize }} |
Code Block | ||
---|---|---|
| ||
Luke |
Rounds the input up to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.
Removes any nil
values from an array.
Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays.
strftime
. The input uses the same format as Ruby’s Time.parse
.default
will show its value if the left side is nil
, false
, or empty.Divides a number by the specified number.
Does not work on dynamicfields.
Code Block | ||
---|---|---|
| ||
{{ 16 | divided_by: 4 }}
|
Code Block | ||
---|---|---|
| ||
4 |
Code Block | ||
---|---|---|
| ||
{{ subTotal| divided_by: 4 }} |
Code Block | ||
---|---|---|
| ||
100 |
Makes each character in a string lowercase. It has no effect on strings which are already all lowercase.
Code Block | ||
---|---|---|
| ||
{{ "Parker Moore" | downcase }} |
Code Block | ||
---|---|---|
| ||
parker moore |
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.nome | downcase}} |
Code Block | ||
---|---|---|
| ||
luke |
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.
Escapes a string without changing existing escaped entities. It doesn’t change strings that don’t have anything to escape.
Returns the first item of an array.
Code Block | ||
---|---|---|
| ||
{% assign my_array = dynamicfields.userid | split: "," %}
{{ my_array.first }} |
Code Block | ||
---|---|---|
| ||
1 |
Code Block | ||
---|---|---|
| ||
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array.first }} |
Code Block | ||
---|---|---|
| ||
apples |
Rounds a number down to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied.
Combines the items in an array into a single string using the argument as a separator.
Code Block | ||
---|---|---|
| ||
{% assign my_array = dynamicfields.userid | split: "," %}
{{ my_array | join: " and " }}
|
Code Block | ||
---|---|---|
| ||
1 and 2 and 3 and 4 and 5 |
Code Block | ||
---|---|---|
| ||
{% assign beatles = "John, Paul, George, Ringo" | split: ", " %}
{{ beatles | join: " and " }} |
Code Block | ||
---|---|---|
| ||
John and Paul and George and Ringo |
Returns the last item of an array.
Code Block | ||
---|---|---|
| ||
{% assign my_array = dynamicfields.userid | split: "," %}
{{ my_array.last}} |
Code Block | ||
---|---|---|
| ||
5 |
Code Block | ||
---|---|---|
| ||
{% assign my_array = "apples, oranges, peaches, plums" | split: ", " %}
{{ my_array.last }} |
Code Block | ||
---|---|---|
| ||
plums |
Removes all whitespaces (tabs, spaces, and newlines) from the beginning of a string. The filter does not affect spaces between words.
Creates an array of values by extracting the values of a named property from another object.
Subtracts a number from another number.
Does not work on dynamicfields.
Code Block | ||
---|---|---|
| ||
{{ 4 | minus: 2 }} |
Code Block | ||
---|---|---|
| ||
2 |
Code Block | ||
---|---|---|
| ||
{{ SubTotal | minus: 100 }} |
Code Block | ||
---|---|---|
| ||
900 |
Returns the remainder of a division operation.
Does not work on dynamicfields.
Code Block | ||
---|---|---|
| ||
{{ 3 | modulo: 2 }} |
Code Block | ||
---|---|---|
| ||
1 |
Code Block | ||
---|---|---|
| ||
{{ SubTotal | modulo: 6}} |
Code Block | ||
---|---|---|
| ||
4 |
Replaces every newline (\n
) with an HTML line break (<br>
).
Adds a number to another number.
Assuming the TotalIncome dynamic field contains 500.
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.TotalIncome| plus: 2 }} |
Code Block | ||
---|---|---|
| ||
502 |
Code Block | ||
---|---|---|
| ||
{{ 5| plus: 2 }} |
Code Block |
---|
7 |
Adds the specified string to the beginning of another string.
Code Block | ||
---|---|---|
| ||
{{ "apples, oranges, and bananas" | prepend: "Some fruit: " }} |
Code Block | ||
---|---|---|
| ||
Some fruit: apples, oranges, and bananas |
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.Name| prepend: "Hello " }} |
Code Block | ||
---|---|---|
| ||
Hello Luke |
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.Name| prepend: dynamicfields.Surname}} |
Code Block | ||
---|---|---|
| ||
Luke Skywalker |
Code Block | ||
---|---|---|
| ||
{{ "Welcome" | prepend: dynamicfields.Name }} |
Code Block | ||
---|---|---|
| ||
Welcome Luke |
Removes every occurrence of the specified substring from a string.
Code Block | ||
---|---|---|
| ||
{{ "I strained to see the train through the rain" | remove: "rain" }} |
Code Block | ||
---|---|---|
| ||
I sted to see the t through the |
Code Block | ||
---|---|---|
| ||
{{ dynamicfields.Name| remove: "uk"}} |
Code Block | ||
---|---|---|
| ||
Le |
Code Block | ||
---|---|---|
| ||
{{"Luke Skywalker" | remove: dynamicfields.Name}} |
Code Block | ||
---|---|---|
| ||
Skywalker |
Removes only the first occurrence of the specified substring from a string.
title | Input |
---|
, the check is case-sensitive. To compare numbers or data types different from a string it is possible to use the built-in functions:
| ||||||||||||||||||
>= | greater than or equal to | It is possible to use this operator with dynamic fields 'as is' only to compare strings.
In this case, the check is case-sensitive. To compare numbers or data types different from a string it is possible to use the built-in functions:
| ||||||||||||||||
<= | less than or equal to | It is possible to use this operator with dynamic fields 'as is' only to compare strings.
In this case, the check is case-sensitive. To compare numbers or data types different from a string it is possible to use the built-in functions:
| ||||||||||||||||
or | logical or |
| ||||||||||||||||
and | logical and |
| ||||||||||||||||
contains | checks for the presence of a substring inside a string |
|
Types
Type | Meaning | Work | Syntax | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
String | Declare a string by wrapping a variable’s value in single quotes: |
| |||||||||||||||||||||||||||||||||||||||||||
Number | Numbers include floats and integers: |
| |||||||||||||||||||||||||||||||||||||||||||
Boolean |
| ||||||||||||||||||||||||||||||||||||||||||||
Nil | Nil is a special empty value that is returned when the Liquid code has no results. It is not a string with the characters “nil”. Nil is treated as false in the conditions of |
| |||||||||||||||||||||||||||||||||||||||||||
Array | Arrays hold lists of variables of any type. |
|
TAGS
Comment
Operator | Meaning | Work | Syntax | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
comment | Any text within the opening and closing comment blocks will not be output, and any Liquid code within will not be executed |
|
Control flow
Operator | Meaning | Work | Syntax | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
if | Executes a block of code only if a certain condition is |
| |||||||||||||||||||||||||||||
unless | Executes a block of code only if a certain condition is not match |
| |||||||||||||||||||||||||||||
elsif/else | Adds more conditions within an if or unless block. |
| |||||||||||||||||||||||||||||
case/when | Creates a switch statement to compare a variable with different values |
|
Iteration
For
Operator | Meaning | Work | Syntax | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
for | Repeatedly executes a block of code. |
| |||||||||||||||||||||||||||||
break | Causes the loop to stop iterating when it encounters the |
| |||||||||||||||||||||||||||||
continue | Causes the loop to skip the current iteration when it encounters the |
| |||||||||||||||||||||||||||||
limit | Limits the loop to the specified number of iterations. |
| |||||||||||||||||||||||||||||
offset | Begins the loop at the specified index. |
| |||||||||||||||||||||||||||||
range | Defines a range of numbers to loop through. The range can be defined by both literal and variable numbers. |
| |||||||||||||||||||||||||||||
reversed | Reverses the order of the loop. |
|
Cycle
Operator | Meaning | Work | Syntax | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Cycle | Repeatedly executes a block of code. |
|
Variable
Operator | Meaning | Work | Syntax | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
assign | Creates a new variable |
| |||||||||||||||||||||||||||||
capture | Captures the string inside of the opening and closing tags and assigns it to a variable. Variables created through {% capture %} are strings. |
| |||||||||||||||||||||||||||||
increment | Creates a new number variable, and increases its value by one every time it is called. The initial value is 0. | ||||||||||||||||||||||||||||||
decrement | Creates a new number variable, and decreases its value by one every time it is called. The initial value is -1. |
Filters
...
Operator | Meaning | Work | Syntax | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
abs | Returns the absolute value of a number. | ||||||||||||||||||||||||||||||||||||||||||
append | Concatenates two strings and returns the concatenated value. |
| |||||||||||||||||||||||||||||||||||||||||
at_least | Limits a number to a minimum value. | ||||||||||||||||||||||||||||||||||||||||||
at_most | Limits a number to a maximum value. | ||||||||||||||||||||||||||||||||||||||||||
capitalize | Makes the first character of a string capitalized. |
| |||||||||||||||||||||||||||||||||||||||||
ceil | Rounds the input up to the nearest whole number. Liquid tries to convert the input to a number before the filter is applied. | ||||||||||||||||||||||||||||||||||||||||||
compact | Removes any | ||||||||||||||||||||||||||||||||||||||||||
concat | Concatenates (joins together) multiple arrays. The resulting array contains all the items from the input arrays. | ||||||||||||||||||||||||||||||||||||||||||
date | Converts a timestamp into another date format. The format for this syntax is the same as strftime . The input uses the same format as Ruby’s Time.parse . | ||||||||||||||||||||||||||||||||||||||||||
default | Allows you to specify a fallback in case a value doesn’t exist. default will show its value if the left side is nil , false , or empty. | ||||||||||||||||||||||||||||||||||||||||||
divided_by | Divides a number by the specified number. | Does not work on dynamicfields.
| |||||||||||||||||||||||||||||||||||||||||
downcase | Makes each character in a string lowercase. It does not affect strings that 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. | Assuming the userid dynamicfield contains "1,2,3,4,5".
| |||||||||||||||||||||||||||||||||||||||||
floor | Rounds a number 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. | Assuming the userid dynamicfield contains "1,2,3,4,5".
| |||||||||||||||||||||||||||||||||||||||||
last | Returns the last item of an array. | Assuming the userid dynamicfield contains "1,2,3,4,5".
| |||||||||||||||||||||||||||||||||||||||||
lstrip | Removes all whitespaces (tabs, spaces, and newlines) from the beginning of a string. The filter does not affect spaces between words. | ||||||||||||||||||||||||||||||||||||||||||
map | Creates an array of values by extracting the values of a named property from another object. | Assuming the products contains:
| |||||||||||||||||||||||||||||||||||||||||
minus | Subtracts a number from another number. | Does not work on dynamicfields.
| |||||||||||||||||||||||||||||||||||||||||
modulo | Returns the remainder of a division operation. | Does not work on dynamicfields.
| |||||||||||||||||||||||||||||||||||||||||
newline_to_br | Replaces every newline ( | ||||||||||||||||||||||||||||||||||||||||||
plus | Adds a number to another number. | Assuming the TotalIncome dynamic field contains 500.
| |||||||||||||||||||||||||||||||||||||||||
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 an argument in a string with the second argument. |
| |||||||||||||||||||||||||||||||||||||||||
replace_first | Replaces only the first occurrence of the first argument is a string with the second argument. |
| |||||||||||||||||||||||||||||||||||||||||
reverse | Reverses the order of the items in an array. | ||||||||||||||||||||||||||||||||||||||||||
round | Rounds an input number to the nearest integer or, if a number is specified as an argument, to that number of decimal places. | Does not work on dynamicfields.
| |||||||||||||||||||||||||||||||||||||||||
rstrip | Removes all whitespace (tabs, spaces, and newlines) from the right side of a string. | ||||||||||||||||||||||||||||||||||||||||||
size | Returns the number of characters in a string or the number of items in an array. |
| |||||||||||||||||||||||||||||||||||||||||
slice | Returns a substring of 1 character beginning at the index specified by the argument passed in. An optional second argument specifies the length of the substring to be returned. String indices are numbered starting from 0. |
Assuming title contains "Return to the future"
| |||||||||||||||||||||||||||||||||||||||||
sort | Sorts items in an array by a property of an item in the array. The order of the sorted array is case-sensitive. | Same behavior of the sort_natural filter.
|
|
|
|
| ||||||||
sort_natural | Sorts items in an array by a property of an item in the array. | |||||||
split | Divides an input 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. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TODO: aggiungere esempi con campi dinamici!
Replaces only the first occurrence of the first argument in a string with the second argument.
Reverses the order of the items in an array. reverse
cannot reverse a string.
Rounds an input number to the nearest integer or, if a number is specified as an argument, to that number of decimal places.
Assuming the dynamic field albumid contains "1,2,3,4,5"
| |||||||||||
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. |
Returns the number of characters in a string or the number of items in an array. size
can also be used with dot notation (for example, {{ my_string.size }}
). This allows you to use size
inside tags such as conditionals.
Returns a substring of 1 character beginning at the index specified by the argument passed in. An optional second argument specifies the length of the substring to be returned.
String indices are numbered starting from 0.
Sorts items in an array by a property of an item in the array. The order of the sorted array is case-sensitive.
split
is commonly used to convert comma-separated items from a string to an array.Removes all whitespace (tabs, spaces, and newlines) from both the left and right side of a string. It does not affect spaces between words.
Removes any HTML tags from a string.
Removes any newline characters (line breaks) from a string.
Multiplies a number by another number.
truncate
shortens a string down to the number of characters passed as a parameter. If the number of characters specified is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count.
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. | Does not work on dynamicfields.
| |||||||||||||||||||||
truncate |
|
| |||||||||||||||||||||
truncatewords | Shortens a string down to the number of words passed as the argument. If the specified number of words is less than the number of words in the string, an ellipsis (…) is appended to the string. |
uniq | Removes any duplicate elements in an array. |
upcase | Makes each character in a string uppercase. It |
does not affect strings that are already all uppercase. |
|
| ||
url_decode | Decodes a string that has been encoded as a URL or by |
url_encode | Converts any URL-unsafe characters in a string into percent-encoded characters. |