SovLabs Template Engine

Filters

Changes the output of a templated Output.

Used within an output and are separated by a pipe character: | or optionally, a colon :.

A comma-separated list of additional parameters can be used on the filter. Each additional parameter must be a valid expression, and each filter pre-defines the parameters it accepts and the order in which they must be passed.

Filters can also be chained together by adding additional filter statements (starting with another pipe character). The output of the previous filter will be the input for the next one.

Example
  • Input
    Hello {{ user.name | append: '!' | downcase }}
  • Output
    hello john smith!

append

Concatenates two strings and returns the concatenated value. Can be used with variables

Example
  • Input
    {{ 'Hello' | append: ' world' }}
  • Output
    Hello world

capitalize

Makes the first character of a string capitalized

Example
  • Input
    {{ 'hello world' | capitalize }}
  • Output
    Hello world

date

Converts a timestamp into another date format. Works on strings if they contain well-formatted dates.

Example
  • Input
    {{ mydate | date: '%Y-%m-%d %H:%M' }}
  • Output
    2017-01-01 08:00

Syntax

SyntaxOutputExample
%aAbbreviated weekdayMon, Tue, Wed ... Sun
%AFull weekday nameMonday, Tuesday, Wednesday ... Sunday
%bAbbreviated monthJan, Feb, Mar ... Dec
%BFull month nameJanuary, February, March ... December
%cPreferred local data and time representation
%dDay of month, zero padded01, 02, 03... 31
%-dDay of month, not zero padded
%eDay of month, not zero padded1, 2, 3... 31
%DFormats the datedd/mm/yy
%FFormats the date in ISO 8691 formatyyyy-mm-dd
%HHour of the day (24 hour)00-23
%IHour of the day (12 hour)1-12
%jDay of the year (Julian)001-366
%kHour of the day (24 hour)1-24
%mMonth of the year01-12
%MMinute of the hour00-59
%pMeridian indicatorAM or PM
%r12 hour time%I:%M:%S %p
%R24 hour time%H:%M
%T12 hour time%H:%M:%S
%UNumber of the week in the year (starting on Sunday)
%WNumber of the week in the year (starting on Monday)
%xFormats the datemm/dd/yy
%yYear without the century00-99
%YYear with the century2018
%ZTimezone name

default

Specify a default value in case a value does not exist

Example
  • {% assign foo = '' %}
  • Input
    {{ foo | default: 'Hello world' }}
  • Output
    Hello world

divided_by

Divides a number by the specified number. The result is rounded down to the nearest integer, if the divisor is an integer

Example
  • Input
    {{ 10 | divided_by: 3 }}
  • Output
    3

downcase

Makes each character in a string lowercase and has no effect on strings which are already all lowercase

Example
  • Input
    {{ 'Hello WORLD' | downcase }}
  • Output
    hello world

escape

Escapes a string by replacing characters with escape sequences (e.g. the escaped string can be used in a URL)

Example
  • Input
    {{ 'Hello & world' | escape }}
  • Output
    Hello & world

escape_once

Escapes a string without changing existing escaped entities

Example
  • Input
    {{ '1 < 2 & 3' | escape_once }}
  • Output
    1 &lt; 2 &amp; 3

first

Returns the first item of an array

Example
  • foo_array = [1, 2, 3, 4, 5, 6]
  • Input
    {{ foo_array.first }}
  • Output
    1

join

Combines the items in an array into a single string using the argument as a separator

Example
  • foo_array = [1, 2, 3, 4, 5, 6]
  • Input
    {{ foo_array | join: ' and ' }}
  • Output
    1 and 2 and 3 and 4 and 5 and 6

json_string

Stringify a JSON object

Example
  • json_obj = { 'key1': { 'val1': 'text 1', 'val2': 'text 2' }, 'key2': ['arr1', 'arr2'] }
  • Input
    {{ json_obj | json_string }}
  • Output
    "{\"key1\":{\"val1\":\"text 1\",\"val2\":\"text 2\"},\"key2\":[\"arr1\",\"arr2\"]}"

last

Returns the last item of an array

Example
  • foo_array = [1, 2, 3, 4, 5, 6]
  • Input
    {{ foo_array.last }}
  • Output
    6

