SovLabs Template Engine

Outputs

Renders the content of an object and is denoted by double curly braces: {{ and }}

Example
  • Input

    Hello {{ user.name }}!
  • Output

    Hello John Smith!
SovLabs Template Engine is rendering the content of the object user.name which contains John Smith

Tags

Creates the logic and control flow for templates and does not produce any visible text. Assign variables and create conditions and loops without showing any of the logic on the page

Denoted by curly braces and percent signs: {% and %}

Example
  • Input

    {% if user %}
                          Hello {{ user.name }}
                        {% endif %}
  • Output

    Hello John Smith!

assign

Assigns some value to a variable

Example
  • Input

    {% assign foo = "Hello world" %}
                          {{ foo }}
  • Output

    Hello world

capture

Block tag that captures text into a variable

Example
  • Input

    {% capture foo %}
                            Hello world
                          {% endcapture %}
    
                          {{ foo }}
  • Output

    Hello world

case/when

Creates a switch statement to compare a variable with different values. case initializes the switch statement, and when compares its values.

Example
  • Input

    {% assign foo = 'banana' %}
                          {% case foo %}
                            {% when 'apple' %}
                              Susy had an apple
                            {% when 'banana' %}
                              Susy had a banana
                            {% else %}
                              Susy did not have an apple or a banana
                          {% endcase %}
  • Output

    Susy had a banana

comment

Any content that you put between {% comment %} and {% endcomment %} tags is turned into a comment.

Example
  • Input

    We made 1 million dollars {% comment %} in losses {% endcomment %} this year
  • Output

    We made 1 million dollars this year

cycle

Loops through a group of strings and outputs them in the order that they were passed as parameters. Each time cycle is called, the next string that was passed as a parameter is output.

cycle must be used within a for loop block

Example
  • Input

    {% cycle 'one', 'two', 'three' %}
    {% cycle 'one', 'two', 'three' %}
    {% cycle 'one', 'two', 'three' %}
    {% cycle 'one', 'two', 'three' %}
  • Output

    one
    two
    three
    one

If no name is supplied for the cycle group, then it's assumed that multiple calls with the same parameters are one group.

To have total control over cycle groups, optionally specify the name of the group. This can even be a variable.

Example
  • Input

    {% cycle 'group 1': 'one', 'two', 'three' %}
    {% cycle 'group 1': 'one', 'two', 'three' %}
    {% cycle 'group 2': 'one', 'two', 'three' %}
    {% cycle 'group 2': 'one', 'two', 'three' %}
  • Output

    one
    two
    one
    two

if/else

Executes a block of code only if a certain condition is true. elsif and else adds more conditions within an if block.

Example
  • Input

    {% if user %}
                            Hello {{ user.name }}
                          {% endif %}
                          
    {% if user.name == 'John Smith' %}
                            Hello John Smith
                          {% elsif user.name == 'Jane Smith' %}
                            Hello Jane Smith
                          {% endif %}
    {% if user.name == 'John Smith' %}
                            Hello John Smith
                          {% else %}
                            Hello Jane Smith
                          {% endif %}

unless/endunless

The opposite of if and executes a block of code only if a certain condition is not met.

Example
  • Input

    {% unless user.name == 'John Smith' %}
                            Hello Jane Smith
                          {% endunless %}
                          

include

Includes another template; useful for partials

for

Loop over collections. for loops can iterate over arrays, hashes, and ranges of integers.

Example
  • Input

    {% assign foo_array = [ "apple", "banana" ] %}
                          {% for item in foo_array %}
                            {{ item }}
                          {% endfor %}
  • Output

    apple
                          banana

Iterating a hash

Example
  • Input

    {% for item in hash %}
                              {{ item[0] }}: {{ item[1] }}
                            {% endfor %}
  • Output

    key: value

When iterating a hash, item[0] contains the key, and item[1] contains the value

Helper variables

The following helper variables are 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?

Optional arguments

There are several optional arguments to the for tag that can influence which items are received in the loop and what order they appear in:

  • limit:# restrict how many items received
  • offset:# start the collection with the n item
  • reversed iterates over the collection from last to first
limit and offset Example
  • Input

    foo_array = [ 1, 2, 3, 4, 5, 6 ]
                            {% for item in foo_array limit:2 offset:2 %}
                              {{ item }}
                            {% endfor %}
                            
  • Output

    3
                            4
reversed Example
  • Input

    foo_array = [ 1, 2, 3 ]
                            {% for item in foo_array reversed %}
                              {{ item }}
                            {% endfor %}
                            
  • Output

    3
                            2
                            1

A for loop can take an optional range clause to define a range of numbers to loop through - can be defined by both literal and variable numbers

for loop range Example
  • Input

    item.quantity = 4
                            {% for i in (1..item.quantity) %}
                               {{ i }}
                            {% endfor %}
  • Output

    1
                            2
                            3
                            4

A for loop can take an optional else clause to display a block of text when there are no items in the collection

for loop else Example
  • Input

    foo_array = [ ]
                            {% for item in foo_array %}
                              {{ item.title }}
                            {% else %}
                              There are no items!
                            {% endfor %}
  • Output

    There are no items!

