Part 2: Liquid in Treepl CMS

Viewing Available Object Data

To answer the first part of the question; "how do you know what data is available", you can do one of three things.

1 If you are editing a Layout within the Treepl CMS admin, you’ll have access to the Properties Manager at the top right of the editor window. Many available data points have been pre-configured here for you to copy and paste.

The Menu module doesn’t have the Properties Manager for it’s layouts, however, most other modules throughout the CMS do.

2 You can reference the documentation for the data output available for your specific component and construct your Liquid syntax manually from there.

For example, the Menu output documentation can be found here.

3 You can temporarily output all the data to your layout and reference it directly on the front-end in your browser.

To do this, you simply reference the root Object of your Liquid layout, which is referred to as this, like so:

{{this}}

This Liquid Object will output the Layout’s complete available dataset in JSON format and when viewed in your browser will render the data to the page.

Although, simply being rendered in your browser window won’t be very readable. So there are two things we can do here to help.

One, wrap the {{this}} Object in an HTML pre element (which is an HTML element that preserves preformatted code), like so:

<pre>{{this}}</pre>

This will help your browser format the JSON in a more readable format.

Alternatively, to get this output off your page and into your browser’s developer console (which is probably a better way to inspect the data) you can use a little bit of JavaScript in your layout, like so:

<script>
  console.log({{this | strip_html}});
</script>

You might notice the addition of | strip_html. This is a Liquid filter that removes HTML markup and it can be handy to add here otherwise any HTML code included in your this output can break the Javascript and cause errors.

Either way, you should get a data structure something like the below sample:

{
 "Name": "Main Nav",
 "LayoutGroup": "My Layout Group",
 "Alias": "main_nav",
 "Items": [
   {
    "Id": 123,
    "ItemName": "Home",
    "ItemUrl": "/home",
    "ItemClass": null,
    "ItemEnabled": true,
    "Items": []
   },
   {
    "Id": 124,
    "ItemName": "About",
    "ItemUrl": "/about",
    "ItemClass": null,
    "ItemEnabled": true,
    "Items": []
   },
   {
    "id": 125,
    "ItemName": "Contact",
    "ItemUrl": "/contact",
    "ItemClass": null,
    "ItemEnabled": true,
    "Items": []
   }
  ]
}

This sample data has been reduced for the simplicity of this tutorial.

With any Object output, we first encounter an open curly bracket { which is then closed at the very end of the output with a closing curly bracket }.

These curly brackets represent Objects and this first (root) curly bracket is always the Object you referenced in your Liquid code, whether it was {{this}} or {{this.Items}} or some other Liquid Object like {{this.formSubmissionData.fields.system}} (which we’ll explore later). The Object data will be output from that level onwards.

Nested data within the Object (as defined by indented lines of code) you’ll see as name/value pairs, for example:

"LayoutGroup": "My Layout Group"

The first part, LayoutGroup, is the property name and the second part, My Layout Group, is the property value. This is the name/value pair.

The value is typically the piece of data you want to render out and the name is the label you’ll use to reference it.

Accessing Available Object Data

Before we dive too far into this intimidating waterfall of data, let’s just get our toes wet and fish out a little tidbit of data. Just to get the feel of how this works.

Let’s say you want to render onto the page the menu’s name. You know the root Object is referenced as this, and nested under that you can see a property called "name" which has the value you want to render out.

So using the dot notation to traverse the Object data you can simply do this:

{{this.Name}}

Which, on the front-end, will render the following:

Main Nav

By the way, referencing Liquid properties here is NOT case sensitive. So {{this.Name}} is the same as {{this.name}} or even {{tHIs.naME}}. Although, it’s probably best practice to match the Title Case syntax used here, as in some cases, particularly when working directly with JSON and JavaScript code, property names ARE case sensitive.

Let’s look at one more example using another piece of Object data, made available in the root level Liquid Object, after a form submission is made. The new Object is called formSubmissionData and you can access it just as we accessed the menu name above. Although, in this case we are no longer in the ‘scope’ of a Menu Layout - instead we might be on a standard web page, so the root Liquid Object is the page itself, but it is still referenced as this, like so:

{{this.formSubmissionData}}

In this example, the output from this Object has several nested Objects defining three system fields (First Name, Last Name, and Email) and one custom field (Enquiry).

Let’s say you want to render the users first name and their enquiry as a thank you/confirmation message on the page - these properties are bolded in the below sample:

{
 "submissionid": 123,
 "form_name": "Contact Form",
 "form_alias": "contact_form",
 "fields": {
  "system": {
   "firstname": {
    "id": "FirstName",
    "name": "First Name",
    "value": "Alex"
   },
   "lastname": {
    "id": "LastName",
    "name": "Last Name",
    "value": "Smith"
   },
   "email": {
    "id": "Email",
    "name": "Email",
    "value": "asmith@example.com"
   }
  },
  "custom": {
   "enquiry": {
    "id": "Enquiry",
    "name": "Enquiry",
    "value": "Hi. This is a test message."
   }
  }
 },
 "error": 0,
 "errormessages": []
}

This sample data has been reduced for the simplicity of this tutorial.

Let’s look at how to render that thank you message, accessing data several levels deep.

