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

В данном документе описаны встроенные теги и фильтры 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>

Вы можете использовать любое количество значений в теге 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 %}

Вы также можете использовать литеральную строку в качестве значения по умолчанию, в случае если все переданные переменные имеют значение 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 устанавливает ряд переменных, доступных внутри цикла:

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

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% empty %}
    <li>Sorry, no athletes in this list.</li>
{% endfor %}
</ul>

В приведённом выше примере, если 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 [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 %}

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

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

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

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

divisibleby

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

Например:

{{ value|divisibleby:"3" }}

Если value равно 21, выходной результат будет True.

escape

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

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

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

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

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

escapejs

Экранирует символы для использования в строках JavaScript. Это не делает строку безопасной для использования в HTML или шаблонах JavaScript, но защищает вас от синтаксических ошибок при использовании шаблонов для генерации JavaScript/JSON.

Например:

{{ value|escapejs }}

Если value равно "testing\r\njavascript 'string\" <b>escaping</b>", выходной результат будет "testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E".

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, отрицательный, он округляет число до указанного количества десятичных знаков – но только если есть десятичная часть, подлежащая отображению. Например:

Если аргумент, переданный к 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=1&me=2", выходной результат будет "?test=1&me=2".

join

Объединяет список со строкой, как в Python’s str.join(list)

Например:

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

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

json_script

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

Аргумент: Необязательный HTML-«id» тега <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 для неопределённой переменной.

length_is

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

Например:

{{ value|length_is:"4" }}

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

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. См. https://diveinto.org/python3/native-datatypes.html#slicinglists для введения.

Пример:

{{ 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м".

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

Предположим, что USE_L10N равно True и 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://goo.gl/aia1t будет преобразована, но goo.gl/aia1t — нет.

Он также поддерживает ссылки только на домен, заканчивающиеся одним из оригинальных доменов верхнего уровня (.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 %}, но часто вы установите USE_L10N в True для того, чтобы локализация была активна по умолчанию.

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

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_STORAGE. Например:

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