Использование include и import в шаблонах jinja2

Содержание:

• Включение шаблона Jinja2, тег include;
• Импорт шаблона Jinja2, тег import;
• Управление контекстом при включении и импорте шаблона..

Тег include шаблона Jinja2.

Тег {% include ... %} полезен для включения шаблона и возврата визуализированного содержимого этого файла в текущее пространство имен (область видимости шаблона):

{% include 'header.html' %}
    Body
{% include 'footer.html' %}

Включенные таким образом шаблоны по умолчанию имеют доступ к переменным активного контекста шаблона. Дополнительные сведения о поведении контекста при импорте import и включении include шаблонов смотрите ниже в подразделе "Управление контекстом при включении и импорте шаблона".

Начиная с Jinja 2.2 и далее, можно пометить включенный шаблон как ignore missing. В этом случае модуль jinja2 проигнорирует инструкцию, если включаемый шаблон не существует. В сочетании с оператором шаблона with context или without context, он должен быть помещен перед оператором видимости контекста. Вот несколько действенных примеров:

{% include "sidebar.html" ignore missing %}
{% include "sidebar.html" ignore missing with context %}
{% include "sidebar.html" ignore missing without context %}

Также можно предоставить список шаблонов, которые проверяются на наличие перед включением. В этом случае будет включен первый существующий шаблон.

{% include ['page_detailed.html', 'page.html'] %}
{% include ['special_sidebar.html', 'sidebar.html'] ignore missing %}

Если задано значение ignore missing, то рендеринг шаблона продолжится, если ни один из шаблонов не существует, в противном случае будет сгенерировано исключение.

Импорт шаблона Jinja2, тег import.

Jinja2 поддерживает включение часто используемого кода макросов при помощи импорта. Эти макросы могут входить в разные шаблоны и импортироваться оттуда. Это работает аналогично операторам импорта в Python. Важно знать, что импорт кэшируется, а импортированные шаблоны не имеют доступа к текущим переменным шаблона, а только к глобальным переменным по умолчанию.

Дополнительные сведения о поведении контекста при импорте import и включении include шаблонов смотрите ниже в подразделе "Управление контекстом при включении и импорте шаблона".

Есть два способа импортировать шаблоны. Можно импортировать полный шаблон в переменную или запросить из него определенные макросы или экспортируемые переменные.

Представьте, что есть вспомогательный модуль, который отображает формы, называемый forms.html:

{# forms.html #}
{% macro input(name, value='', type='text') -%}
    <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}">
{%- endmacro %}

{%- macro textarea(name, value='', rows=10, cols=40) -%}
    <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols
        }}">{{ value|e }}</textarea>
{%- endmacro %}

Самый простой и гибкий способ получить доступ к переменным и макросам шаблона - это импортировать весь модуль шаблона в переменную. Таким образом, можно получить доступ к атрибутам:

{% import 'forms.html' as forms %}
<dl>
    <dt>Username</dt>
    <dd>{{ forms.input('username') }}</dd>
    <dt>Password</dt>
    <dd>{{ forms.input('password', type='password') }}</dd>
</dl>
<p>{{ forms.textarea('comment') }}</p>

В качестве альтернативы можно импортировать определенные имена из шаблона в текущее пространство имен:

{% from 'forms.html' import input as input_field, textarea %}
<dl>
    <dt>Username</dt>
    <dd>{{ input_field('username') }}</dd>
    <dt>Password</dt>
    <dd>{{ input_field('password', type='password') }}</dd>
</dl>
<p>{{ textarea('comment') }}</p>

Макросы и переменные, начинающиеся с одного или нескольких символов подчеркивания, являются приватными и не могут быть импортированы.

Управление контекстом при включении и импорте шаблона.

По умолчанию включенным {% include ... %} шаблонам передается весь текущий контекст, а импортированным {% import ... %} шаблонам нет. Причина этого в том, что импорт, в отличие от включения, кэшируется. Так оператор шаблона import часто используется просто как модуль, содержащий макросы.

Это поведение можно изменить явно: добавив значение with context или without context к тегам операторов шаблона import/include. В случае с {% import ... with context %}, текущий контекст может быть передан в шаблон, при этом кэширование автоматически отключится.

Вот два примера:

{% from 'forms.html' import input with context %}
{% include 'header.html' without context %}

Примечание:

В Jinja 2.0 контекст, который передается во включенный {% include ... %} шаблон, не включал переменные, определенные в шаблоне. Следующий код не работал:

{% for box in boxes %}
    {% include "render_box.html" %}
{% endfor %}

В Jinja 2.0, шаблон render_box.html не может получить доступ к переменной box. Начиная с Jinja 2.1, render_box.html может это делать.