Встроенные теги и фильтры

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

Справочник по встроенным тегам

autoescape
Управляет текущим автоматическим экранированием. Этот тег принимает в качестве аргумента либо on, либо off и определяет, действует ли автоматическое экранирование внутри блока. Блок закрывается конечным тегом endautoescape.

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

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

Образец использования:

{% autoescape on %}
{{ body }}
{% endautoescape %}
block
Определяет блок, который может быть переопределен дочерними шаблонами. Смотрите Наследование шаблонов для получения дополнительной информации.

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

Образец использования:

<p>Rendered text with {{ pub_date|date:"c" }}</p>
{% comment "Optional note" %}
<p>Commented out text with {{ create_date|date:"c" }}</p>
{% endcomment %}
Теги comment не могут быть вложенными.

csrf_token
Этот тег используется для защиты CSRF, как описано в документации для Подделки межсайтовых запросов.

cycle
Производит один из своих аргументов каждый раз, когда встречается этот тег. Первый аргумент возникает при первой встрече, второй аргумент - при второй встрече и так далее. Как только все аргументы исчерпаны, тег циклически переходит к первому аргументу и производит его снова.

Этот тег особенно полезен в цикле:

{% for o in some_list %}
<tr class="{% cycle 'row1' 'row2' %}">
...
</tr>
{% endfor %}
Первая итерация создает HTML-код, который ссылается на класс row1, второй - на row2, третий снова на row1 и так далее для каждой итерации цикла.

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

{% for o in some_list %}
<tr class="{% cycle rowvalue1 rowvalue2 %}">
...
</tr>
{% endfor %}
Переменные, включенные в цикл, будут экранированы. Вы можете отключить автоматическое экранирование с помощью:

{% for o in some_list %}
<tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">
...
</tr>
{% endfor %}
Вы можете смешивать переменные и строки:

{% for o in some_list %}
<tr class="{% cycle 'row1' rowvalue2 'row3' %}">
...
</tr>
{% endfor %}
В некоторых случаях вы можете захотеть обратиться к текущему значению цикла без перехода к следующему значению. Для этого дайте тегу {% cycle %} имя, используя «as», например, так:

{% cycle 'row1' 'row2' as rowcolors %}
С этого момента вы можете вставить текущее значение цикла в любое место вашего шаблона, указав имя цикла как контекстную переменную. Если вы хотите переместить цикл к следующему значению независимо от исходного тега cycle, вы можете использовать другой тег cycle и указать имя переменной. Итак, следующий шаблон:

<tr>
<td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
<tr>
<td class="{% cycle rowcolors %}">...</td>
<td class="{{ rowcolors }}">...</td>
</tr>
выведет:

<tr>
<td class="row1">...</td>
<td class="row1">...</td>
</tr>
<tr>
<td class="row2">...</td>
<td class="row2">...</td>
</tr>
В теге цикла можно использовать любое количество значений, разделенных пробелами. Значения, заключенные в одинарные кавычки (') или двойные кавычки ("), обрабатываются как строковые литералы, а значения без кавычек обрабатываются как переменные шаблона.

По умолчанию, когда вы используете ключевое слово as с тегом цикла, использование {% cycle %}, которое запускает цикл, само генерирует первое значение в цикле. Это может быть проблемой, если вы хотите использовать значение во вложенном цикле или во включенном шаблоне. Если вы хотите только объявить цикл, но не вывести первое значение, вы можете добавить ключевое слово silent в качестве последнего ключевого слова в теге. Например:

{% for obj in some_list %}
{% cycle 'row1' 'row2' as rowcolors silent %}
<tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
{% endfor %}
Это выведет список элементов <tr>, где class чередуется между row1 и row2. Подшаблон будет иметь доступ к rowcolors в своем контексте, а значение будет соответствовать классу окружающего его элемента <tr>. Если бы ключевое слово silent было опущено, row1 и row2 были бы выданы как обычный текст, за пределами элемента <tr>.

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

{% cycle 'row1' 'row2' as rowcolors silent %}
{% cycle rowcolors %}
Вы можете использовать тег resetcycle, чтобы перезапустить тег {% cycle %} с его первого значения, когда он встретится в следующий раз.

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

extends
Сигнализирует, что этот шаблон расширяет родительский шаблон.

Этот тег можно использовать двумя способами:

{% extends "base.html" %} (в кавычках) использует буквальное значение "base.html" в качестве имени родительского шаблона для расширения.
{% extends variable %} использует значение variable. Если переменная вычисляется как строка, Django будет использовать эту строку как имя родительского шаблона. Если переменная оценивается как объект Template, Django будет использовать этот объект в качестве родительского шаблона.
Смотрите Наследование шаблона для получения дополнительной информации.

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

dir1/
template.html
base2.html
my/
base3.html
base1.html
В шаблоне template.html допустимы следующие пути:

{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}
filter
Фильтрует содержимое блока с помощью одного или нескольких фильтров. С помощью конвейеров можно указать несколько фильтров, а фильтры могут иметь аргументы, как и в синтаксисе переменных.

Обратите внимание, что блок включает весь текст между тегами filter и endfilter.

Образец использования:

{% filter force_escape|lower %}
This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}
Примечание

