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

Управляет поведением встроенного механизма автоматического экранирования символов (autoescape). Принимает в качестве аргумента одно из значений on или off (соответственно включить либо выключить экранирование внутри данного блока).

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

Действие этого тега не распространяется на переменные, отмеченные как «безопасные» для экранирования либо кодом, который присвоил значение этой переменной, либо посредством применения фильтров safe или escape.

Определяет блок, который может быть переопределен шаблонами-потомками. Подробнее см. «Наследование шаблонов».

Предписывает шаблонному процессору игнорировать все, что заключено между тегами {% comment %} и {% endcomment %}.

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

В версиях Джанго 1.1.X — тег-заглушка, возвращающий пустую строку для совместимости с будущими версиями. В версиях Джанго 1.2 и более поздних используется для защиты от подделки HTTP-запросов (см. документацию в разделе «Cross Site Request Forgeries»).

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

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

Внутри цикла каждый раз использует следующую из переданных строк:

{% for o in some_list %}
  <tr class="{% cycle 'row1' 'row2' %}">
    ...
  </tr>
{% endfor %}

Также можно использовать переменные. Например, если у вас есть две шаблонные переменные, rowvalue1 и rowvalue2, вы можете по очереди использовать их значения:

{% for o in some_list %}
  <tr class="{% cycle rowvalue1 rowvalue2 %}">
    ...
  </tr>
{% endfor %}

Да, в одном теге можно использовать и строки, и переменные:

{% for o in some_list %}
  <tr class="{% cycle 'row1' rowvalue2 'row3' %}">
    ...
  </tr>
{% endfor %}

В некоторых случаях вам может понадобиться использовать очередное значение циклической переменной вне цикла. Для этого требуется всего лишь дать имя тегу {% cycle %}, используя слово «as» следующим образом:

{% cycle 'row1' 'row2' as rowcolors %}

После такого объявления можно вставлять текущее значение цикла в любом месте шаблона:

<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>

