Liquid Filter Reference

From Spiffy Stores Knowledge Base

Revision as of 08:36, 16 January 2016 by Admin (talk | contribs)

Introduction

Array Filters

first(array) Get the first element of an array.
{{ product.images | first | img_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 | img_tag }}
map(input, property) Select the elements of an array of hashes or drops using the specified property.
{{ names | map: 'last_name' }}
reverse(input) Reverse the order of the elements in an array of objects.
{{ collections.all.all_products | map: 'title' | reverse | join: ',' }}
size(input) Return the size of an array or of a string.
{{ variant.title | size }}
sort(input, property = nil) Sorts the elements in an array. An optional property can be specified to be used to sort an array of hashes or drops.
{{ names | sort | join: ',' ) }}

HTML Filters

img_tag(url, alt='', width:, height:) 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.jpg' | img_tag }}
{{ 'image.jpg' | file_asset_url | img_tag: 'Alternate Text' }}

This filter also takes additional optional keyword parameters to allow you to specify the width and height of the image. If you want to use these keyword parameters, then you must specify the alt parameter.

{{ 'image.jpg' | img_tag: '', width: 100, height: 150 }}
{{ 'image.jpg' | img_tag: 'Alt text', height: 100 }}
script_tag(url, defer = false) 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. An option defer option may be specified which specifies that deferred loading is required for the script.
{{ 'shop.js' | asset_url | script_tag }}
{{ 'jquery.js' | global_asset_url | script_tag: true }}
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 }}

Mathematics Filters

ceil(input) Round a number up to the next highest integer.
{{ total | divided_by: 100 | ceil }}
divided_by(input, operand) Perform a division operation.
{{ 12 | divided_by: 3 }} => '4'
{{ 14 | divided_by: 3 }} => '4'
{{ 15 | divided_by: 3 }} => '5'
floor(input) Round a number down to the next lowest integer.
{{ total | divided_by: 100 | floor }}
minus(input, operand) Perform minus operation.
{{ 5 | minus: 1 }} => '4'
modulo(input, operand) Perform modulo operation.
{{ 5 | modulo: 2 }} => '1'
plus(input, operand) Perform plus operation.
{{ 1 | plus: 1 }} => '2'
{{ '1' | plus:'1' }} => '11'
round(input, precision = 0) Round a number up or down to the nearest value with the specified precision. By default, the precision is 0, meaning that the number will be rounded to an integer.
You saved {{ discount | divided_by: total | times: 100 | round }}% today
times(input, operand) Perform times operation.
{{ 3 | times: 4 }} => '12'
{{ 'foo' | times: 4 }} => 'foofoofoofoo'

Money Filters

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 returns it formatted to 2 decimal places.
{{ 1.45 | money_without_currency }}

In this example, this will be formatted as

1.45

String Filters

size(input) Return the size of an array or of a string.
{{ variant.title | size }}

URL Filters

Colour Filters

adjust_brightness(colour, percent) Returns a new colour with the brightness adjusted by the specified percentage. Negative percentages will darken the colour; positive percentages will brighten the colour.
{{ settings.btn_colour | adjust_brightness: -20 }}
adjust_hue(colour, percent) Returns a new colour with the hue adjusted by the specified percentage. Negative percentages will reduce the hue; positive percentages will increase the hue.
{{ settings.btn_colour | adjust_hue: 15 }}
adjust_saturation(colour, percent) Returns a new colour with the saturation adjusted by the specified percentage. Negative percentages will reduce the saturation; positive percentages will increase the saturation.
{{ settings.btn_colour | adjust_saturation: -35 }}
brightness(input) Returns a number between 0 and 100 which represents the brightness level of a colour string. Black is 0 and white is 100.
{% assign background_colour_brightness = settings.background_colour | brightness %}
{% if background_colour_brightness > 50 %}Way too bright!{% endif %}
darken_by(colour, percent) Mix the RGB hue of the colour with Black so that the RGB hue is the specified percentage of the resulting colour.
{{ settings.btn_colour | darken_by: 20 }}
lighten_by(colour, percent) Mix the RGB hue of the colour with White so that the RGB hue is the specified percentage of the resulting colour.
{{ settings.btn_colour | lighten_by: 20 }}

Additional Filters

append(input, string) Add a string to the beginning of another string.
{{ 'This is first' | append: ' and this is last' }}
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 }}
collection_img_url(url, style = 'small') This filter takes a url of a collection'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)
  • compact (160x160)
  • medium (240x240)
  • large (480x480)
  • grande (800x600)
  • 1024x1024 (1024x1024)
  • 2048x2048 (2048x2048)
  • original - No resizing, but image is resized so that it doesn't exceed 2048x2048.
  • 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.

If an uploaded image is smaller than a standard size, its size is maintained and it is not upscaled.

<a href="{{collection.url}}">
  <img src="{{ collection.image | collection_img_url: 'thumb' }}" />
</a>
customer_account_link(link) Take the link text provided and return a link to the customer account page.
{{ 'My Account' | customer_account_link }}
customer_login_link(link) Take the link text provided and return a link to the customer login page.
{{ 'Log in' | customer_login_link }}
customer_logout_link(link) Take the link text provided and return a link to the customer logout page.
{{ 'Log out' | customer_logout_link }}
customer_register_link(link) Take the link text provided and return a link to the customer registration page.
{{ 'Create an account' | customer_register_link }}
customer_reset_password_link(link) Take the link text provided and return a link to the customer reset password page.
{{ 'Reset Password' | customer_reset_password_link }}
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 - Number of seconds since 1970-01-01 00:00:00 UTC
%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(input, default_value = '') Return a default value if the input is blank or empty.
{{ input_value | default: 'Default value set' }}
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>
default_errors(errors) This filter takes one or more errors and wraps them in HTML returning a div containing an unordered list of errors.
{{ form.errors | default_errors }}