map

Creates an array of values by extracting the values of a named property from another object

Example
  • foo = { 'food': { 'fruit': [ 'apple', 'banana' ] } } {% assign all_fruits = foo.food | map: 'fruit' %}
  • Input
    {% for item in all_fruits %}{{ item }}{% endfor %}
  • Output
    apple, banana

matches

Performs a match (including Regex)

Example
  • user = 'John Smith'
  • Input
    {% if user | matches: '^John Smith$' %}Hello {{ user.name }}!{% endif %}
  • Output
    Hello John Smith!

minus

Subtracts a number from another number

Example
  • Input
    {{ 10 | minus: 3 }}
  • Output
    7

modulo

Returns the remainder of a division operation

Example
  • Input
    {{ 3 | modulo: 2 }}
  • Output
    1

plus

Adds a number to another number

Example
  • Input
    {{ 10 | plus: 2 }}
  • Output
    12

prepend

Adds the specified string to the beginning of another string

Example
  • Input
    {{ 'world' | prepend: 'Hello ' }}
  • Output
    Hello world

remove

Removes every occurrence of the specified substring from a string

Example
  • Input
    {{ 'sea shells by the sea shore' | remove: 'sea' }}
  • Output
    shells by the shore

remove_first

Removes only the first occurrence of the specified substring from a string

Example
  • Input
    {{ 'sea shells by the sea shore' | remove_first: 'sea' }}
  • Output
    shells by the sea shore

replace

Replaces every occurrence of an argument in a string with the second argument

Example
  • Input
    {{ 'sea shells by the sea shore' | replace: 'sea', 'ocean' }}
  • Output
    ocean shells by the ocean shore

replace_first

Replaces only the first occurrence of an argument in a string with the second argument

Example
  • Input
    {{ 'sea shells by the sea shore' | replace_first: 'sea', 'ocean' }}
  • Output
    shells by the ocean shore

required

Requires that the templated value does not return a null or "" and will throw an error. Please note that the error will not specify the field that returned a blank value.

Example
  • Input
    {{ foo | required }}

size

Returns the number of characters in a string or the number of items in an array

Example
  • Input
    {{ 'Hello' | size }}
  • Output
    5

sort

Sorts items in an array by a property of an item in the array. The order of the sorted array is case-sensitive

Example
  • foo_array = [ 'orange', 'apple', 'banana' ]
  • Input
    {{ foo_array | sort }}
  • Output
    [ 'apple', 'banana', 'orange' ]

split

Divides an input string into an array using the argument as a separator and is commonly used to convert comma-separated items from a string to an array.

Example
  • Input
    {{ 'apple, banana' | split: ', ' }}
  • Output
    [ 'apple', 'banana' ]

strip_html

Removes any HTML tags from a string

Example
  • Input
    {{ '<b>Hello world</b>' | strip_html }}
  • Output
    Hello world

strip_newlines

Removes any newline characters (line breaks) from a string

Example
  • {% capture foo %}
    Hello
    world
    {% endcapture %}
  • Input
    {{ foo | strip_newlines }}
  • Output
    Helloworld

substring

Returns a substring of 1 character beginning at the index specified by the argument passed in. An optional second argument specifies the length of the substring to be returned.

String indices are numbered starting from 0.

Example
  • Input
    {{ 'Hello' | substring: '2' }}
    {{ 'Hello' | substring: '2, 3' }}
    {{ 'Hello' | substring: '-3, 2' }}
  • Output
    l
    llo
    ll

times

Multiplies a number by another number

Example
  • Input
    {{ 10 | times: 3 }}
  • Output
    30

truncate

Shortens a string down to the number of characters passed as a parameter. If the number of characters specified is less than the length of the string, an ellipsis (…) is appended to the string and is included in the character count

Example
  • Input
    {{ 'Hello world' | truncate: 5 }}
  • Output
    Hello

upcase

Makes each character in a string uppercase. It has no effect on strings which are already all uppercase

Example
  • Input
    {{ 'Hello world' | upcase }}
  • Output
    HELLO WORLD
References: Shopify Liquid: Wiki