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

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

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

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

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

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

firstof

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

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

{% firstof var1 var2 var3 %}

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

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

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

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

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

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

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

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

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

for

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

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

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

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

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

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

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

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

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

for … empty

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

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

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

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

if

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

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

В приведённом примере, если athlete_list не пуста, количество спортсменов отобразится с помощью переменной {{ athlete_list|length }}.

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

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

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

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

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

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

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

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

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

{% if athlete_list and coach_list or cheerleader_list %}

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

if (athlete_list and coach_list) or cheerleader_list

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

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

== оператор

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

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

!= оператор

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

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

< оператор

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

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

> оператор

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

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

<= оператор

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

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

>= оператор

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

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

in оператор

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

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

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

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

not in оператор

Не содержит. Это отрицание оператора in.

is оператор

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

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

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

is not оператор

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

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

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

Фильтры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ifequal и ifnotequal

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

ifchanged

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

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

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

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

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

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

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

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

include

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

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

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

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

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

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

{% include template_name %}

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

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

• Контекст: переменная person имеет значение "John", а переменная greeting имеет значение "Hello".

• Шаблон:

  {% include "name_snippet.html" %}
  

• Шаблон name_snippet.html:

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

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

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

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

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

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

load

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

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

{% load somelibrary package.otherlibrary %}

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

{% load foo bar from somelibrary %}

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

lorem

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

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

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

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

Примеры:

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

now

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

Пример:

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

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

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

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

It is {% now "SHORT_DATETIME_FORMAT" %}

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

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

regroup

Группирует список похожих объектов по общему атрибуту.

Этот сложный тег лучше всего продемонстрировать на примере: предположим, что cities — это список городов, представленных словарями, содержащими ключи "name", "population", и "country":

