Home platformOS Logo

Liquid - platformOS Liquid Tags

Last edit: Apr 23, 2020


Invokes code within the tag asynchronously, in the background. You will only have access to variables you explicitly pass to the background tag. The context object is available by default, but with limitations - you need to explicitly pass page/layout metadata if you want to use it, as well as device and constants.


Name Type Description
options Hash Any variable provided to the background tag will become accessible in the code.
options.delay Integer which defines the number of minutes to delay running code (defaults to 0, which means run code as soon as possible)
options.priority String low, default or high - see AsyncCallbackPriorityEnum GraphQL Object
options.max_attempts Integer the number of time to re-try job upon failing. Default is 1, maximum is 5
options.source_name String your label of the job, which would help you identify it


        The following code will run all the log queries in the background, not earlier than 5 minutes since the execution. You will only have access to variables
explicitly provided to the background tag: "data" and "hey". Note that you will not have access to the "my_data" variable. Also note
that the result of this background tag will not be rendered, and you will not have access to any variable inside the background tag.

{% parse_json my_data %}{ "hello": "world" }{% endparse_json %}
{% assign not_available_in_background = "You will not see me" %}
{% background priority: 'low', delay: 5, max_attempts: 3, source_name: "my custom job", data: my_data, hey: 'hello' %}
  {% log not_available_in_background %} {% comment %}Will be null, as this variable was not passed to the background tag {% endcomment %}
  {% log data %} {% comment %}You will see { "hello": "world" }, as it was provided to the background tag{% endcomment %}
  {% log hey %} {% comment %}You will see "hello" as it was provided to the background tag{% endcomment %}
  {% log context %} {% comment %}You will copy the current request context and make it available in the background{% endcomment %}
  {% assign not_available_outside = "You will not see me" %}
  {{ not_available_outside }} {% comment %}This variable will be rendered in the background, meaning you won't see anything on the page{% endcomment %}
{% endbackground %}
{{ not_available_outside }} {% comment %}This will be blank, because the assign will happen in the background - you won't have access to it here{% endcomment %}


Checks if there's string cached for the given key. If yes, it just returns the value without processing anything inside the cache tag, otherwise it executes code, stores the result in the cache. When you hit the page with such code for the first time, the code will be executed and hence it will iterate through the loop and generate random strings. However, then the result of the block will be cached and all the following requests within 20 seconds would not invoke the code - instead, it would just take the value from the cache. The output will not change. When the cache expires, the code will be evaluated again, producing another set of random string. Cache is automatically invalidated if any changes are applied to any view/translation.


Name Type Description
key String the key which should uniquely identify the cached fragment
expire Integer optional. number of seconds since populating the cache to expiration


        {% cache 'this is my key', expire: 20 %}
    {% for i in (1..100) %}
  • {{ 18 | random_string }}
  • {% endfor %}
{% endcache %}

        {% parse_json pagesUpdatedAt %}
{%- cache pagesUpdatedAtCache -%}
{%- graphql g = 'pages_updated_at' | dig: 'admin_pages', 'results' -%}
{{- g -}}
{%- endcache -%}
{% endparse_json %}
{%- export pagesUpdatedAt, namespace: 'nav' -%}


Stores a block of markup in an identifier for later use. Render it later with `yield` tag.


Name Type Description
name String the markups will be stored under this name
flush Boolean optional. If the flush parameter is true content_for replaces the blocks it is given instead of appending content to the existing one


        {% content_for 'header' %}
  Hello world
{% endcontent_for %}


Makes variables defined inside partial accessible anywhere via context.exports.`namespace`


Name Type Description
variable Any variable to be stored inside the namespace
namespace String namespace under which variable will be in context.exports


        {% assign a = 'value for a' %}
{% assign b = 'value for b' %}
{% export a, b, namespace: 'my_hash' %}

{{ context.exports.my_hash }} => { "a": "value for a", "b": "value for b" }
{% parse_json company %}
  "name": "platformOS",
  "technologies": ["liquid", "graphql"],
  "countries": { "USA": 5, "Poland": 5, "Romania": 2 }
{% endparse_json %}