Starting at the top (root) you already know that the Object is referenced at this.formSubmissionData, so this is your starting point from the very first open curly bracket ({). Then you need to follow the nested ‘path’ all the way down to your desired piece of data, traversing through the properties fields > system > firstname > value, to get to the first name value.

Using the dot notation you’ll end up with something like this:

{{this.formSubmissionData.fields.system.firstname.value}}

Which will render:

Alex

And likewise for the enquiry value:

{{this.formSubmissionData.fields.custom.enquiry.value}}

Which will render:

Hi. This is a test message.

If it’s easier, you can instead work backwards and traverse up the Object data path. Starting at your desired piece of data and referencing each parent property until you reach the root Object.

Finally, let’s code this into our layout along with some HTML:

<p>Thank you {{this.formSubmissionData.fields.system.firstname.value}}!</p>
<p>One of our team members will get back to you regarding your enquiry:</p>
<blockquote>
  {{this.formSubmissionData.fields.custom.enquiry.value}}
</blockquote>

It’s like Mail Merge in Microsoft Word… but for the web and way cooler.

Ok, so that was easy. Now let’s really geek-out and take a deeper look at all this Object data to understand all the different parts you might encounter.

Strings

As mentioned above, Strings are simply a line of characters that form the value of the property. They are defined by being wrapped in double quotes and generally are handled as plain text.

{
  "name": "I am a String - just plain old text."
}

Numbers and Booleans

Numbers and Boolean values are shown without being wrapped in quotes.

For this example let’s refer back to the sample Object data for the Menu. Here it is again for reference:

{
 "Name": "Main Nav",
 "LayoutGroup": "My Layout Group",
 "Alias": "main_nav",
 "Items": [
  {
   "Id": 123,
   "ItemName": "Home",
   "ItemUrl": "/home",
   "ItemClass": null,
   "ItemEnabled": true,
   "Items": []
  },
  {
   "Id": 124,
   "ItemName": "About",
   "ItemUrl": "/about",
   "ItemClass": null,
   "ItemEnabled": true,
   "Items": []
  },
  {
   "id": 125,
   "ItemName": "Contact",
   "ItemUrl": "/contact",
   "ItemClass": null,
   "ItemEnabled": true,
   "Items": []
  }
 ]
}

Let’s take the item’s ID to illustrate a number value:

"Id": 123

And an example of a true/false boolean (which can only ever have a true or false keyword):

"ItemEnabled": true

How you render these data types doesn’t change and you can still use the dot notation like so:

{{this.Id}}

Rendering the ID value of:

123

However, working with these different data types in advanced Liquid logic does have some slight variations, which we’ll cover later. But for now you just want to be aware of, and able to recognise, these different data types.

Nested Objects

The previously mentioned formSubmissionData Object is a good example of nested Objects:

{
 "submissionid": 123,
 "form_name": "Contact Form",
 "form_alias": "contact_form",
 "fields": {
  "system": {
   "firstname": {
    "id": "FirstName",
    "name": "First Name",
    "value": "Alex"
   }
   ...
  }
  ...
 }
 ...
}

Looking at the property name of fields, where you would expect to see a value, you instead see the start of another Object (defined by the open curly bracket {). And within that Object, more names with Objects as their values and so on.

And just to illustrate again how you traverse through these Objects:

{{this.formSubmissionData.fields.system.firstname.value}}

Which will render:

Alex

Arrays and Array Objects

If the value of a property is an array it will be wrapped in square brackets, for example:

"Items": [ … ]

A simple array might just be a comma separated list of values, which might look like this:

"Items": [
  "Dog",
  "Cat",
  "Watermelon"
]

Attempting to render the Items property, like this:

{{this.Items}}

Would give you the value of all array items head-to-tail:

DogCatWatermelon

Which typically isn’t much use and you’d instead want to process each array item in turn, or perhaps selectively render out just one item. Both are possible.

To selectively render, let’s say "Cat", assuming we know the position in the array (which is called its index), we can write the following:

{{this.Items[1]}}

An array’s index always starts at 0, so in this case "Cat" has an array index of 1, so you’d place 1 in square brackets directly after the Items reference. This will pick out just the array item at index 1, giving us:

Cat

But what if you don’t know the index, or you want to render all array items in a more meaningful way. This is where you’d employ the use of a for Tag which will iterate over each array item, one after the other, allowing you to process each item in turn.

We’ll look at the for Tag later in this course when we explore Advanced Liquid Tags.

Furthermore, the value or an array might be more Objects, so the curly brackets will again be present inside the square brackets of the array. For example, this is a 3 Object array:

"Items": [
  { ... },
  { ... },
  { ... }
]

Again, you’d use a for Tag to access these Objects, but we’ll get to that later.

The important thing here is being able to identify the type of data needing to be accessed so you know which tools to use to reference it.

Empty or null

Often a property will exist within a dataset but has not yet had any data saved against it. In this case the data will be null, eg:

"ItemClass": null

This is a special Liquid keyword, much like a true/false boolean has a true or false keyword, null signifies that there is absolutely no data present for this property and that there never has been any data present. Although, unlike true/false booleans which will render a string of either "true" or "false", null will not render anything to the page.

This is similar to, but not to be confused with, an empty property value, which is literally defined as an empty set of double quotes, eg:

"ItemClass": ""

This differs from the null value as it implies the property value has been saved along with the dataset but just doesn’t have any strings or numbers included. Or that a string or number was previously the value but has since been removed.

For this section of the course we don’t need to go much further with this concept, it’s just to be aware of this difference in data type and how to recognise them.