Crash Course on Liquid

by Christina Moore Updated Jun 25, 2019

Liquid is an open-source markup language that can be used to expand your App’s functionality.

Liquid can help you:

  • Format data: If you have a number in a Field (e.g., 1000), you could format it as a currency value (e.g., $1,000.00) using Liquid. This might be necessary when using the number in an email or report.
  • Perform Math: You could add two Fields together to calculate and populate the value of a third Field.
  • Make Decisions: Liquid can help you build decision making into your App. For example, you can create “if/then” statements, which allow you to define how your App should behave in various situations.
  • A whole lot more! The examples above barely scratch the surface. Once you learn Liquid’s basics, you’ll find many opportunities to expand your App’s functionality.

If you’ve never heard of Liquid before, not to worry! Learning the basics isn’t difficult, and does not require any programming knowledge. In many cases, you can achieve a great deal in an App with only a limited understanding of Liquid.

In this tutorial, we’ll cover Liquid’s basic concepts and syntax.

Where can I use Liquid?

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.

Clicking the Editor button (shown above) will open the Liquid Editor, which is a tool that helps you build and validate your Liquid. This editor also shows you a list of the available variables that you can access and manipulate using Liquid.

Though most do, not all Fields that allow Liquid have an Editor button. Sometimes you can use Liquid in a textbox that does not have this button.

Object vs. Tag

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

Object

An object looks like this:

{{ expression }}

The result of the expression will be printed/displayed wherever the Liquid is being used.

For example:

{{ customer_name }} 

This Liquid says, “In the location where this Liquid markup appears, insert the customer’s name”. In this example, customer_name is a Field within your App. The exact customer name that will be printed/displayed depends on which Record is running.

Tag

The second type of Liquid markup is called a tag, which uses different surrounding characters.

Tags looks like this:

{% logic %}

Tags are used to perform decision making. Tags don’t print/display anything on their own -- they run logic.

For example:

{% if customer_name == 'Acme' %} do something {% endif %}

In this example, there are two separate tags being used: an opening tag and a closing tag. This Liquid means, “Only do something if the customer’s name is Acme.”

The example above uses an “if/then” statement, which you’ll learn more about below. What’s important to understand right now is that logic goes inside of tags.

You can also use objects within tags. For example:

{% if X == Y %} <= Tag

  {{ field_name }} <= Object

{% endif %} <= Tag

This Liquid says, “Only print/display field_name if X equals Y.”

Piping Data

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)."

In both examples above, it’s not important that you understand the currency or date filters, or the now keyword. The key concept here is how one value is being passed to the right, so that it can be modified.

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 }}

Decision Making

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.

When using “if/then” statements, you’ll want to be aware of the various operators that Liquid provides. Examples of operators include > (greater than) and == (equal to). A list of operators is available in the official Liquid documentation.

In addition to “if/then” statements, Liquid also offers a “case/when” statements, which can help you build decision making logic.

Arrays

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.”

Loops

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 == 'jdoe@email.com' %}

    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.”

The {% break %} command (which is optional) tells your Liquid to stop looping once the “if/then” statement is satisfied. In other words, once you find the first event that was performed by the user in question, don’t worry about any other events -- stop looping. If you removed the “break” statement, Liquid would keep looping, even after finding the first (and any subsequent) events performed by this particular user.

Next Steps

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:

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.

Previous Article Building Your First App
Next Article Using the Liquid Editor

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.