Guide to: Liquid and Liquid Logic

Liquid is a template language supported in the Figure Eight platform that allows users to display source data into a job’s user interface.

For more information about Liquid check out this article.

Fig 1. Source data


Fig 2. CML calling in variable from the source data

Fig 3. Job design using Liquid

Using Liquid Logic to display questions based on source data

The source data in Fig 1. shows there are two different types of "item_type", "watch" and "electronic". We want to use different brands for items that are watches and items that are electronic. Rather than separating this work into two separate jobs, we can display two unique question sets to contributors within the same job.

Fig. 4: Preview of the job displaying specific questions based on the source data

Regardless of the "item_type" we want to ask the relevance of the "search_query" to the "item_title", shown in our first radio question. The code below demonstrates how to alter the second question to be specific to the "item_type". The CML to create this question would look like this:

Fig. 5: CML with Liquid logic to show questions based on a specific column

Liquid For-loops: Iterate through a List

Liquid can also be used to iterate through a list in your source data. Rather than having a hard coded list of brand options, let’s say you want to populate the options dynamically from the source data. For example, the column titled ‘possible_brands’ below contains a list of potential brands for each row.


Fig. 6: Source data with an additional column, ‘possible_brands’


Fig. 7: Job preview using ForLoops

In order to allow the contributor to select from the possibilities in this list, we can use a Liquid loop:


Fig. 8: CML with Forloops

Note: We first create a Liquid variable, named "brand", to refer to each item in the column "possible_brands". For a single row, the column named "possible_brands" contains the data "timex, rolex, michael_kors", where each type of brand is listed in the data cell.

There are a few things to note about the Liquid within the cml:radio tag:

  • value="{{ possible_brands[forloop.index0] }}"
  • The value is referencing the column "possible_brands" and the index of the forloop iteration, with the index starting at 0
  • The radio value must reference the column header instead of the Liquid-generated variable, "brand"
  • label="{{ brand | replace:'_',' ' }}"
  • The label is referencing the Liquid forloop-generated variable "brand"
  • The "replace" Liquid filter is used to replace all occurrences of an underscore with a space

In order for ForLoops to work, we'll need to split the column "possible_brands" on the Data page. This will convert each cell in that column into an array based off a specified delimiter :


Fig. 9: Notice "timex, rolex, michael_kors" are converted to ["timex", "rolex", "michael_kors"].

What if the source file has some missing data points?

Source data can sometimes be incomplete. In this case we can use Liquid logic to hide the missing data from the job design to reduce confusion.


Fig. 10: Source data with missing ‘possible_brands’ data

Instead of displaying ‘No data available’, we can hide these fields that are empty. The following code will hide the "possible_brands" question on the rows it’s empty.


Fig. 11: Hidden possible brands question using Liquid logic


Fig. 12: CML with Liquid to hide question when there is no source data to display

When using Liquid for-loops, make sure to include the JavaScript function below in the Javascript style sheet on your Design page. This code snippet will ensure you can update test questions in the user interface without any issues.

var showGold = function(){
    var data = $$('form').retrieve('gold')[0].options.unitData; 
       var answers = data[input.get('class').split(" ")[0]];
     if ( (answers == input.value ) || (Array.isArray(answers) && answers.contains(input.value))) {
        input.checked = true;
  if(_cf_cml.digging_gold) {

Was this article helpful?
1 out of 1 found this helpful

Have more questions? Submit a request
Powered by Zendesk