Фильтры escape и :filter:`safe` не являются приемлемыми аргументами. Вместо этого используйте тег autoescape для управления автоматическим экранированием блоков кода шаблона.

firstof
Выводит первую переменную аргумента, которая не является «ложной» (т.е. существует, не пуста, не является ложным булевым значением и не является нулевым числовым значением). Ничего не выводит, если все переданные переменные «ложные».

Образец использования:

{% firstof var1 var2 var3 %}
Это эквивалентно:

{% if var1 %}
{{ var1 }}
{% elif var2 %}
{{ var2 }}
{% elif var3 %}
{{ var3 }}
{% endif %}
Вы также можете использовать буквальную строку в качестве резервного значения в случае, если все переданные переменные имеют значение False:

{% firstof var1 var2 var3 "fallback value" %}
Этот тег автоматически экранирует значения переменных. Вы можете отключить автоматическое экранирование с помощью:

{% autoescape off %}
{% firstof var1 var2 var3 "<strong>fallback value</strong>" %}
{% endautoescape %}
Или, если нужно экранировать только некоторые переменные, вы можете использовать:

{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}
Вы можете использовать синтаксис {% firstof var1 var2 var3 as value %} для сохранения вывода внутри переменной.

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

<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
</ul>
Вы можете перебрать список в обратном порядке, используя {% for obj in list reversed %}.

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

{% for x, y in points %}
There is a point at {{ x }},{{ y }}
{% endfor %}
Это также может быть полезно, если вам нужно получить доступ к элементам в словаре. Например, если ваш контекст содержит словарь data, следующее будет отображать ключи и значения словаря:

{% for key, value in data.items %}
{{ key }}: {{ value }}
{% endfor %}
Имейте в виду, что для оператора точки поиск ключа словаря имеет приоритет над поиском метода. Поэтому, если словарь data содержит ключ с именем 'items', data.items вернет data['items'] вместо data.items(). Избегайте добавления ключей с именами как словарные методы, если вы хотите использовать эти методы в шаблоне (items, values, keys и т.д.). Дополнительные сведения о порядке поиска оператора точки смотрите в документации по переменным шаблона.

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

Переменная Описание
forloop.counter Текущая итерация цикла (начинается с индекса 1)
forloop.counter0 Текущая итерация цикла (начинается с индекса 0)
forloop.revcounter Количество итераций с конца цикла (начинается с индекса 1)
forloop.revcounter0 Количество итераций с конца цикла (начинается с индекса 0)
forloop.first True, если это первый раз в цикле
forloop.last True, если это последняя итерация цикла
forloop.parentloop Для вложенных циклов это цикл, окружающий текущий.
for … empty
Тег for может принимать необязательное предложение {% empty %}, текст которого отображается, если данный массив пуст или не может быть найден:

<ul>
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% empty %}
<li>Sorry, no athletes in this list.</li>
{% endfor %}
</ul>
Вышеупомянутое эквивалентно - но короче, чище и, возможно, быстрее - следующему:

<ul>
{% if athlete_list %}
{% for athlete in athlete_list %}
<li>{{ athlete.name }}</li>
{% endfor %}
{% else %}
<li>Sorry, no athletes in this list.</li>
{% endif %}
</ul>
if
Тег {% if %} оценивает переменную, и если эта переменная имеет значение «истина» (т.е. существует, не пуста и не является логическим значением false), выводится содержимое блока:

{% 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}}.

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

Логические операторы
В if можно использовать and, or или not для проверки ряда переменных или отрицания заданной переменной:

{% if athlete_list and coach_list %}
Both athletes and coaches are available.
{% endif %}

{% if not athlete_list %}
There are no athletes.
{% endif %}

{% if athlete_list or coach_list %}
There are some athletes or some coaches.
{% endif %}

{% if not athlete_list or coach_list %}
There are no athletes or there are some coaches.
{% endif %}

