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]]

Uniq (unique)

Removes all double values in an array. 

{% assign products = ["a", "a", "b", "c"] %}
{{ products | uniq }} >>> ["a", "b", "c"]

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  "1 

escape_xml

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

##{{ "" | 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
 Two
 Three

raw/no_escape(input)

Returns unescaped variables.

##{{ " test " | raw }} or ##{{ " test " | 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

##{{ " Hello  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 }} #=> BettyBlocks

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 >>> 

link_to(record, user)

A link to a record (e.g. an invoice) and a specific user (e.g. a guest)

##{{ record | link_to:guest  }} #=> profile

url_encode

Encodes characters so that they can be used in an URL.

##{{ "john@example.com" | url_encode }} => john%40example.com

Additional filters

format(input, size)

Choose the right format for an image (also possible with image.format)

##{{ format (record, width:600, height:400) }}

parse(input)

Parse a Betty Blocks expression

to_currency(input, unit, precision, delimiter, separator)

Unit:

Sets the denomination of the currency.

Precision:

Sets the level of precision.

Delimiter:

Sets the thousands delimiter.

Separator:

Sets the separator between the units.

Using to_currency without parameters will give the standard USD notation.

##{{1234567 | to_currency: '€', 2, '.', ','}} #=> €1.234.567,00##{{1234567 | to_currency } #=> $1,234.567.00

to_currency_without_cents(input, unit, delimiter)

Convert an integer to a currency.

Control flow tags

case

Case is used as if-statement with a number of else-ifs.

{% assign handle = 'betty' %}
{% case handle %}
  {% when 'betty' %}
     This is betty
  {% when 'blocks' %}
     This is blocks
  {% else %}
     This is not betty nor blocks
{% endcase %}

if else

Standard if/else block

{% if product.title == 'Awesome Shoes' %}
    These shoes are awesome!
{% endif %}

You can extend an if-statement using else or elsif. You can also use multiple conditions using 'and' and 'or'.

{% if product.title == 'Awesome Shoes' %}
 These shoes are awesome!
{% elsif product.title 'Awesome Shoes' and product.stock > 0 %}
These shoes are awesome, and in stock!
{% else %}
These shoes aren't awesome..
{% endif %}

unless

Unless mirrors the if-statement.

{% unless product.title == 'Awesome Shoes' %}
    These shoes are not awesome.
 {% endunless %}

Variable tags

assign

Assigns some value to a variable.

{% assign my_variable = false %}
  {% if my_variable != true %}
  This statement is valid.
  {% endif %} # => This statement is valid.

capture

Block tag that captures text into a variable

{% capture my_variable %}
I am being captured.
{% endcapture %}
##{{ my_variable }} #=> I am being captured.

image.size

An image property can hold multiple sizes of an image. Add the name of this size to your image property to get the url of this sized image. Read more about image sizes here.

##{{record.image}} --> image url##{{record.image.size_1}} --> Image url with custom size

Iteration tags

cycle

Cycle is usually used within a loop to alternate between values, like colors or DOM classes.

{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %} #=> one, two, three, one...

for

Repeatedly executes a block of code.

{% for p in collection.products %}
##{{ p.title }}
{% endfor %} #=> product1, product2, product3

The name of the loop-object (p in this case) can be anything.

Theme tags

Comment

Create a comment from the text in the block.

My name is {% comment %}Betty{% endcomment %} Blocks. #=> My name is Blocks.

include

Includes another template from the back-end; useful for partials.

{% include 'snippet-name' %}

Note: Place you partial name within the apostrophes

raw

Temporarily disable tag processing to avoid syntax conflicts.

{% raw %}##{{ 6 | plus: 5 }}{% endraw %} will result in 11.

Date filters

Localize

Converts date to current app language. Date standard format is "%-d %B %Y”.

##{{ "today", format = "date" }} #=> 04/22/14

date

Reformate a date in seconds, minutes, hours, days, weeks, months and years.

##{{ article.published_at | date: "%D" }} #=> 04

These are all supported formats.
These also apply to date-expressions.

        %Y - Year with century (can be negative, 4 digits at least)
              -0001, 0000, 1995, 2009, 14292, etc.
        %C - year / 100 (round down.  20 in 2009)
        %y - year % 100 (00..99)
        %m - Month of the year, zero-padded (01..12)
              %_m  blank-padded ( 1..12)
        %B - The full month name (``January'')
              %^B  uppercased (``JANUARY'')
        %b - The abbreviated month name (``Jan'')
              %^b  uppercased (``JAN'')
        %h - Equivalent to %b
        %d - Day of the month, zero-padded (01..31)
              %-d  no-padded (1..31)
        %e - Day of the month, blank-padded ( 1..31)
        %j - Day of the year (001..366)
        Time (Hour, Minute, Second, Subsecond):
        %H - Hour of the day, 24-hour clock, zero-padded (00..23)
        %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
        %I - Hour of the day, 12-hour clock, zero-padded (01..12)
        %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
        %P - Meridian indicator, lowercase (``am'' or ``pm'')
        %p - Meridian indicator, uppercase (``AM'' or ``PM'')
        %M - Minute of the hour (00..59)
        %S - Second of the minute (00..59)
        %L - Millisecond of the second (000..999)
        %N - Fractional seconds digits, default is 9 digits (nanosecond)
              %3N  millisecond (3 digits)
              %6N  microsecond (6 digits)
              %9N  nanosecond (9 digits)
              %12N picosecond (12 digits)
        Time zone:
        %z - Time zone as hour and minute offset from UTC (e.g. +0900)
              %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
              %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
              %:::z - hour, minute and second offset from UTC
                                                (e.g. +09, +09:30, +09:30:30)
        %Z - Time zone abbreviation name
        Weekday:
        %A - The full weekday name (``Sunday'')
              %^A  uppercased (``SUNDAY'')
        %a - The abbreviated name (``Sun'')
              %^a  uppercased (``SUN'')
        %u - Day of the week (Monday is 1, 1..7)
        %w - Day of the week (Sunday is 0, 0..6)
        ISO 8601 week-based year and week number:
        The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
        The days in the year before the first week are in the last week of
        the previous year.
        %G - The week-based year
        %g - The last 2 digits of the week-based year (00..99)
        %V - Week number of the week-based year (01..53)
        Week number:
        The week 1 of YYYY starts with a Sunday or Monday (according to %U
        or %W).  The days in the year before the first week are in week 0.
        %U - Week number of the year.  The week starts with Sunday.  (00..53)
        %W - Week number of the year.  The week starts with Monday.  (00..53)
        Seconds since the Unix Epoch:
        %s - Number of seconds since 1970-01-01 00:00:00 UTC.
        %Q - Number of microseconds since 1970-01-01 00:00:00 UTC.
        Literal string:
        %n - Newline character (\n)
        %t - Tab character (\t)
        %% - Literal ``%'' character
        Combination:
        %c - date and time (%a %b %e %T %Y)
        %D - Date (%m/%d/%y)
        %F - The ISO 8601 date format (%Y-%m-%d)
        %v - VMS date (%e-%b-%Y)
        %x - Same as %D
        %X - Same as %T
        %r - 12-hour time (%I:%M:%S %p)
        %R - 24-hour time (%H:%M)
        %T - 24-hour time (%H:%M:%S)
        %+ - date(1) (%a %b %e %H:%M:%S %Z %Y)

plus_days

Add a number of days to a date.
The value of "number of days" are summed to the specific date.

##{{ "01-01-2016" | plus_days: 7  | date: '%d-%m-%Y' }} #=> 08-01-2016
Did this answer your question?