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

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

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

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

Фильтрует содержимое блока через один или несколько фильтров. Несколько фильтров можно указать с помощью символов '|' (pipe), и фильтры могут иметь аргументы, так же как и в синтаксисе переменных.

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

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

{% filter force_escape|lower %}
    This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %}

firstof

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

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

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

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

ifequal и ifnotequal

{% ifequal a b %} ... {% endifequal %} — устаревший способ записи {% if a == b %} ... {% endif %}. Аналогично, {% ifnotequal a b %} ... {% endifnotequal %} заменён на {% if a != b %} ... {% endif %}. Теги ifequal и ifnotequal будут устаревшими в будущей версии.

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 в вашем контексте.

Включенный шаблон рендерится в контексте шаблона, который его включает. В этом примере получается вывод "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 %}

Если включённый шаблон вызывает исключение во время рендеринга (включая случай, если он отсутствует или содержит синтаксические ошибки), поведение зависит от template engine's опции debug (если она не задана, эта опция по умолчанию имеет значение DEBUG). Когда режим отладки включен, будет выброшено исключение, подобное TemplateDoesNotExist или TemplateSyntaxError. Когда режим отладки выключен, {% include %} запишет предупреждение в журнал django.template с исключением, произошедшим во время рендеринга включённого шаблона, и вернёт пустую строку.

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 %} внутри тега шаблона, например, blocktrans:

{% now "Y" as current_year %}
{% blocktrans %}Copyright {{ current_year }}{% endblocktrans %}

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

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

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

{% templatetag openblock %} url 'entry_list' {% templatetag closeblock %}

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 в переменной. Это может быть полезно, например, в blocktrans таком виде:

{% widthratio this_value max_value max_width as width %}
{% blocktrans %}The width is: {{ width }}{% endblocktrans %}

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

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

Например:

{{ value|cut:" " }}

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

date

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

Использует формат, аналогичный функции date() PHP (https://php.net/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').

Вы можете комбинировать 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 без аргументов эквивалентно использованию floatformat с аргументом -1.

force_escape

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

Например, если вы хотите поймать HTML-элементы <p>, созданные фильтром 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 str.join(list)

Например:

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

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

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. По умолчанию этот суффикс — '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. См. http://www.diveintopython3.net/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".

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

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

{{ value|time:"TIME_FORMAT" }}

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

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

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

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

{{ value|time }}

это то же самое, что и:

{{ value|time:"TIME_FORMAT" }}

timesince

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

Принимает необязательный аргумент, который является переменной, содержащей дату, используемую в качестве точки сравнения (без аргумента, точка сравнения — сейчас). Например, если blog_date — это экземпляр даты, представляющий полночь 1 июня 2006 года, а comment_date — это экземпляр даты для 8: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:9 }}

Если value является "Joel is a slug", то результатом будет "Joel i...".

truncatechars_html

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

Например:

{{ value|truncatechars_html:9 }}

Если 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.djangopr...</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 %}" type="text/css" media="screen" />

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

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

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 MEDIA_URL, например:

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

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