Язык шаблонов Django¶

Шаблоны¶

Шаблон - это текстовый файл. Он может генерировать любой текстовый формат (HTML, XML, CSV и т.д.).

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

Ниже приведен минимальный шаблон, иллюстрирующий некоторые основы. Каждый элемент будет объяснен позже в этом документе.

{% extends "base_generic.html" %}

{% block title %}{{ section.title }}{% endblock %}

{% block content %}
<h1>{{ section.title }}</h1>

{% for story in story_list %}
<h2>
  <a href="{{ story.get_absolute_url }}">
    {{ story.headline|upper }}
  </a>
</h2>
<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

Переменные¶

Переменные выглядят так: {{ variable }}. Когда механизм шаблонов встречает переменную, он оценивает эту переменную и заменяет ее результатом. Имена переменных состоят из любой комбинации буквенно-цифровых символов и символа подчеркивания ("_"), но не могут начинаться с подчеркивания и не могут быть числом. Точка (".") также появляется в разделах переменных, хотя это имеет особое значение, как указано ниже. Важно отметить, что в именах переменных нельзя использовать пробелы или знаки препинания.

Используйте точку (.) Для доступа к атрибутам переменной.

{% for k, v in defaultdict.items %}
    Do something with k and v here...
{% endfor %}

В приведенном выше примере {{section.title}} будет заменен атрибутом title объекта section.

Если вы используете переменную, которой не существует, система шаблонов вставит значение параметра string_if_invalid, который по умолчанию установлен на '' (пустая строка).

Обратите внимание, что «bar» в шаблонном выражении типа {{ foo.bar }} будет интерпретироваться как литеральная строка, а не как значение переменной «bar», если таковая существует в контексте шаблона.

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

Фильтры¶

Вы можете изменять переменные для отображения с помощью фильтров.

Фильтры выглядят так: {{ name|lower }}. Это отображает значение переменной {{ name }} после фильтрации с помощью фильтра lower, который преобразует текст в нижний регистр. Используйте вертикальную черту (|), чтобы применить фильтр.

Фильтры можно «связать». Выходные данные одного фильтра применяются к следующему. {{ text|escape|linebreaks }} - распространенная идиома для экранирования текстового содержимого с последующим преобразованием разрывов строк в теги <p>.

Некоторые фильтры принимают аргументы. Аргумент фильтра выглядит так: {{ bio|truncatewords:30 }}. Это отобразит первые 30 слов переменной bio.

Аргументы фильтра, содержащие пробелы, должны быть заключены в кавычки; например, чтобы присоединиться к списку с запятыми и пробелами, вы должны использовать {{ list|join:", " }}.

Django предоставляет около шестидесяти встроенных шаблонных фильтров. Вы можете прочитать все о них в справочнике по встроенным фильтрам. Чтобы дать вам представление о том, что доступно, вот некоторые из наиболее часто используемых шаблонных фильтров:

default

Если переменная ложна или пуста, используйте данное значение по умолчанию. В противном случае используйте значение переменной. Например:

{{ value|default:"nothing" }}

Если value не указано или пусто, в приведенном выше сообщении будет отображаться значение «nothing».

length

Возвращает длину значения. Это работает как для строк, так и для списков. Например:

{{ value|length }}

Если value равно ['a', 'b', 'c', 'd ], на выходе будет 4.

filesizeformat

Форматирует значение как «удобочитаемый» размер файла (например, '13 KB', '4.1 MB', '102 bytes' и т.д.). Например:

{{ value|filesizeformat }}

Если value равно 123456789, то на выходе будет 117.7 MB.

Опять же, это всего лишь несколько примеров; смотрите справочник по встроенным фильтрам для получения полного списка.

Вы также можете создавать свои собственные фильтры шаблонов; смотрите Как создавать пользовательские теги и фильтры шаблонов.

Тэги¶

Теги выглядят так: {% tag %}. Теги более сложны, чем переменные: некоторые создают текст в выходных данных, некоторые управляют потоком, выполняя циклы или логику, а некоторые загружают внешнюю информацию в шаблон для использования последующими переменными.

Для некоторых тегов требуются начальные и конечные теги (например, {% tag %} ... tag contents ... {% endtag %}).

Django поставляется с двумя десятками встроенных тегов шаблонов. Вы можете прочитать все о них в справочнике по встроенным тегам <ref-templates-builtins-tags>. Чтобы дать вам представление о том, что доступно, вот некоторые из наиболее часто используемых тегов:

for

Перебераеи каждый элемент в массиве. Например, чтобы отобразить список спортсменов, представленный в athlete_list:

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% endfor %}
</ul>

