Liquid - platformOS Objects
context
Context is a global object accessible in every Liquid file of the project. This includes pages, partials and layouts, as well as Email, SMS, and API Call Notifications. It is the only predefined object that you will use when working with platformOS. This is because you are able to create your own Objects.
context.authenticity_token
context.authenticity_token
is populated by the server and automatically included in every form generated by the {% form %}
tag. It is used to mitigate Cross Site Request Forgery attacks. It must be added to the payload in all server requests other than GET.
context.constants
context.constants
provides access to sensitive data like API credentials and tokens. To protect you from accidentally leaking this information, you need to explicitly call {{ context.constants }}
, as these values are hidden from {{ context }}
by default. You can set constants using the GraphQL mutation constant_set or via the pos-cli GUI.
context.cookies
context.cookies
returns an object with all the cookies of the site.
context.current_user
context.current_user
returns basic data of the currently logged-in user. The available attributes are: first_name
, last_name
, email
, id
and slug
. It will return null
instead of an object if no user is logged in.
context.device
context.device
returns a hash with useful information based on UserAgent. Most notably, context.device.device_type
returns one of the following: desktop, smartphone, tablet, console, portable media player, tv, car browser, camera.
context.environment
context.environment
returns a string: staging
or production
. A common use case is to hide some functionalities on production without blocking the release.
context.flash
context.flash
returns object with possible keys: alert, notice. Value for each key is a message string. Flash messages are set on form submissions.
context.headers
context.headers
contains allowed HTTP headers with the data from the current HTTP request.
Available headers are:
- SERVER_NAME
- REQUEST_METHOD
- PATH_INFO
- REQUEST_URI
- HTTP_AUTHORIZATION
- HTTP_HOST
- HTTP_USER_AGENT
- HTTP_REFERER
- SERVER_PORT
- QUERY_STRING
- X-FORWARDED-FOR
- HTTP_STRIPE_SIGNATURE
- HTTP_AUTHENTICATION_TOKEN
context.is_xhr
context.is_xhr
returns null
for non-XHR, and Boolean true
for XHR requests. A request is identified as XHR by checking if the value of the X-Requested-With
header matches XMLHttpRequest
.
context.language
context.language
returns a String, the language ISO code used in the current request.
For more information about built-in translation mechanism go to the translations section.
context.location
context.location
contains URL data of current request.
Available attributes are:
- href
- host
- pathname
- search
Example 1: Extracting params from path name with extract_url_params
URL: www.mysite.com/app/admin/content/nyc/brooklyn/main
{% liquid
assign template = '/app/admin/content/{city}/{area}/{street}'
assign params = context.location.pathname | extract_url_params: template
%}
"params": {
"city": "nyc",
"area": "brooklyn",
"street": "main"
}
The street is {{ context.params.street }}.
Example 2: Conditional list class
<li class="{% if context.location.href contains link.href %}active{% endif %}">
<a href="#">{{ link.name }}</a>
</li>
context.modules
Information about the version and subscription status of installed modules.
Example: List all properties for installed modules
<section>
{% for module in context.modules %}
Module name: {{ module[0] }}
<table>
<tbody>
{% for properties in module[1] %}
<tr>
<th> {{ properties[0] }} </th>
<td> {{ properties[1] }} </td>
</tr>
{% endfor %}
</tbody>
</table>
{% endfor %}
</section>
context.page
context.page
contains information about the page on which it is included.
Available attributes are:
{{ context.page }}
{
"id" => 1,
"slug" => "foo",
"layout" => "application",
"metadata" => {}
}
context.params
context.params
contains user data provided in forms and query params.
Most common use cases are:
- Include form data in notifications
- Form data manipulation through default_payload
- Data validation in Authorization Policies
Example 1: site path params mapping
When visiting the page with path www.mysite.com/app/admin/content/nyc/brooklyn/main
the value of context.params
would be:
{
"slug": "app",
"slug2": "admin",
"slug3": "content",
"slugs": "nyc/brooklyn/main"
}
Another way of extracting page params is using context.location.pathname as shown in Example 1.
context.session
context.session
allows for quick access to session storage. Use mutations in order to store data in session like in this example.
The browser generates a session ID and stores it as a cookie, then sends the session ID with every request. On the server side, we check if we have an entry matching this session_id and get the JSON associated with it. This JSON can contain anything, including user_id if the user is logged in but if the user is not logged in, we still have the session_id, and as mentioned, it can contain other data - for example product_ids to power the shopping cart functionality for a not logged in user.
After some time we just remove the data associated with the session_id — this is when the server invalidates the session,
but a user can also invalidate the session by manually removing the session_id and then the browser will generate a new one.
For user sessions of logged in users, visit also timeout_in_minutes.
context.useragent
context.useragent
returns an object with user agent data.
Example 1: Displaying useragent
{{ context.useragent }}
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebkKit/537.36
(KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36
context.visitor
context.visitor
returns an object describing browser user. For now there is only one available attribute ip
.
Exposing a local variable within the context object
It is possible to promote a local variable so it is available in the context.exports
namespace. Use the export
tag to do that as in the following example:
{% liquid
assign foo = "bar"
export foo, namespace: "baz"
%}
{{ context.exports.baz.foo }}