Liquid - Types
String
Declare a string by wrapping a variable’s value in single or double quotes:
{% assign my_string = "Hello World!" %}
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 the user does not exist (that is, user returns nil), Liquid will not print the greeting:
{% if user %}
Hello {{ user.name }}!
{% endif %}
Tags or outputs that return nil will not print anything to the page.
Input
The current user is {{ user.name }}
Output
The current user is
Hash (Object)
Hash represents an object as a key value dictionary, allowing a value to be another Hash. The most used object is context - a built-in global object
Initializing a new object
To initialize an object, the most common way is to either use parse_json filter:
{% assign my_object = '{ "hello": "world" }' | parse_json %}
or parse_json tag tag:
{% parse_json my_object
{ "hello": "world" }
{% end_parsejson %}
Accessing object attributes
To access a value of an object, you can use dot notation or if you would like to use variables instead of hardcoded key, you could use [] notation.
Input
{{ my_object.hello }}
{%- assign var = 'hello' -%}
{{ my_object[val] }}
Output
world
world
Working with an object
You can extend objects with various filters and tags. The most commonly used one is hash_assign tag, which stores a value at the given object path.
Another useful way to extend an object is by merging two objects, which can be accomplished with hash_merge filter
If you need to perform certain operation on object, most likely there is already implemented platformOS filter for that with hash_
prefix.
Array
Arrays hold lists of variables of any type.
Accessing items in arrays
To access all the items in an array, you can loop through each item in the array using an iteration tag.
Input
{% comment %} if site.users = "Tobi", "Laura", "Tetsuro", "Adam" {% endcomment %}
{% for user in site.users %}
{{ user }}
{% endfor %}
Output
Tobi Laura Tetsuro Adam
Accessing specific items in arrays
You can use square bracket [
]
notation to access a specific item in an array. Array indexing starts at zero.
Input
{% comment %} if site.users = "Tobi", "Laura", "Tetsuro", "Adam" {% endcomment %}
{{ site.users[0] }}
{{ site.users[1] }}
{{ site.users[3] }}
Output
Tobi
Laura
Adam
Initializing arrays
You cannot initialize arrays using only Liquid.
You can, however, use the split filter to break a string into an array of substrings.
{% assign arr = '1,2,3,4,5' | split: ',' %}
{{ arr }} => [1, 2, 3, 4, 5]
Searching in arrays
contains
You can check for the presence of a substring in a string, but contains
can also check for the presence of a string in an array of strings. You can use it only for searching strings. You cannot use it to check for an object in an array of objects.
{% comment %} site.users = ["Tobi", "Laura", "Tetsuro", "Adam"] {% endcomment %}
{% if site.users contains 'Tobi' %}
Tobi is in users.
{% endif %}
any
You can check if the given array contains at least one of the queried string/number.
params
- array (Array) - array to search in - default: []
- query (StringNumber) - String/Number compared to each item in the given array - default: 'true'
{% comment %} site.users = ["Tobi", "Laura", "Tetsuro", "Adam"] {% endcomment %}
{% if site.users | any: 'Tobi' %}
Tobi is in users.
{% endif %}
Truthy and falsy values
In programming, anything that returns true in a conditional is called truthy. Anything that returns false in a conditional is called falsy. All object types can be described as either truthy or falsy.
Truthy
All values in Liquid are truthy except nil and false.
In the example below, the string “Tobi” is not a boolean, but it is truthy in a conditional:
{% assign tobi = "Tobi" %}
{% if tobi %}
This condition will always be true.
{% endif %}
Strings, even when empty, are truthy. The example below will result in empty HTML tags if settings.fp_heading
is empty:
Input
{% if settings.fp_heading %}
<h1>{{ settings.fp_heading }}</h1>
{% endif %}
Output
<h1></h1>
Falsy
The falsy values in Liquid are nil
and false
.
Truthiness summary table
Liquid expressions are tested for "truthiness" in a Ruby-like way:
truthy | falsy | |
---|---|---|
true | • | |
false | • | |
nil | • | |
string | • | |
empty string | • | |
0 | • | |
integer | • | |
float | • | |
array | • | |
empty array | • | |
page | • | |
EmptyDrop | • |
Note
This topic is a compilation of knowledge found at: Shopify Themes, Liquid Documentation, Liquid Gem Documentation, and Liquid for Designers.