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, pdf's but also JSON or XML based files.

Basic usage

There are two types of markup in Liquid: Output and Tag.

Output

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

Here is a simple example of Output:

  Hello {{name}}
  Hello {{user.name}}
  Hello {{ 'tobi' }}

Output markup takes filters. Filters are simple methods. The first parameter is always the output of the left side of the filter. The return value of the filter will be the new left value when the next filter is run. When there are no more filters, the template will receive the resulting string.

  Hello {{ 'tobi' | upcase }}
  Hello tobi has {{ 'tobi' | size }} letters!
  Hello {{ '*tobi*' | textilize | upcase }}
  Hello {{ 'now' | date: "%Y %h" }}

Tags

Tag markup (which cannot resolve to text) is surrounded by {% matched pairs of curly brackets and percent signs %}.

tags are used for the programmic logic in your template. Tags are wrapped in: {% %}.



Array filters



Randomize

Gives an array randomized sorting

{{ "[Hello, World, Goodbye, Planet]" | randomize }} #=> Goodbye World Hello Planet


first

Returns the first element of the array. If the array is empty, the first form returns nil, and the second form returns an empty array.

{{ 'q, r, s, t' | first }} #=> "q"


flatten

Flattens self in place. Returns nil if no modifications were made (when the array contains no subarrays). The optional level argument determines the level of recursion to flatten.

a = [ 1, 2, [3, [4, 5] ] ]
a.flatten!   #=> [1, 2, 3, 4, 5]
a.flatten!   #=> nil
a            #=> [1, 2, 3, 4, 5]
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten!(1) #=> [1, 2, 3, [4, 5]]


group(array, group_by)

It groups the array by checking the property between "". Important: don't change key in the liquid, this is a reference to the property at 'group: "..." '.

{% assign rows_by_product = product | group: "name" %}
{% for product in rows_by_product %}
{{product.key}}
{% for klant_email in klant.array %}
{{klant_email.naam}}
{% endfor %}
{% endfor %}


join

Joins the elements of an array with the character passed as the parameter. The result is a single string.

{% assign tags = product | map: 'tag' %}
{{ tags | join: ', '}}  #=> tag1, tag2, tag3


last

Gets the last element passed in an array.

{{ awesome | last }}  #=> e


map

Accepts an array element's attribute as a parameter and creates a string out of each array element's value.

collection.title = "Spring", "Summer", "Fall", "Winter"
{% assign collection_titles = collections | map: 'title' %}
{{ collection_titles }} #=> SpringSummerFallWinter


size

Returns the size of a string or an array.

{{ 'is this a 30 character string?' | size }} #=> 30

{{ record.size }} >>> 30



sort(array, sortation)

Sorts the elements of an array by a given attribute of an element in the array.

products = ["a", "b", "A", "B"]
{% assign products = collection.products | sort: 'title' %}
{% for product in products %}
   {{ product.title }}
{% endfor %} #=> A, B, a, b

​or


products = ["a", "b", "A", "B"]

{% assign products = collection.products | sort: 'title' | reverse %}

{% for product in products %}

{{ product.title }}

{% endfor %} #=> b, a, B, A



sum(array)

Sums the values of an array

{{purchasebills | sum:'amount_to_pay' }} #=> 2.000

Math filters



divided_by

Divides an output by a number. The output is rounded to the nearest integer.

{{ 48 | divided_by: 10 }} #=> 4


minus

Subtracts a number from an output.

{{ 200 | minus: 15 }} #=> 185


modulo

Divides an output by a number and returns the remainder

{{ 3 | modulo:2 }} #=> 1


plus

Adds a number to a number

{{ 200 | plus: 15 }} #=> 215


round()

Rounds the output to the nearest full number or specified number of decimals.

{{ 1.6 | round }} --> 2

{{ 1.2 | round }} --> 1

{{ 4.1234 | round: 2 }} --> 4.12



times

Multiplies a number by a number

{{ 4 | times: 5 }} #=> 20

String filters



Prepend

Prepends characters to a string.

{{ 'sale' | prepend: 'Made a great ' }} #=> Made a great sale


append

Appends characters to a string

{{ 'sales' | append: '.jpg' }} #=> sales.jpg


capitalize

Capitalize a string. Making the first character of a string a capital.

{{ 'capitalize me' | capitalize }} #=> Capitalize me

Note: this command downcases the whole string first. "capitalize ME" wil also return "Capitalize me"



downcase

Converts a string into lowercase.

{{ 'UPPERCASE' | downcase }} #=> uppercase


downcase_first

Converts the first word of the string into lowercase.

{{ 'UPPERCASE UPPERCASE' | downcase_first }} #=> uppercase UPPERCASE


escape

Escape a string, the HTML code remains visible on the page.

{{ "test" | escape }} #=> test


escape once

Returns an escaped version of html without affecting existing escaped entities.

{{ "1 < 2 & 3" | escape_once }} #=> "1 < 2 & 3"


escape_xml

The escape_xml method can be used to escape a String with these entities.

{{ "<sometext>" | escape_xml }} #=>


newline_to_br

Inserts a <br> linebreak HTML tag in front of each line break in a string.

{% capture var %}
One
Two
Three
{% endcapture %}
{{ var | newline_to_br }} #=> One<br> Two<br> Three<br>


raw/no_escape(input)

Returns unescaped variables.

{{ "<p>test</p>" | raw }} or {{ "<p>test</p>" | no_escape }} #=> test


remove

Removes all occurrences of a substring from a string.

{{ "Hello, world. Goodbye, world." | remove: "world" }} #=> Hello, . Goodbye, .



remove_first

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

{{ "Hello, world. Goodbye, world." | remove_first: "world" }} #=> Hello, . Goodbye, world.


replace

Replaces all occurrences of a string with a substring.

product.title = "Awesome Shoes"

{{ product.title | replace: 'Awesome', 'Mega' }} #=> Mega Shoes


replace_first

Replaces the first occurrence of a string with a substring.

product.title = "Awesome Awesome Shoes"

{{ product.title | replace: 'Awesome', 'Mega' }} #=> Mega Awesome Shoes



split

The split filter takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. You can output different parts of an array using array filters.

{{ "a~b" | split:"~" }} #=> ["a", "b"]



squeeze

Changes the input value in the pattern value when the words of the input value are more than two times next to each other.

{{  "moon" | squeeze:'o' }} #=> mon


strip_html

Strips alle HTML tags from a string

{{ "<h1>Hello</h1> World" | strip_html }} #=> Hello World


strip_newlines

Remove any line breaks/newlines from a string.

{{ product.description | strip_newlines }}


textilize

Method which take one parameter and return a modified string.

{{ '*BettyBlocks*' | textilize }} #=> <strong>BettyBlocks</strong>


truncate

Truncates a string down to 'x' characters, where x is the number passed as a parameter. An ellipsis (...) is appended to the string, this can be modified with an extra parameter. The chosen addition is also counted as a character (or multiple).

{{ "The cat came back the very next day" | truncate: 10, "~" }} #=> The cat c~



truncatewords

Truncates a string down to 'x' words, where x is the number passed as a parameter. Standard, an ellipsis (...) is appended to the string, this can be modified with an extra parameter.

{{ "The cat came back the very next day" | truncatewords: 2, "~" }} #=> The cat~


URL filters



.url

Returns the url of an image, mostly used for placing in src of <img src="">.

{{record.image.url}} >>> https://weblink.to.image.png

<img src="{{record.image.url}}"> >>> <img src="https://weblink.to.image.png">


Didn’t find what you want?Ask your question on the forum!