Appearance
Tags
Liquid implements business-logic independent tags. This section contains the specification and demos for all the tags implemented by WISMOlabs implementation of Liquid.
There’re a dozen of tags supported by Liquid. These tags can be categorized into these groups:
| Category | Purpose | Tags |
|---|---|---|
| Iteration | iterate over a collection | or, cycle, tablerow |
| Control Flow | control the execution branch of template rendering | if, unless, elsif, else, case, when |
| Variable | define and alter variables | assign, increment, decrement, capture, echo |
| Language | temporarily disable Liquid syntax | # (inline comment), raw, comment, liquid |
# (inline comment)
Add comments to a Liquid template using an inline tag. Text enclosed in an inline comment tag will not be printed.
Input
Anything inside an inline comment tag will not be printed.
{% # this is an inline comment %}
But every line must start with a '#'.
{%
# this is a comment
# that spans multiple lines
%}Output
Anything inside an inline comment tag will not be printed.
But every line must start with a '#'.Inline comments are useful inside Liquid tags too.
{% liquid
# required args
assign product = collection.products.first
# optional args
assign should_show_border = should_show_border | default: true
assign should_highlight = should_highlight | default: false
%}But they don’t work well for commenting out blocks of Liquid code. The comment block tag is the better option when you need to temporarily stop other tags from being executed.
Input
{%- # {% echo 'Welcome to WISMOlabs!' %}
-%}
{% comment %}{% echo 'Welcome to WISMOlabs!' %}{% endcomment %}Output
-%}assign
Creates a new variable.
Input
{% assign my_variable = false %}
{% if my_variable != true %}
This statement is valid.
{% endif %}Output
This statement is valid.Wrap a variable value in quotations " to save it as a string.
Input
{% assign foo = "bar" %}
{{ foo }}Output
barcapture
Captures the string inside of the opening and closing tags and assigns it to a variable. Variables created through capture are strings.
Input
{% capture my_variable %}I am being captured.{% endcapture %}
{{ my_variable }}Output
I am being captured.Using capture, you can create complex strings using other variables created with assign:
Input
{% assign favorite_food = "pizza" %}
{% assign age = 35 %}
{% capture about_me %}
I am {{ age }} and my favorite food is {{ favorite_food }}.
{% endcapture %}
{{ about_me }}Output
I am 35 and my favourite food is pizza.case
Creates a switch statement to compare a variable with different values. case initializes the switch statement, and when compares its values.
Input
{% assign handle = "cake" %}
{% case handle %}
{% when "cake" %}
This is a cake
{% when "cookie", "biscuit" %}
This is a cookie
{% else %}
This is neither a cake nor a cookie
{% endcase %}Output
This is a cakecomment
Allows you to leave un-rendered code inside a WISMOlabs liquid template. Any text within the opening and closing comment blocks will not be printed, and any Liquid code within will not be executed.
Input
Anything you put between {% comment %} and {% endcomment %} tags
is turned into a comment.Output
Anything you put between tags
is turned into a comment.cycle
Loops through a group of strings and prints them in the order that they were passed as arguments. Each time cycle is called, the next string argument is printed.
Basic Usage
Input
{% cycle "one", "two", "three" %}
{% cycle "one", "two", "three" %}
{% cycle "one", "two", "three" %}
{% cycle "one", "two", "three" %}Output
one
two
three
oneUses for cycle include: applying odd/even classes to rows in a table applying a unique class to the last product thumbnail in a row
Parameters
cycle accepts a “cycle group” parameter in cases where you need multiple cycle blocks in one template. If no name is supplied for the cycle group, then it is assumed that multiple calls with the same parameters are one group.
Input
{% cycle "first": "one", "two", "three" %}
{% cycle "second": "one", "two", "three" %}
{% cycle "second": "one", "two", "three" %}
{% cycle "first": "one", "two", "three" %}Output
one
one
two
twodecrement
Creates a new number variable, and decreases its value by one every time it is called. The first value is -1.
Input
{% decrement variable %}
{% decrement variable %}
{% decrement variable %}Output
-1
-2
-3Like , variables declared inside decrement are independent from variables created through or .
echo
Outputs an expression in the rendered HTML. This is identical to wrapping an expression in {{ and }}, but works inside liquid tags and supports filters.
{% assign username = 'Bob' %}
{% echo username | append: ", welcome to WISMOlabs Liquid!" | capitalize %}Output
Bob, welcome to WISMOlabs Liquid!for
Iteration tags run blocks of code repeatedly.
Basic Usage
for…inRepeatedly executes a block of code.
Input
{% for product in collection.products %}
{{ product.title }}
{% endfor %}Output
hat shirt pantsFor loops can iterate over arrays, hashes, and . When iterating a hash, item[0] contains the key, and item[1] contains the value:
Input
{% for item in hash %}
* {{ item[0] }}: {{ item[1] }}
{% endfor %}Output
* key1: value1
* key2: value2elseSpecifies a fallback case for a for loop which will run if the loop has zero length.
Input
{% for product in collection.products %}
{{ product.title }}
{% else %}
The collection is empty.
{% endfor %}Output
The collection is empty.breakCauses the loop to stop iterating when it encounters the break tag.
Input
{% for i in (1..5) %}
{%- if i == 4 -%}
{% break %}
{%- else -%}
{{ i }}
{%- endif -%}
{% endfor %}Output
123continueCauses the loop to skip the current iteration when it encounters the continue tag.
Input
{% for i in (1..5) %}
{%- if i == 4 -%}
{%- continue -%}
{%- else -%}
{{ i }}
{%- endif -%}
{% endfor %}Output
1235forloopThere’s a forloop object available inside for loops. It’s used to indicate the current state of for loop. The forloop.first, forloop.last and forloop.length property:
Input
{% for i in (1..5) %}
{%- if forloop.first == true -%} First
{%- elsif forloop.last == true -%} Last
{%- else -%} {{ forloop.length }}
{%- endif %}
{% endfor -%}Output
First
5
5
5
LastThe forloop.index, forloop.index0, forloop.rindex and forloop.rindex0 property:
Input
index index0 rindex rindex0
{% for i in (1..5) %}
{{- forloop.index }} {{ forloop.index0 }} {{ forloop.rindex }} {{ forloop.rindex0 }}
{% endfor -%}Output
index index0 rindex rindex0
1 0 5 4
2 1 4 3
3 2 3 2
4 3 2 1
5 4 1 0Parameters
limitLimits the loop to the specified number of iterations.
Input
<!-- for array = [1,2,3,4,5,6] -->
{% for item in array limit:2 %}
{{- item -}}
{% endfor %}Output
12offsetBegins the loop at the specified index.
Input
<!-- for array = [1,2,3,4,5,6] -->
{% for item in array offset:2 %}
{{- item -}}
{% endfor %}Output
3456offset:continue Offset value can be continue to continue previous loop. For example:
Input
<!-- for array = [1,2,3,4,5,6] -->
{% for item in array limit:2 %}
{{- item -}}
{% endfor%}
{% for item in array offset:continue %}
{{- item -}}
{% endfor%}Output
12
3456For the same variable name ("item" in this case) and same collection ("array" in this case), there’s one position record. That means you can start a new loop with a different variable name:
Input
<!-- for array = [1,2,3,4,5,6] -->
{% for item in array limit:2 %}
{{- item -}}
{% endfor%}
{% for item2 in array offset:continue %}
{{- item2 -}}
{% endfor%}Output
12
123456rangeDefines a range of numbers to loop through. The range can be defined by both literal and variable numbers.
Input
{% for i in (3..5) %}
{{- i -}}
{% endfor-%}
{% assign num = 4 %}
{% for i in (1..num) %}
{{- i -}}
{% endfor %}Output
345
1234reversedReverses the order of the loop. Note that this flag’s spelling is different from the filter reverse.
Input
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array reversed %}
{{ item }}
{% endfor %}Output
6 5 4 3 2 1When used with additional parameters, order is important. Leading with reversed reverses the order of the loop before executing the other parameters.
Input
{% for i in (1..8) reversed limit: 4 %}
{{ i }}
{% endfor %}Output
8 7 6 5Input
{% for i in (1..8) limit: 4 reversed %}
{{ i }}
{% endfor %}Output
4 3 2 1if
Executes a block of code only if a certain condition is true.
{% if product.title == "Awesome Shoes" %}
These shoes are awesome!
{% endif %}Output
These shoes are awesome!elsif / else
Adds more conditions within an if or unless block.
Input
<!-- If customer.name = "anonymous" -->
{% if customer.name == "kevin" %}
Hey Kevin!
{% elsif customer.name == "anonymous" %}
Hey Anonymous!
{% else %}
Hi Stranger!
{% endif %}Output
Hey Anonymous!increment
Creates a new number variable, and increases its value by one every time it is called. The first value is 0.
Input
{% increment my_counter %}
{% increment my_counter %}
{% increment my_counter %}Output
0
1
2Variables created through the increment tag are independent from variables created through or . In the example below, a variable named “var” is created through assign. The increment tag is then used several times on a variable with the same name. Note that the increment tag does not affect the value of “var” that was created through assign.
Input
{% assign var = 10 %}
{% increment var %}
{% increment var %}
{% increment var %}
{{ var }}Output
0
1
2
10liquid
Encloses multiple tags within one set of delimiters, to allow writing Liquid logic more concisely.
Input
{% liquid
assign names = 'Bob, Sally' | split: ', '
for name in names
echo 'Hello, ' | append: name
unless forloop.last
echo ', '
endunless
endfor
%}Output
Hello, Bob, Hello Sallyraw
Raw temporarily disables tag processing. This is useful for generating content(eg, Mustache, Handlebars) which uses conflicting syntax. Input
{% raw %}
In Handlebars, {{ this }} will be HTML-escaped, but
{{{ that }}} will not.
{% endraw %}Output
In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
tablerow
Generates an HTML table. Must be wrapped in opening <table> and closing </table> HTML tags.
Basic Usage
Input
<table>
{% tablerow product in collection.products %}
{{ product.title }}
{% endtablerow %}
</table>Output
<table>
<tr class="row1">
<td class="col1">
Cool Shirt
</td>
<td class="col2">
Alien Poster
</td>
<td class="col3">
Batman Poster
</td>
<td class="col4">
Bullseye Shirt
</td>
<td class="col5">
Another Classic Vinyl
</td>
<td class="col6">
Awesome Jeans
</td>
</tr>
</table>Parameters
colsDefines how many columns the tables should have.
Input
{% tablerow product in collection.products cols:2 %}
{{ product.title }}
{% endtablerow %}Output
<table>
<tr class="row1">
<td class="col1">
Cool Shirt
</td>
<td class="col2">
Alien Poster
</td>
</tr>
<tr class="row2">
<td class="col1">
Batman Poster
</td>
<td class="col2">
Bullseye Shirt
</td>
</tr>
<tr class="row3">
<td class="col1">
Another Classic Vinyl
</td>
<td class="col2">
Awesome Jeans
</td>
</tr>
</table>limitExits the tablerow after a specific index.
{% tablerow product in collection.products cols:2 limit:3 %}
{{ product.title }}
{% endtablerow %}offsetStarts the tablerow after a specific index.
{% tablerow product in collection.products cols:2 offset:3 %}
{{ product.title }}
{% endtablerow %}rangeDefines a range of numbers to loop through. The range can be defined by both literal and variable numbers.
<!--variable number example-->
{% assign num = 4 %}
<table>
{% tablerow i in (1..num) %}
{{ i }}
{% endtablerow %}
</table>
<!--literal number example-->
<table>
{% tablerow i in (3..5) %}
{{ i }}
{% endtablerow %}
</table>unless
The opposite of if – executes a block of code only if a certain condition is not met.
Input
{% unless product.title == "Awesome Shoes" %}
These shoes are not awesome.
{% endunless %}Output
These shoes are not awesome.This would be the equivalent of doing the following:
{% if product.title != "Awesome Shoes" %}
These shoes are not awesome.
{% endif %}