Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The pOS documentation covers Liquid comprehensibly and includes Liquid functionality specific to the pOS Platform and Siteglide.
Siteglide runs on platformOS and we use their implementation of Liquid which adds a large range of useful functionality.
The best place to start learning is their Introduction to Liquid documentation, which will explain the different types of Liquid syntax. From there, you can find more helpful documentation on the Liquid topic you are interested in.
Some useful Liquid tags:
This Liquid is useful when you are accessing a WebApp 'collection', creating a Categories layout, using a custom GraphQL query and more.
Understanding dot notation is a really useful skill for Developers who are trying to get the most out of Siteglide and the platformOS technology it runs on. This Getting Started Article will cover:
What is dot notation?
How to find a property of an Object
How to chain dot-notation
The Data Tree
Visualising the Data Tree
You will come across the following terms which might be new:
Object
Array
Key-value Pairs
properties
Curly Bracket
This Article is intended to be the starting point for a Series of Articles involving dot notation.
Normally when you're accessing data on Siteglide, you simply want to access a single value. For example, on a Starter Site (using the WebApp installed by default, Gallery), you might need to output a Title on your Layout: {{this.Title}}
In this example, this outputs a String: The Latest Music
You could use this syntax from memory, or by referring to the Docs, but you're actually already using dot notation. The syntax above takes a variable this
which returns an object. .Title
is dot notation which specifies that the Developer wants to access the Title
which is a property of this
.
Note: Sometimes you may see something like this: {{this['Title']}}
This is the exactly same thing, except this alternative syntax also allows you to add spaces in field names. We'll cover this in more detail in the next Article.
Another important piece of terminology is the concept of a Key-Value Pair.
A key is a place where data is stored; a value is the data itself.
In the previous example, this
and Title
are both keys. The key Title
has the value The Latest Music
.
You can chain dot notation. The following example will output the first name of the User currently signed in to a Secure Zone: {{context.current_user.first_name}}
This accesses the context
object, then accesses its current_user
property and finally accesses the id
property of current_user
. current_user
can be considered an Object, because it has properties of its own, however, id
has no properties and is stored as a String.
You can think of objects in pOS and Siteglide as a Tree. The Object you start on like context
or this
is like the trunk of the tree. Each time you use a dot to access a property, you are going one level down the tree, until you reach the branch of data you needed.
Just outputting this
on its own would show you the real JSON Object behind the first example in this Article and all of its properties: {{this}}
This outputs an object of data, which to start with is a little hard to read. That's because whitespace is removed for efficiency reasons. Adding the whitespace back in with a third party tool will allow us to read it more easily (see the next section).
To make sense of the JSON that the Liquid outputs, you'll need a tool for automatically formatting the JSON data and adding whitespace. Some tools even help you visualise the data in other more advanced ways.
Important Note
We'd recommend when parsing JSON using third party tools that you do not use sensitive Client data. It's best to use test data and publically accessible data when testing and developing dot-notation. We cannot verify that any third party tool will handle your data safely.
Here is an example of a tree-view. It's the JSON data with extra whitespace and newlines added for readability (colours too).
From this view you can make the same observations we made when using the <pre> tag, but it is easier because each level of the tree is indented and all keys are coloured light blue:
The first and last character is a curly bracket- this represents the this object we are accessing.
The key id has no properties, it has a value of 98656
which is stored as a String. this.id will be enough to access it.
The key properties has properties which are accessible by dot notation. You can tell because the properties key is followed by more curly brackets indicating that it is an object. All the properties inside this set of curly brackets are properties of properties. `{{this.properties.name}}`
will access the name property of properties.
Here is a chart view from the same tool. It shows more clearly how some objects are nested within others. You can use this to help you chain dot-notation to get the values you need.
You may notice that category_array
looks slightly different in the examples above. This is because its value is an array. You can notice an array in your data when square brackets are used around a list of values separated by commas e.g "category_array":["98479", "111111"]
We will cover arrays in the next Article: Advanced Dot Notation: Arrays and Key Maps
Choose your favourite third party tool for parsing and formatting JSON. Everyone has a different favourite tool, but you can see a third party comparison here to help you get started and find one: We'll look at this again below in "Using a Third Party Tool to Visualise Objects"
We don't have a favourite JSON parsing tool, but you can see a third-party comparison here: Many Code Editing environments also have a tool for prettifying JSON data.
How to use Liquid For Loops and Indexing to handle arrays. Also, how to use a key to access key maps, using categories as an example.
This Article is the second in a series on using Dot Notation in Siteglide. We strongly recommend reading the Article below first:
If you're using dot notation, you'll probably come across arrays and maps. The syntax for dealing with them is slightly different, but this actually makes them more powerful when you're building complex Layouts.
The examples below focus mainly on Categories because they are a good example of arrays and maps.
An array is a group or list of data. A key might have a single value, or an array of values.
In Siteglide for example, each WebApp item for example has a field called category_array
which stores a list of the IDs of every Category assigned to that item. The more categories an item belongs to, the longer the array. E.g. { "category_array":["98479", "111111"] }
If you try to use standard dot notation as we practised in the previous Article, you will be able to output the array as it is using the key category_array
and the liquid {{this.category_array}}
:
["98479", "111111"]
However, there aren't many places where this would actually be helpful. It would probably be more useful to do one of the following:
Access one of the Array items by its Index
Loop over the array Items
Find the length of the array (how many items are there?)
Arrays have an index, which means they are numbered. In Siteglide (and in JavaScript) Arrays are zero-indexed, meaning the first item has the index of 0
while the second item has the index of 1
.
We can access the first value in the category_array
by its index using the following Liquid: {{this.category_array[0]}}
outputs 98479
Note that straight after the key, we give the index number of the value we want in square brackets. If the array contained objects, you could go a step further and access one of their properties with a dot after the square brackets.
We can access all values in the Array using a Liquid For Loop:
This outputs:
You can find the length of an array using a Liquid filter: {{this.category_array | size}}
outputs: 2
As well as arrays, you might come across a map of data. Here is an example which can be tried on any Siteglide Starter Site using the Liquid: {{context.exports.categories}}
It outputs something like this (but I've shortened it here!):
A map is used to store data when you know the ID of an item and want to fetch it using it's ID as a key. In Siteglide we use them for performance reasons. You can tell this is a map, because the key items
contains several comma-separated objects instead of a single value. Each of these has a key representing an ID, instead of the name of a property.
Let's say you have the ID of a category, but you want to display the Category's name: {{context.exports.categories.items["98490"].name}}
This outputs: Women
This sounds odd, but it's the name of the eCommerce Category we wanted! You can achieve the same if you have the ID stored as a variable:
You can loop over all keys in a key map using a Liquid FOR loop. Inside the loop, each key-value pair is treated as an array with the key being the first item in the array and the value being the second and last value in the array.
In this example, we'll loop over all Categories in context.exports.categories.data
and see what data is available to output:
Here's a challenge you can try.
Can you create a WebApp with Categories and in your Layout output a list of the Category names that belong to the item?
Step 1) Create a WebApp and assign more than one Category to each of the Items. Step 2) In the Layout, access the this object. Step 3) Use your Understanding of arrays to loop through every category belonging to the item. Step 4) Use your understanding of maps to find the name of each category in the Loop and output it.
Next, we'll look at how you can use dot-notation to work with WebApp collections: Using WebApp Collections
How to check if a variable exists/ is null/ is false?
Not all the variables on Siteglide will be stored as either "true" or "false". In many scenarios something may exist in one location, and simply not exist in another . To better explain this i'll use a homepage as an example:
Whether a page is the homepage or not is determined by the is_homepage variable: is_homepage
which has the value true
. However if a Page is not the homepage, rather than is_homepage
being set to false
, the is_homepage
variable doesn't exist.
Say I wanted to run some code on every Page that isn't the homepage, I'd write something like this:
This would work fine if we were on the Homepage, as the variable's value would be true. However, on other Pages, it would not behave as expected, as is_homepage would be undefined..
Now lets look at the Liquid keyword "blank". This refers to having a value of either: Empty, Null or False.
If I now check "is_homepage" like so:
This will now work!
Want to use Liquid Dot Notation to find dynamic data on your Site? The context variable is most likely the place to look.
In this Article, we'll be using dot notation, so if you're not familiar with it, you may want to brush up here:
Once you've got a good understanding of Liquid Dot Notation, the next step is branch out and discover what is possible.
Here are some of the most useful places to look for data:
{{context}}
The platformOS object context
contains a huge tree of information about your Site- often including variables you didn't know you wanted until you discovered them.
{{this}}
- This is a Siteglide variable containing data specific to a Layout- you'll only be able to use if within a Layout file. The data will completely change depending on the type of content, so it's a good place to use Dot Notation to explore each time you try a new feature.
In this article, we'll explore the context
object in more detail.
The this
object is used differently in different features, so the best place to learn about it is by reading the documentation on the specific feature you're using it with.
The context
object's role is to provide your Site with contextual information which might help it render HTML in a more flexible and personalised way.
Context should be available in any Liquid file, and this includes auto-responder and workflow notifications. However, bear in mind that context may work subtly differently in an email- for example- it's not possible to see information about the person reading an email- current_user
would refer to the person submitting the Form which triggers the email to be queued.
We'll go through the top level of context's keys and explain each namespace's role. Beyond that, you will have to explore for yourself!
If a property is marked advanced only, it is because we haven't found a use-case for it yet on a Siteglide site, or they are not supported, or there is a newer version of this property which is easier to use. We may mark a feature as advanced only because it is possible for it to conflict with a Siteglide feature and it needs to be used with caution. You may be able to discover your own Use Cases for these- if so we'd be very interested to hear about them! To be clear, we can't offer support if these are used in your Site, but we're noting them here in order to be comprehensive.
Advanced only - You won't need to use this directly- it is a frequently changing token used as part of the security on form submissions.
***Adding Session Fields ***You can add fields to session and exports objects only.
Compatibility: To avoid conflicting with future Siteglide features, we recommend that if you use this feature, you prefix any new fields with the initials or name of your Agency.
e.g. Let's say a User has decided to opt-in to a particular non-essential feature or cookie. You could remember this: <div data-gb-custom-block data-tag="session" data-agency_optional_features='true'></div>
You can then use logic to only show these features to Users who have opted-in.
***Removing Session Fields ***To continue our previous example, if the User chooses to change their preferences and opt out, you can forget the setting by setting it to an empty String: `
`
Unlike session
, this only holds information relating to a User if they are currently logged in to a Secure Zone. It is more sensitive than `session`
and will include a name and email address. If there is no current_user, it will hold the value null
.
Headers are information sent and received when a browser sends a request to a server for an HTML Page. This is a technical area which can be nevertheless useful on some every-day use cases.
Another helpful property is HTTP_REFERER
. This tells you the URL of the Page that the User was visited before the current one- assuming this was not deliberately hidden. This can be really useful for redirecting a User back to a particular Page after carrying out an Action.
This object helpfully takes the URL of the current Page and dissects it into chunks which you can use.
slugs refer to parts of a URL separated by forward slashes / - slug, slug2 and slug3 will be available to you only if they exist. This can be helpful if you're implementing breadcrumbs.
query parameters will become available to you if they exist and will be available under the same key they use in the URL. E.g. a parameter in the URL https://siteglide.com?password=test will become available here: {{context.params.password}}
Advanced only- When using CLI- params
can also be used in a form_configuration to interrogate the form data being sent to the server, including virtual fields.
Advanced only- You can ignore this, as Siteglide does not support this pOS feature.
Advanced only- This will currently only read the value of "Production" as currently all Siteglide Sites are Production ready- but watch this space!
Advanced only - Returns true if the Page is being rendered by an XHR (sometimes referred to as Ajax) Request.
This is analogous to "location" in JavaScript and can provide you with useful URL information.
{{context.location.url}}
will get you the full absolute URL for the current Page
{{context.location.href}}
will get you the relative URL for the current Page without query parameters- useful if you want to set new query parameters!
{{context.location.pathname}}
will get you the relative URL for the current Page including query parameters.
This Object is often useful when you use it alongside params
.
This contains metadata for the Page.
This actually gives you metadata relating to the chosen Page Template, not about Layouts on the Page.
This contains objects for each module you have installed on your Site. It includes Siteglide Modules and any Modules you've installed via platformOS. It only contains metadata- if you want data relating to items in that Module, you'll have to access it in a Layout with {{this}}
or through making a collection
and then looking in {{context.exports}}
.
Advanced only- Contains the IP Address of the visitor.
Advanced only-
Advanced only- Use device
instead!
Device should give you information about your visitor's device, operating system and browser. However, use it with caution - you'll still need to make websites responsive! You could use this to suggest to certain Users that they will have a better experience if they update their browser to a modern one.
This lists the cookies currently used by the Site.
Any payment gateways you are using as part of Siteglide eCommerce e.g. Stripe may also have a cookie listed here.
You may also see cookies relating to browser extensions. Ignore these- as your Users will have different extensions to your Developers!
Advanced only
Advanced only
Advanced only
This is where all context data is kept which is custom- either to Siteglide or that you have added to your Site.
Take control over your WebApp Layouts by exposing the Data and making your own For Loop with Liquid
In this Tutorial, we'll be using dot notation, so if you're not familiar with it, you may want to brush up here:
You'll also need to be familiar with WebApps:
By default in Siteglide, when you include a WebApp, we query the database and loop over the items for you. We take the data inside the loop and assign it to a variable called this
which holds dynamic data about the current item. In certain situations, you may want to do something different, so we have provided the optional parameter collection
.
Setting collection to 'true'
makes the data from the behind-the-scenes query available to you directly, without a layout.
In the following example, we show the difference between a WebApp list which does use Collection and one which doesn't:
This outputs:
To break it down further, setting collection to true
exports the data to {{context.exports}}
Under that, you can access it by the id of the WebApp in the original include
tag. In this example, it's 1
so we can access {{context.exports.webapp_1.data | json}}
.
You can then use dot notation to access the data as you wish.
When would you use collection?
Well some people will prefer to always use collection, others will prefer to use layouts. One possible use-case where Collection works better though is if you want to display the same WebApp twice on the Page but differently each time.
For example, what if you wanted to display the first item largely at the top, then display other items in smaller cards below?
You could use the `
` tag twice to achieve this, with different Layouts each time, but this would have a negative effect on performance. This would slow the Page down, because we would be querying the database behind the scenes twice (once for every time you include the tag).
Alternatively, you could include the webapp just once as a collection, then use Liquid to display the items you want in the way you want:
This outputs:
Great! Only one query needed behind the scenes and we've nearly met the objective, but there's one problem. The item "A Special Guest Appearance" has been included twice!
We can use the offset
parameter on our loop tag to start the loop at a different index. Let's skip the first index when we loop, as this item has already been displayed.
Hang on, wasn't the point of Collections to avoid Layouts? Not quite! The idea was to give you control over the loop- layouts are still possible. I can still include my portfolio_2
layout, but I need to work out its path from SITE MANAGER / Code Editor in Admin.
I can now include the Layout at this Path: `
`
The Layout is expecting an object called this
containing the data, but as in the example above we already assigned variables called this
containing the right data, the Layout works without further modification:
- You might not need to fully understand this topic- but a first read of it will be very useful in helping you to recognise the more difficult to handle types of data structure- even if you're not ready to tackle them yet.
{{context.exports}}
The object exports
sits on the root level of context
and its role is to allow a global storage location for any custom variables not already included in context
. You'll mostly use it as a place to access Siteglide specific data, for example, it is the home of data relating to Siteglide categories and will contain WebApp or module data when you use the collection
parameter in the include
tag. exports
will also contain any keys that you have entered within the area in Siteglide Admin. You can also add your own data to a namespace in exports
- see the to see how. This is especially useful if you want to include some data in a Content Section, Code Snippet or Layout- but access it in on a higher level e.g. the Page Template.
platformOS uses a single cookie to identify a visitor- whether signed in or not. The session
object holds information in the database which relates to the visitor with that cookie. This is used in Siteglide eCommerce to allow us to identify someone who has added items to a Cart, without requiring them to Sign In. Learn more about how we use this essential cookie .
The easiest way to add session fields is to use the <div data-gb-custom-block data-tag="session"></div>
tag.
Ending a Session- Advanced only You can use custom GraphQL to completely forget a visitor and end their session. Use at your own risk as we cannot support Secure Zones with Users who have had their Session ended in this way:
For example, in this Article, we show you how to set up canonical URLs. We use the headers
object to grab a useful version of the URL:
Siteglide only uses the session cookie directly which you can learn more about here:
You can do a lot with loops. Offset is just one of your options. Head to the pOS documentation to learn more about loops in Liquid: