Templating Language Features

Nunjucks, the templating engine that the Storefront Toolkit uses, provides a set of templating features. This topic highlights the features most relevant for theme customization with the Toolkit.

See the HTML templating engine video tutorial for a quick description of the Theme Editor templating engine and the features available for use in your templates.

Main Templating Language Features:

• Extends
• Macro
• Include
• Filters

See the Nunjucks documentation for more information about available features.

Extends

extends specifies template inheritance, which is used as the base template as shown in the following example:

    {% extends "/layout/base.html" %}

Macro

macro defines reusable content. It is similar to a function in a programming language. These files are located in themes/themeName/content/macros. The following is an example of macro:

{% macro field(name, value='', type='text') %}
    <div class="field">
        <input type="{{ type }}" name="{{ name }}"
                value="{{ value | escape }}" />
    </div>
{% endmacro %}

The macro, field is defined in the previous example. You can now call field like a normal function, as shown in the following example:

{% from "/macros/form.html" import field %}

{{ field('user') }}
{{ field('pass', type='password') }}

Additionally, you can import macros from other templates and reuse them freely across your project.

Include

include pulls in other templates in its place, which is useful when you need to share small sections of content across several templates that already inherit other templates.

{% include "/includes/item.html" %}

Additionally, you can use include templates in the middle of loops:

{% for item in items %}
    {% include "item.html" %}
{% endfor %}

You can use include in this way to separate templates into sections so that browsers can render the small sections when it refreshes the page.

Included templates can extend other templates, which means that you can have a set of related includes that all inherit a common structure. An included template does not participate in the block structure of its including template: it has a separate inheritance tree and block namespace. In other words, an include is not a pre-processor that pulls the included template code into the including template before rendering. Instead, it renders the included template separately, and the results of that rendering are included.

Filters

Filters are functions that can be applied to variables. See the Builtin Filters available for Nunjucks.