В теге {% cycle %} можно указывать любое количество значений, разделенных пробелами. Значения, заключенные в одинарные (') или двойные (") кавычки, считаются строковыми литералами, а значения без кавычек — шаблонными переменными.

Обратите внимание, что переменные, переданные в цикл, при выводе не экранируются, поскольку по умолчанию теги не экранируют свое содержимое. Любой код (HTML или Javascript), переданный в переменной, будет выведен «как есть», что потенциально может привести к уязвимостям.

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

{% filter force_escape %}
  {% cycle var1 var2 var3 %}
{% endfilter %}

Для обратной совместимости тег {% cycle %} поддерживает устаревший ограниченный синтаксис из предыдущих версий Джанго. Не используйте старый синтаксис в своих новых проектах и на всякий случай посмотрите, как это было:

{% cycle row1,row2,row3 %}

В этом случае каждое значение интерпретируется как строковый литерал и вы никак не можете использовать переменные. И запятые внутри строк тоже не можете. Как и пробелы. Мы уже сказали вам не использовать этот синтаксис в новых проектах?

Выводит полный набор отладочной информации, включая текущий контекст и импортированные модули.

Сообщает, что данный шаблон является расширением родительского шаблона.

Используется двумя способами:

Подробнее см. «Наследование шаблонов».

Преобразует содержимое блока в соответствии с указанным фильтром.

Фильтры могут быть применены последовательно друг за другом и им могут быть переданы аргументы — так же, как в синтаксисе переменных.

Пример использования:

{% filter force_escape|lower %}
  Этот текст будет экранирован (для HTML) и приведен к нижнему регистру.
{% endfilter %}

Выводит первую переменную из переданных, которая не приводится к False. Не экранирует вывод. Если все переменные приводятся к False, не выводит ничего.

Пример использования:

{% firstof var1 var2 var3 %}

Это эквивалентно следующему коду:

{% if var1 %}
  {{ var1|safe }}
{% else %}{% if var2 %}
  {{ var2|safe }}
{% else %}{% if var3 %}
  {{ var3|safe }}
{% endif %}{% endif %}{% endif %}

Допускается использование строкового литерала в качестве запасного значения, если все переданные переменные приведутся к False:

{% firstof var1 var2 var3 "запасное значение" %}

Обратите внимание, что переменные, указанные в теге, при выводе не экранируются, поскольку теги сами по себе не экранируют свое содержимое. Любой код (HTML или Javascript), переданный в переменной, будет выведен как есть, что потенциально может привести к уязвимостям.

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

{% filter force_escape %}
  {% firstof var1 var2 var3 "запасное значение" %}
{% endfilter %}

Организует цикл по всем элементам переданного массива (итератора). Например, выведем данные об атлетах, перечисленных в списке athlete_list:

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

Можно указать обратный порядок прохождения массива, используя конструкцию {% for obj in list reversed %}.

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

Если элементами перебираемого списка являются тоже списки, их можно распаковывать в отдельные переменные. Допустим, каждый элемент списка представляет собой пару координат (x,y), описывающих точки, тогда вы можете вывести список этих точек следующим образом:

{% for x, y in points %}
  Имеется точка с координатами {{ x }},{{ y }}
{% endfor %}

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

{% for key, value in data.items %}
  {{ key }}: {{ value }}
{% endfor %}

Цикл for определяет несколько переменных, доступных внутри цикла:

Добавлено с 1.1.

Тег for может содержать необязательную ветвь {% empty %}, которая будет выведена, если указанный массив пуст либо не найден:

<ul>
  {% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
  {% empty %}
    <li>Извините, в списке нет атлетов.</li>
  {% endfor %}
<ul>

Этот код делает то же самое, что и нижеприведенный, однако он короче, проще и порой быстрее:

<ul>
  {% if athlete_list %}
    {% for athlete in athlete_list %}
      <li>{{ athlete.name }}</li>
    {% endfor %}
  {% else %}
    <li>Извините, в списке нет атлетов.</li>
  {% endif %}
</ul>

Тег {% if %} вычисляет значение переменной и, если эта переменная приводится к True (т.е. существует, не является пустой и не равна логическому значению false), выводит содержимое блока между {% if %} и {% endif %}:

{% if athlete_list %}
  Число атлетов: {{ athlete_list|length }}
{% else %}
  Атлетов нет.
{% endif %}

В описанном случае, если массив athlete_list не пуст, переменная {{ athlete_list|length }} выведет число атлетов (длину массива).

Как вы уже увидели, тег if может иметь необязательную ветвь {% else %}, которая будет выведена, если условие не соблюдено.

{% if athlete_list and coach_list %}
  Есть и атлеты, и тренеры.
{% endif %}

{% if not athlete_list %}
  Атлетов нет.
{% endif %}

{% if athlete_list or coach_list %}
  Кто-то из атлетов или тренеров точно есть.
{% endif %}

{% if not athlete_list or coach_list %}
  То ли нет атлетов, то ли есть тренеры (ну да, перевод
  с логического на русский выглядит довольно глупо,
  но мы не виноваты).
{% endif %}

{% if athlete_list and not coach_list %}
  Есть несколько атлетов и ни одного тренера.
{% endif %}

{% if athlete_list and coach_list or cheerleader_list %}

if (athlete_list and coach_list) or cheerleader_list

{% if somevar == "x" %}
  Это предложение будет выведено, если переменная somevar равна строке "x"
{% endif %}

{% if somevar != "x" %}
  Это предложение будет выведено, если переменная somevar не равна строке "x"
  или вообще не найдена в контексте.
{% endif %}

{% if somevar < 100 %}
  Это предложение будет выведено, если переменная somevar меньше 100.
{% endif %}

{% if somevar > 0 %}
  Это предложение будет выведено, если переменная somevar больше 0.
{% endif %}

{% if somevar <= 100 %}
  Это предложение будет выведено, если переменная somevar меньше или равна 100.
{% endif %}

{% if somevar >= 1 %}
  Это предложение будет выведено, если переменная somevar больше или равна 1.
{% endif %}

{% if "bc" in "abcdef" %}
  Это предложение выводится, поскольку "bc" является подстрокой "abcdef"
{% endif %}

{% if "hello" in greetings %}
  Если greetings представляет собой список или множество, одним из
  элементов которого является "hello", это предложение будет выведено.
{% endif %}

{% if user in users %}
  Если users представляет собой множество типа QuerySet, это предложение
  будет выведено, если экземпляр user входит в это множество.
{% endif %}

{% if a > b > c %}  (WRONG)

{% if a > b and b > c %}

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

{% if messages|length >= 100 %}
  Сегодня у вас туча сообщений!
{% endif %}

Все вышеперечисленные операторы можно объединять в составные выражения. В этом случае важно учитывать порядок действий выражений (даны в порядке возрастания приоритета):

(Точно так же, как и в Python). Таким образом, тег if в следующем примере:

                   {% if a == b or c == d and e %}

... будет интерпретирован как:

                   (a == b) or ((c == d) and e)

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

Проверяет, изменилось ли значение переменной на очередной итерации цикла.

Блочный тег ifchanged используется внутри циклов и имеет два варианта применения.

Выводит содержимое блока, если два переданных аргумента равны.

Пример:

{% ifequal user.id comment.user_id %}
  ...
{% endifequal %}

Как и с тегом {% if %} , можно использовать необязательную ветвь {% else %}.

Аргументы могут быть строковыми константами, то есть возможен такой вариант:

{% ifequal user.username "adrian" %}
  ...
{% endifequal %}

Аргументы сравниваются только с переменными шаблона или со строковыми константами. Нельзя проверить переменную на равенство с Python-объектами типа True или False. Если вам нужно проверить истинность или ложность переменной, лучше примените для этого тег if.

Добавлено с 1.2.

Альтернативой тегу ifequal является использование тега if с оператором ==.

То же самое, что и ifequal, только проверяет аргументы на неравенство.

Добавлено с 1.2.

Альтернативой тегу ifnotequal является использование тега if с оператором !=.

Загружает шаблон и обрабатывает его в текущем контексте. Таким способом можно «включать» другие шаблоны в данный шаблон.

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

В следующем примере подключается содержимое шаблона "foo/bar.html":

{% include "foo/bar.html" %}

А в этом примере подключается содержимое шаблона, имя которого содержит переменная template_name:

{% include template_name %}

Включенный шаблон обрабатывается с учетом контекста шаблона, в который он включен. Следующий пример выводит "Hello, John":

См. также: {% ssi %}.

Загружает набор пользовательских тегов.

Подробнее см. «Библиотеки пользовательских тегов и фильтров».

Выводит текущую дату, отформатированную в соответствии с указанной строкой.

Использует несколько расширенный формат PHP-функции date() (http://php.net/date).

Пример:

Сейчас {% now "jS F Y H:i" %}

Обратите внимание на необходимость экранировать буквы, входящие в набор символов формата, если они являются частью текста. В примере ниже буква «f» экранирована обратным слэшем, поскольку иначе будет восприниматься как символ формата, выводящий время. Букву «o» экранировать не требуется, поскольку она не относится к символам форматирования:

It is the {% now "jS o\f F" %}

Такой код выведет:

It is the 4th of September

Группирует список похожих элементов по одинаковому признаку.

Действие этого составного тега проще объяснить на примере: допустим, переменная people является списком людей, каждый из которых представлен словарем с ключами first_name, last_name и gender:

people = [
  {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
  {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
  {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
  {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
  {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
]

... и вы хотите вывести двухуровневый список, сгруппировав людей по полу, например, вот так:

* Male:
* George Bush
* Bill Clinton
* Female:
* Margaret Thatcher
* Condoleezza Rice
* Unknown:
* Pat Smith

Это можно сделать при помощи тега {% regroup %}. Код шаблона для этой операции показан ниже:

{% regroup people by gender as gender_list %}

<ul>
  {% for gender in gender_list %}
    <li>{{ gender.grouper }}
      <ul>
        {% for item in gender.list %}
          <li>{{ item.first_name }} {{ item.last_name }}</li>
        {% endfor %}
      </ul>
    </li>
  {% endfor %}
</ul>

Рассмотрим этот пример подробнее. Тег {% regroup %} принимает три аргумента: список для группировки, признак, по которому нужно сгруппировать элементы, и имя полученного списка. В данном случае мы группируем список people по атрибуту gender и полученный результат называем gender_list.

Результатом работы {% regroup %} является список (в данном случае — gender_list) групповых объектов. У каждого группового объекта есть два атрибута:

Имейте в виду, что {% regroup %} не упорядочивает обрабатываемый список! В нашем примере мы предполагаем, что список people был изначально упорядочен по атрибуту gender. Если элементы списка people не упорядочены по атрибуту gender, перегруппировка простодушно покажет несколько групп для одного и того же пола. Допустим, что наш список people изначально был вот таким (заметьте, что в этом списке мужчины не находятся рядом):

people = [
  {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
  {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
  {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
  {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
  {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
]

При таком значении переменной people, вышеприведенный пример шаблона с тегом {% regroup %} выдаст следующее:

* Male:
* Bill Clinton
* Unknown:
* Pat Smith
* Female:
* Margaret Thatcher
* Male:
* George Bush
* Female:
* Condoleezza Rice

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

Если нужные данные представлены в виде списка словарей, то можно отсортировать данные прямо в шаблоне, применив фильтр dictsort:

{% regroup people|dictsort:"gender" by gender as gender_list %}

Удаляет пробельные символы между HTML-тегами, в т.ч. символы табуляции и новой строки.

Пример использования:

{% spaceless %}
  <p>
    <a href="foo/">Foo</a>
  </p>
{% endspaceless %}

Этот шаблон выведет следующий HTML-код:

<p><a href="foo/">Foo</a></p>

Удаляются только пробелы между тегами, пробелы между тегами и текстом не удаляются. В следующем примере, пробелы вокруг слова Hello останутся нетронутыми:

{% spaceless %}
  <strong>
    Hello
  </strong>
{% endspaceless %}

Выводит на страницу содержимое указанного файла.

Подобно тегу include, {% ssi %} включает в данную страницу содержимое другого файла (указанный путь к файлу должен быть абсолютным):

{% ssi /home/html/ljworld.com/includes/right_generic.html %}

Если указан необязательный параметр parsed, содержимое указанного файла обрабатывается как шаблон с использованием текущего контекста:

{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}

Перед применением тега {% ssi %} в целях безопасности необходимо определить константу ALLOWED_INCLUDE_ROOTS в настройках Джанго.

См. также тег {% include %}.

Выводит одну из последовательностей символов, используемых для указания тегов в шаблоне.

Поскольку в шаблонной системе Джанго не предусмотрено понятие «экранирования», то для вывода последовательности символов, используемых для указания тегов в шаблоне, нужно использовать тег {% templatetag %}.

Аргумент тега указывает, какую именно последовательность символов нужно вывести:

Возвращает абсолютный URL (т.е. URL без имени домена), соответствующий указанной функции представления и необязательным параметрам. Использование этого тега позволяет выводить ссылки, не нарушая принцип DRY указанием конкретных ссылок в шаблонах:

{% url path.to.some_view v1 v2 %}

Первый аргумент тега — путь к функции представления в виде package.package.module.function. Остальные аргументы необязательны и представляют собой разделенные пробелами значения аргументов для указанного URL. Пример выше показывает передачу позиционных аргументов функции. Можно также передавать именованные аргументы:

{% url path.to.some_view arg1=v1 arg2=v2 %}

Не используйте позиционные и именованные аргументы в одном вызове. Обязательно указывайте все аргументы, требуемые в схеме URL.

Рассмотрим пример. Допустим, у вас есть функция представления app_views.client, схема URL которой принимает ID клиента (в данном случае, client() — это метод в файле представлений app_views.py). Соответствующая строка в схеме URL может выглядеть так:

('^client/(\d+)/$', 'app_views.client')

Если схема URL данного приложения включена в схему URL всего проекта подобным образом:

('^clients/', include('project_name.app_name.urls'))

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

{% url app_views.client client.id %}

Тег шаблона выведет строку /clients/client/123/.

Добавлено с 1.0.

В случае использования именованных URL-паттернов вместо указания пути к функции представления достаточно сослаться на имя паттерна в теге url.

Имейте в виду, что если URL, который вы пытаетесь вычислить, не существует, Джанго вызовет исключение NoReverseMatch, что приведет к отображению страницы ошибки вашего сайта.

Если вам требуется получить URL, не отображая его, немного измените вызов тега:

{% url path.to.view arg arg2 as the_url %}

<a href="{{ the_url }}">Я ссылаюсь на {{ the_url }}</a>

Синтаксис {% url ... as var %} не вызывает ошибку, если искомое представление отсутствует. На практике можно использовать такой вызов для ссылки на необязательные представления:

{% url path.to.view as the_url %}
{% if the_url %}
  <a href="{{ the_url }}">Ссылка на что-нибудь необязательное</a>
{% endif %}

Добавлено с 1.1.

Если вам нужно получить URL в определенном пространстве имен, укажите полное имя представления:

{% url myapp:view-name %}

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

Добавлено с 1.2.

Для обратной совместимости тег {% url %} поддерживает использование запятой для разделения аргументов. Не используйте этот синтаксис в новых проектах и на всякий случай посмотрите, как это выглядело:

{% url path.to.view arg,arg2 %}
{% url path.to.view arg, arg2 %}

В этом случае нельзя использовать внутри строковых аргументов запятые и знаки равенства. Мы уже сказали вам не использовать этот синтаксис в новых проектах?

Для создания диаграмм и т.п. рассчитывает отношение текущего значения к максимальному и применяет это отношение к указанной константе.

Пример:

<img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />

Если this_value равно 175, а max_value равно 200, то ширина рисунка «bar.gif» будет 88 точек (поскольку 175/200 = .875; .875 * 100 = 87.5, округленно 88).

Добавлено с 1.0.

Кэширует составную переменную под отдельным именем. Полезно в случаях многократного обращения к «дорогостоящему» методу (использующему вычислительные ресурсы, например, доступ к базе данных).

Пример:

{% with business.employees.count as total %}
  {{ total }} employee{{ total|pluralize }}
{% endwith %}

Переменная, получившая значение (в данном примере total), доступна только между тегами {% with %} и {% endwith %}.