The syntax for Tag markup is {% matched pairs of curly brackets and percent signs %} .Tag markup are used for the logic in your template and is not resolved to text, table 1 lists the supported tags:
Markup |
Notes |
assign |
Assigns some value to a variable |
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. |
for |
For loop |
if |
Standard if/else block |
include |
Includes another template; useful for partials |
raw |
temporarily disable tag processing to avoid syntax conflicts. |
Table 1: Available tag markups
Comments
Comment is the simplest tag. It just swallows content.
We made 1 million dollars {% comment %} in losses {% endcomment %} this year |
Listing 1: Comments in Text templates
Raw
Raw temporarily disables tag processing. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
{% raw %} In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not. {% endraw %} |
Listing 2: Raw tag in text templates
If / Else
if / else should be well-known from any other programming language. This tag allows you to write simple expressions in the if or unless (and optionally, elsif and else) clause:
{% if user %} Hello {{ user.name }} {% endif %} |
Listing 3: Example for conditional processing
# Same as above {% if user != null %} Hello {{ user.name }} {% endif %} |
Listing 4: Example for conditional processing
{% if user.name == 'tobi' %} Hello tobi {% elsif user.name == 'bob' %} Hello bob {% endif %} |
Listing 5: Example for conditional processing
{% if user.name == 'tobi' or user.name == 'bob' %} Hello tobi or bob {% endif %} |
Listing 6: Example for conditional processing
{% if user.name == 'bob' and user.age > 45 %} Hello old bob {% endif %} |
Listing 7: If / Else example
{% if user.name != 'tobi' %} Hello non-tobi {% endif %} |
Listing 8: Example for conditional processing
# Same as above {% unless user.name == 'tobi' %} Hello non-tobi {% endunless %} |
Listing 9: If / Else example
# Check for the size of an array {% if user.payments == empty %} you never paid ! {% endif %} {% if user.payments.size > 0 %} you paid ! {% endif %} |
Listing 10: Example for conditional processing
{% if user.age > 18 %} Login here {% else %} Sorry, you are too young {% endif %} |
Listing 11: Example for conditional processing
# array = 1,2,3 {% if array contains 2 %} array includes 2 {% endif %} |
Listing 12: Example for conditional processing
# string = 'hello world' {% if string contains 'hello' %} string includes 'hello' {% endif %}
|
Listing 13: Example for conditional processing
Case Statement
If you need more conditions, you can use the case statement. Listing 14 shows the syntax for case statements, Listing 15 shows a usage example.
{% case condition %} {% when 1 %} hit 1 {% when 2 or 3 %} hit 2 or 3 {% else %} ... else ... {% endcase %} |
|
Listing 14: Case statement syntax
{% case template %}
{% when 'label' %} // {{ label.title }} {% when 'product' %} // {{ product.vendor | link_to_vendor }} / {{ product.title }} {% else %} // {{page_title}} {% endcase %} |
Listing 15: Case statement example
Cycle
Often you have to alternate between different colors or similar tasks. Text templates have built-in support for such operations, using the cycle tag. Listing 16 shows an example of the cycle tag, listing 17 the result if this tag rendered.
{% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %} {% cycle 'one', 'two', 'three' %} |
Listing 16: Case statement example
one two three one |
Listing 17: Result of template shown in listing 16
If no name is supplied for the cycle group, then it's 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. See Listing 18 for a template example and Listing 19 for the result of this template.
{% cycle 'group 1': 'one', 'two', 'three' %} {% cycle 'group 1': 'one', 'two', 'three' %} {% cycle 'group 2': 'one', 'two', 'three' %} {% cycle 'group 2': 'one', 'two', 'three' %} |
Listing 18: Example of cycles with group names
one two one two |
Listing 19: Result of processing template in listing 18
For loops
Text templates allow for loops over collections:
{% for item in array %} {{ item }} {% endfor %} |
Listing 20: syntax of for loops
When iterating a hash, item[0] contains the key, and item[1] contains the value:
{% for item in hash %} {{ item[0] }}: {{ item[1] }} {% endfor %} |
Listing 21: For loop example
During every for loop, the following helper variables are 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? |
Listing 22: Variables available in for loops
There are several attributes you can use to influence which items you receive in your loop
limit:int lets you restrict how many items you get. offset:int 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 |
Listing 23: Limiting iterated items
Reversing the loop:
{% for item in collection reversed %} {{item}} {% endfor %} |
Listing 24: Example for reversed for loop
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 |
Listing 25: Defining loop collection on the fly
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 %} <p>Freestyle!</p> {% endif %}{% endfor %} |
Listing 26: Assigning variables
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 %} <p>Freestyle!</p> {% endif %} |
Listing 27: Assigning variables
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, then assigns the captured value to the given variable instead of rendering it to the screen.
{% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}
<label for="{{ attribute_name }}">Color:</label> <select name="attributes[{{ attribute_name }}]" id="{{ attribute_name }}"> <option value="red">Red</option> <option value="green">Green</option> <option value="blue">Blue</option> </select> |
Listing 28: Assigning variables
