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

Roughly speaking, Liquid can be used anywhere that 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 that have an Editor button in their top-right corner (as seen in the screenshot below). This is an indication that you can use Liquid within the text box. The Liquid that you insert into a textbox will be executed when your App runs.

The example 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 often 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 very basic 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 that you have a starting if and an ending endif.

You’ll have lots of opportunities to use “if/then” statements when 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, a 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 a pretty 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 name and the variable’s name. 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 in the same way that 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 that you care about.

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

{% 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 that was 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 that 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 your head wrapped around the Liquid basics, you might also want to check out our Liquid Examples article, which can help inspire you as to all the ways Liquid can be used to augment workflows in Onit.