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