{% export company, namespace: 'data' %}

{{ context.exports.data }} =>
  {"company"=>{"name"=>"platformOS", "technologies"=>["liquid", "graphql"], "countries"=>{"USA"=>5, "Poland"=>5, "Romania"=>2}}}
{{ context.exports.data.company.technologies }} => liquidgraphql
{{ context.exports.data.company.name }} => platformOS


Used to generate a html form element for a resource. Use within `form configuration`. Inside the tag you can use `form_builder` variable.


Name Type Description
html-id String set id attribute in `<form id="">` element
html-novalidate String add `novalidate` attribute to `<form novalidate>` element
html-class String add css class `<form class="">` element
html-multipart Boolean add `enctype="multipart/form-data"` attribute to `<form enctype="multipart/form-data">` element.
Multipart is enabled by default
html-data- attr [String] add data attribute to `<form data-[attr]="">` element


        {% form %}
  {{ form_builder }}
{% endform %}

        {% form html-id: 'someid', html-novalidate: true, html-class: 'big-form green-form', html-data-user-id: '12345', html-multipart: false %}
{% endform %}


Allows to store a variable returned by a partial


        {% function res = 'path/to/my/partial', arg1: 'hello' %}


Used to execute GraphQL query stored in a file or invoke GraphQL query inline. All arguments provided to the tag will be passed to GraphQL. It returns a hash with the data or the errors that occurred (for example, variable type mismatch, required variable not provided, syntax error) etc.


Name Type Description
query_name String name of the GraphQL query. For get_users.graphql file name of the query is get_users
arguments Object optional. key:value pair(s) which will be passed to GraphQL query
args JSON optional. JSON object (in form of String) of the arguments which will be passed to GraphQL query


        Invoke query "get_models" and store the result in variable "g":
{% graphql g = "get_models", model_id: context.params.slug2 %}

        Chain filters to extract results in one line:
{% graphql g = "get_models", model_id: context.params.slug2 | fetch: 'models' | fetch: 'results' %}

        Pass all arguments at once as a hash to have graphql tag in one line and/or compose arguments hash dynamically:
{% parse_json arguments %}
    "model_id": {{ context.params.slug2 | json }},
    "user_id": {{ context.params.user_id | json }}
{% endparse_json %}

{% graphql g = "get_models", args: arguments %}

        Pass all arguments at once as a JSON string:

{% capture arguments %}
   "per_page": 20,
   "page": 2
{% endcapture %}

{% graphql g = "get_models", args: arguments %}

        Invoke inline query and store the result in variable "g". This is recommended for one-time used queries.

