Liquid - Tags: Include

The include tag allows you to make your code more maintainable by including templates within other templates.

The simplest example of include looks like this:

app/views/pages/include.liquid

{% include 'mypartial' %}
<br/>
{% include 'mypartial2' %}

app/views/partials/mypartial.liquid

This is first partial

app/views/partials/mypartial2.liquid

This is second partial

After expanding include, rendered content becomes:

This is first partial
<br/>
This is second partial

You can include the same partial multiple times in multiple places for code reuse.

Passing parameters to a partial

You can pass any number of parameters to a partial.

app/views/pages/index.liquid

{% assign makers = 'subaru,honda,toyota,suzuki,lexus' | split: ',' %}
{% include 'car', minYear: 2000, transmission: 'auto', makers: makers %}

app/views/partials/car.liquid

{{ minYear }} => 2000
{{ transmission }} => auto
{{ makers }} => ["subaru","honda","toyota","suzuki","lexus"]

Local variable using with

Liquid has some issues when you try to use a variable that is named exactly the same as the partial.
For example, if you have this car.liquid partial:

<p>This is the value of the variable called "car": {{ car }}<p>

You won't be able to set the car variable by passing it during the include:

{% parse_json cars %}
[{
  "maker": "Honda",
  "model": "CRX"
}]
{% endparse_json %}
{% include 'car', car: cars[0] %}

but you will be able to set this variable by using with:

{% parse_json cars %}
[{
  "maker": "Honda",
  "model": "CRX"
}]
{% endparse_json %}
{% include 'car' with cars[0] %}

This will create the variable called car with hash inside of it.

{"maker"=>"Honda", "model"=>"CRX"}

The properties of hash are accessible using the object["key"] syntax, for example:

{{ car["maker"] }} => Honda

Iterating over a collection using for

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

{% include 'product' for cars %}

This will iterate over the collection and render the partial for each item. Each iteration will have the product variable populated with the current item.

Having a partial that looks like this:

app/views/partials/product.liquid

{{ product }}

Will render (whitespace has been changed for readability):

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

Private variables and exporting them

Our Liquid implementation is 99% compatible with the official one, but we couldn't ignore the issue that you can only use global variables in Liquid.

In platformOS, when you define a variable in a partial, it is not visible by default in a page that is including that partial.

It works from top to bottom though: If you define a variable on a page and then include it in a partial, it will be accessible in the partial.

That means that given this partial:

app/views/partials/variable.liquid

{% assign my_car = "Honda" %}

And this page using it:

app/views/pages/include.liquid

{% include 'variable' %}
This is empty: {{ my_car }}

Will not return Honda in the page. The my_car variable can be accessed only inside the variable partial.

To use a variable that has been defined inside a partial, outside of it, you need to use the export tag and context.exports.

app/views/partials/export.liquid

{% parse_json honda %}
{
  "maker": "Honda",
  "model": "CRX",
  "year": "1991"
}
{% endparse_json %}
{% export honda, namespace: "my_car" %}

app/views/pages/include.liquid

{% include 'export' %}
Car: {{ context.exports.my_car }}
My car maker: {{ context.exports.my_car.honda.maker }}

This should render the stringified hash stored inside the variable in the first line, and nested key in the second:

Car: {"honda"=>{"maker"=>"Honda", "model"=>"CRX", "year"=>"1991"}}
My car maker: Honda

Live demo and source code

You can find a live demo of this page among our example pages, and source code at the examples GitHub page.