Introduction

Liquid - Render Engine

Liquid is an open-source template language created by Shopify and written in Ruby. It is the backbone of Shopify themes and is used to load dynamic content on storefronts.

Read about the basics of Liquid, or check out reference material on objects, tags, and filters.

Release History

• 1.0.0   Initial Release

created by Michael Lopez

published by EasyCode-IT AG

Liquid

Liquid is used by the following products:

• EasyNews
• EasyShop
• EasyWeb

Liquid basics

Liquid uses a combination of tags, objects, and filters to load dynamic content. They are used inside template files, which are a group of files that make up a theme.

In this article

• Tags
• Objects
• Filters
• Object handles
• Operators
  • Basic operators
  • contains
  • Order of operations
• Types
  • String
  • Number
  • Boolean
  • Nil
  • Array
  • EmptyDrop
• Truthy and falsy
  • Truthy
  • Falsy

Tags

Tags make up the programming logic that tells templates what to do. Read more >

{% if user.name == 'elvis' %}
  Hey Elvis
{% endif %}

Objects

Objects contain attributes that are used to display dynamic content on a page. Read more >

{{ product.title }} <!-- Output: Awesome T-Shirt-->

Filters

Filters are used to modify the output of strings, numbers, variables, and objects. Read more >

{{ 'sales' | append: '.jpg' }} <!-- Output: sales.jpg -->

Object handles

Handles are used to access the attributes of Liquid objects. By default, a handle is the object’s title in lowercase with any spaces and special characters replaced by hyphens (-). Some objects in EasyShop (collections, navigations) have handles.

For example, a navigation with the title “Main” can be accessed in Liquid via its handle main as shown below:

<!-- the content of the About Us page -->
{{ navigations.main.links }}

Operators

Liquid uses a combination of tags, objects, and filters to load dynamic content. They are used inside template files, which are a group of files that make up a theme.

In this article

• Logical and comparison operators
• Basic operators
• contains
• Order of operations

Logical and comparison operators

Liquid has access to many logical and comparison operators. You can use operators to create logic with control flow tags.

Basic operators

Examples

{% if customer.has_account == true %}
  Welcome back to our store!
{% endif %}

You can do multiple comparisons in a tag using the and and or operators:

{% if product.type == "Shirt" or product.type == "Shoes" %}
  This is a shirt or a shoe.
{% endif %}

contains

contains checks for the presence of a substring in a string.

{% if customer.email contains "easycode-it.com" %}
  Hey there, EasyCode employee!
{% endif %}

contains can also check for the presence of a string in an array of strings.

{% if product.tags contains "outdoor" %}
  This product is great for using outdoors!
{% endif %}

contains can only search strings. You cannot use it to check for an object in an array of objects.

Order of operations

In tags with more than one and or or operator, all and operators are evaluated first, and then or operators are evaluated. You cannot change the order of operations using parentheses ‘(’ and ‘)’. Parentheses are invalid characters in Liquid tags and will prevent your tags from working.

Types

Liquid objects can be one of six types. You can initialize Liquid variables using assign or capture tags.

In this article

• String
• Number
• Boolean
• Nil
• Array
  • Accessing items in arrays
  • Accessing specific items in arrays
  • Initializing arrays
• EmptyDrop
  • Checking for emptiness

String

Strings are declared by wrapping a variable’s value in single or double quotes.

{% assign my_string = "Hello EasyCode-IT AG!" %}

Number

Numbers include floats and integers.

{% assign my_int = 25 %}
{% assign my_float = 39.756 %}

Boolean

Booleans are either true or false. No quotations are necessary when declaring a boolean.

{% assign foo = true %}
{% assign bar = false %}

Nil

Nil is a special empty value that is returned when Liquid code has no results. It is not a string with the characters “nil”.

Nil is treated as false in the conditions of if blocks and other Liquid tags that check the truthfulness of a statement.

