Tags
Overview
Review of ZMP platform tags
Comment
It allows you to leave un-rendered code in content. Any text within the opening and closing comment blocks will not be output, and any ZML 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.
Control Flow
Control flow tags can change the information ZML shows using logic.
If
Executes a block of code only if a certain condition is true.
Input
{% if first_name %} Hello {{ first_name }}! {% endif %}
Output
Hello Ryan!
Unless
The opposite of if – executes a block of code only if a certain condition is not met.
Input
{% unless first_name == "Ryan" %}
Hello {{ first_name }}! {% endunless %}
Because first_name is equal to Ryan, the output is empty.
Output
Elsif / Else
Adds more conditions within an if or unless block. Note the missing 'e' in elsif. This is intentional.
Input
{% if first_name == "Ryan" %} Hello {{ first_name }}!
{% elsif first_name == "Jeremy" %}
This guys name is Jeremy.
{% else %}
This person's name is neither Ryan nor Jeremy.
{% endif %}
Case / When
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' %}
This is a cookie
{% else %}
This is not a cake nor a cookie
{% endcase %}
Output
This is a cake
Iteration
Iteration tags run blocks of code repeatedly.
For
Repeatedly executes a block of code. For a full list of attributes available within a for loop, see forloop (object).
Input
<!-- subscription_preferences = "newsletter", "promotions" -->
{% for preference in subscription_preferences %} {{ preference }}
{% endfor %}
Output
newsletter promotions
Break
Causes 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
1 2 3
Continue
Causes 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
1 2 3 5
For (Parameters)
Limit
Limits the loop to the specified number of iterations.
Input
<! -- array = [1,2,3,4,5,6] -->
{% for item in array limit:2 %}
{{ item }}
{% endfor %}
Output
1 2
Offset
Begins the loop at the specified index.
Input
<! -- array = [1,2,3,4,5,6] -->
{% for item in array offset:2 %}
{{ item }}
{% endfor %}
Output
3 4 5 6
Range
Defines 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 }}
{% enddfor %}
Output
3 4 5
1 2 3 4
Reversed
Reverses the order of the loop. Note that the flag’s spelling is different to 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 1
Cycle
Loops through a group of strings and outputs them in the order that they were passed as parameters. Each time cycle is called, the next string that was passed as a parameter is output.
cycle must be used within a for loop block.
Input
<!-- if array = [1,2,3,4,5,6] -->
{% for item in array reversed %}
{{ item }}
{% endfor %}
Output
one
two
three
one
Uses for cycle include:
Alternating between odd/even rows
applying a unique class to the last product thumbnail in a row
Cycle (Parameters)
cycle accepts a parameter called cycle group 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. More information on cycle groups can be found here.
Tablerow
See here for more information on creating tables with ZML.
Raw
Raw temporarily disables tag processing. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax but may not have much usefulness within content end users will see.
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.
Variable
Variable tags create new ZML variables.
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 in quotations " to save it as a string.
Input
{% assign foo = "bar" %}
{{ foo }}
Output
bar
Capture
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 favorite food is pizza.
Increment
Creates a new number variable, and increases its value by one every time it is called. The initial value is 0.
Input
{% increment my_counter %}
{{my_counter}}
{% increment my_counter %}
{{my_counter}}
{% increment my_counter %}
{{my_counter}}
Output
0
1
2
Variables created through the increment tag are independent from variables created through assign or capture.
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
10
Decrement
Creates a new number variable, and decreases its value by one every time it is called. The initial value is -1. Like increment, variables declared inside decrement are independent from variables created through assign or capture.