{% if athlete_list and not coach_list %}
There are some athletes and absolutely no coaches.
{% endif %}
Допускается использование предложений and и or в одном теге, причем and имеет более высокий приоритет, чем or, например:

{% if athlete_list and coach_list or cheerleader_list %}
будет интерпретироваться как:

if (athlete_list and coach_list) or cheerleader_list
Использование круглых скобок в теге if является недопустимым синтаксисом. Если вам нужно, чтобы они указывали приоритет, вы должны использовать вложенные теги if.

В теге if также можно использовать операторы ==, !=, <, >, <=, >=, in, not in, is, и is not которые работают следующим образом:

оператор ==
Равенство. Пример:

{% if somevar == "x" %}
This appears if variable somevar equals the string "x"
{% endif %}
Оператор !=
Неравенство. Пример:

{% if somevar != "x" %}
This appears if variable somevar does not equal the string "x",
or if somevar is not found in the context
{% endif %}
Оператор <
Меньше, чем. Пример:

{% if somevar < 100 %}
This appears if variable somevar is less than 100.
{% endif %}
Оператор >
Больше чем. Пример:

{% if somevar > 0 %}
This appears if variable somevar is greater than 0.
{% endif %}
Оператор <=
Меньше или равно. Пример:

{% if somevar <= 100 %}
This appears if variable somevar is less than 100 or equal to 100.
{% endif %}
Оператор >=
Больше или равно. Пример:

{% if somevar >= 1 %}
This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}
Оператор in
Содержится в. Этот оператор поддерживается многими контейнерами Python, чтобы проверить, находится ли данное значение в контейнере. Ниже приведены несколько примеров того, как будет интерпретироваться x in y:

{% if "bc" in "abcdef" %}
This appears since "bc" is a substring of "abcdef"
{% endif %}

{% if "hello" in greetings %}
If greetings is a list or set, one element of which is the string
"hello", this will appear.
{% endif %}

{% if user in users %}
If users is a QuerySet, this will appear if user is an
instance that belongs to the QuerySet.
{% endif %}
Оператор not in
Не содержится внутри. Это отрицание оператора in.

Оператор is
Идентичность объекта. Проверяет, являются ли два значения одним и тем же объектом. Пример:

{% if somevar is True %}
This appears if and only if somevar is True.
{% endif %}

{% if somevar is None %}
This appears if somevar is None, or if somevar is not found in the context.
{% endif %}
Оператор is not
Отрицательная идентичность объекта. Проверяет, не являются ли два значения одним и тем же объектом. Это отрицание оператора is. Пример:

{% if somevar is not True %}
This appears if somevar is not True, or if somevar is not found in the
context.
{% endif %}

{% if somevar is not None %}
This appears if and only if somevar is not None.
{% endif %}
Фильтры
Вы также можете использовать фильтры в выражении if. Например:

{% if messages|length >= 100 %}
You have lots of messages today!
{% endif %}
Сложные выражения
Все вышеперечисленное можно комбинировать для образования сложных выражений. Для таких выражений может быть важно знать, как группируются операторы при вычислении выражения, то есть правила приоритета. Приоритет операторов, от низшего к высшему, следующий:

or
and
not
in
==, !=, <, >, <=, >=
(Это в точности соответствует Python). Так, например, следующий комплекс if:

{% if a == b or c == d and e %}
…будет интерпретироваться как:

(a == b) or ((c == d) and e)
Если вам нужен другой приоритет, вам нужно будет использовать вложенные теги if. Иногда это лучше для ясности, для тех, кто не знает правил приоритета.

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

{% if a > b > c %} (WRONG)
вы должны использовать:

{% if a > b and b > c %}
ifchanged
Проверьте, изменилось ли значение с последней итерации цикла.

Тег блока {% ifchanged %} используется внутри цикла. У него есть два возможных применения.

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

<h1>Archive for {{ year }}</h1>