In the following example, if a tracking number does not exist (that is, fulfillment.tracking_numbers returns ``nil`), Liquid will not print the text:

{% if fulfillment.tracking_numbers %}
  There is a tracking number.
{% endif %}

Tags or outputs that return nil will not print anything to the page.

Tracking number: {{ fulfillment.tracking_numbers }}

Output:

Tracking numbre:

Array

Arrays hold lists of variables of any type.

Accessing items in arrays

To access all of the items in an array, you can loop through each item in the array using a for or tablerow tag.

{% for tag in product.tags %}
  {{ tag }}
{% endfor %}

Output:

sale summer spring wholesale

Accessing specific items in arrays

You can use square bracket [ ] notation to access a specific item in an array. Array indexing starts at zero.

<!-- if product.tags = "sale", "summer", "spring", "wholesale" -->
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[2] }}

Output:

sale
summer
spring

Initializing arrays

You cannot initialize arrays using only Liquid.

You can, however, use the split filter to break a single string into an array of substrings.

EmptyDrop

An EmptyDrop object is returned if you try to access a deleted object (such as a navigation or collection) by its handle. In the example below, collection_1, collection_2 and collection_3 are all EmptyDrop objects.

{% assign variable = "hello" %}
{% assign page_1 = pages[variable] %}
{% assign page_2 = pages["does-not-exist"] %}
{% assign page_3 = pages.this-handle-does-not-exist %}

EmptyDrop objects only have one attribute, empty?, which is always true.

Collections and pages that do exist do not have an empty? attribute. Their empty? is “falsy”, which means that calling it inside an if statement will return false. When using an unless statement on existing collections and pages, empty? will return true.

Checking for emptiness

You can check to see if an object exists or not before you access any of its attributes.

{% unless pages == empty %}
  <!-- This will only print if the page with handle "about" is not empty -->
  <h1>{{ pages.frontpage.title }}</h1>
  <div>{{ pages.frontpage.content }}</div>
{% endunless %}

If you don’t check for emptiness first, Liquid might print empty HTML elements:

<h1></h1>
<div></div>

You can check for emptiness with collections as well:

{% unless collections.frontpage == empty %}
  {% for product in collections.frontpage.products %}
    {% include "product-grid-item" %}
  {% else %}
    <p>We have a "frontpage" collection, but it's empty.</p>
  {% endfor %}
{% endunless %}

Truthiness and falsiness in Liquid

When a non-boolean data type is used in a boolean context (such as a conditional tag), Liquid decides whether to evaluate it as true or false. Data types that return true by default are called truthy. Data types that return false by default are called falsy.

In this article

• Truthy
• Falsy

Truthy

All values in Liquid are truthy except nil and false.

In the example below, the text “Tobi” is not a boolean, but it is truthy in a conditional:

{% assign name = "Tobi" %}

{% if name == true %}
  This text will always appear if "name" is defined.
{% endif %}

Empty strings are truthy. The example below will create empty HTML tags if current_page.title exists but is empty:

{% if current_page.title %}
  <h1>{{ current_page.title }}</h1>
{% endif %}

Output

<h1></h1>

To avoid this, you can check to see if the string is blank, as follows:

{% unless current_page.title == blank %}
    <h1>{{ current_page.title }}</h1>
{% endunless %}

An EmptyDrop is also truthy. In the example below, if settings.page is an empty string or set to a hidden or deleted object, you will end up with an EmptyDrop. The result is an undesirable empty <div>.

Input

{% if pages[settings.page] %}
<div>{{ pages[settings.page].content }}</div>
{% endif %}

Output

<div></div>

Falsy

The only values that are falsy in Liquid are nil and false.

nil is returned when a Liquid object doesn’t have anything to return. For example, if a collection doesn’t have a collection image, collection.image will be set to ``nil`. Since that is “falsy”, you can do this:

{% if collection.image %}
<!-- output collection image -->
{% endif %}

The value false is returned through many Liquid object properties such as product.available.

Whitespace control

In Liquid, you can include a hyphen in your tag syntax {{-, -}}, {%-, and -%} to strip whitespace from the left or right side of a rendered tag.

Normally, even if it doesn’t output text, any line of Liquid in your template will still output an empty line in your rendered HTML:

Tags

To be defined

Objects

To be defined

Filters

To be defined