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

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

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

{% firstof var1 var2 var3 "fallback value" %}

Этот тег выполняет автоматическую экранизацию значений переменных. Вы можете отключить автоматическую экранизацию с помощью:

{% autoescape off %}
    {% firstof var1 var2 var3 "<strong>fallback value</strong>" %}
{% endautoescape %}

Или, если необходимо экранировать только некоторые переменные, можно использовать:

{% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %}

Можно использовать синтаксис {% firstof var1 var2 var3 as value %} для хранения вывода в переменной.

for

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

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

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

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

{% for x, y in points %}
    There is a point at {{ x }},{{ y }}
{% endfor %}

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

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

Помните, что для оператора точки, поиск по ключу словаря имеет приоритет над поиском по методу. Поэтому, если словарь data содержит ключ под названием 'items', data.items вернёт data['items'] вместо data.items(). Избегайте добавления ключей, которые имеют имена, подобные именам методов словаря, если вы хотите использовать эти методы в шаблоне (items, values, keys и т. д.). Подробнее о порядке поиска оператора точки в документации по переменным шаблона.

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

for … empty

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

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

Вышеприведённый код эквивалентен, но короче, чище и, возможно, быстрее, чем следующий:

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

if

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

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% elif athlete_in_locker_room_list %}
    Athletes should be out of the locker room soon!
{% else %}
    No athletes.
{% endif %}

В приведённом выше примере, если athlete_list не пусто, количество спортсменов будет отображено переменной {{ athlete_list|length }}.

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

Булевы операторы

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

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

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

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

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

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
{% endif %}

Использование как and, так и or условий в одном теге разрешено, при этом and имеет более высокий приоритет, чем or, например:

{% if athlete_list and coach_list or cheerleader_list %}

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

if (athlete_list and coach_list) or cheerleader_list

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

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

== оператор

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

{% if somevar == "x" %}
  This appears if variable somevar equals the string "x"
{% endif %}

!= оператор

Неравенство. Пример:

{% if somevar != "x" %}
  This appears if variable somevar does not equal the string "x",
  or if somevar is not found in the context
{% endif %}

< оператор

Меньше. Пример:

{% if somevar < 100 %}
  This appears if variable somevar is less than 100.
{% endif %}

> оператор

Больше. Пример:

{% if somevar > 0 %}
  This appears if variable somevar is greater than 0.
{% endif %}

<= оператор

Меньше или равно. Пример:

{% if somevar <= 100 %}
  This appears if variable somevar is less than 100 or equal to 100.
{% endif %}

>= оператор

Больше или равно. Пример:

{% if somevar >= 1 %}
  This appears if variable somevar is greater than 1 or equal to 1.
{% endif %}

in оператор

Входит в. Этот оператор поддерживается многими контейнерами Python для проверки, содержится ли заданное значение в контейнере. Ниже приведены некоторые примеры того, как интерпретируется x in y:

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

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

{% if user in users %}
  If users is a QuerySet, this will appear if user is an
  instance that belongs to the QuerySet.
{% endif %}

not in оператор

Не входит в. Это отрицание оператора in.

is оператор

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

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

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

is not оператор

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

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

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

Фильтры

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

{% if messages|length >= 100 %}
   You have lots of messages today!
{% endif %}

Сложные выражения

Всё вышеперечисленное может быть объединено в сложные выражения. Для таких выражений важно понимать, как операторы группируются при вычислении выражения — это правила приоритета. Приоритет операторов (от низшего к высшему):

• or
• and
• not
• in
• ==, !=, <, >, <=, >=

(Это точно соответствует Python). Например, следующий сложный if тег:

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

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

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

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

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

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

следует использовать:

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

ifchanged

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

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

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

   <h1>Archive for {{ year }}</h1>
   
   {% for date in days %}
       {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
       <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
   {% endfor %}
   

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

   {% for date in days %}
       {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
       {% ifchanged date.hour date.date %}
           {{ date.hour }}
       {% endifchanged %}
   {% endfor %}
   

Тег ifchanged также может принимать необязательное {% else %} условие, которое будет отображаться, если значение не изменилось:

{% for match in matches %}
    <div style="background-color:
        {% ifchanged match.ballot_id %}
            {% cycle "red" "blue" %}
        {% else %}
            gray
        {% endifchanged %}
    ">{{ match }}</div>
{% endfor %}

include

Загружает шаблон и отображает его с текущим контекстом. Это способ «включения» других шаблонов в шаблон.

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

В этом примере содержимое шаблона "foo/bar.html":

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

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

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

{% include template_name %}

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

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

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

• Контекст: переменная person установлена в "John", а переменная greeting установлена в "Hello".

• Шаблон:

  {% include "name_snippet.html" %}
  

• Шаблон name_snippet.html:

  {{ greeting }}, {{ person|default:"friend" }}!
  

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

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

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

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

load

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

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

{% load somelibrary package.otherlibrary %}

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

{% load foo bar from somelibrary %}

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

lorem

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

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

{% lorem [count] [method] [random] %}

Тег {% lorem %} может использоваться с нулём, одним, двумя или тремя аргументами. Аргументы:

Примеры:

• {% lorem %} отобразит общий абзац «lorem ipsum».
• {% lorem 3 p %} отобразит общий абзац «lorem ipsum» и два случайных абзаца, каждый из которых заключён в HTML-теги <p>.
• {% lorem 2 w random %} отобразит два случайных латинских слова.

now

Отображает текущую дату и/или время, используя формат, указанный в строке. Строка может содержать символы спецификаторов формата, как описано в разделе фильтра date.

Пример:

It is {% now "jS F Y H:i" %}

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

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

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

It is {% now "SHORT_DATETIME_FORMAT" %}

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

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

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

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

.. code-block:: html

<h1>Gareth</h1> <p class=”odd”>Harry</p> <p class=”even”>John</p> <p class=”odd”>Nick</p>

<h1>John</h1> <p class=”odd”>Andrea</p> <p class=”even”>Melissa</p>

Обратите внимание, как первый блок заканчивается class="odd" и новый начинается с class="odd". Без тега {% resetcycle %} второй блок начинался бы с class="even".

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

{% for item in list %}
    <p class="{% cycle 'odd' 'even' as stripe %} {% cycle 'major' 'minor' 'minor' 'minor' 'minor' as tick %}">
        {{ item.data }}
    </p>
    {% ifchanged item.category %}
        <h1>{{ item.category }}</h1>
        {% if not forloop.first %}{% resetcycle tick %}{% endif %}
    {% endifchanged %}
{% endfor %}

В этом примере у нас есть как чередующиеся строки «odd/even», так и строка «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"))

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

.. code-block:: html+django

Тег шаблона выведет строку /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

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

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

Особенно полезно передать 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 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://, www., или https://. Например, 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 в STORAGES. Например:

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

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

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

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

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

get_static_prefix

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

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

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

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

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

get_media_prefix

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

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

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