Встроенные теги и фильтры шаблонов

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

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

autoescape

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

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

{% autoescape on %}
    {{ body }}
{% endautoescape %}

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

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

В области отключенной автоматической экранизации цепочка фильтров, включая escape, может привести к неожиданным (но задокументированным) результатам, таким как следующие:

{% autoescape off %}
    {{ my_list|join:", "|escape }}
{% endautoescape %}

Вышеприведенный код выведет соединенные элементы my_list без экранирования. Это происходит потому, что последовательность применения фильтров сначала выполняет join на my_list (без применения экранирования к каждому элементу, так как autoescape является off), тем самым помечая результат как безопасный. Впоследствии этот безопасный результат передаётся фильтру escape, который не применяет второе экранирование.

Для правильного экранирования каждого элемента в последовательности используйте фильтр escapeseq:

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% 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>

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

По умолчанию, когда вы используете ключевое слово as с тегом cycle, использование тега {% 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

Выводит массу отладочной информации, включая текущий контекст и импортированные модули. {% debug %} не выводит ничего, когда значение настройки DEBUG равно False.

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

firstof

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

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

{% firstof var1 var2 var3 %}

Это эквивалентно:

{% if var1 %}
    {{ var1 }}
{% elif var2 %}
    {{ var2 }}
{% elif var3 %}
    {{ var3 }}
{% endif %}

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

{% 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 устанавливает ряд переменных, доступных внутри цикла:

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 %} вычисляет переменную, и если эта переменная имеет значение “истина” (т.е. существует, не пустая и не имеет значение ложь), содержимое блока выводится:

{% 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 %} используется внутри цикла. Он имеет два возможных применения.

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

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

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

   {% 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" }}!
  

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

{% include "name_snippet.html" with person="Jane" greeting="Hello" %}

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

{% include "name_snippet.html" with greeting="Hi" only %}

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 %} может использоваться с нулем, одной, двумя или тремя аргументами. Аргументы:

Примеры:

• {% 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" %}

Это отобразится как «Сегодня 4 сентября».

It is {% now "SHORT_DATETIME_FORMAT" %}

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

{% now "Y" as current_year %}
{% blocktranslate %}Copyright {{ current_year }}{% endblocktranslate %}

querystring

Выводит закодированную по URL-адресу строку запроса, основанную на предоставленных параметрах.

Этот тег требует экземпляра QueryDict, который по умолчанию равен request.GET, если не указано иное.

Если QueryDict пуста и дополнительные параметры не указаны, возвращается пустая строка. Непустой результат включает в себя ведущий "?".

Базовое использование

{% querystring %}

Выводит текущую строку запроса дословно. Таким образом, если строка запроса равна ?color=green, вывод будет ?color=green.

{% querystring size="M" %}

Выводит текущую строку запроса с добавлением параметра size. Следуя предыдущему примеру, вывод будет ?color=green&size=M.

Настраиваемый QueryDict

{% querystring my_query_dict %}

Вы можете предоставить настраиваемый QueryDict для использования вместо request.GET. Так, если my_query_dict равен <QueryDict: {'color': ['blue']}>, вывод будет ?color=blue.

Установка элементов

{% querystring color="red" size="S" %}

Добавляет или изменяет параметры в строке запроса. Каждый именованный аргумент будет добавлен в строку запроса, заменяя любое существующее значение для этого ключа. Например, если текущая строка запроса равна ?color=green, вывод будет ?color=red&size=S.

Удаление элементов

{% querystring color=None %}

Передача None в качестве значения удаляет параметр из строки запроса. Например, если текущая строка запроса равна ?color=green&size=M, вывод будет ?size=M.

Обработка списков

{% querystring color=my_list %}

Если my_list равно ["red", "blue"], вывод будет ?color=red&color=blue, сохраняя структуру списка в строке запроса.

Динамическое использование

Частый пример использования этого тега — сохранение текущей строки запроса при отображении страницы результатов, а также добавление ссылки на следующие и предыдущие страницы результатов. Например, если страницификатор находится на странице 3, а текущая строка запроса равна ?color=blue&size=M&page=3, следующий код выведет ?color=blue&size=M&page=4:

{% querystring page=page.next_page_number %}

Также можно сохранить значение в переменную. Например, если вам нужны несколько ссылок на одну и ту же страницу, определите её так:

{% querystring page=page.next_page_number as next_page %}

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
• США
  • Нью-Йорк: 20 000 000
  • Чикаго: 7 000 000
• Япония
  • Токио: 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 — элемент, по которому группируются (например, строка «Индия» или «Япония»).
• list — список всех элементов в этой группе (например, список всех городов с country=’Индия’).

Поскольку {% 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
• США
  • Нью-Йорк: 20 000 000
• Индия
  • Калькутта: 15 000 000
• США
  • Чикаго: 7 000 000
• Япония
  • Токио: 33 000 000

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

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

{% regroup cities|dictsort:"country" by country as country_list %}

Группировка по другим свойствам

Любое допустимое представление шаблона является законным атрибутом группировки для тега regroup, включая методы, атрибуты, ключи словарей и элементы списков. Например, если поле «country» является внешним ключом к классу с атрибутом «description», вы можете использовать:

{% 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>Gareth</h1>
<p class="odd">Harry</p>
<p class="even">John</p>
<p class="odd">Nick</p>

<h1>John</h1>
<p class="odd">Andrea</p>
<p class="even">Melissa</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 %}

В этом примере у нас есть как чередующиеся строки чётных/нечётных строк, так и строка «major» каждые пять строк. Только цикл с пятью строками сбрасывается при изменении категории.

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 %} для отображения одной из комбинаций символов тега шаблона.

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

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

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' %}

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

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

Справочник по встроенным фильтрам

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

Удаляет все значения аргумента из данной строки.

Например:

{{ value|cut:" " }}

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

date

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

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

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

Например:

{{ 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, или настраиваемым форматом, использующим символы формата, показанные в таблице выше. Обратите внимание, что предопределённые форматы могут отличаться в зависимости от текущей локали.

Предполагая, что 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

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

divisibleby

Возвращает True, если значение делится на аргумент.

Например:

{{ value|divisibleby:"3" }}

Если value — 21, выводом будет True.

escape

Экранирует HTML-строку. Конкретно, это выполняет следующие замены:

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

Применение escape к переменной, для которой обычно применяется автоматическое экранирование результата, приведёт только к одному раунду экранирования. Поэтому эту функцию безопасно использовать даже в средах с автоматическим экранированием. Если требуется несколько проходов экранирования, используйте фильтр force_escape.

Например, вы можете применить escape к полям, когда autoescape выключен:

{% autoescape off %}
    {{ title|escape }}
{% endautoescape %}

escapejs

Экранирует символы для использования в виде целого литерала строки JavaScript, в одинарных или двойных кавычках, как показано ниже. Этот фильтр не делает строку безопасной для использования в «литералах шаблонов JavaScript» (синтаксис JavaScript с обратными апострофами). Другие использования, не перечисленные выше, не поддерживаются. В общем случае рекомендуется передавать данные с помощью атрибутов HTML data- или фильтра json_script, а не встраивать JavaScript.

Например:

<script>
let myValue = '{{ value|escapejs }}'

escapeseq

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

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% endautoescape %}

filesizeformat

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

Например:

{{ value|filesizeformat }}

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

first

Возвращает первый элемент в списке.

Например:

{{ value|first }}

Если value представляет список ['a', 'b', 'c'], то выводом будет 'a'.

floatformat

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

При использовании с числовым целочисленным аргументом, floatformat округляет число до указанного количества десятичных знаков. Например:

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

Если аргумент, переданный в floatformat, имеет суффикс g, он принудительно группирует цифры через разделитель, определенный в THOUSAND_SEPARATOR для активного языка. Например, при активном языке en (английский):

Вывод всегда локализован (независимо от тега {% localize off %}), если аргумент, переданный в floatformat, не имеет суффикса u, который отключит локализация. Например, когда активный язык pl (польский):

Использование floatformat без аргумента эквивалентно использованию floatformat с аргументом -1.

force_escape

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

Например, если вы хотите поймать <p> HTML элементы, созданные фильтром linebreaks:

{% autoescape off %}
    {{ body|linebreaks|force_escape }}
{% endautoescape %}

get_digit

Для целого числа возвращает запрашиваемую цифру, где 1 — самая правая цифра, 2 — вторая справа и т.д. Возвращает исходное значение для некорректного ввода (если входное значение или аргумент не целое число, или если аргумент меньше 1). В противном случае вывод всегда является целым числом.

Например:

{{ value|get_digit:"2" }}

Если value равно 123456789, то выводом будет 8.

iriencode

Преобразует IRI (международный идентификатор ресурса) в строку, подходящую для включения в URL. Это необходимо, если вы пытаетесь использовать строки, содержащие не-ASCII символы, в URL.

Безопасно использовать этот фильтр на строке, которая уже прошла через фильтр urlencode.

Например:

{{ value|iriencode }}

Если value равно "?test=I ♥ Django", то выводом будет "?test=I%20%E2%99%A5%20Django".

join

Объединяет список с помощью строки, подобно str.join(list) в Python.

Например:

{{ value|join:" // " }}

Если value представляет список ['a', 'b', 'c'], то выводом будет строка "a // b // c".

json_script

Безопасно выводит объект Python как JSON, заключённый в тег <script>, готовый к использованию с JavaScript.

Аргумент: Необязательный атрибут «id» HTML тега <script>.

Например:

{{ value|json_script:"hello-data" }}

Если value представляет словарь {'hello': 'world'}, то выводом будет:

<script id="hello-data" type="application/json">{"hello": "world"}</script>

Доступ к полученным данным в JavaScript можно получить так:

const value = JSON.parse(document.getElementById('hello-data').textContent);

Атаки XSS смягчаются путём экранирования символов «<», «>» и «&». Например, если value равно {'hello': 'world</script>&amp;'}, то выводом будет:

<script id="hello-data" type="application/json">{"hello": "world\\u003C/script\\u003E\\u0026amp;"}</script>

Это совместимо с жёсткой политикой Content Security Policy, которая запрещает выполнение скриптов на странице. Это также поддерживает чистое разделение пассивных данных и исполняемого кода.

last

Возвращает последний элемент в списке.

Например:

{{ value|last }}

Если value представляет список ['a', 'b', 'c', 'd'], то выводом будет строка "d".

length

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

Например:

{{ value|length }}

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

Фильтр возвращает 0 для неопределённой переменной.

linebreaks

Заменяет символы перевода строки в обычном тексте на соответствующие HTML-теги; одиночная новая строка преобразуется в HTML-тег разрыва строки (<br>) а новая строка, за которой следует пустая строка, преобразуется в тег разрыва абзаца (</p>).

Например:

{{ value|linebreaks }}

Если value равно Joel\nis a slug, результат будет <p>Joel<br>is a slug</p>.

linebreaksbr

Преобразует все символы новой строки в фрагменте обычного текста в HTML-разрывы строк (<br>).

Например:

{{ value|linebreaksbr }}

Если value равно Joel\nis a slug, результат будет Joel<br>is a slug.

linenumbers

Отображает текст с номерами строк.

Например:

{{ value|linenumbers }}

Если value равно:

one
two
three

результат будет:

1. one
2. two
3. three

ljust

Выравнивает значение по левому краю в поле заданной ширины.

Аргумент: размер поля

Например:

"{{ value|ljust:"10" }}"

Если value равно Django, результат будет "Django    ".

lower

Преобразует строку в нижний регистр.

Например:

{{ value|lower }}

Если value равно Totally LOVING this Album!, результат будет totally loving this album!.

make_list

Возвращает значение, преобразованное в список. Для строки — список символов. Для целого числа аргумент преобразуется в строку перед созданием списка.

Например:

{{ value|make_list }}

Если value — строка "Joel", результат будет списком ['J', 'o', 'e', 'l']. Если value равно 123, результат будет списком ['1', '2', '3'].

phone2numeric

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

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

Например:

{{ value|phone2numeric }}

Если value равно 800-COLLECT, результат будет 800-2655328.

pluralize

Возвращает суффикс множественного числа, если значение не равно 1, '1', или объекту длиной 1. По умолчанию этот суффикс равен 's'.

Пример:

You have {{ num_messages }} message{{ num_messages|pluralize }}.

Если num_messages равно 1, результат будет You have 1 message. Если num_messages равно 2, результат будет You have 2 messages.

Для слов, требующих суффикса, отличного от 's', можно указать альтернативный суффикс в качестве параметра фильтра.

Пример:

You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.

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

Пример:

You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.

pprint

Обёртка вокруг pprint.pprint() — в основном для отладки.

random

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

Например:

{{ value|random }}

Если value — список ['a', 'b', 'c', 'd'], результат может быть "b".

rjust

Выравнивает значение по правому краю в поле заданной ширины.

Аргумент: размер поля

Например:

"{{ value|rjust:"10" }}"

Если value равно Django, результат будет "    Django".

safe

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

{{ var|safe|escape }}

safeseq

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

{{ some_list|safeseq|join:", " }}

В этом случае напрямую использовать фильтр safe нельзя, так как он сначала преобразует переменную в строку, а не работает с отдельными элементами последовательности.

slice

Возвращает срез списка.

Использует тот же синтаксис, что и срезы списков в Python. См. документацию Python для ознакомления.

Пример:

{{ some_list|slice:":2" }}

Если some_list равно ['a', 'b', 'c'], результат будет ['a', 'b'].

slugify

Преобразует в ASCII. Заменяет пробелы на дефисы. Удаляет символы, которые не являются алфавитно-цифровыми, символами подчеркивания или дефисами. Преобразует в нижний регистр. Также удаляет начальные и конечные пробелы.

Например:

{{ value|slugify }}

Если value равно "Joel is a slug", результат будет "joel-is-a-slug".

stringformat

Форматирует переменную в соответствии с аргументом, строковым спецификатором форматирования. Этот спецификатор использует синтаксис форматирования строк в стиле printf, за исключением того, что ведущий символ "%" опускается.

Например:

{{ value|stringformat:"E" }}

Если value равно 10, результат будет 1.000000E+01.

striptags

Делает все возможное, чтобы удалить все теги [X]HTML.

Например:

{{ value|striptags }}

Если value равно "<b>Joel</b> <button>is</button> a <span>slug</span>", результат будет "Joel is a slug".

time

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

Заданный формат может быть предопределённым TIME_FORMAT, или пользовательским, аналогично фильтру date. Обратите внимание, что предопределённый формат зависит от локали.

Например:

{{ value|time:"H:i" }}

Если value эквивалентно datetime.datetime.now(), результат будет строкой "01:23".

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

{{ value|time:"H\h i\m" }}

Это отобразится как «01ч 23м».

Другой пример:

Предположим, что LANGUAGE_CODE равно, например, "de", тогда для:

{{ value|time:"TIME_FORMAT" }}

результатом будет строка "01:23" (спецификатор формата "TIME_FORMAT" для локали de в поставленной версии Django — "H:i").

Фильтр time принимает параметры в строке формата только, относящиеся к времени суток, а не к дате. Если вам нужно отформатировать значение date, используйте фильтр date (или вместе с time, если нужно отобразить полное значение datetime).

Есть одно исключение из этого правила: при передаче значения datetime с присоединённой информацией о часовом поясе (объект часового пояса datetime экземпляр) фильтр time примет спецификаторы формата, связанные с часовым поясом, 'e', 'O', 'T' и 'Z'.

При использовании без строки формата используется спецификатор формата TIME_FORMAT:

{{ value|time }}

это эквивалентно:

{{ value|time:"TIME_FORMAT" }}

timesince

Форматирует дату как время, прошедшее с этой даты (например, «4 дня, 6 часов»).

Принимает необязательный аргумент, являющийся переменной, содержащей дату, используемую в качестве точки сравнения (без аргумента — текущее время). Например, если blog_date — экземпляр даты, представляющий полночь 1 июня 2006 года, а comment_date — экземпляр даты на 08:00 1 июня 2006 года, тогда следующее вернёт «8 часов»:

{{ blog_date|timesince:comment_date }}

Сравнение даты без смещения и даты с смещением вернёт пустую строку.

Минуты — наименьшая единица измерения, и «0 минут» будет возвращено для любой даты, которая находится в будущем относительно точки сравнения.

timeuntil

Аналогично timesince, за исключением того, что она измеряет время от текущего момента до заданной даты или даты и времени. Например, если сегодня 1 июня 2006 года, а conference_date — экземпляр даты, содержащий 29 июня 2006 года, то {{ conference_date|timeuntil }} вернёт «4 недели».

Принимает необязательный аргумент, являющийся переменной, содержащей дату для использования в качестве точки сравнения (вместо текущего момента). Если from_date содержит 22 июня 2006 года, то следующее вернёт «1 неделя»:

{{ conference_date|timeuntil:from_date }}

Сравнение временных меток с отступом и временных меток со смещением вернёт пустую строку.

Минуты — наименьшая используемая единица, и «0 минут» будет возвращено для любой даты, которая предшествует точке сравнения.

title

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

Например:

{{ value|title }}

Если value — это "my FIRST post", результат будет "My First Post".

truncatechars

Усекает строку, если она длиннее указанного количества символов. Усечённые строки будут заканчиваться переводимым многоточием («…»).

Аргумент: Количество символов для усечения

Например:

{{ value|truncatechars:7 }}

Если value — это "Joel is a slug", результат будет "Joel i…".

truncatechars_html

Аналогично truncatechars, но учитывает HTML-теги. Любые открытые теги в строке, не закрытые до точки усечения, закрываются сразу после усечения.

Например:

{{ value|truncatechars_html:7 }}

Если value — это "<p>Joel is a slug</p>", результат будет "<p>Joel i…</p>".

Новые строки в HTML-контенте сохраняются.

truncatewords

Усекает строку после определённого количества слов.

Аргумент: Количество слов для усечения после

Например:

{{ value|truncatewords:2 }}

Если value — это "Joel is a slug", результат будет "Joel is …".

Новые строки внутри строки будут удалены.

truncatewords_html

Аналогично truncatewords, но учитывает HTML-теги. Любые открытые теги в строке, не закрытые до точки усечения, закрываются сразу после усечения.

Это менее эффективно, чем truncatewords, поэтому должно использоваться только при передаче HTML-текста.

Например:

{{ value|truncatewords_html:2 }}

Если value — это "<p>Joel is a slug</p>", результат будет "<p>Joel is …</p>".

Новые строки в HTML-контенте сохраняются.

unordered_list

Рекурсивно принимает самовложенный список и возвращает HTML-неупорядоченный список — БЕЗ открытия и закрытия <ul> тегов.

Предполагается, что список имеет правильный формат. Например, если var содержит ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']], то {{ var|unordered_list }} вернёт:

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

upper

Преобразует строку в верхний регистр.

Например:

{{ value|upper }}

Если value — это "Joel is a slug", результат будет "JOEL IS A SLUG".

urlencode

Экранирует значение для использования в URL.

Например:

{{ value|urlencode }}

Если value — это "https://www.example.org/foo?a=b&c=d", результат будет "https%3A//www.example.org/foo%3Fa%3Db%26c%3Dd".

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

Если не указано, символ «/» считается безопасным. Можно указать пустую строку, когда все символы должны быть экранированы. Например:

{{ value|urlencode:"" }}

Если value — это "https://www.example.org/", результат будет "https%3A%2F%2Fwww.example.org%2F".

urlize

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

Этот тег работает со ссылками, начинающимися с http://, https://, или www.. Например, https://djangocon.eu будет преобразован, но djangocon.eu — нет.

Он также поддерживает ссылки только с доменом, заканчивающиеся одним из оригинальных доменных имен верхнего уровня (.com, .edu, .gov, .int, .mil, .net, и .org). Например, djangoproject.com преобразуется.

Ссылки могут иметь заключительные знаки пунктуации (точки, запятые, закрывающие скобки) и начальные знаки пунктуации (открывающие скобки), и urlize по-прежнему будет работать правильно.

Ссылки, сгенерированные urlize, имеют добавленный атрибут rel="nofollow".

Например:

{{ value|urlize }}

Если value — это "Check out www.djangoproject.com", результат будет "Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproject.com</a>".

В дополнение к веб-ссылкам, urlize также преобразует адреса электронной почты в mailto: ссылки. Если value — это "Send questions to foo@example.com", результат будет "Send questions to <a href="mailto:foo@example.com">foo@example.com</a>".

Фильтр urlize также принимает необязательный параметр autoescape. Если autoescape — это True, текст ссылки и URL будут экранированы с помощью встроенного фильтра Django escape. Значение по умолчанию для autoescape — True.

urlizetrunc

Преобразует URL и адреса электронной почты в нажимаемые ссылки, как и urlize, но усекает URL, длина которых превышает заданный лимит символов.

Аргумент: Количество символов, до которых должен усекаться текст ссылки, включая многоточие, которое добавляется, если необходимо.

Например:

{{ value|urlizetrunc:15 }}

Если value — это "Check out www.djangoproject.com", результат будет 'Check out <a href="http://www.djangoproject.com" rel="nofollow">www.djangoproj…</a>'.

Как и с urlize, этот фильтр следует применять только к простому тексту.

wordcount

Возвращает количество слов.

Например:

{{ value|wordcount }}

Если value — это "Joel is a slug", результат будет 4.

wordwrap

Обрезает слова при указанной длине строки.

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

Например:

{{ value|wordwrap:5 }}

Если value — это Joel is a slug, результат будет:

Joel
is a
slug

yesno

Преобразует значения True, False, и (необязательно) None, в строки «да», «нет», «возможно», или пользовательское отображение, переданное в виде списка через запятую, и возвращает одну из этих строк в соответствии со значением:

Например:

{{ value|yesno:"yeah,no,maybe" }}

Международные теги и фильтры

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

i18n

Эта библиотека позволяет указывать переводимый текст в шаблонах. Для её активации установите USE_I18N в True, затем загрузите её с помощью {% load i18n %}.

См. Международная локализация: в коде шаблона.

l10n

Эта библиотека предоставляет контроль над локализациями значений в шаблонах. Вам нужно только загрузить библиотеку с помощью {% load l10n %}.

См. Управление локализацией в шаблонах.

tz

Эта библиотека предоставляет контроль над преобразованиями часовых поясов в шаблонах. Как и l10n, вам нужно только загрузить библиотеку с помощью {% load tz %}, но обычно вы также установите USE_TZ в True, чтобы преобразование в местное время происходило по умолчанию.

См. Часовые пояса в шаблонах.

Другие библиотеки тегов и фильтров

Django поставляется с несколькими другими библиотеками тегов шаблонов, которые необходимо явно включить в настройке INSTALLED_APPS и активировать в вашем шаблоне с помощью тега {% load %}.

django.contrib.humanize

Набор Django-фильтров шаблонов, полезных для добавления «человеческого» аспекта к данным. См. django.contrib.humanize.

static

static

Для ссылки на статические файлы, сохранённые в STATIC_ROOT, Django поставляется с тегом шаблона static. Если приложение django.contrib.staticfiles установлено, тег будет обслуживать файлы с помощью метода url() хранилища, указанного в staticfiles в STORAGES. Например:

{% load static %}
<img src="{% static 'images/hi.jpg' %}" alt="Hi!">

Он также может использовать стандартные переменные контекста, например, предполагая, что переменная user_stylesheet передана в шаблон:

{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" media="screen">

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

{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}">

get_static_prefix

Вы должны предпочитать тег шаблона static, но если вам нужен больший контроль над тем, где и как STATIC_URL вставляется в шаблон, вы можете использовать тег шаблона get_static_prefix:

{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!">

Также есть вторая форма, которую вы можете использовать, чтобы избежать лишней обработки, если вам нужно значение несколько раз:

{% load static %}
{% get_static_prefix as STATIC_PREFIX %}

<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!">
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!">

get_media_prefix

Аналогично get_static_prefix, get_media_prefix заполняет переменную шаблона префиксом медиа MEDIA_URL, например:

{% load static %}
<body data-media-url="{% get_media_prefix %}">

Хранение значения в атрибуте данных гарантирует, что оно правильно экранировано, если мы хотим использовать его в контексте JavaScript.