Sometimes it will become necessary to perform some actions for every item in a list/array/dictionary. With such commands, you are able to iterate through such a list.
Loops like for loops are the most used iterators. With them, you are able to go through lists and dictionaries item by item and create HTML code for each such item. Beside the basic functionality, there are some extensions which helps on the processing of lists.
The for command starts with specifying a new variable name (which will receive a new item on each loop iteration) followed by 'in' and a list variable.
Example:
{% for product in collection.products %}
{{ product.title }},
{% endfor %}
Output:
Star Wars, The Hobbit, Aladdin,
The variable 'product' didn't exist before, we created the variable by using the for command. We could also have used 'pr' (and thus {{ pr.title }}) instead, the result would have been the same. Also, the comma is also repeated as many times as products are in the list, as it is a normal character and just rendered as any other HTML text.
The forloop provides some attributes on the forloop object, which can be accessed when you are within a for loop. For more information, please have a look at the object definitions for the forloop object.
The paginate command alters the list by taking excerpts of the list defined by the number of elements per page and currently displayed page. More on that topic, see on the command paginate .
Another variant of the for loop allows you to loop through a range of int values. You specify a start and end value, the loop will produce one iteration for each of the values in the given range. You could of course also specify a liquid variable instead of a constant, which is possible for all values in Liquid commands.
Example:
{% for i in (4..8) %}
{{ i }}
{% endfor %}
{% assign upto = 3 %}
{% for i in (1..upto) %}
{{ i }}
{% endfor %}
Output:
4 5 6 7 8
1 2 3
There are additional parameters for the for loop available, namely limit, offset and reversed. For the following examples, image that the variable named 'array' holds a list with content [1, 2, 3, 4, 5, 6, 7, 8].
This parameter with a given length will only process the first elements of a list until the limit is reached
Example:
{% for element in array limit: 3 %}
{{ element }}
{% endfor %}
Output:
1 2 3
If you want to start some elements in the list, you can use offset with the number of elements you want to skip from the beginning of the list
Example:
{% for element in array offset: 2 %}
{{ element }}
{% endfor %}
Output:
3 4 5 6 7 8
Sometimes it is necessary to output a list upside down (in order to change the sort order, etc). For this, you can use the parameter reversed (without any additional number).
Example:
{% for element in array reversed %}
{{ element }}
{% endfor %}
Output:
8 7 6 5 4 3 2 1
It is possible to combine several parameters if needed (e.g. reversed and limit).
For loops can also contain three special commands for some specific cases. A for loop can have an else part, which is called when the loop has no elements.
Example:
{% for p in collection.products %}
{{ p.title }}
{% else %}
There are no products in this collection
{% endfor %}
Output:
There are no products in this collection
Also, you are able to leave the loop prematurely or continue with the next operation without processing the rest of the block. A break command will leave the loop directly and will not perform any further iterations.
Example:
{% for i in (1..5) %}
{{ i }}
{% if i >= 3 %}
{% break %}
{% endif %}
Euro
{% endfor %}
Output:
1 Euro 2 Euro 3
Finally, the continue command just stops the processing of the current iteration and starts over with the next iteration.
Example:
{% for i in (1..5) %}
{{ i }}
{% if i >= 3 %}
{% continue %}
{% endif %}
Euro
{% endfor %}
Output:
1 Euro 2 Euro 3 4 5
This is another iteration command, which is usually used within a for loop. The parameters are any number of strings (but of course at least 2). On each iteration of cycle, the next parameter will be outputted. This might e.g. be used for coloring every other line of a table differently.
Example:
{% for i in (1..5) %}
{{ i }} {% cycle 'odd', 'even' %} -
{% endfor %}
Output:
1 odd - 2 even - 3 odd - 4 even - 5 odd -
The cycle command can use another parameter, which allows you to group several cycle commands. This is necessary in case you use several cycles with exact the same cycle parameters within one page, as the second cycle would start exactly where the first cycle stopped processing. Usually, it would be preferable to start anew with each new loop or new cycle command. For that you need to specify a group name before the actual parameters followed by a ':'.
Example:
Wrong handling:
{% for i in (1..5) %}
{{ i }} {% cycle 'odd', 'even' %} -
{% endfor %}
{% for i in (1..5) %}
{{ i }} {% cycle 'odd', 'even' %} -
{% endfor %}
<br/>
Correct handling:
{% for i in (1..5) %}
{{ i }} {% cycle 'group1': 'odd', 'even' %} -
{% endfor %}
{% for i in (1..5) %}
{{ i }} {% cycle 'group2': 'odd', 'even' %} -
{% endfor %}
Output:
Wrong handling:
1 odd - 2 even - 3 odd - 4 even - 5 odd - 1 even - 2 odd - 3 even - 4 odd - 5 even -
Correct handling:
1 odd - 2 even - 3 odd - 4 even - 5 odd - 1 odd - 2 even - 3 odd - 4 even - 5 odd -
This command creates HTML table rows. Therefore, this command need to be enclosed in <table> and </table> tags. Basically, it works exactly like the for command, including the additional parameters offset and limit. Additionally, it also accepts another parameter called 'cols' which defines how many columns the table should have. Also, it provides some more attributes on the tablerow object, which can be accessed when you are within a tablerow loop. For more information, please have a look at the object definitions for the TableRow object.
Example:
<table>
{% tablerow product in collection.products cols: 3 %}
{{ product.title }}
{% endtablerow %}
</table>
Output:
<table>
<tr class="row1">
<td class="col1">
Tears of Steel
</td><td class="col2">
Sintel
</td><td class="col3">
Route 66
</td></tr>
<tr class="row2"><td class="col1">
Star Wreck: In the Pirkinning
</td><td class="col2">
Big Buck Bunny
</td><td class="col3">
Elephants Dream
</td></tr>
</table>
Read more about other command types: