Liquid - Tags: Include

Last edit: Jun 29, 2019
  • Contributors:
  • pavelloz

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:

views/pages/include.liquid


---
slug: include
---
{% include 'mypartial' %}
<br/>
{% include 'mypartial2' %}

views/partials/mypartial.liquid

This is first partial

views/partials/mypartial2.liquid

This is second partial

After expanding include, it becomes:

---
slug: include
---
This is first partial
<br/>
This is second partial

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

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, for the product.liquid file, you would name the variable product.
include has a method to deal with this issue, at least when you pass data to the partial.

Anything after the with keyword will be assigned to a variable that is called the same as this partial.


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

Partial:


{{ product }}

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

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

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


{{ product["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:

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:

views/partials/variable.liquid


{% assign my_car = "Honda" %}

And this page using it:

views/pages/include.liquid


---
slug: include
---
{% 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.

views/partials/export.liquid


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

views/pages/include.liquid


---
slug: include
---
{% 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.