returns

<div class="errors">
  <ul>
    <li>Error line 1</li>
    <li>Error line 2</li>
    ...
  </ul>
</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".

{{ 'Usage: foo "bar" <baz>' | escape }}

=> "Usage: foo &quot;bar&quot; &lt;baz&gt;"
escape_once(input) Escape a string so that all special characters are properly escaped without affecting any existing escaped entities.
escape_javascript(input) Escape a string so that carriage returns and single and double quotes are escaped for use in Javascript segments..
<a href="..." ... onmouseover="Tip('{{ item.title | escape_javascript }}')" ...>
file_asset_url(input) Returns the URL for an uploaded file asset.
{{ 'catalog.pdf' | file_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/files/catalog.pdf"
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 }}
handle/handleize(string) This filter converts a string into a 'handle', which is a lowercase string of words separated by a dash symbol. The handle is typically used in URLs.
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 %}
link_to(link, url, title='', target:) 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', 'The best shopping cart on the planet' }}

This filter also takes an additional optional keyword parameter to allow you to specify the target of a link. If you want to use this keyword parameter, then you must specify both the url and title parameters.

{{ 'External Site' | link_to: 'http://www.spiffystores.com', 'Link to external site', target: '_blank' }}
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, text='') 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.

A type may also be passed to this filter instead of a string.

The text of the link may be optionally specified, and if so, it overrides the default value.
{{ product.type | link_to_type: 'Click this link' }}
link_to_vendor(vendor, text='') 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.

A vendor may also be passed to this filter instead of a string.

The text of the link may be optionally specified, and if so, it overrides the default value.
{{ product.vendor | link_to_vendor: 'Click this link' }}
lstrip(input) Strip out any tabs, spaces and newlines from the left side of a string.
{{ '    lots of spaces' | lstrip }}
newline_to_br(input) Add <br /> tags to the beginning of all lines in the input string.
{{ output_lines | newline_to_br }}
payment_type_img_url(type) This filter returns the URL for the payment type's SVG image. It is normally used in conjunction with the shop.enabled_payment_types variable.
{% for type in shop.enabled_payment_types %}
  <img src="{{ type | payment_type_img_url }}" width="80" />
{% endfor %}
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.
prepend(input, string) Add a string to the end of another string.
{{ ' and this is last' | prepend: 'This is first' }}
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)
  • compact (160x160)
  • medium (240x240)
  • large (480x480)
  • grande (800x600)
  • 1024x1024 (1024x1024)
  • 2048x2048 (2048x2048)
  • original - No resizing, but image is resized so that it doesn't exceed 2048x2048.
  • 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.

If an uploaded image is smaller than a standard size, its size is maintained and it is not upscaled.

<a href="{{product.url}}">
  <img src="{{ product.featured_image | product_img_url: 'thumb' }}" />
</a>
remove(input, string) Remove all occurrences of a string.
{{ 'This is a test' | remove: 'is a' }}
remove_first(input, string) Remove the first occurrence of a string.
{{ 'This is a test' | remove_first: 'is' }}
repeat(input, times) Return the input string repeated the requested number of times.
{{ 'Ho! ' | repeat: 3 }}
replace(input, string, replacement = '') Replace all occurrences of a string with another.
{{ 'This is a test' | replace: 'a', 'my' }}
replace_first(input, string, replacement = '') Replace the first occurrence of a string with another.
{{ 'This is a test' | replace_first: 'is', 'at' }}
rstrip(input) Strip out any tabs, spaces and newlines from the right side of a string.
{{ 'lots of spaces    ' | rstrip }}
size_words(input) Return the number of words in a string.
{{ article.content | size_words }}
split(input, delimiter=$;) Split a string into substrings based on a delimiter, returning an array of those substrings. The delimiter can be a string or a regular expression. If the delimiter is omitted, the delimiter defaults to splitting the string using whitespace as the delimiter.
{{ 'mellow yellow' | split: 'ello' }}
strip(input) Strip out any tabs, spaces and newlines from both the left and right sides of string.
{{ '    lots of spaces    ' | strip }}
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.
substring(input, start, length=nil) Return a substring from a string, starting at start for length characters. The start index is a zero-based index. If length is not specified, then all the remaining characters up to the end of the string are returned.
{{ product.title | substring: 0, 3 | upcase }}
system_images_url(input) Returns the URL for a system image file.
{{ 'spiffy-stores-logo.gif' | system_images_url }}

The above example returns the path plus filename of the specified file that resides in the images directory on the system server. In this case it could be something like:

"http://server1.spiffystores.com/images/spiffy-stores-logo.gif"

You will most probably use this URL with another filter to create an image tag.

{{ 'spiffy-stores-logo.gif' | system_images_url | img_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) Encode a string so that it can be used in a URL.
{{ "Programming Ruby:  The Pragmatic Programmer's Guide" | url_encode }}

=> "Programming%20Ruby%3A%20%20The%20Pragmatic%20Programmer%27s%20Guide"
url_for_type(type) This filter creates a valid URL for a type name.

A type may also be passed to this filter instead of a string.
url_for_vendor(vendor) This filter creates a valid URL for a vendor name.

A vendor may also be passed to this filter instead of a string.
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 .

Further Reference