====== Liquid Tags ======
[[Liquid templates]] are constructed with Liquid drops and filters ("output") and tags. These are the Liquid tags available in SandwichBoard.
===== Comments =====
Comment is the simplest tag. It just swallows content.
Hi tobi {% comment %} you rock! {% endcomment %}
===== If / Else =====
If Else should be well known from any language imaginable. Liquid allows you to write simple expressions
in the If, including ranges and collection inspection.
{% if user %}
Hi {{ user.name }}
{% endif %}
{% if user.name == 'tobi' %}
hi tobi
{% endif %}
{% if user.name includes 'tobi' %}
hi tobi
{% endif %}
{% if user.name != 'tobi' %}
hi non-tobi
{% endif %}
{% if user.name == blank %}
hi no one
{% endif %}
{% if user.creditcard == null or user.creditcard == nil %}
poor sob
{% endif %}
{% if user.payments == empty %}
you never paid !
{% endif %}
{% if user.paid == false %}
you never paid !
{% endif %}
{% if user.paid or user.owed_amount == 0 %}
you do not owe anything
{% endif %}
{% if user.age > 18..121 and user.human == true %}
Login here
{% else %}
Sorry, you are too young...or lying
{% endif %}
===== Case Statement =====
If you need more than one condition you can use the Case Statement.
{% case condition %}
{% when 1 %}
hit 1
{% when 2 %}
hit 2
{% else %}
elseblock
{% endcase %}
{% case template %}
{% when 'label' %}
{{ label.title }}
{% when 'product' %}
{{ product.vendor | link_to_vendor }} / {{ product.title }}
{% else %}
{{page_title}
{% endcase %}
===== Cycle =====
Often you have to alternate between different colors for similar tasks.
Liquid has build in support for such operations using the cycle tag.
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
{% cycle 'one', 'two', 'three' %}
will result in
one
two
three
one
If no name is supplied for the cycle group then its assumed that multiple calls with the same parameters are one group.
If you want to have total control over cycle groups you can optionally specify the name of the group. This can even be a variable.
{% cycle 'group 1': 'one', 'two', 'three' %}
{% cycle 'group 1': 'one', 'two', 'three' %}
{% cycle 'group 2': 'one', 'two', 'three' %}
{% cycle 'group 2': 'one', 'two', 'three' %}
will result in
one
two
one
two
===== For Loops =====
Liquid allows for loops over collections.
{% for item in array %}
{{ item }}
{% endfor %}
During every for loop there are following helper variables available for extra styling needs:
forloop.length # => length of the entire for loop
forloop.index # => index of the current iteration
forloop.index0 # => index of the current iteration (zero based)
forloop.rindex # => how many items are still left?
forloop.rindex0 # => how many items are still left? (zero based)
forloop.first # => is this the first iteration?
forloop.last # => is this the last iteration?
There are several attributes you can use to influence which items you receive in your loop
''limit'' lets you restrict how many items you get.
''offset'' lets you start the collection with the nth item.
# array = [1,2,3,4,5,6]
{% for item in array limit:2 offset:2 %}
{{ item }}
{% endfor %}
# results in 3,4
Instead of looping over an existing collection, you can define a range of numbers to loop through. The range can be defined by both literal and variable numbers:
# if item.quantity is 4...
{% for i in (1..item.quantity) %}
{{ i }}
{% endfor %}
# results in 1,2,3,4
===== Tables =====
Liquid can create table rows and cells for you (you still need to wrap a table tag around the tablerow instruction):
{% tablerow item in items cols: 3 limit: 12 %}
{{ item.variable }}
{% endtablerow %}
You can also find out whether a table cell is the first or last column in a row or directly query the column number:
tablerowloop.length # => length of the entire for loop
tablerowloop.index # => index of the current iteration
tablerowloop.index0 # => index of the current iteration (zero based)
tablerowloop.rindex # => how many items are still left?
tablerowloop.rindex0 # => how many items are still left? (zero based)
tablerowloop.first # => is this the first iteration?
tablerowloop.last # => is this the last iteration?
tablerowloop.col # => index of column in the current row
tablerowloop.col0 # => index of column in the current row (zero based)
tablerowloop.col_first # => is this the first column in the row?
tablerowloop.col_last # => is this the last column in the row?
{% tablerow item in items cols: 3 %}
{% if col_first %}
First column: {{ item.variable }}
{% else %}
Different column: {{ item.variable }}
{% endif %}
{% endtablerow %}
===== Variable Assignment =====
You can store data in your own variables, to be used in output or other tags as desired. The simplest way to create a variable is with the '''assign''' tag, which has a pretty straightforward syntax:
{% assign name = 'freestyle' %}
{% for t in collections.tags %}
{% if t == name %}
Freestyle!
{% endif %}
{% endfor %}
Another way of doing this would be to assign true/false values to the variable:
{% assign freestyle = false %}
{% for t in collections.tags %}
{% if t == 'freestyle' %}
{% assign freestyle = true %}
{% endif %}
{% endfor %}
{% if freestyle %}
Freestyle!
{% endif %}
If you want to combine a number of strings into a single string and save it to a variable, you can do that with the '''capture''' tag. This tag is a block which "captures" whatever is rendered inside it and assigns it to the given variable instead of rendering it to the screen. Here's how it works:
{% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}
===== Include =====
You can break Liquid templates down to smaller ones and piece them together. Sometimes you will want to pass collections to included Liquid templates using the ''with'' designator. The Asian theme in our default theme pack provides a good example.
Example:
menu.liquid
{% if menu.description %}
{{ menu.description | simple_format }}
{% endif %}
{% for section in menu.sections %}
{{ section.name }}
{% if section.description %}
{{ section.description | simple_format }}
{% endif %}
{% include 'item' with section.items %}