Introduction

In this first tutorial, we will introduce some useful vocabulary for Liquid building blocks and let you spot the syntax (punctuation) in Liquid code which helps you spot each different building block. Becoming confident in these technical terms will help you not just to copy and paste, but to really understand Liquid in future tutorials!

Don’t worry if you don’t understand everything the Liquid is doing right away or don’t feel confident writing it yet. For now, just pay attention to the syntax (punctuation) of the code and spot the types of Liquid syntax we are learning about.

Some of the examples will have two tabs- a Liquid tab and a HTML tab. If you think of the Liquid as a recipe for HTML, the HTML tab will show the resulting HTML “cake” which the server will send to the browser.

Let’s start looking at some Liquid recipes!

Tags

Liquid tags have an extremely versatile set of uses, but in short they “make something happen”! For example:

• {% assign new_variable = "Hello World" %} - Stores a new string of text in a new variable

• {% include "awesome_file", layout: "layout_1" %} - Outputs a smaller file in the larger page

Notice the shared syntax between these examples? That’s right, they all follow a similar syntax:

1. Begins with {% to start the tag. We call this particular bracket a “curly brace” to distinguish it from round brackets ( or square brackets [ which have other meanings.

2. Next comes the tag name e.g. assign or include - this will often be a verb indicating as briefly as possible what the tag will do.

3. For some variables, like assign, there is an extra step with an equals sign = - this allows us to give a name (before the equals sign) to a new or existing variable which will store some given information (after the equals sign) after the tag has done its job. You’ll notice include doesn’t have this step, that’s because include doesn’t store anything, instead it “renders”, disappearing and leaving HTML in its place when it runs.

4. Next some tags will have parameters, think of these as settings. You can usually only use settings which are defined in the documentation for the tag, but some tags like include are extremely flexible, allowing you to create your own parameters. Parameters are optionally separated by commas, but this is optional and just improves readability. The important syntax to know is that they usually have a parameter name, followed by a semi-colon : then a parameter value.

5. Finally a tag will be closed with %}

Exceptions

Minus signs

Sometimes a tag will also have a minus sign after its opening percentage sign or before its closing percentage sign. We’ll come back to this in a future tutorial. {%- assign string = “I will not leave any whitespace behind after I am rendered” -%}

Groups of Tags

Sometimes a tag will consist of not just a single tag but a group of related tags. We’ll return to this in a future tutorial, but here’s an example:

Example
Liquid
Copy
{% if weather == "rainy" %}
  {% comment %} Put up an umbrella {% endcomment %}
{% else %}
  {% comment %} Go to the beach! {% endcomment %}
{% endif %}

The if, else and endif tags work together in a group. We can think of them really as doing the job of a single tag.

The comment and endcomment tags also work together in a group.

We usually indent tags working in a group to help with readability. Even if this causes the resulting HTML to be incorrectly indented.

Variable Names

If setting a variable name in assign, it must be one word without quotes; if you want to use multiple words, join them with underscores just_like_this (this is called snake case because it looks a bit like a snake zig-zagging up and down!)

Example
Liquid
Copy
{% assign name_of_box = "contents_of_box" %}

Activity: Spot the tags:

Can you spot how many tags are in this Liquid example?

Example
Liquid
Copy
{% assign new_words = "Hello World" %}
{% assign my_favourite_number = 7 %}
{{ new_words }}
{%- print my_favourite_number -%}

Outputs

The job of outputs is always to write something on the final HTML page.

Like tags, they use curly braces, but use double curly braces instead of a percentage sign:

Example
Liquid
Result in HTML
Copy
<p>{{ "Hello World" }},</p>
<p>My favourite number is: {{7}}</p>

This example doesn’t really make sense on its own, because we could have written those words and numbers directly in HTML. Combining this with tags, it becomes more useful:

First we will store a number in a variable, then we will output the contents of the variable later on:

Example
Liquid
Result in HTML
Copy
{% assign favourite_number = 2 %}

<p>{{ "Hello World" }},</p>
<p>My favourite number is: {{favourite_number }}</p>

Activity - Spot the Outputs

How many outputs in the example?

Example
Liquid
Resulting HTML
Copy
{{"Hello World"}}

{% assign mood = "happy" %}
I'm feeling {{mood}}.
{% if mood == "sad" %}
  {% assign message = "Please cheer me up!" %}
{% else %}
  {% assign message = "I'm feeling good!" %}
{% endif %}
{{message}}

Filters

Filters are used to modify the values of outputs and some tags - specifically, the kind of tags that allow you to use an equals sign to create a new variable. Filters go inside tags and outputs, never existing on their own, but they can be recognised by the pipe character | they always start with.

Example
Liquid
Resulting HTML
Copy
{% assign mood = 'feeling happy' %}
{{mood}}
{% assign mood = mood | replace: 'happy', 'angry' %}
{{mood}}
{{mood | upcase }}

Check the Resulting HTML tab in the example to see the effect of each filter; notice:

1. The | replace filter is applied to an assign tag

2. The | upcase filter is applied to the last mood output

3. The | replace filter has 2 parameters, the first straight after the colon, the second is separated by a comma. For this specific filter, the first finds a string and the second is the string it should be removed and replaced with. It’s good to check the reference documentation to find out what parameters are available for each filter and any exceptions to the syntax.

Filters can be used to carry out formatting, calculations and other small adjustments where you need to work with variables before they are outputted to the page.

Filters can be chained within the same tag or output, one after another. Each is carried out in sequence, modifying the output from the filter before it.

Example
Liquid
Resulting HTML
Copy
{% assign a = 0 | plus: 3 | times: 2 %}
{{a}}

Activity - Recognise Tags, Outputs and Filters

Example
Liquid
Copy
{% assign time_now = "now" %}
{% assign time_in_seconds = time_now | strftime: "%s" | plus: 0 %}
{% if time_now == 943920000 %}
  Welcome to the year 2000! Watch out for millennium bugs!
{% else %}
  Just another year. The date is {{time_now | strftime: "%d/%m/%Y"}}. 
{% endif %}