Before learning Liquid, it’s essential to understand where it can be used within an App.

Roughly speaking, Liquid can be used anywhere you want to return a value or perform decision-making. For example, when creating Conditions, UI Actions, filters, and Field Calculations — among many other things.

When configuring an App, you’ll often see text boxes with an Editor button in the top-right corner (as in the screenshot below). This indicates that you can use Liquid within the text box. The Liquid you insert into a textbox will be executed when your App runs.

The screenshot below shows how Liquid can be used to build a condition.

There are two basic types of Liquid markup: object and tag.

Very often, you will need to retrieve a value from somewhere and then modify it using Liquid. To do so, you will frequently use the pipe character, which looks like this: |. This character is usually above the enter key.

The pipe character essentially means, “Take the value that lives on my left and pass it to the expression that lives on my right.”

For example:

{{ price | currency }}

This Liquid means, “Get the value of the price Field, and then pass it to the currency filter so that it gets formatted like a currency (e.g., $315.67).”

Here’s another example:

{{ now | date: “%y” }}

This Liquid means, “Take whatever the date/time is right now, and pass that to the date filter so that only a year is printed/displayed (e.g., 2018)."

The examples above each contain only one pipe character. Note though that you can pipe as many times as necessary within a single expression. For example:

{{ variable | expression1 | expression2 | expression3 }}

Often, an App should make decisions based on a set of predefined rules. A fundamental example would be: if a Field is greater than a certain amount, do something.

Liquid can help you define decision-making logic using “if/then” blocks, which look like this:

{% if field > X %}

  Do something

{% elsif field > Y %}

  Do a different thing Y

{% else %}

  Do yet a different thing

{% endif %}

It’s important to note that not all “if/then” statements will have this exact structure. That’s because certain elements shown above are optional. If you don’t need them, you can remove the elsif and else sections. The only requirement is to have a starting if and an ending endif.

You’ll have many opportunities to use “if/then” statements when using Apps. It’s common to use them when creating conditions, calculating Fields, and building UI actions, amongst other things.

Most of the time, an App will present its data as single-valued variables. For example, a Record’s customer_name Field contains only one value: a customer’s name.

However, sometimes, you’ll need to work with a special type of variable that contains more than one value (at the exact same time). These special variables are called arrays.

For example, an App returns a variable named current_user, which contains various properties about (you guessed it!) the current user. Because a user has multiple properties (like a name and an email address), the current_user variable is an array.

To make things even more interesting, there are different types of arrays. How you work with any given array will depend on its type.

One type of array contains a single series of data. That’s an abstract statement, so let’s look at an example.

The current_user array contains data about a single user, not multiple users. As a result, current_user has only one name value because humans have only one name (well, usually). So, current_user is a single-series array.

To work with arrays that contain a single series of data, we can use the following syntax:

{{ array_name.value_you_want }}

Note the period character (.), which you place between the array’s and variable’s names. For example: {{ current_user.name }} might return John Doe. In this example, name is a variable that lives inside of the current_user array.

Alternatively, another type of array contains multiple series of data.

For example, a Record’s histories variable contains metadata about each of the significant events that have occurred in the life of a particular Record. Because multiple events can occur, histories usually contains multiple series of data. As a result, we can’t work with this array the same way we would a single-series array. Instead, we’ll need to work with something called a “loop.”

Liquid offers a “for loop” as a way to “loop” over an array. Within the loop, you can interact with each series of data (one by one) and then extract (or act on) the specific pieces of data you care about.

In the example below, we loop over histories, find the event attributed to a certain user, and then “do something” with that specific data series.

{% for event in histories %}

  {% if event.actor == '[email protected]' %}

    Do something 

   {% break %}

  {% endif %}

{% endfor %}

This Liquid essentially says, “Loop over histories (which is an array) and then find the first event performed by a specific user (based on their email address). Once you find it, do something.”

Nice work! You’re now familiar with the basics of Liquid. Depending on the complexity of the Apps you plan to build, you may need to learn about various other Liquid concepts. Luckily, Liquid is a well-documented tool. We recommend checking out the following resources:

• Liquid Reference (from Shopify’s website)
• Liquid for Designers (from Liquid’s GitHub repository)

Additionally, you may be interested in learning how to use Onit's Liquid Editor, which can help you write and preview your Liquid scripts. See our Using the Liquid Editor tutorial for more information. 

Once you have grasped the basics of liquid, you might also want to check out our Liquid Examples article, which can inspire you to explore all the ways Liquid can augment workflows in Onit.