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

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

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

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

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

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

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

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

Например:

{{ 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'). И «d», и «e» экранированы обратными слешами, иначе каждый из них будет строкой формата, отображающей день и имя часового пояса соответственно.

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

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

Например, если вы хотите получить <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 так:

var 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>

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

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://www.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-style String Formatting с исключением, что ведущая «%» опускается.

Например:

{{ value|stringformat:"E" }}

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

striptags

Предпринимает все возможные усилия для удаления всех тегов [X]HTML.

Например:

{{ value|striptags }}

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

time

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

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

Например:

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

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

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

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

Это будет отображено как «01ч 23м».

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

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

{{ value|time:"TIME_FORMAT" }}

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

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

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

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

{{ value|time }}

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

{{ value|time:"TIME_FORMAT" }}

timesince

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

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

{{ blog_date|timesince:comment_date }}

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

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

timeuntil

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

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

{{ conference_date|timeuntil:from_date }}

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

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

title

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

Например:

{{ value|title }}

Если value равно "my FIRST post", вывод будет "My First Post".

truncatechars

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

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

Например:

{{ value|truncatechars:7 }}

Если value равно "Joel is a slug", вывод будет "Joel i…".

truncatechars_html

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

Например:

{{ value|truncatechars_html:7 }}

Если value равно "<p>Joel is a slug</p>", вывод будет "<p>Joel i…</p>".

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

truncatewords

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

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

Например:

{{ value|truncatewords:2 }}

Если value равно "Joel is a slug", вывод будет "Joel is …".

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

truncatewords_html

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

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

Например:

{{ value|truncatewords_html:2 }}

Если value равно "<p>Joel is a slug</p>", вывод будет "<p>Joel is …</p>".

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

unordered_list

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

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

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

upper

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

Например:

{{ value|upper }}

Если value равно "Joel is a slug", вывод будет "JOEL IS A SLUG".

urlencode

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

Например:

{{ value|urlencode }}

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

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

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

{{ value|urlencode:"" }}

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

urlize

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

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

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

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

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

Например:

{{ value|urlize }}

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

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

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

urlizetrunc

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

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

Например:

{{ value|urlizetrunc:15 }}

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

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

wordcount

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

Например:

{{ value|wordcount }}

Если value равно "Joel is a slug", вывод будет 4.

wordwrap

Разбивает слова на указанную длину строки.

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

Например:

{{ value|wordwrap:5 }}

Если value равно Joel is a slug, вывод будет:

Joel
is a
slug

yesno

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

Например:

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

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

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

i18n

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

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

l10n

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

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

tz

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

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

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

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

django.contrib.humanize

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

static

static

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

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

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

{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" 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.