include
;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
, то рендеринг шаблона продолжится, если ни один из шаблонов не существует, в противном случае будет сгенерировано исключение.
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
может это делать.