Template Language Reference (Liquid)

Our template language, which is based on the Liquid open source project, uses a combination of tags, objects, and filters to merge dynamic content into templates. Templates can be used for web pages, e-mails, and pdf’s but also JSON or XML based files.

Basic usage

There are two types of markup in Liquid:

Output

Output markup (which often resolves to text) is surrounded by {{ }}, matched pairs of curly brackets (ie, braces).

Here is a simple example of Output:

Output markup use filters. Filters are simple methods. They're used to alter or affect the value that has been used as parameter in the tag. Filter are processed in the order they're included in a tag. After processing all tags, the value of the tag is parsed.

Variables

Variables are instances of values that can be saved and altered. Liquid templates can use variables in several places. Variables are mostly used in output statements but can also be used as arguments in tags or filters. Every type of variable can be accessed by using the name of the variable inside an output or tag markup.

Text: When using text this must be surrounded by quotes. It doesn’t matter if single or double quotes are used.

Numbers: Numbers used in either output or tag statements don’t need to be quoted.

Booleans and nil: With these values, the literal values true, false, and nil can be used without surrounding quotes.

Collections: A single item in a collection can be fetched by using the name of the collection, followed immediately by square brackets containing a key. This key must be a number or an expression where the outcome will become a number.

Objects: The property of an object can be fetched by using the name of the object, followed by a period and the name of the property.

Hash: The value of a hash can be fetched in multiple ways. The same ‘dot’ notation as with the objects can be used. Or the name of the hash, followed by square brackets containing the key of the property. In this case, the key must be the name of the property surrounded by quotes.

Note: The syntax of fetching values of collections, objects and hashes can be combined if the fetch would result in another collection, object or hash.

Filters

Filters can be used to modify the result of a value within the output markup. A filter can be called by using a pipe character after the value that you want to have filtered. Filters can also be chained together by using another pipe character after the first filter. The output of the previous filter will be the input of the next one.

Examples of filters

Append

Adds the set text value after the value within the output markup.

Capitalize

Capitalizes text, making the first character of the text capital. Note that this command downcases the whole text first so that only the first character will be capital.

Ceil

Rounds a number with decimal up to the nearest number.

Date

Reformats a date by using special characters. With this filter it's also possible to convert text to a date property if the correct formatting is used on the text value.

All supported date formats are listed below:

Default

Returns the value within the output markup unless it is nil or an empty value, in which case it will return the set default value.

Divided_by

Divides a number by the set number value. The outcome will be rounded up to the nearest number.

Downcase_first

Converts the first character of a text value to all lowercase characters.

Downcase

Converts a text value to all lowercase characters.

Escape_once

Converts HTML entities to their corresponding entity name without affecting characters that are already converted.

Escape_xml

Converts XML entities to their corresponding entity name. If there already is a converted entity name in the text, the & character of that entity name will get converted again.

Escape

Converts HTML entities to their corresponding entity name. If there already is a converted entity name in the text, the & character of that entity name will get converted again. When this is the case you should use the escape_once filter.

Flatten

Flattens the subcollections in a collection so that the collection will have no extra layers. The optional level argument determines the level of recursion to flatten.

Find_result_by_key_value

Returns a value from a collection, this value is fetched by a combination of parameters that the filter accepts:

The first parameter is the name of a key property in the collection, note that this property has to be unique.
The second parameter is the value of that key property for the row that you want to fetch the value of.
The third parameter is the name of the property that you want to have returned from the filter.

First

Gets the first element of the value within the output markup. If the value contains text then it will return the first character of that text, if it contains a collection then it will return the first item of that collection. When using this filter on a collection it is also possible to use the ‘dot’ notation.

Floor

Rounds a number with decimal down to the nearest number.

Group

Groups the items of a collection based on a shared property. This filter could, for instance, group a products collection on the company of the products. The objects of the new collection will contain 2 properties, these properties can be used to fetch the:

Key: The key value contains the value that the collection was grouped on. This key should never be changed since it is a reference to the property that was grouped on.
Array: The array value contains the objects of the collection which where grouped on the key value.

Image.size

An image property can hold multiple sizes for an image. Add the name of this size to the name of the image property to get the url of this sized image.

Join

Joins the items of a collection together with the set character between the elements. The result will return text.

Json

Converts a collection or object into json format.

Last

Gets the last element of the value within the output markup. If the value contains text then it will return the last character of that text. If it contains a collection, it will return the last item of that collection. When using this filter on a collection it is also possible to use the ‘dot’ notation.

Localize

Converts a date to the current app locale.

Lstrip

Removes all whitespaces from the beginning of a text property.

Map

Generates a collection based on the values of the given parameter. The parameter is based on the property of the collection used within the output markup.

Minus

Subtracts the set number value from a number.

Modulo

Divides the set number value by a number and returns the remainder.

Newline_to_br

Inserts a <br /> HTML tag in front of each line break of a text property.

Plus_days

Adds the set number value as days to a date.

Plus

Adds the set number value to a number.

Prepend

Adds the set text before the value within the output markup.

Randomize

Returns a randomized order of the given collection.

Raw / No_escape

Converts HTML tags within a text property. HTML tags that are in a text property will not be seen as HTML tags for the page. When using this filter, the HTML tags will be properly read.

Remove_first

Removes the first occurrence of the set text from the value within the output markup.

Remove

Removes each occurence of the set text from the value within the output markup.

Replace_first

Replaces the first occurrence of the first set text with the second set text from the value within the output markup.

Replace

Replaces each occurrence of the first set text with the second set text from the value within the output markup.

Reverse

Reverses the value within the output markup. This only works when this value is a collection property.

