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