cities = [
    {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
    {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
    {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
    {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
    {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]

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

• Индия
  • Мумбаи: 19 000 000
  • Колката: 15 000 000
• США
  • Нью-Йорк: 20 000 000
  • Чикаго: 7 000 000
• Япония
  • Токио: 33 000 000

Вы можете использовать тег {% regroup %} для группировки списка городов по стране. Следующий фрагмент кода шаблона позволит это сделать:

{% regroup cities by country as country_list %}

<ul>
{% for country in country_list %}
    <li>{{ country.grouper }}
    <ul>
        {% for city in country.list %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Давайте разберём этот пример. {% regroup %} принимает три аргумента: список, который нужно сгруппировать, атрибут для группировки и имя результирующего списка. Здесь мы группируем список cities по атрибуту country и называем результат country_list.

{% regroup %} создаёт список (в данном случае country_list) из **объектов групп**. Объекты групп — это экземпляры namedtuple() с двумя полями:

• grouper — элемент, по которому группировался список (например, строка «Индия» или «Япония»).
• list — список всех элементов в этой группе (например, список всех городов с country='Индия').

Поскольку {% regroup %} создаёт объекты namedtuple(), вы также можете переписать предыдущий пример как:

{% regroup cities by country as country_list %}

<ul>
{% for country, local_cities in country_list %}
    <li>{{ country }}
    <ul>
        {% for city in local_cities %}
          <li>{{ city.name }}: {{ city.population }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Обратите внимание, что {% regroup %} не упорядочивает свой вход! Наш пример полагается на то, что список cities изначально был упорядочен по атрибуту country. Если список cities не упорядочивал свои элементы по атрибуту country, группировка бы неадекватно отображала более одной группы для одной страны. Например, скажем, список cities был задан так (обратите внимание, что страны не сгруппированы вместе):

cities = [
    {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
    {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
    {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
    {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
    {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]

При таком входе для cities, пример шаблона кода {% regroup %} выше приведет к следующему выводу:

• Индия
  • Мумбаи: 19 000 000
• США
  • Нью-Йорк: 20 000 000
• Индия
  • Колката: 15 000 000
• США
  • Чикаго: 7 000 000
• Япония
  • Токио: 33 000 000

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

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

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

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

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

{% regroup cities by country.description as country_list %}

Или, если country — это поле с choices, у него будет доступен метод get_FOO_display() в качестве атрибута, позволяя группироваться по строке отображения, а не по ключу choices:

{% regroup cities by get_country_display as country_list %}

{{ country.grouper }} теперь отобразит значения полей из набора choices вместо ключей.

resetcycle

Сбрасывает предыдущий тег cycle, чтобы он начинался с первого элемента при следующем обращении. Без аргументов, {% resetcycle %} сбросит последний тег {% cycle %} , определённый в шаблоне.

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

{% for coach in coach_list %}
    <h1>{{ coach.name }}</h1>
    {% for athlete in coach.athlete_set.all %}
        <p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
    {% endfor %}
    {% resetcycle %}
{% endfor %}

Этот пример вернул бы такой HTML:

<h1>José Mourinho</h1>
<p class="odd">Thibaut Courtois</p>
<p class="even">John Terry</p>
<p class="odd">Eden Hazard</p>

<h1>Carlo Ancelotti</h1>
<p class="odd">Manuel Neuer</p>
<p class="even">Thomas Müller</p>

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

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

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

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

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() name. Он может быть строковой литеральной константой или любой другой переменной контекста. Дополнительные аргументы необязательны и должны быть значениями, разделёнными пробелами, которые будут использоваться в качестве аргументов в URL. Приведённый выше пример демонстрирует передачу позиционных аргументов. В качестве альтернативы можно использовать синтаксис с ключевыми словами:

{% url 'some-url-name' arg1=v1 arg2=v2 %}

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

Например, предположим, что у вас есть представление, app_views.client, для которого в URLconf указан идентификатор клиента (здесь, client() — метод внутри файла представлений app_views.py). Строка в URLconf может выглядеть так:

('^client/([0-9]+)/$', app_views.client, name='app-views-client')

Если URLconf этого приложения включён в URLconf проекта по пути, например, такому:

('^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

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

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

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

Например:

{{ value|date:"D d M Y" }}

Если value является объектом datetime (например, результатом datetime.datetime.now()), вывод будет строкой 'Wed 09 Jan 2008'.

Переданный формат может быть одним из предопределенных DATE_FORMAT, DATETIME_FORMAT, SHORT_DATE_FORMAT или SHORT_DATETIME_FORMAT, или пользовательским форматом, который использует спецификаторы формата, показанные в таблице выше. Обратите внимание, что предопределенные форматы могут различаться в зависимости от текущего языка.

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

{{ value|date:"SHORT_DATE_FORMAT" }}

вывод будет строкой "09/01/2008" (спецификатор формата "SHORT_DATE_FORMAT" для языка es поставляется с Django равен "d/m/Y").

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

{{ value|date }}

вывод будет 9 de Enero de 2008 (спецификатор формата DATE_FORMAT для языка es равен r'j \d\e F \d\e Y').

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

{{ 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 к переменной, к результату которой обычно применяется автоматическое экранирование, приведет только к одному циклу экранирования. Поэтому этот метод безопасно использовать даже в средах с автоматическим экранированием. Если вы хотите применить несколько проходов экранирования, используйте фильтр force_escape.

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

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

escapejs

Экранирует символы для использования в строках JavaScript. Это не делает строку безопасной для использования в HTML, но защищает вас от синтаксических ошибок при использовании шаблонов для генерации 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".

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

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

Например:

{{ value|make_list }}

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

phone2numeric

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

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

Например:

{{ value|phone2numeric }}

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

pluralize

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

Пример:

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

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

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

Пример:

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

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

Пример:

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

pprint

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

random

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

Например:

{{ value|random }}

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

rjust

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

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

Например:

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

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

safe

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

{{ var|safe|escape }}

safeseq

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

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

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

slice

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

Использует ту же синтаксис, что и срезы списков в Python. Обратитесь к http://www.diveintopython3.net/native-datatypes.html#slicinglists для ознакомления.

Пример:

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

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

slugify

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

Например:

{{ value|slugify }}

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

stringformat

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

Например:

{{ value|stringformat:"E" }}

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

striptags

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

Например:

{{ value|striptags }}

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

time

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

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

Например:

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

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

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

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

{{ value|time:"TIME_FORMAT" }}

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

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

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

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

{{ value|time }}

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

{{ value|time:"TIME_FORMAT" }}

timesince

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

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

{{ blog_date|timesince:comment_date }}

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

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

timeuntil

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

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

{{ conference_date|timeuntil:from_date }}

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

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

title

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

Например:

{{ value|title }}

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

truncatechars

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

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

Например:

{{ value|truncatechars:9 }}

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

truncatechars_html

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

Например:

{{ value|truncatechars_html:9 }}

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

Новые строки в HTML-содержимом будут сохранены.

truncatewords

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

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

Например:

{{ value|truncatewords:2 }}

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

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

truncatewords_html

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

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

Например:

{{ value|truncatewords_html:2 }}

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

Новые строки в HTML-содержимом будут сохранены.

unordered_list

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

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

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

upper

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

Например:

{{ value|upper }}

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

urlencode

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

Например:

{{ value|urlencode }}

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

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

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

{{ value|urlencode:"" }}

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

urlize

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

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

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

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

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

Например:

{{ value|urlize }}

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

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

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

urlizetrunc

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

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

Например:

{{ value|urlizetrunc:15 }}

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

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

wordcount

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

Например:

{{ value|wordcount }}

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

wordwrap

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

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

Например:

{{ value|wordwrap:5 }}

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

Joel
is a
slug

yesno

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

Например:

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

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

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

i18n

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

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

l10n

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

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

tz

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

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

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

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

django.contrib.humanize

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

static

static

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

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

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

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

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

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

get_static_prefix

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

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

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

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

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

get_media_prefix

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

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

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