Liquid Basics
From Spiffy Stores Knowledge Base
Contents
Liquid Template Syntax Basics
This is an introduction to the Spiffy Stores' Liquid template syntax, and a reference for Spiffy Stores-specific Tags and Filters.
Liquid is the templating engine for customizing your store layout. It's a small and fast template language which is quick and easy to learn but contains very powerful features 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.
For instance if your liquid template has a product object exposed to it you can print the name of the product to the screen by referencing
{{ product.title }}
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 {{ 'fred' }}
Acceptable Tags and Comments
We sanitize all templates, so that you may not use javascript or tags that might be harmful to the application. Disallowed tags include, but aren’t limited to:
- HEAD
- BODY
- SCRIPT
Comments
HTML comments are automatically sanitized by our system. If you wish to place comments in your code, do it with a liquid comment, like so:
{{ # This is a comment in liquid, and won't show up on the output }}
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.
Hello {{ 'fred' | upcase }}
Hello fred has {{ 'fred' | length }} letters!
Hello {{ '*fred*' | textilize | upcase }}
Hello {{ 'now' | date: "%Y %h" }}
Filter Reference
| capitalize | Capitalize all words in the input string. |
|---|---|
| date | Reformat a date using an optional format string. Please see below for a list of the valid format characters. **TODO** |
| downcase | Convert a string to lower case. |
| escape | URL encode a string so that all special characters are converted to their % form and can be recognized by browsers. This may also be aliased as "h". |
| first | Get the first element of an array.{{ product.images | first | to_img }}
|
| format_date **TODO** | Formats a date in your account’s selected date format. (Set from the admin prefs.) |
| format_date_in_english **TODO** | Transforms a date into English of when that event happened. (Ex 1 day ago, 2 months from now) |
| format_money **TODO** | Transforms money string into your home currency, and possibly your client's home currency if you've selected one for them. |
| format_text **TODO** | Transforms text using Markdown syntax. Automatically inserts HTML tags like P, BR, etc. |
| image_path **TODO** | Returns the proper image path for your file. Useful if you want to use it in a CSS document, or perhaps create your own image tags. |
| image_tag **TODO** | Creates an IMG tag for a file you've uploaded to the server for use inside your document. Ex: {{ 'image_name.jpg' | image_tag }}
|
| join | Join elements of an array with an optional join character, which defaults to a space.{{ names | join(',') }}
|
| last | Get the last element of an array.{{ product.images | last | to_img }}
|
| make_label **TODO** | Makes an input label, or heading for a table. |
| number_to_percentage **TODO** | Formats number as a percentage. |
| number_to_phone **TODO** | Formats as a phone number. |
| number_with_delimiter **TODO** | Shows a number with delimiter you specify. Ex: {{ invoice.sales_tax | number_with_delimiter: ',' }}
|
| size | Return the size of an array or of a string. |
| sort | Sorts the elements in an array. |
| strip_html | Strip out any html tags. This is a simple filter which simply removes any characters in the form of an HTML tag, such as "<...>". |
| truncate | Truncate a string down to x characters. Additionally, a character string can be specified to indicate that truncation has occurred.{{ 'my long string' | truncate: 50, '...' }}
|
| truncatewords | Truncate a string down to a number of words. This is the same as "truncate", except that the length is specified in words, rather than characters. |
| upcase | Convert a string to upper case. |
Tags
Tags are for the logic in your template. New tags are very easy to code and I hope to get many contributions to the standard tag library after releasing this code.
Here is a list of currently supported tags:
Comments
Comment is the simplest tag. It just swallows content.
Hi fred {% comment %} you stink {% endcomment %}
If / Else
If else should be well known from any language imaginable. Liquid allows you to write simple expressions in the if.
{% if user %}
Hi {{ user.name }}
{% endif %}
{% if user.name == 'fred' %}
hi fred
{% endif %}
{% if user.name != 'fred' %}
hi non-fred
{% endif %}
{% if user.creditcard == null %}
poor sob
{% endif %}
{% if user.payments == empty %}
you never paid !
{% endif %}
{% if user.age > 18 %}
Login here
{% else %}
Sorry, you are too young
{% endif %}
Case Statement
If you need more than one condition you can use the Case Statement
{% case line_item.quantity %}
{% when 0 %}
none
{% when 1 %}
one
{% when 2 %}
two
{% else %}
a few more...
{% endcase %}
Example:
{% 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 colours 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 %}
<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 collections.tags %}{% 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 %}{{ 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>