Using Liquid Markup Template

Liquid is the engine of Onigi’s customization. It’s a small and fast template language which is quick to learn but very powerful for full customization.

Basics ¶

There are two types of markup in liquid: Output and Tag.

• Output is surrounded by
 {{ two curly brackets }}

• Tags are surrounded by
 {% a curly bracket and a percent %}

Output blocks will always be replaced with the data which they reference. If your liquid template has a product object exposed to it you can print the name of the product to the screen by referencing TemplatePage

Tags drive the logic of templates. They are responsible for loops and branching logic such as If / Else.
Output

Here is a simple example of Output:

Hello {{name}}
Hello {{user.name}}
Hello {{ 'tobi' }}

Filters ¶

Output markup takes filters. Filters are simple methods. The first parameter is always the output of the left side of the filter. The return value of the filter will be the new left value when the next filter is run. When there are no more filters the template will receive the resulting string.

The word "tobi" in uppercase: {{ 'tobi' | upcase }}
The word "tobi" has {{ 'tobi' | size }} letters!
Change "Hello world" to "Hi world": {{ 'Hello world' | replace: 'Hello', 'Hi' }}
The date today is {{ 'now' | date: "%Y %b %d" }}


The code above results in the following:

The word "tobi" has 4 letters!
Change "Hello world!" to "Hi world!": Hi world
The date today is 2009 Mar 02 [depends on when you're viewing this document]

Tags ¶

Tags are for the logic in your template. Not to be confused with product tags.
Here is a list of currently supported tags:

Comments ¶

Comments are enclosed with a {% comment %} opening tag and a {% endcomment %} closing tag. As in other languages, all characters enclosed by these tags are ignored and will not be parsed by the language. These tags also work for multi-line comments.

Hello world. {% comment %} Now this is a single-line comment {% endcomment %} <br />
Hello world,
I think I'm gonna be happy today. {% comment %} Now this is a
multi-line comment that should be ignored too,
just like the single-line comment {% endcomment %}

The code above will result in:

Hello world.
Hello world, I think I'm gonna be happy today.

No Liquid Zone: the raw tag ¶

Any Liquid tags between a {% raw %} opening tag and a {% endraw %} closing tag will be ignored by the Liquid parser. What is enclosed by the raw tags is sent back to the browser, this differentiates raw tags from comment tags. Use raw tags to wrap JavaScript templates that use curly braces. 
##{% raw %}{{ 5 | plus: 6 }}{% endraw %} is equal to{{ 5 | plus: 6 }}##.

The code above will result in:

{{ 5 | plus: 6 }} is equal to 11

If / Else / Unless ¶

If else should be well known from any language imaginable. Liquid allows you to write simple expressions in the if. Unless is the opposite of If and is useful if you only need to check that something isn’t true.
PLEASE NOTE: Onigi does not export a user variable. This example is for conditional logic demonstration purposes only.

{% if user %}
  Hi {{ user.name }}
{% endif %}

{% if user.name == 'tobi' %}
  hi tobi
{% endif %}

{% if user.name != 'tobi' %}
  hi non-tobi
{% endif %}

{% unless user.name == 'tobi' %}
  hi non-tobi
{% endunless %}

{% if user.name == 'tobi' or user.name == 'marc' %}
  hi marc or tobi
{% endif %}

{% if user.name == 'tobi' and user.last_name == 'scottish' %}
  hi tobi scottish
{% endif %}

{% if user.name contains 'tobi' %}
  hi tobias
{% endif %}

{% if user.creditcard == nil %}
   poor sob
{% endif %}

{% if user.payments == empty %}
   you haven't paid yet!
{% endif %}

{% if user.age > 18 %}
   Login here
{% else %}
   Sorry, you are too young
{% endif %}

{% unless user.age > 18 %}
  Sorry, you are too young
{% else %}
  Login here
{% endunless %}

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 %}
    hit else
{% endcase %}

Example:

{% case template %}
  {% when 'index' %}
     Welcome
  {% when 'product' %}
     {{ product.url | link_to_vendor }} / {{ product.name }}
  {% 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' %}<br />
{% cycle 'one', 'two', 'three' %}<br />
{% cycle 'one', 'two', 'three' %}<br />
{% 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.

Important

To use many cycle in one template, you must use named groups for predictable results.
Take this example where we iterate through 2 different collections to output their respective products:

<ul>
{% for product in products %}
  <li{% cycle ' style="clear:both;"', '', '', ' class="last"' %}>
    <a href="{{ product.url | within: collection }}">
      <img src="{{ product.picture | product_img_url: "medium" }}" alt="{{ product.picture }}" />
    </a>
  </li>
{% endfor %}
</ul>
<ul>
{% for product in products %}
  <li{% cycle ' style="clear:both;"', '', '', ' class="last"' %}>
    <a href="{{ product.url | within: collection }}">
      <img src="{{ product.picture | product_img_url: "medium" }}" alt="{{ product.picture }}" />
    </a>
  </li>
{% endfor %}
</ul>

In the above example, if the first collection only has 2 products in it then the next collection loop will pick up the ‘cycle’ where the first one left off resulting in this undesired output:

<ul>
  <li style="clear:both"></li>
  <li></li>
</ul>
<ul>
  <li></li>
  <li class="last"></li>
  <li style="clear:both"></li>
  <li></li>
</ul>

To avoid that, you must use a cycle group for each of your loop blocks like so:

<ul>
{% for product in products.items %}
  <li{% cycle 'group1': ' style="clear:both;"', '', '', ' class="last"' %}>
    <a href="{{ product.url | within: collection }}">
      <img src="{{ product.picture  | product_img_url: "medium" }}" alt="{{ product.picture  }}" />
    </a>
  </li>
{% endfor %}
</ul>
<ul>
{% for product in products %}
  <li{% cycle 'group2': ' style="clear:both;"', '', '', ' class="last"' %}>
    <a href="{{ product.url | within: collection }}">
      <img src="{{ product.picture | product_img_url: "medium" }}" alt="{{ product.picture }}" />
    </a>
  </li>
{% endfor %}
</ul>

With the above code, we now get the desired output as shown below:

<ul>
  <li style="clear:both"></li>
  <li></li>
</ul>
<-- new cycle group starts! -->
<ul>
  <li style="clear:both"></li>
  <li></li>
  <li></li>
  <li class="last"></li>
</ul>

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 products in array limit:2 offset:2 %}
    {{ products }}
  {% 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 products.items is 4...
  {% for i in (1..products.items) %}
    {{ 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 product in products.items cols: 3 limit: 12 %}
    {{product.name}}
  {% 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 product in products.items cols: 3 %}
    {% if tablerowloop.col_first %}
      First column: {{product.name}}
    {% else %}
      Different column: {{product.name}}
    {% 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 products.items %}{% if t == name %}
  <p>Freestyle!</p>
{% endif %}{% endfor %}

Another way of doing this would be to assign true/false values to the variable:

{% assign freestyle = false %}
{% for t in products.items %}{% if t == 'freestyle' %}
  {% assign freestyle = true %}
{% endif %}{% endfor %}
{% if freestyle %}
  <p>Freestyle!</p>
{% 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 %}{{ product.name | 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>