{% for date in days %}
{% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
<a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
{% endfor %}
Если задана одна или несколько переменных, проверяет, не изменилась ли какая-либо переменная. Например, следующее показывает дату каждый раз, когда она изменяется, и показывает час, если час или дата изменились:

{% for date in days %}
{% ifchanged date.date %} {{ date.date }} {% endifchanged %}
{% ifchanged date.hour date.date %}
{{ date.hour }}
{% endifchanged %}
{% endfor %}
Тег ifchanged также может принимать необязательное предложение {% else %}, которое будет отображаться, если значение не изменилось:

{% for match in matches %}
<div style="background-color:
{% ifchanged match.ballot_id %}
{% cycle "red" "blue" %}
{% else %}
gray
{% endifchanged %}
">{{ match }}</div>
{% endfor %}
include
Загружает шаблон и отображает его с текущим контекстом. Это способ «включения» других шаблонов в шаблон.

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

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

{% include "foo/bar.html" %}
Обычно имя шаблона указывается относительно корневого каталога загрузчика шаблонов. Строковый аргумент также может быть относительным путем, начинающимся с ./ Или ../, как описано в теге extends.

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

{% include template_name %}
Переменная также может быть любым объектом с методом render(), который принимает контекст. Это позволяет вам ссылаться на скомпилированный Template в вашем контексте.

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

Включенный шаблон отображается в контексте шаблона, который его включает. В этом примере создается вывод "Hello, John!":

Контекст: для переменной person установлено значение "John", а для переменной greeting - значение "Hello".

Шаблон:

{% include "name_snippet.html" %}
Шаблон name_snippet.html:

{{ greeting }}, {{ person|default:"friend" }}!
Вы можете передать дополнительный контекст в шаблон, используя ключевое слово arguments:

{% include "name_snippet.html" with person="Jane" greeting="Hello" %}
Если вы хотите отображать контекст только с предоставленными переменными (или даже без переменных), используйте параметр only. Для включенного шаблона нет других переменных:

{% include "name_snippet.html" with greeting="Hi" only %}
Примечание

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

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

load
Загружает настраиваемый набор тегов шаблона.

Например, следующий шаблон загрузит все теги и фильтры, зарегистрированные в somelibrary и otherlibrary, расположенных в пакете package:

{% load somelibrary package.otherlibrary %}
Вы также можете выборочно загружать отдельные фильтры или теги из библиотеки, используя аргумент from. В этом примере теги/фильтры шаблона с именами foo и bar будут загружены из somelibrary:

{% load foo bar from somelibrary %}
Смотрите Пользовательские библиотеки тегов и фильтров для получения дополнительной информации.

lorem
Отображает случайный латинский текст «lorem ipsum». Это полезно для предоставления образцов данных в шаблонах.

Использование:

{% lorem [count] [method] [random] %}
Тег {% lorem %} может использоваться с нулем, одним, двумя или тремя аргументами. Аргументы следующие:

Аргумент Описание
count Число (или переменная), содержащее количество абзацев или слов для создания (по умолчанию 1).
method w для слов, p для абзацев HTML или b для блоков абзацев с обычным текстом (по умолчанию - b).
random Слово random, если оно задано, не использует общий абзац («Lorem ipsum dolor sit amet…») при генерации текста.
Примеры:

{% lorem %} выведет общий абзац «lorem ipsum».
{% lorem 3 p %} выведет общий абзац «lorem ipsum» и два случайных абзаца, каждый из которых заключен в теги HTML <p>.
{% lorem 2 w random %} выведет два случайных латинских слова.
now
Отображает текущую дату и/или время в формате, соответствующем заданной строке. Такая строка может содержать символы спецификаторов формата, как описано в разделе фильтра date.

Пример:

It is {% now "jS F Y H:i" %}
Обратите внимание, что вы можете экранировать строку формата с помощью обратной косой черты, если хотите использовать «сырое» значение. В этом примере и «o», и «f» экранированы обратной косой чертой, потому что в противном случае каждая из них представляет собой строку формата, которая отображает год и время соответственно:

It is the {% now "jS \o\f F" %}
Это будет отображаться как «It is the 4th of September».

Примечание

Переданный формат также может быть одним из предопределенных DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT или SHORT_DATETIME_FORMAT. Предопределенные форматы могут различаться в зависимости от текущей локали и, если Локализация формата включен, например:

It is {% now "SHORT_DATETIME_FORMAT" %}
Вы также можете использовать синтаксис {% now "Y" as current_year %} для хранения вывода (в виде строки) внутри переменной. Это полезно, если вы хотите использовать {% now %} внутри тега шаблона, например blocktranslate:

{% now "Y" as current_year %}
{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}
regroup
Группирует список похожих объектов по общему атрибуту.

Этот сложный тег лучше всего проиллюстрировать на примере: скажем, что cities - это список городов, представленных словарями, содержащими "name", "population" и "country" ключи:

cities = [
{'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
{'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
{'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
{'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
{'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]
…и вы хотите отобразить иерархический список, отсортированный по странам, например:

Индия
Мумбаи: 19,000,000
Калькутта: 15,000,000
USA
New York: 20,000,000
Chicago: 7,000,000
Japan
Tokyo: 33,000,000
Вы можете использовать тег {% regroup %}, чтобы сгруппировать список городов по странам. Следующий фрагмент кода шаблона выполнит это:

{% regroup cities by country as country_list %}

<ul>
{% for country in country_list %}
<li>{{ country.grouper }}
<ul>
{% for city in country.list %}
<li>{{ city.name }}: {{ city.population }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
Давайте рассмотрим этот пример. {% regroup %} принимает три аргумента: список, который вы хотите перегруппировать, атрибут, по которому нужно группировать, и имя результирующего списка. Здесь мы перегруппируем список cities по атрибуту country и вызываем результат country_list.

{% regroup %} создает список (в данном случае country_list) групповых объектов. Объекты группы - это экземпляры namedtuple() с двумя полями:

grouper – элемент, который был сгруппирован (например, строка «India» или «Japan»).
list – список всех элементов в этой группе (например, список всех городов с country=“India“).
Поскольку {% regroup %} производит объекты namedtuple(), вы также можете записать предыдущий пример как:

{% regroup cities by country as country_list %}

<ul>
{% for country, local_cities in country_list %}
<li>{{ country }}
<ul>
{% for city in local_cities %}
<li>{{ city.name }}: {{ city.population }}</li>
{% endfor %}
</ul>
</li>
{% endfor %}
</ul>
Обратите внимание, что {% regroup %} не упорядочивает свой ввод! Наш пример основан на том факте, что список cities был упорядочен в первую очередь по country. Если бы список cities не упорядочивал своих участников по country, перегруппировка наивно отображала бы более одной группы для одной страны. Например, предположим, что список cities был настроен на это (обратите внимание, что страны не сгруппированы вместе):

cities = [
{'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
{'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
{'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
{'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
{'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]
С этим вводом для cities пример кода шаблона {% regroup %}, приведенный выше, приведет к следующему результату:

Индия
Мумбаи: 19,000,000
USA
New York: 20,000,000
Индия
Калькутта: 15,000,000
USA
Chicago: 7,000,000
Japan
Tokyo: 33,000,000
Самое простое решение этой проблемы - убедиться в коде представления, что данные упорядочены в соответствии с тем, как вы хотите их отображать.

Другое решение - отсортировать данные в шаблоне с помощью фильтра dictsort, если ваши данные находятся в списке словарей:

{% regroup cities|dictsort:"country" by country as country_list %}
Группировка по другим свойствам
Любой допустимый поиск в шаблоне является допустимым атрибутом группировки для тега перегруппировки, включая методы, атрибуты, ключи словаря и элементы списка. Например, если поле «страна» является внешним ключом для класса с атрибутом «описание», вы можете использовать:

{% regroup cities by country.description as country_list %}
Или, если country`- это поле с ``choices, у него будет метод get_FOO_display(), доступный как атрибут, позволяющий группировать по строке описания, а не ключу choices:

{% regroup cities by get_country_display as country_list %}
{{ country.grouper }} теперь будет отображать поля значений из набора choices, а не ключи.

resetcycle
Сбрасывает предыдущий cycle, так что он перезапускается с первого элемента при следующем проходе. Без аргументов {% resetcycle %} сбросит последний {% cycle %}, определенный в шаблоне.

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

{% for coach in coach_list %}
<h1>{{ coach.name }}</h1>
{% for athlete in coach.athlete_set.all %}
<p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
{% endfor %}
{% resetcycle %}
{% endfor %}
Этот пример вернет этот HTML:

<h1>José Mourinho</h1>
<p class="odd">Thibaut Courtois</p>
<p class="even">John Terry</p>
<p class="odd">Eden Hazard</p>

<h1>Carlo Ancelotti</h1>
<p class="odd">Manuel Neuer</p>
<p class="even">Thomas Müller</p>
Обратите внимание, как первый блок заканчивается на class="odd", а новый начинается на class="odd". Без тега {% resetcycle %} второй блок будет начинаться с class="even".

Вы также можете сбросить именованные теги цикла:

{% for item in list %}
<p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
{{ item.data }}
</p>
{% ifchanged item.category %}
<h1>{{ item.category }}</h1>
{% if not forloop.first %}{% resetcycle tick %}{% endif %}
{% endifchanged %}
{% endfor %}
В этом примере у нас есть как чередующиеся нечетные/четные строки, так и «основная» строка в каждой пятой строке. При изменении категории сбрасывается только пятистрочный цикл.

spaceless
Удаляет пробелы между тегами HTML. Сюда входят символы табуляции и новые строки.

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

{% spaceless %}
<p>
<a href="foo/">Foo</a>
</p>
{% endspaceless %}
Этот пример вернет этот HTML:

<p><a href="foo/">Foo</a></p>
Удаляется только пробел между тегами, но не пробел между тегами и текстом. В этом примере пространство вокруг Hello не будет удалено:

{% spaceless %}
<strong>
Hello
</strong>
{% endspaceless %}
templatetag
Выводит один из синтаксических символов, используемых для создания тегов шаблона.

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

Аргумент сообщает, какой бит шаблона выводить:

Аргумент Выходы
openblock {%
closeblock %}
openvariable {{
closevariable }}
openbrace {
closebrace }
opencomment {#
closecomment #}
Образец использования:

The {% templatetag openblock %} characters open a block.
Смотрите также тег verbatim для другого способа включения этих символов.

url
Возвращает ссылку на абсолютный путь (URL без имени домена), соответствующую заданному представлению и необязательным параметрам. Любые специальные символы в полученном пути будут закодированы с использованием iri_to_uri().

Это способ вывода ссылок без нарушения принципа DRY за счет необходимости жесткого кодирования URL-адресов в ваших шаблонах:

{% url 'some-url-name' v1 v2 %}
Первый аргумент - это Имя шаблона URL. Это может быть литерал в кавычках или любая другая контекстная переменная. Дополнительные аргументы являются необязательными и должны быть значениями, разделенными пробелами, которые будут использоваться в качестве аргументов в URL-адресе. В приведенном выше примере показана передача позиционных аргументов. В качестве альтернативы вы можете использовать синтаксис ключевого слова:

{% url 'some-url-name' arg1=v1 arg2=v2 %}
Не смешивайте позиционный синтаксис и синтаксис ключевых слов в одном вызове. Должны присутствовать все аргументы, требуемые URLconf.

Например, предположим, что у вас есть представление app_views.client, URLconf которого принимает идентификатор клиента (здесь client() - это метод внутри файла представлений app_views.py). Строка URLconf может выглядеть так:

path('client/<int:id>/', app_views.client, name='app-views-client')
Если URLconf этого приложения включен в URLconf проекта по следующему пути:

path('clients/', include('project_name.app_name.urls'))
…затем в шаблоне вы можете создать ссылку на это представление следующим образом:

{% url 'app-views-client' client.id %}
Тег шаблона выведет строку /clients/client/123/.

Обратите внимание: если URL-адрес, который вы определяете, не существует, вы получите исключение NoReverseMatch, которое приведет к отображению страницы с ошибкой на вашем сайте.

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

{% url 'some-url-name' arg arg2 as the_url %}

<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>
Область видимости переменной, созданной синтаксисом as var, - это {% block %}, в которой появляется тег {% url %}.

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

{% url 'some-url-name' as the_url %}
{% if the_url %}
<a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}
Если вы хотите получить URL-адрес в пространстве имен, укажите полное имя:

{% url 'myapp:view-name' %}
Это будет следовать обычной стратегии :ref:`разрешения URL-адресов в пространстве имен <topics-http-reversing-url-namespaces>, включая использование любых подсказок, предоставляемых контекстом для текущего приложения.

Предупреждение

Не забудьте заключить в кавычки шаблон URL-адреса name, иначе значение будет интерпретировано как переменная контекста!

verbatim
Останавливает механизм шаблонов от рендеринга содержимого этого тега блока.

Обычно используется для разрешения в шаблоне JavaScript, который конфликтует с синтаксисом Django. Например:

{% verbatim %}
{{if dying}}Still alive.{{/if}}
{% endverbatim %}
Вы также можете назначить специальный закрывающий тег, позволяющий использовать {% endverbatim %} как часть неотрисованного содержимого:

{% verbatim myblock %}
Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}
widthratio
Для создания гистограмм и т.п. этот тег вычисляет отношение заданного значения к максимальному значению, а затем применяет это отношение к константе.

Например:

<img src="bar.png" alt="Bar"
height="10" width="{% widthratio this_value max_value max_width %}">
Если this_value равно 175, max_value равно 200, а max_width равно 100, изображение в приведенном выше примере будет иметь ширину 88 пикселей (потому что 175/200 = 0,875; 0,875 * 100 = 87,5, что округляется до 88).

В некоторых случаях вы можете захотеть записать результат widthratio в переменную. Это может быть полезно, например, в blocktranslate, как это:

{% widthratio this_value max_value max_width as width %}
{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}
with
Кэширует сложную переменную под более простым именем. Это полезно при многократном доступе к «дорогостоящему» методу (например, тот, который делает запрос в базу данных).

Например:

{% with total=business.employees.count %}
{{ total }} employee{{ total|pluralize }}
{% endwith %}
Заполненная переменная (в приведенном выше примере total) доступна только между тегами {% with %} и {% endwith %}.

Вы можете назначить более одной контекстной переменной:

{% with alpha=1 beta=2 %}
...
{% endwith %}
Примечание

По-прежнему поддерживается предыдущий более подробный формат: {% with business.employees.count as total %}

Справочник по встроенному фильтру
add
Добавляет аргумент к значению.

Например:

{{ value|add:"2" }}
Если value равно 4, то на выходе будет 6.

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

Например, если у нас есть:

{{ first|add:second }}
и first равно [1, 2, 3], а second - [4, 5, 6], тогда вывод будет [1, 2, 3 , 4, 5, 6].

Предупреждение

Строки, которые можно привести к целым числам, будут суммироваться, а не объединяться, как в первом примере выше.

addslashes
Добавляет косую черту перед кавычками. Полезно, например, для экранирования строк в CSV.

Например:

{{ value|addslashes }}
Если value равно "I'm using Django", вывод будет "I\'m using Django".

capfirst
Делает первый символ значения заглавным. Если первый символ не является буквой, этот фильтр не действует.

Например:

{{ value|capfirst }}
Если value равно django, вывод будет Django.

center
Центрирует значение в поле заданной ширины.

Например:

"{{ value|center:"15" }}"
Если value равно "Django", вывод будет " Django ".

cut
Удаляет все значения arg из данной строки.

Например:

{{ value|cut:" " }}
Если value равно "String with spaces", вывод будет "Stringwithspaces".

date
Форматирует дату в соответствии с заданным форматом.

Использует формат, аналогичный функции PHP date() с некоторыми отличиями.

Примечание

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

Доступные форматные строки:

Формат символа Описание Пример вывода
День
d День месяца, 2 цифры с ведущими нулями. От '01'``до ``'31'
j День месяца без ведущих нулей. От '1'``до ``'31'
D День недели, текстовый, 3 буквы. 'Fri'
l День недели, текстовый, длинный. 'Friday'
S Английский порядковый суффикс дня месяца, 2 символа. 'st', 'nd', 'rd' или 'th'
w День недели, цифры без ведущих нулей. '0' (Воскресенье) - '6' (Суббота)
z День года. От 1 до 366
Неделя
W Номер недели в году согласно ISO-8601, недели начинаются с понедельника. 1, 53
Месяц
m Месяц, 2 цифры с ведущими нулями. От '01' до '12'
n Месяц без ведущих нулей. '1' - '12'
M Месяц, текстовый, 3 буквы. 'Jan'
b Месяц, текстовое, 3 буквы, строчные. 'jan'
E Месяц, альтернативное представление для конкретной локали, обычно используемое для представления длинной даты. 'listopada' (для польского языка, в отличие от 'Listopad')
F Месяц, текстовый, длинный. 'January'
N Аббревиатура месяца в стиле Associated Press. Собственное расширение. 'Jan.', 'Feb.', 'March', 'May'
t Количество дней в данном месяце. 28 to 31
Год
y Год, 2 цифры с ведущими нулями. '00' к '99'
Y Год, 4 цифры с ведущими нулями. '0001', …, '1999', …, '9999'
L Логическое значение високосного года. True или False
o Год нумерации недель ISO-8601, соответствующий номеру недели ISO-8601 (W), в котором используются високосные недели. Смотрите Y для более распространенного формата года. '1999'
Время
g Часовой 12-часовой формат без ведущих нулей. '1' - '12'
G Часовой, 24-часовой формат без ведущих нулей. '0' - '23'
h Часовой, 12-часовой формат. От '01' до '12'
H Часовой, 24-часовой формат. '00' - '23'
i Минуты. '00' - '59'
s Секунды, 2 цифры с ведущими нулями. '00' - '59'
u Микросекунды. 000000 - 999999
a 'a.m.' или 'p.m.' (обратите внимание, что это немного отличается от вывода PHP, потому что он включает точки, соответствующие стилю Associated Press.) 'a.m.'
A 'AM' или 'PM'. 'AM'
f Время в 12-часовых часах и минутах с отсечкой минут, если они равны нулю. Собственное расширение. '1', '1:30'
P Время в 12-часовых часах, минутах и „a.m.“/“p.m.“, с оставленными минутами, если они равны нулю, и специальными строками «полночь» и «полдень», если необходимо. Собственное расширение. '1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.'
Часовой пояс
e Название часового пояса. Может быть в любом формате или может возвращать пустую строку в зависимости от даты и времени. '', 'GMT', '-500', 'US/Eastern' и т.п.
I Переход на летнее время, независимо от того, действует оно или нет. '1' или '0'
O Разница в часах по Гринвичу. '+0200'
T Часовой пояс этой машины. 'EST', 'MDT'
Z Смещение часового пояса в секундах. Смещение для часовых поясов к западу от UTC всегда отрицательно, а для часовых поясов к востоку от UTC всегда положительно. -43200 - 43200
Дата/Время
c Формат ISO 8601. (Примечание: в отличие от других форматеров, таких как «Z», «O» или «r», форматер «c» не будет добавлять смещение часового пояса, если значение является наивным datetime (см. datetime.tzinfo). 2008-01-02T10:30:00.000123+02:00, или 2008-01-02T10:30:00.000123, если дататайм является наивным
r RFC 5322 форматированная дата. 'Thu, 21 Dec 2000 16:01:07 +0200'
U Секунды с эпохи Unix (1 января 1970 00:00:00 UTC).
Например:

{{ value|date:"D d M Y" }}
Если value является объектом datetime (например, результатом datetime.datetime.now()), то на выходе будет строка 'Wed 09 Jan 2008'.

Передаваемый формат может быть одним из предопределенных форматов DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT или SHORT_DATETIME_FORMAT, или пользовательским форматом, использующим спецификаторы формата, приведенные в таблице выше. Обратите внимание, что предопределенные форматы могут отличаться в зависимости от текущей локали.

Если предположить, что USE_L10N есть True, а LANGUAGE_CODE есть, например, "es", то для:

{{ value|date:"SHORT_DATE_FORMAT" }}
на выходе будет строка "09/01/2008" (спецификатором формата "SHORT_DATE_FORMAT" для локали es, поставляемой с Django, является "d/m/Y").

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

{{ value|date }}
выводит 9 de Enero de 2008 (спецификатором формата DATE_FORMAT для локали es является r'j \d\e F \d\e Y'). И «d», и «e» имеют обратную косую черту, поскольку в противном случае каждая из них является форматной строкой, отображающей день и название часового пояса, соответственно.

Вы можете комбинировать date с фильтром time, чтобы получить полное представление значения datetime. Например:

{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}
default
Если значение равно False, используется заданное значение по умолчанию. В противном случае используется значение.

Например:

{{ value|default:"nothing" }}
Если value равно "" (пустая строка), то на выходе будет nothing.

default_if_none
Если (и только если) значение равно None, используется заданное значение по умолчанию. В противном случае используется значение.

Обратите внимание, что если задана пустая строка, значение по умолчанию не будет использоваться. Используйте фильтр default, если вы хотите отступать для пустых строк.

Например:

{{ value|default_if_none:"nothing" }}
Если value равно None, то на выходе будет nothing.

dictsort
Принимает список словарей и возвращает этот список, отсортированный по ключу, указанному в аргументе.

Например:

{{ value|dictsort:"name" }}
Если value есть:

[
{'name': 'zed', 'age': 19},
{'name': 'amy', 'age': 22},
{'name': 'joe', 'age': 31},
]
тогда вывод будет таким:

[
{'name': 'amy', 'age': 22},
{'name': 'joe', 'age': 31},
{'name': 'zed', 'age': 19},
]
Вы также можете делать более сложные вещи, например:

{% for book in books|dictsort:"author.age" %}
* {{ book.title }} ({{ book.author.name }})
{% endfor %}
Если books есть:

[
{'title': '1984', 'author': {'name': 'George', 'age': 45}},
{'title': 'Timequake', 'author': {'name': 'Kurt', 'age': 75}},
{'title': 'Alice', 'author': {'name': 'Lewis', 'age': 33}},
]
тогда на выходе будет:

* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)
dictsort может также упорядочить список списков (или любой другой объект, реализующий __getitem__()) по элементам с указанным индексом. Например:

{{ value|dictsort:0 }}
Если value есть:

[
('a', '42'),
('c', 'string'),
('b', 'foo'),
]
тогда вывод будет таким:

[
('a', '42'),
('b', 'foo'),
('c', 'string'),
]
Вы должны передать индекс как целое число, а не как строку. Следующие команды выдают пустой результат:

{{ values|dictsort:"0" }}
dictsortreversed
Принимает список словар