Liquid Basics

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.

The Spiffy Stores Liquid Variables Reference can be found here.

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

asset_url(input)	Returns the URL for an asset. {{ 'shop.css' | asset_url }} The above example returns the path plus filename of the specified file. In this case it could be something like: "http://asset2.spiffyserver.com/sites/3457/shop.css" You will most probably use this URL with another filter to create a link or an include tag for instance: {{ 'shop.css' | asset_url | stylesheet_tag }}
capitalize(input)	Capitalize all words in the input string. {{ variant.title | capitalize }}
date(input, format)	Reformat a date using an optional format string. Please see below for a list of the valid format characters. %a - The abbreviated weekday name ("Sun") %A - The full weekday name ("Sunday") %b - The abbreviated month name ("Jan") %B - The full month name ("January") %c - The preferred local date and time representation %d - Day of the month (01..31) %H - Hour of the day, 24-hour clock (00..23) %I - Hour of the day, 12-hour clock (01..12) %j - Day of the year (001..366) %m - Month of the year (01..12) %M - Minute of the hour (00..59) %p - Meridian indicator ("AM" or "PM") %S - Second of the minute (00..60) %U - Week number of the current year, starting with the first Sunday as the first day of the first week (00..53) %W - Week number of the current year, starting with the first Monday as the first day of the first week (00..53) %w - Day of the week (Sunday is 0, 0..6) %x - Preferred representation for the date alone, no time %X - Preferred representation for the time alone, no date %y - Year without a century (00..99) %Y - Year with century %Z - Time zone name %% - Literal "%" character {{ order_date | date: "%m %B, %Y" }}
default_pagination(paginate)	This filter is to be used in conjunction with the Liquid Paginate Tag. It will produce default pagination for the paginated collection if you pipe in the paginate hash which is created by the paginate tag. <div id="paginate">{{ paginate | default_pagination }}</div>
downcase(input)	Convert a string to lower case. {{ variant.title | downcase }}
escape(input)	Escape a string so that all special characters are converted to their % form and can be recognised by browsers. This may also be aliased as "h". {{ product.url | escape }}
first(array)	Get the first element of an array. {{ product.images | first | to_img }}
global_asset_url(input)	Returns the URL for a global asset. Global assets are kept in a certain directory on the Spiffy Stores web servers which is aggressively cached and compressed. Using assets from this global directory can improve the loading times of your pages dramatically. Here's a complete listing of all the global assets available: {{ 'prototype.js' | global_asset_url | script_tag }} {{ 'builder.js' | global_asset_url | script_tag }} {{ 'controls.js' | global_asset_url | script_tag }} {{ 'dragdrop.js' | global_asset_url | script_tag }} {{ 'effects.js' | global_asset_url | script_tag }} {{ 'scriptaculous.js' | global_asset_url | script_tag }} {{ 'slider.js' | global_asset_url | script_tag }} {{ 'sound.js' | global_asset_url | script_tag }} {{ 'lightbox.css' | global_asset_url | stylesheet_tag }} {{ 'lightbox.js' | global_asset_url | script_tag }} {{ 'lightbox/v1/lightbox.css' | global_asset_url | stylesheet_tag }} {{ 'lightbox/v1/lightbox.js' | global_asset_url | script_tag }} {{ 'lightbox/v2/lightbox.css' | global_asset_url | stylesheet_tag }} {{ 'lightbox/v2/lightbox.js' | global_asset_url | script_tag }}
highlight_active_tag(tag, css_class='active')	This filter creates a span with the class active around the tag if it is active. An active tag means that it is currently used to narrow down the selection of displayed products in a given collection. A tag becomes active when someone clicks on a tag link generated by a link_to_tag or link_to_add_tag filter. {% for tag in collection.tags %} {{ tag | highlight_active_tag | link_to_tag: tag }} {% endfor %}
img_tag(url, alt="")	This filter creates an image tag, using the url parameter as image source (<img src="...>) and an optional second parameter as an alt description of the image. {{ 'image_name.jpg' | image_tag }}
join(input, glue = ' ')	Join elements of an array with an optional join character, which defaults to a space. {{ names | join: ',' }}
last(array)	Get the last element of an array. {{ product.images | last | to_img }}
link_to(link, url, title="")	A link_to filter creates a link (<a href="...>) for the given parameters. The first parameter is the link name, the second is the url and the third parameter specifies an optional title. {{ 'Spiffy Stores' | link_to: 'http://www.spiffystores.com.au', 'The best shopping cart on the planet' }}
link_to_add_tag(label, tag)	This filter creates a link to all products in a collection that have the given tag including and all the previous tags that might have been added. {% for tag in collection.tags %} {{ '+' | link_to_add_tag: tag }} {{ tag }} {% endfor %} The above code creates a list of links for each tag for each product in the collection. In this case, the '+' is the clickable link name followed by a tag name. Using this filter, you can specify the search by using more than just one tag. For example, you can add the tags "green", "summer sale" and "cheap" within a collection called "clothing" and it would show you only products that are in this collection that also have all of the added tags.
link_to_remove_tag(label, tag)	This filter creates a link to all products in a collection with the given tag removed, but maintaining all of the previous tags that have been added. {% for tag in collection.tags %} {{ '-' | link_to_remove_tag: tag }} {{ tag }} {% endfor %}
link_to_tag(label, tag, all=false)	This filter creates a link to all products in a collection that have the given tag. {% for tag in collection.tags %} {{ tag | link_to_tag: tag }} {% endfor %} The above code creates a list of links for each tag for each product in the collection. Each link will show all of the products in the collection that are tagged with the corresponding tag.
link_to_type(type)	This filter creates a link to all items in the collection matching the given type. {{ "Shirt" | link_to_type }} In this example, a link would be created called "Shirt" which links to all products of the type Shirt.
link_to_vendor(vendor)	This filter creates a link to all items in the collection matching the given vendor. {{ "Spiffy" | link_to_vendor }} In this example, a link would be created called "Spiffy" which links to all products belonging to the vendor Spiffy.
money(money)	This filter takes a number and converts it to a string formatted based on your store currency format, which is selected from the General Preferences screen. {{ 1.45 | money }} By default, using AUD as the currency, this would be formatted as $1.45
money_rounded(money)	This filter takes a number and rounds it to an integer number. {{ 1.45 | money_rounded }} In this example, this will be formatted as 1
money_with_currency(money)	This filter takes a number and converts it to a string formatted based on your store currency format, which is selected from the General Preferences screen. {{ 1.45 | money_with_currency }} By default, using AUD as the currency, this would be formatted as $1.45 AUD
money_without_currency(money)	This filter takes a number and converts it to a string formatted based on your store currency format, which is selected from the General Preferences screen. {{ 1.45 | money_without_currency }} By default, using AUD as the currency, this would be formatted as $1.45
pluralize(input, singular, plural)	This filter accepts a number, and two words - one for singular, one for plural and returns the singular word if the input equals 1, otherwise it returns the plural. You have {{ cart.item_count }} {{ cart.item_count | pluralize: 'item', 'items' }} in your shopping cart.
product_img_url(url, style = 'small')	This filter takes a url of a product's image filename and returns its full path. It takes an optional second parameter to set its size and returns the URL of the small sized version of the image by default. Available Sizes pico (16x16) icon (32x32) thumb (50x50) small (100x100) medium (240x240) large (480x480) original - No resizing, but maximum size is 800x600. custom1 - Custom size configured by the Theme Editor custom2 - Custom size configured by the Theme Editor custom3 - Custom size configured by the Theme Editor These are the maximum images sizes, and all images are resized to maintain the original aspect ratio, so rectangular images will have one dimension that is less than the maximum size for that image size. <a href="{{product.url}}"><img src="{{ product.featured_image | product_img_url: 'thumb' }}" /></a>
script_tag(url)	This filter takes a URL with a .js file and puts a script tag around it. Use this filter in the page header for all your javascript files. {{ 'shop.js' | asset_url | script_tag }}
size(input)	Return the size of an array or of a string. {{ variant.title | size }}
sort(array)	Sorts the elements in an array. {{ names | sort | join: ',' ) }}
strip_html(input)	Strip out any html tags. This is a simple filter which removes any characters in the form of an HTML tag, such as "<...>". This can be useful in combination with truncate, to generate fragment summaries of formatted text. {{ 'my long<br>string' | strip_html }}
strip_newlines(input)	Remove all new lines from the string.
stylesheet_tag(url, media="all")	This filter takes a URL with a .css file and puts a link tag around it. Use this filter in the page header for all your stylesheet files. {{ 'shop.css' | asset_url | stylesheet_tag }}
truncate(input, length = 50, truncate_string = "...")	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(input, words = 15, truncate_string = "...")	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. {{ 'my long string' | truncatewords: 2, '...' }}
unescape(input)	Unescape a string so that all special characters are converted from their % form into their original characters.. {{ encoded_string | unescape }}
upcase(input)	Convert a string to upper case. {{ variant.title | upcase }}
url_encode(input)	** TODO ** This appears to be the same function as escape.
url_for_type(type_title)	This filter creates a valid URL for a type name.
url_for_vendor(vendor_title)	This filter creates a valid URL for a vendor name.
weight(grams)	This filter takes a weight in grams and converts it into the appropriate unit system ( metric, imperial ) for the shop. The unit of weight is not displayed. All weights are stored internally in grams so you should always use this filter when displaying weights to clients. {{ product.weight | weight }}
weight_with_unit(grams)	This filter takes a weight in grams and converts it into the appropriate unit system ( metric, imperial ) for the shop. All weights are stored internally in grams so you should always use this filter when displaying weights to clients. {{ product.weight | weight_with_unit }}
within(product_url, collection)	This filter is used to indicate that the filtered URL of a passed in object belongs to a specified collection. {{product.url | within: collection }} There is further discussion on this filter in Liquid Collection Navigation .

Tags

Tags are for the logic in your template.

Comments

A comment is the simplest of tags. It just swallows content.

Hi fred {% comment %} you stink {% endcomment %}

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 }}-{{ i }}-color{% endcapture %}

  <label for="{{ attribute_name }}">Colour:</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>

If / Else

The conditional expressions formed with If/Else should be a familiar construction from most programming languages. Liquid allows you to write simple expressions in the if. Compound expressions may be formed by the use of or and and expressions.

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

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

{% if user.name != 'fred' %}
  you aren't fred
{% endif %}

{% if user.name == 'fred' or if user.name == 'dirk' %}
  hi dirk or fred
{% endif %}

{% if user.name == 'fred' and if user.last_name == 'bloggs' %}
  hi fred bloggs
{% endif %}

{% if user.creditcard == null %}
   user has no credit
{% 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 cycle through an number of alternative values. Liquid has built-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. This allows you to loop over things like line-items in an order.

  {% for item in order.line-items %}
    {{ item.description }}
  {% endfor %}

The order of the loop may be reversed by adding the flag reversed.

  {% for item in order.line-items reversed %}
    {{ item.description }}
  {% endfor %}

During every For loop, the following helper variables are available for additional control over the results.

 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 also create table rows and cells for you, although you still need to wrap a table tag around the tablerow tag.

  <table>
    {% tablerow item in items cols: 3 limit: 12 %}
      {{ item.variable }}
    {% endtablerow %}
  </table>

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 %}