Liquid for Template Designers

This document describes the syntax and semantics of the template engine and will be most useful as reference to those creating Liquid templates.

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

• Output markup (which may resolve to text) is surrounded by

{{ matched pairs of curly brackets (ie, braces) }}

• Tag markup (which cannot resolve to text) is surrounded by

{% matched pairs of curly brackets and percent signs %}

Output

Here is a simple example of Output:

Template:

Hello {{ name }}
Hello {{ company }}
Hello {{ user.name }}
Hello {{ 'Harald' | upcase }}

Data:

<?php
array(
  'name' => 'Harald',
  'company' => 'DELACAP',
  'user' => array(
    'name' => 'Superuser'
  )
);

Output:

Hello Harald
Hello DELACAP
Hello Superuser
HARALD

Advanced output: Filters

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

Standard Filters

• append - append a string e.g. {{ 'foo' | append:'bar' }} #=> 'foobar'

• capitalize - capitalize words in the input sentence

• date - reformat a date (syntax reference)

• divided_by - division e.g {{ 10 | divided_by:2 }} #=> 5

• downcase - convert an input string to lowercase

• escape - escape a string

• escape_once - returns an escaped version of html without affecting existing escaped entities

• first - get the first element of the passed in array

• join - join elements of the array with certain character between them

• last - get the last element of the passed in array

• map - map/collect an array on a given property

• minus - subtraction e.g {{ 4 | minus:2 }} #=> 2

• newline_to_br - replace each newline (\n) with html break

• plus - addition e.g {{ '1' | plus:'1' }} #=> '11', {{ 1 | plus:1 }} #=> 2

• prepend - prepend a string e.g. {{ 'bar' | prepend:'foo' }} #=> 'foobar'

• replace - replace each occurrence e.g. {{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'

• replace_first - replace the first occurrence e.g. {{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'

• remove - remove each occurrence e.g. {{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'

• remove_first - remove the first occurrence e.g. {{ 'barbar' | remove_first:'bar' }} #=> 'bar'

• size - return the size of an array or string

• sort - sort elements of the array

• strip_html - strip html from string

• strip_newlines - strip all newlines (\n) from string

• times - multiplication e.g {{ 'foo' | times:4 }} #=> 'foofoofoofoo', {{ 5 | times:4 }} #=> 20

• truncate - truncate a string down to x characters

• truncatewords - truncate a string down to x words

• upcase - convert an input string to uppercase

Tags

Tags are used for the logic in your template. New tags are very easy to code, so I hope to get many contributions to the standard tag library after releasing this code.

Here is a list of currently supported tags:

• assign - Assgins some value to a variable.
• block - Blocks are used for inheritance and act as placeholders and replacements.
• capture - Block tag that captures text into a variable.
• case - Block tag, its the standard case...when block.
• comment - Block tag, comments out the text in the block.
• cycle - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
• extends - The extends tag can be used to extend a template from another one.
• for - For loop
• if - Standard if/else block
• include - Includes another template, useful for partials.
• unless - Mirror of if statement.

---

This Page is based on https://github.com/Shopify/liquid/wiki/Liquid-for-Designers