Round

Rounds the value within the output markup to the nearest number or number with decimal, depending on the set number.

Rstrip

Removes all whitespaces from the end of a text property.

Size

Returns the amount of items in a collection or the amount of characters in a string.

Slice

Slices the value within the output markup with the first set number value as offset and the second set number value as length.

Sort

Sorts the elements of a collection based on a property of the item. The order of the sorted collection is case-sensitive.

Split

Split a text property on a matching pattern, this matching pattern has to be set as a parameter. The set text value will be used to divide the text property into a collection.

Squeeze

Removes patterns out of a text property based on the set text value. If the set text value occurs multiple times next to each other in the text property then these will be removed out of the text property so that only one occurrence is left.

Strip_html

Removes all HTML tags from a text property.

Strip_newlines

Removes all line breaks/newlines from a text property.

Strip

Removes all whitespaces from both ends of a text property. It does not affect whitespaces between words.

Sum

Adds every value of the set property of a collection together. If the set property contains a number then it will return the total value of those numbers, if it contains text then it will add every value after the other.

Textilize

Converts certain combinations of characters of a text property into HTML code. For a complete list of all character combinations, you can take a look at this website: Textile language.

Time_in_timezone

Changes the value of a Date time property to match the time in another timezone. The time zone can be set by using the timezone’s abbreviation. This only works for Date time properties that are created in the Back Office, not for Date time properties created in liquid.

Times

Multiplies the set number value by a number.

To_currency

Converts a number or a number with decimal to a currency value. This filter accepts 4 parameters:

The first parameter for the currency unit.
The second parameter for the number of decimals.
The third parameter for a thousands delimiter.
The last parameter for the separator between units.

Transliterate

Converts all non-ASCII characters of a text property to an ASCII approximation, or if none exists, a question mark character will be used as default.

Truncate_html

Cuts a text property down to a set amount of characters, excluding HTML tags. The amount of characters is the set number value. An ellipsis (...) is added to the text value.

Truncate

Cuts a text property down to a set amount of characters. The amount of characters is the set number value. An ellipsis (...) is added to the text property. A second parameter is accepted that will change the ellipsis in the set text value. The chosen text value is also counted in the set amount of characters.

Truncatewords

Cuts a text property down to a set amount of words. The amount of words is the set number value. An ellipsis (...) is added to the text property. A second parameter is accepted that will change the ellipsis in the set text value.

Uniq

Removes all double values of a collection property.

Upcase

Upcases every character of a text property.

Url_encode

Converts any URL-unsafe characters in a text property into encoded characters so it can be used in a URL.

Url

Returns the URL that belongs to an image.

Assign

Assigns a value to a variable. An output filter can be combined with this tag to alter the value of the variable.

Capture

Captures everything that is in between the tags and assigns the captured value to the given variable. Everything inside of the tags will not be rendered onto the page.

Case/when

Checks a property or variable on set conditions and executes the first condition that’s true. The case tag is the body of this statement, containing multiple when tags that are used for the conditions. The else tag can be used as a default when no condition matches with the property.

Comment

Any content that is placed in between the tags is turned into a comment, thus making it not visible on the page.

Cycle

Cycles through the values set inside the tag each time the tag is called. This tag is usually used within a loop to alternate the values. To have more control over the cycles, a name can be given to the group. This way the cycles can’t be mixed up with each other.

For

Loops through a block of code. A for loop can iterate over collections, hashes, and ranges of integers. A loop object is specified to access the objects of the collection that is being looped through. The name for this loop object can be anything but is usually named after the object of the collection.

Instead of looping over a collection, a range of numbers can also be used to create a loop. Ranges are parentheses containing a start value, two periods, and an end value. The start and end values must be numbers or expressions that resolve to numbers.

To exit a loop early the following tags can be used inside of the loop:

Continue: Immediately ends the current iteration but continues the for loop with the next value.
Break: Immediately ends the current iterations and completely ends the for loop.

Both are best used when combined with an if/else statement.

During every for loop special for loop variables can be used to get specific data about the loop or iteration, these variables are called helper variables.

To influence which items you receive in your loop and what order they appear in these optional arguments can be added to the for tag:

Limit: Limits the amount of items the for tag loops through.
Offset: Skips over the set number of items.
Reversed: Iterates over the collection from last to first.

A for loop can take an optional else tag to execute when there are no items in the collection.

If/Else

With an if/else statement a block of code is executed when a specified condition is true. If the condition is false, another block of code is executed. The specified condition is set inside of the if tag.

A condition is made out of properties and operators, the operators indicate how the properties will be compared to each other. The following operators can be used within the if/else conditions:

It is possible to have multiple conditions within one if tag by using and or or. When using and both of the conditions have to be true for the code block to be executed. When using or either one of the conditions has to be true for the code block to be executed. Another way of having multiple conditions is by using the elsif tag, another condition can be specified within this tag to execute a code block when the condition is true. Any number of elsif tags can be used inside an if tag.

A condition can also be valid without using an operator. When leaving out the operator and just using a property, the property will be tested for its truthiness. This means that it will return true when the property exists. This works on collections, objects and numbers. Text on the other hand will always return true even when it is empty text.

Include

Includes another template from the back-end. This is useful for partials or for scripts and stylesheets. The partial name must always be surrounded by quotes.

Raw

Temporarily disables tag processing, HTML tags will still be processed but all liquid tags will not. This comes in handy when generating content that uses conflicting syntax.

Unless

The unless tag mirrors the if/else tag, a code block will be executed when a specified condition is false. The condition is set inside of the unless tag. This tag cannot be combined with the elsif and else tags of the if/else tag.