{% graphql g, id: context.params.slug2, message: "new message" %}
  mutation set_message($id: ID!, $message: String!) {
     id: $id
     model: {
       properties: [{ name: "message", value: $message }]
   ) {
     message: property(name: "message")
{% endgraphql %}


Allows to easily modify a Hash with a syntax same as assign tag.


        {% parse_json my_hash %}{ "a": { "b": { "c": "12", "d": "hello" } } }{% endparse_json %}
{% hash_assign my_hash["a"]["b"]["d"] = "bye" | upcase %}
{{ my_hash }} => {"a":{"b":{"c":"12","d":"BYE"}}}

        {% parse_json my_hash %}{ "a": { "b": { "c": "12", "d": "hello" } } }{% endparse_json %}
{% hash_assign my_hash["a"]["b"] = null %}
{{ my_hash }} => {"a":{"b":null}}


This tag should be used to render forms defined in forms directory


Name Type Description
form_name String name of the form configuration from forms directory
id ID id of the resource you want to edit
parent_resource_id String name of the resource type, f.e. name of custom_model_type, transactable_type, user_profile_type


        {% include_form 'signup_form' %}

        {% include_form 'edit_user', id: user.id %}

        {% include_form 'manager_invite_to_interview', parent_resource_id: 'invitation', user: g.user %}


Print any information to marketplace logs


Name Type Description
message Any Any object that can be printed
type String type of log entry. Use it to tag your logs to make it easier to differentiate logs. If you set it to 'error' pos-cli will also notify your OS about it.


        {% log 'hello world' %}

        {% log params, type: 'request-params' %}

        {% log user.id, type: 'debug' %}

        {% log context.current_user, type: 'error' %}


Captures and parses the JSON string inside of the opening and closing tags and assigns it to a variable.


Name Type Description
variable_name String variable name that will be used to assign contents after it is parsed
content String valid JSON string to be assigned


        {% parse_json car %}
  { "type": "SUV", "gearbox": "AT" }
{% endparse_json %}

{{ car }} => {"type"=>"SUV", "gearbox"=>"AT"}
{{ car.type }} => SUV

        {% parse_json cars %}
    { "maker": "Honda", "model": "CRX" },
    { "maker": "Subaru", "model": "Forester"},
    { "maker": "Lexus", "model": "LFA" }
{% endparse_json %}

{{ cars }} => {"maker"=>"Honda", "model"=>"CRX"}{"maker"=>"Subaru", "model"=>"Forester"}{"maker"=>"Lexus", "model"=>"LFA"}

        In order to create JSON object from exsting values print them using `json` filter.
This is required only for strings and will escape properly `"` and `'` characters.
Other types will be handled automatically.

{% parse_json nested %}
    "price": 100
{% endparse_json %}
{% assign color = "red" %}
{% assign car = 'Mazda "5"' %}
{% parse_json data %}
    "color": {{ color | json }},
    "car": {{ car | json }},
    "nested": {{ nested }}
{% endparse_json %}

{{ data }} => {"color":"red","car":"Mazda \"5\"","nested":{"price":100}}


Print variable, skipping any additional sanitization. It provides a way to display a variable which consists of both safe and unsafe html.


Name Type Description
variable String Variable containing safe and potentially unsafe HTML


        {% assign invokable_script = "<script>alert('I will be executed')</script>" %}
{% assign malicious_script = "<script>alert('I should be escaped')</script>" %}
{% capture result %}
  {{ malicious_script }}{{ invokable_script | html_safe }}
{% endcapture %}
{% print result %}


Redirects browser to target


Name Type Description
target String path or url
status Int 3xx HTTP code, default 302


        {% redirect_to '/dashboard' %}

        {% redirect_to 'https://example.com/signup' %}

        {% redirect_to '/dashboard', status: 301 %}


Allows you to set HTTP status for the response. Default 200.


Name Type Description
status Int HTTP status, default 200


        {% response_status 204 %}

        {% response_status 404 %}


Used inside a partial invoked by a function tag to return a variable


        {% assign result = 1 | plus: 3 %}
{% return result %}


Stores data during user's session Sets field of given name to given value in context.session


        {% session foo = 'bar' %}
{{ context.session | json }} => { "foo": "bar" }

        {% assign bar = "42" }
{% session foo = bar %}
{{ context.session | json }} => { "foo": "42" }

        {% session foo = null %}
{{ context.session | json }} => {}

        {% session foo = blank %}
{{ context.session | json }} => {}


Generates html for spam protection. Supports Google reCAPTCHA strategies: recaptcha_v2, recaptcha_v3


Name Type Description
strategy String name of protection strategy. Default is recaptcha_v2
action String action name for reCAPTCHA V3, action may only contain alphanumeric characters and slashes


        {% form %}
  {% spam_protection "recaptcha_v2" %}
{% endform %}

        {% form %}
  {% spam_protection "recaptcha_v3", action: "signup" %}
{% endform %}


Execute code wrapped inside content_for


Name Type Description
name String name of content_for block


        Use this in a liquid view first. Then you can use yield inside the layout (for example) or another subsequently rendered view, like below:
{% content_for 'greeting' %}Hello world{% endcontent_for %}

# another_file.liquid
{% yield 'greeting' %}


We are always happy to help with any questions you may have.

contact us