Шаблоны¶

Настройка Jinja¶

Если Jinja2 не настраивается, Flask конфигурируется следующим образом:

• автозавершение включено для всех шаблонов, заканчивающихся на .html, .htm, .xml, а также .xhtml при использовании render_template().

• При использовании render_template_string() для всех строк включается автозавершение.

• в шаблоне есть возможность включить/выключить автозавершение с помощью тега {% autoescape %}.

• Flask вставляет пару глобальных функций и помощников в контекст Jinja2, в дополнение к значениям, которые присутствуют по умолчанию.

Стандартный контекст¶

Следующие глобальные переменные доступны в шаблонах Jinja2 по умолчанию:

config

Текущий объект конфигурации (flask.config)

Добавлено в версии 0.6.

Изменено в версии 0.10: Теперь это всегда доступно, даже в импортированных шаблонах.

request

Текущий объект запроса (flask.request). Эта переменная недоступна, если шаблон был отрисован без активного контекста запроса.

session

Текущий объект сессии (flask.session). Эта переменная недоступна, если шаблон был отрисован без активного контекста запроса.

g

Связанный с запросом объект для глобальных переменных (flask.g). Эта переменная недоступна, если шаблон был отрисован без активного контекста запроса.

url_for()

Функция flask.url_for().

get_flashed_messages()

Функция flask.get_flashed_messages().

{% from '_helpers.html' import my_macro with context %}

Стандартные фильтры¶

Flask предоставляет следующие фильтры Jinja2 в дополнение к фильтрам, предоставляемым самим Jinja2:

tojson()

Эта функция преобразует заданный объект в представление JSON. Это, например, очень полезно, если вы пытаетесь генерировать JavaScript на лету.

<script type=text/javascript>
    doSomethingWith({{ user.username|tojson }});
</script>

Также безопасно использовать вывод |tojson в однокавычном HTML-атрибуте:

<button onclick='doSomethingWith({{ user.username|tojson }})'>
    Click me
</button>

Обратите внимание, что в версиях Flask до 0.10 при использовании вывода |tojson внутри script обязательно отключите экранирование с помощью |safe. Во Flask 0.10 и выше это происходит автоматически.

Управление автоэскейпом¶

Автоэскейпинг - это концепция автоматического экранирования специальных символов. Специальные символы в смысле HTML (или XML, а значит и XHTML) - это &, >, <, ", а также '. Поскольку эти символы сами по себе несут специфическое значение в документах, вы должны заменить их так называемыми «сущностями», если хотите использовать их для текста. Если этого не сделать, то это не только вызовет разочарование пользователей из-за невозможности использовать эти символы в тексте, но и может привести к проблемам безопасности. (см. Межсайтовый скриптинг (XSS))

Однако иногда необходимо отключить автозавершение в шаблонах. Это может произойти, если вы хотите явно внедрить HTML в страницы, например, если они поступают из системы, которая генерирует безопасный HTML, например, из конвертера markdown в HTML.

Этого можно достичь тремя способами:

• В коде Python оберните строку HTML в объект Markup перед тем, как передать ее в шаблон. В целом это рекомендуемый способ.

• Внутри шаблона используйте фильтр |safe, чтобы явно пометить строку как безопасный HTML ({{ myvariable|safe }})

• Временно отключите систему автобегства.

Чтобы отключить систему автоэскейпа в шаблонах, можно использовать блок {% autoescape %}:

{% autoescape false %}
    <p>autoescaping is disabled here
    <p>{{ will_not_be_escaped }}
{% endautoescape %}

Когда бы вы это ни делали, пожалуйста, будьте очень осторожны с переменными, которые вы используете в этом блоке.

Регистрация фильтров¶

Если вы хотите зарегистрировать собственные фильтры в Jinja2, у вас есть два способа сделать это. Вы можете либо поместить их вручную в jinja_env приложения, либо использовать декоратор template_filter().

Два следующих примера работают одинаково и оба обращают объект:

@app.template_filter('reverse')
def reverse_filter(s):
    return s[::-1]

def reverse_filter(s):
    return s[::-1]
app.jinja_env.filters['reverse'] = reverse_filter

В случае декоратора аргумент необязателен, если вы хотите использовать имя функции в качестве имени фильтра. После регистрации вы можете использовать фильтр в своих шаблонах так же, как и встроенные фильтры Jinja2, например, если у вас есть список Python в контексте под названием mylist:

{% for x in mylist | reverse %}
{% endfor %}

Контекстные процессоры¶

Чтобы автоматически вводить новые переменные в контекст шаблона, во Flask существуют контекстные процессоры. Контекстные процессоры запускаются до отрисовки шаблона и имеют возможность вводить новые значения в контекст шаблона. Контекстный процессор - это функция, которая возвращает словарь. Ключи и значения этого словаря затем объединяются с контекстом шаблона для всех шаблонов в приложении:

@app.context_processor
def inject_user():
    return dict(user=g.user)

Приведенный выше контекстный процессор делает переменную user доступной в шаблоне со значением g.user. Этот пример не очень интересен, потому что g все равно доступна в шаблонах, но он дает представление о том, как это работает.

Переменные не ограничиваются значениями; контекстный процессор может также сделать функции доступными для шаблонов (поскольку Python позволяет передавать функции):

@app.context_processor
def utility_processor():
    def format_price(amount, currency=u'€'):
        return u'{0:.2f}{1}'.format(amount, currency)
    return dict(format_price=format_price)

Приведенный выше контекстный процессор делает функцию format_price доступной для всех шаблонов:

{{ format_price(0.33) }}

Вы также могли бы построить format_price как фильтр шаблона (см. Регистрация фильтров), но это демонстрирует, как передавать функции в контекстном процессоре.