Basics

The following are basic concepts that you need to effectively interact with Liquid tags, filters, and objects.

Object handles

Objects that represent store resources, such as events, people, articles, and blogs, have handles for identifying an individual resource. The handle is used to build the URL for the resource, or to return properties for the resource.

Other objects like navigation, and settings also have handles.

Code

{{ event.title | handle }}

Data

{
    "event": {
        "title": "Hamlet",
        "slug": "hamlet"
    }
}

Output

hamlet

Creating and modifying handles

Handles are automatically generated based on the resource title. They follow a set of rules:

• Handles are always lowercase
• Whitespace and special characters are replaced with a hyphen -.
• If there are multiple consecutive whitespace or special characters, then they’re replaced with a single hyphen.
• Whitespace or special characters at the beginning are removed.

Handles need to be unique, so if a duplicate title is used, then the handle is auto-incremented by one. For example, if you had two events called Hamlet, then their handles would be hamlet and hamlet-1.

After a resource has been created, changing the resource title doesn’t update the handle.

Note

You can modify a resource’s handle within the Basker Studio. This can be done either using the Slug field. If you reference resources by their handle, then be sure to update those references when modifying handles.

Referencing handles

All objects that have a handle have a handle property. For example, you can output a event’s handle with event.handle. You can reference an object, from within its parent object, by its handle in two ways:

• Square bracket notation [ ]: Accepts a handle wrapped in quotes ', a Liquid variable, or an object reference. Dot notation .: Accepts a handle without quotes.

Note

Referencing an object by its handle is similar to referencing array elements by their index.

Code

'About us' page URL: {{ pages['about-us'].url }}
Enable event suggestions: {{ settings.predictive_search_enabled }}

Data

{
    "settings": {
        "predictive_search_enabled": true
    }
}

Output

'About us' page URL: /about-us
Enable product suggestions: true

Operators

Logical and comparison operators

Liquid supports basic logical and comparison operators for use with conditional tags.

Operator	Function
==	equals
!=	does not equal
>	greater than
<	less than
>=	greater than or equal to
<=	less than or equal to
or	Condition A or Condition B
and	Condition A and Condition B
contains	Checks for strings in strings or arrrays

contains

You can use contains to check for the presence of a string within an array, or another string. You can’t use contains to check for an object in an array of objects.

Code

{% if event.tags contains 'theatre' %}
    This event is tagged with theatre.
{% endif %}

Data

{
    "event": {
        "tags": [
            "theatre"
        ]
    }
}

Output

This event is tagged with theatre.

Order of operations

When using more than one operator in a tag, the operators are evaluated from right to left, and you can’t change this order.

Caution

Parentheses () aren’t valid characters within Liquid tags. If you try to include them to group operators, then your tag won’t be rendered.

Code

{% unless true and false and false or true %}
    This evaluates to false, since Liquid checks tags like this:

    true and (false and (false or true))
    true and (false and true)
    true and false
    false
{% endunless %}

Output

This evaluates to false, since Liquid checks tags like this:

    true and (false and (false or true))
    true and (false and true)
    true and false
    false

Types

Liquid output can be one of six data types.

string

Any series of characters, wrapped in single or double quotes.

number

boolean

nil

An undefined value.

Tags or outputs that return nil don’t print anything to the page. They are also treated as false.

array

A list of variables of any type.

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

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

You can’t initialize arrays using only Liquid. You can, however, use the split filter to break a single string into an array of substrings.

empty

An empty object is returned if you try to access an object that is defined, but has no value. For example a page or event that’s been deleted, or a setting with no value.

You can compare an object with empty to check whether an object exists before you access any of its attributes.

TODO

Truthy and falsy

All data types must return either true or false. Those which return true by default are called truthy. Those that return false by default are called falsy.

Example

Because nil and false are the only falsy values, you need to be careful how you check values in Liquid. A value might not be in the format you expect, but still be truthy.

For example, empty strings are truthy, so you need to check whether they’re empty with blank. EmptyDrop objects are also truthy, so you need to check whether the object you’re referencing is empty.

TODO

Whitespace control

Even if it doesn’t output text, any line of Liquid outputs a line in your rendered content. By including hyphens in your Liquid tag, you can strip any whitespace that your Liquid generates when rendered.

If you want to remove whitespace on only one side of the Liquid tag, then you can include the hyphen on either the opening or closing tag.

TODO