Homepage

Liquid - Tags: Include

Last edit: Jun 11, 2024

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"]

Tip

Make sure you put space between the parameter name and its value. minYear:2000 will not work.


Warning

You cannot name a parameter the same as the partial (in this case car).

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.

Questions?

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

contact us