Язык шаблонов 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

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

{{ 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 поставляется примерно с двумя десятками встроенных тегов шаблонов. Подробнее о них читайте в справочнике по встроенным тегам. Вот несколько наиболее часто используемых тегов:

for

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

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

if, elif, and else

Вычисляет переменную и, если её значение истинно, отображает содержимое блока:

{% 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 не пуст, будет выведено сообщение «Спортсмены должны выйти…». Если оба списка пусты, будет выведено «Спортсменов нет.»

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

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

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

block and 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 }} это может стать эффективным способом внести небольшие изменения. Полный пример см. в разделе Расширение переопределённого шаблона руководства Переопределение шаблонов.

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

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

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

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

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

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

  {% if change_title %}
      {% block title %}Hello!{% endblock title %}
  {% endif %}
  

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

Фрагменты шаблонов

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

{% partialdef user-info %}
    <div id="user-info-{{ user.username }}">
        <h3>{{ user.name }}</h3>
        <p>{{ user.bio }}</p>
    </div>
{% endpartialdef %}

{% partialdef user-info %}
    {# ... #}
{% endpartialdef user-info %}

{% partial user-info %}

{% block content %}
    <h2>Authors</h2>
    {% for user in authors %}
        {% partial user-info %}
    {% endfor %}

    <h2>Editors</h2>
    {% for user in editors %}
        {% partial user-info %}
    {% endfor %}
{% endblock %}

{# Define and render immediately. #}
{% partialdef user-info inline %}
    <div id="user-info-{{ user.username }}">
        <h3>{{ user.name }}</h3>
        <p>{{ user.bio }}</p>
    </div>
{% endpartialdef %}

{# Other page content here. #}

{# Reuse later elsewhere in the template. #}
<section class="featured-authors">
    <h2>Featured Authors</h2>
    {% for user in featured %}
        {% partial user-info %}
    {% endfor %}
</section>

from django.contrib.auth.models import User
from django.shortcuts import get_object_or_404, render


def user_info_partial(request, user_id):
    user = get_object_or_404(User, id=user_id)
    return render(request, "authors.html#user-info", {"user": user})

{% include "authors.html#user-info" %}

{% for user in users %}
    {% partial user-info %}
{% endfor %}

{% with user=featured_author %}
    <h2>Featured Author of the Month</h2>
    {% partial user-info %}
{% endwith %}

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

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

Hello, {{ name }}

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

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

При таком значении имени результат обработки шаблона будет выглядеть так:

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

…и браузер выведет диалоговое окно JavaScript alert!

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

<b>username

В результате обработки шаблона получится следующее:

Hello, <b>username

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

Очевидно, нельзя безоговорочно доверять данным, введённым пользователем, и напрямую вставлять их на веб-страницы: злоумышленник может воспользоваться этой уязвимостью и причинить вред. Такая уязвимость называется межсайтовым скриптингом (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. #}

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

Большинство методов объектов также доступны из шаблонов. Это означает, что шаблоны могут обращаться не только к атрибутам классов (например, именам полей) и переменным, переданным из представлений. Например, ORM Django предоставляет синтаксис «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 %}

Информацию о том, как создавать собственные библиотеки шаблонов, см. в разделе Как создавать пользовательские теги и фильтры шаблонов.