if, elif, и else

Оценивает переменную, и если эта переменная имеет значение «true», отображается содержимое блока:

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% elif athlete_in_locker_room_list %}
    Athletes should be out of the locker room soon!
{% else %}
    No athletes.
{% endif %}

В приведенном выше примере, если athlete_list не пуст, количество спортсменов будет отображаться переменной {{ athlete_list|length }}. В противном случае, если athlete_in_locker_room_list не пуст, будет отображено сообщение «Athletes should be out…». Если оба списка пусты, будет отображаться «No athletes.».

Вы также можете использовать фильтры и различные операторы в теге if:

{% if athlete_list|length > 1 %}
   Team: {% for athlete in athlete_list %} ... {% endfor %}
{% else %}
   Athlete: {{ athlete_list.0.name }}
{% endif %}

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

block и extends

Настройте наследование шаблонов (смотрите ниже), мощный способ сократить количество лишних повторений в шаблонах.

Опять же, приведенное выше - это лишь выборка всего списка; смотрите полный список справочник по встроенным тегам.

Вы также можете создавать собственные настраиваемые теги шаблонов; смотрите Как создавать пользовательские теги и фильтры шаблонов.

Коментарі¶

Чтобы закомментировать часть строки в шаблоне, используйте синтаксис комментария: {# #}.

Например, этот шаблон будет отображаться как 'hello':

{# greeting #}hello

Комментарий может содержать любой код шаблона, недействительный или нет. Например:

{# {% if foo %}bar{% else %} #}

Этот синтаксис можно использовать только для однострочных комментариев (символы новой строки между разделителями {# и #} не допускаются). Если вам нужно закомментировать многострочную часть шаблона, смотрите тег comment.

Наследование шаблона¶

Самая мощная и, следовательно, самая сложная часть шаблонизатора Django - это наследование шаблонов. Наследование шаблонов позволяет вам создать базовый «скелетный» шаблон, который содержит все общие элементы вашего сайта и определяет блоки, которые дочерние шаблоны могут переопределить.

Давайте посмотрим на наследование шаблонов, начав с примера:

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="style.css">
    <title>{% block title %}My amazing site{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        {% endblock %}
    </div>

    <div id="content">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

Этот шаблон, который мы назовем base.html, определяет скелет HTML-документа, который вы можете использовать для страницы с двумя столбцами. Задача «дочерних» шаблонов - заполнить пустые блоки содержимым.

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

Дочерний шаблон может выглядеть так:

{% extends "base.html" %}

{% block title %}My amazing blog{% endblock %}

{% block content %}
{% for entry in blog_entries %}
    <h2>{{ entry.title }}</h2>
    <p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}

Тег extends является здесь ключевым. Он сообщает механизму шаблонов, что этот шаблон «расширяет» другой шаблон. Когда система шаблонов оценивает этот шаблон, сначала она находит родительский объект - в данном случае «base.html».

В этот момент механизм шаблонов заметит три тега block в base.html и заменит эти блоки содержимым дочернего шаблона. В зависимости от значения blog_entries вывод может выглядеть так:

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="style.css">
    <title>My amazing blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
    </div>

    <div id="content">
        <h2>Entry one</h2>
        <p>This is my first entry.</p>

        <h2>Entry two</h2>
        <p>This is my second entry.</p>
    </div>
</body>
</html>

Обратите внимание, что, поскольку дочерний шаблон не определил блок sidebar, вместо него используется значение из родительского шаблона. Контент внутри тега {% block %} в родительском шаблоне всегда используется в качестве запасного варианта.

Вы можете использовать столько уровней наследования, сколько необходимо. Один из распространенных способов использования наследования - это следующий трехуровневый подход:

• Создайте шаблон base.html, который будет содержать основной внешний вид вашего сайта.
• Создайте шаблон base_SECTIONNAME.html для каждого раздела вашего сайта. Например, base_news.html, base_sports.html. Все эти шаблоны расширяют файл base.html и включают стили/дизайн для конкретных разделов.
• Создавайте индивидуальные шаблоны для каждого типа страницы, например для новостной статьи или записи в блоге. Эти шаблоны расширяют соответствующий шаблон раздела.

Такой подход максимизирует повторное использование кода и помогает добавлять элементы в области общего содержимого, например навигацию по разделу.

Вот несколько советов по работе с наследованием:

• Если вы используете {% extends %} в шаблоне, это должен быть первый тег шаблона в этом шаблоне. В противном случае наследование шаблонов работать не будет.

• Чем больше {% block %} в ваших базовых шаблонах - тем лучше. Помните, что дочерние шаблоны не обязательно должны определять все родительские блоки, поэтому вы можете указать разумные значения по умолчанию в нескольких блоках, а затем определять только те, которые вам понадобятся позже. Лучше иметь больше частей для обработки, чем меньше.

• Если вы обнаружите, что дублируете контент в нескольких шаблонах, это, вероятно, означает, что вам следует переместить этот контент в {% block %} в родительском шаблоне.

• Если вам нужно получить содержимое блока из родительского шаблона, переменная {{ block.super }} поможет. Это полезно, если вы хотите добавить к содержимому родительского блока, а не полностью его переопределить. Данные, вставленные с использованием {{ block.super }}, не будут автоматически экранированы (смотрите следующий раздел), поскольку они уже были экранированы, если необходимо, в родительском шаблоне.

• Используя то же имя шаблона, от которого вы наследуете, {% extends %} может использоваться для наследования шаблона одновременно с его переопределением. В сочетании с {{ block.super }} это может быть мощным способом внесения небольших настроек. Смотрите exnding_an_overridden_template в Переопределении шаблонов Практического руководства для полного примера.

• Переменные, созданные вне {% block %} с использованием синтаксиса тега шаблона as, не могут использоваться внутри блока. Например, этот шаблон ничего не отображает:

  {% translate "Title" as title %}
  {% block content %}{{ title }}{% endblock %}
  

• Для большей удобочитаемости вы можете дополнительно присвоить имя своему тегу {% endblock %}. Например:

  {% block content %}
  ...
  {% endblock content %}
  

  В более крупных шаблонах этот метод помогает увидеть, какие теги {% block %} закрываются.

Наконец, обратите внимание, что вы не можете определить несколько тегов block с одинаковыми именами в одном шаблоне. Это ограничение существует, потому что тег блока работает «в обоих» направлениях. То есть тег блока не просто предоставляет дыру для заполнения - он также определяет контент, который заполняет дыру в родительском. Если бы в шаблоне было два тега block с одинаковыми именами, родительский элемент этого шаблона не знал бы, какой из содержимого блоков использовать.

Автоматическое экранирование HTML¶

При создании HTML из шаблонов всегда существует риск того, что переменная будет включать символы, влияющие на результирующий HTML. Например, рассмотрим этот фрагмент шаблона:

Hello, {{ name }}

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

<script>alert('hello')</script>

С этим значением имени шаблон будет отображаться как:

Hello, <script>alert('hello')</script>

…это означает, что в браузере появится всплывающее окно с предупреждением JavaScript!

Точно так же, что, если имя содержит символ '<', как это?

<b>username

В результате получится такой шаблон, как этот:

Hello, <b>username

…что, в свою очередь, приведет к тому, что остальная часть веб-страницы будет выделена жирным шрифтом!

Очевидно, что данным, переданным пользователем, не следует доверять вслепую и вставлять их непосредственно в веб-страницы, поскольку злоумышленник может использовать такую брешь для совершения потенциально плохих действий. Этот тип атаки безопасности называется Cross Site Scripting (XSS).

Чтобы избежать этой проблемы, у вас есть два варианта:

• Во-первых, вы можете убедиться, что каждая ненадежная переменная пропущена через фильтр escape (описанный ниже), который преобразует потенциально опасные символы HTML в опасные. Это было решение по умолчанию в Django в течение первых нескольких лет, но проблема в том, что оно возлагает бремя на вас, разработчика/автора шаблона, чтобы гарантировать, что вы избегаете всего. Легко забыть экранировать данные.
• Во-вторых, вы можете воспользоваться автоматическим экранированием HTML в Django. В оставшейся части этого раздела описывается, как работает автоматическое экранирование.

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

• < преобразуется в <
• > преобразуется в >
• ' (одинарная кавычка) конвертируется в '
• " (двойная кавычка) преобразуется в "
• & преобразуется в &

Опять же, мы подчеркиваем, что это поведение включено по умолчанию. Если вы используете систему шаблонов Django, вы защищены.

This will be escaped: {{ data }}
This will not be escaped: {{ data|safe }}

This will be escaped: <b>
This will not be escaped: <b>

{% autoescape off %}
    Hello {{ name }}
{% endautoescape %}

Auto-escaping is on by default. Hello {{ name }}

{% autoescape off %}
    This will not be auto-escaped: {{ data }}.

    Nor this: {{ other_data }}
    {% autoescape on %}
        Auto-escaping applies again: {{ name }}
    {% endautoescape %}
{% endautoescape %}

{% autoescape off %}
<h1>{% block title %}{% endblock %}</h1>
{% block content %}
{% endblock %}
{% endautoescape %}

{% extends "base.html" %}
{% block title %}This & that{% endblock %}
{% block content %}{{ greeting }}{% endblock %}

<h1>This &amp; that</h1>
<b>Hello!</b>

{{ data|default:"This is a string literal." }}

{{ data|default:"3 < 2" }}

{{ data|default:"3 < 2" }}  {# Bad! Don't do this. #}

Доступ к вызовам методов¶

Большинство вызовов методов, прикрепленных к объектам, также доступны из шаблонов. Это означает, что шаблоны имеют доступ к гораздо большему, чем просто атрибуты класса (например, имена полей) и переменные, передаваемые из представлений. Например, Django ORM предоставляет синтаксис «entry_set» для поиска коллекции объектов, связанных с внешним ключом. Следовательно, учитывая модель под названием «comment» с отношением внешнего ключа к модели под названием «task», вы можете просмотреть все комментарии, прикрепленные к данной задаче, следующим образом:

{% for comment in task.comment_set.all %}
    {{ comment }}
{% endfor %}

Аналогичным образом QuerySets предоставляет метод count() для подсчета количества содержащихся в них объектов. Следовательно, вы можете получить количество всех комментариев, относящихся к текущей задаче, с помощью:

{{ task.comment_set.all.count }}

Вы также можете получить доступ к методам, которые вы явно определили в своих собственных моделях:

class Task(models.Model):
    def foo(self):
        return "bar"

{{ task.foo }}

Поскольку Django намеренно ограничивает объем логической обработки, доступной в языке шаблонов, невозможно передавать аргументы в вызовы методов, доступные из шаблонов. Данные должны вычисляться в представлениях, а затем передаваться в шаблоны для отображения.

Пользовательские библиотеки тегов и фильтров¶

Некоторые приложения предоставляют настраиваемые библиотеки тегов и фильтров. Чтобы получить к ним доступ в шаблоне, убедитесь, что приложение находится в INSTALLED_APPS (в этом примере мы добавили бы django.contrib.humanize), а затем используйте тег load в шаблоне:

{% load humanize %}

{{ 45000|intcomma }}

В приведенном выше примере тег load загружает библиотеку тегов humanize, которая затем делает фильтр intcomma доступным для использования. Если вы включили django.contrib.admindocs, вы можете проконсультироваться в области документации в вашей админке, чтобы найти список настраиваемых библиотек в вашей установке.

Тег load может принимать несколько имен библиотек, разделенных пробелами. Пример:

{% load humanize i18n %}

Смотрите Как создавать пользовательские теги и фильтры шаблонов для получения информации о написании собственных библиотек пользовательских шаблонов.