break

Exits a for loop

Example
  • Input

    {% assign foo_array = [ 1, 2, 3, 4, 5 ] %}
    
                            {% for item in foo_array %}
                              {% if item == 4 %}
                                {% break %}
                              {% else %}
                                {{ item }}
                              {% endif %}
                            {% endfor %}
  • Output

    1
                            2
                            3

continue

Skips the remaining code in the current for loop and continues with the next loop

Example
  • Input

    {% assign foo_array = [ 1, 2, 3, 4, 5 ] %}
    
                            {% for item in foo_array %}
                              {% if item == 4 %}
                                {% continue %}
                              {% else %}
                                {{ item }}
                              {% endif %}
                            {% endfor %}
  • Output

    1
                            2
                            3
                            5

raw

Temporarily disables tag processing and is useful for generating content (e.g Mustache, Handlebars) which uses conflicting syntax.

Example
  • Input

    {% raw %}
                            In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not.
                          {% endraw %}

Filters

Changes the output of a templated Output.

Used within an output and are separated by a pipe character: |

Optionally, a colon (:) and 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: "!" }}
  • Output

    Hello John Smith!

append

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

Example
  • Input

    {% assign foo = " world" %}
                          {{ "Hello" | append: foo }}
  • 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
SyntaxReturn
%aAbbreviated weekday

(e.g Mon, Tue, Wed ... Sun)

%AFull weekday name

(e.g Monday, Tuesday, Wednesday ... Sunday)

%bAbbreviated month

(e.g Jan, Feb, Mar ... Dec)

%BFull month name

(e.g January, February, March ... December)

%cPreferred local data and time representation
%dDay of month, zero padded

(e.g 01, 02, 03... 12)

%-d or %eDay of month, not zero padded

(e.g 1, 2, 3... 12)

%DFormats the date: dd/mm/yy
%FFormats the date in ISO 8691 format: yyyy-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 year: 01-12
%MMinute of the hour: 00-59
%pMeridian indicator: AM 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 date: mm/dd/yy
%yYear without the century: 00-99
%YYear with the century:

(e.g 2017)

%ZTimezone name

default

Specify a default value in case a value does not exist

Example
  • Input

    var foo = ""
                          {{ 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

    {{ "John Smith" | downcase }}
  • Output

    john smith

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
  • Input

    foo_array = [ "apple", "banana" ]
    
                          {{ foo_array.first }}
  • Output

    apple

json_string

Stringify a JSON object

Example
  • Input

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

    "{\"key1\":{\"val1\":\"text 1\",\"val2\":\"text 2\"},\"key2\":[\"arr1\",\"arr2\"]}"

join

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

Example
  • Input

    foo_array = [ "apple", "banana" ]
    
                          {{ foo_array | join: " and " }}
  • Output

    apple and banana

last

Returns the last item of an array

Example
  • Input

    foo_array = [ "apple", "banana" ]
    
                          {{ foo_array.last }}
  • Output

    banana

map

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

Example
  • Input

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

    apple
                          banana

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

newline_to_br

Replaces every newline (\n) with an HTML line break (</br>).

Example
  • Input

                            {% capture foo %}
                              Hello
                              world
                            {% endcapture %}
    
                            {{ foo | newline_to_br }}
                          
  • Output

    </br>Hello</br>world</br>

pluralize

If the output is greater or equal to 1, return the first input, otherwise return the second input

Example
  • Input

    {{ 3 | pluralize: "child", "children" }}
                            {{ 1 | pluralize: "child", "children" }}
                          
  • Output

    children
                            child
                          

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

Example
  • Input

                            {{ "sea shells by the sea shore" | replace_first: "sea", "see" }}
                          
  • Output

                            see shells by the sea shore
                          

reverse

Reverses the order of the items in an array. Cannot reverse a string

Example
  • Input

                            foo_array = [ "apple", "banana", "orange" ]
    
                            {{ foo_array | reverse }}
                          
  • Output

                            [ "orange", "banana", "apple" ]
                          

round

Rounds an input number to the nearest integer or, if a number is specified as an argument, to that number of decimal places

Example
  • Input

    {{ 1.5 | round }}
    {{ 1.567 | round: 2 }}
  • Output

    2
    1.57

size

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

Example
  • Input

    {{ "Hello" | size }}
    foo_array = ["apple", "banana" ]
                          {{ foo_array | size }}
  • Output

    5
    2

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
  • Input

                            foo_array = [ "banana", "apple", "orange" ]
    
                            {{ 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

Removes all whitespace (tabs, spaces, and newlines) from both the left and right side of a string. It does not affect spaces between words

Example
  • Input

                            {{ "   Hello world    " | strip }}
                          
  • Output

                            Hello world
                          

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
  • Input

                            {% capture foo %}
                                Hello
                                world
                              {% endcapture %}
    
                              {{ 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
                          

truncatewords

Shortens a string down to the number of words passed as the argument. If the specified number of words is less than the number of words in the string, an ellipsis (…) is appended to the string.

Example
  • Input

                            {{ "Hello world" | truncatewords: 1 }}
                          
  • 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