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

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

Справочник по встроенным тегам

autoescape

Управляет текущим поведением автоматической обработки экранирования. Этот тег принимает on или off в качестве аргумента, что определяет, включено ли автоматическое экранирование внутри блока. Блок закрывается тегом endautoescape.

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

{% autoescape on %}
    {{ body }}
{% endautoescape %}

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

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

В рамках выключенного автоматического экранирования, цепочка фильтров, включая escape, может привести к неожиданным (но задокументированным) результатам, таким как:

{% autoescape off %}
    {{ my_list|join:", "|escape }}
{% endautoescape %}

Вышеприведенный код выведет объединённые элементы my_list без экранирования. Это потому, что последовательность фильтров сначала выполняет join над my_list (без применения экранирования к каждому элементу, так как autoescape является off), помечая результат как безопасный. Впоследствии этот безопасный результат передаётся фильтру escape, который не применяет повторное экранирование.

Для правильного экранирования каждого элемента в последовательности используйте фильтр escapeseq:

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% 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

Выводит множество отладочной информации, включая текущий контекст и импортированные модули. {% debug %} ничего не выводит, когда значение настройки DEBUG равно False.

extends

Указывает, что этот шаблон расширяет родительский шаблон.

Этот тег может быть использован двумя способами:

• {% extends "base.html" %} (с кавычками) использует буквальное значение "base.html" как имя родительского шаблона для расширения.
• {% extends variable %} использует значение variable. Если переменная имеет значение строки, Django использует эту строку как имя родительского шаблона. Если переменная имеет значение объекта Template, Django использует этот объект как родительский шаблон.

Подробнее см. Наследование шаблонов.

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

dir1/
    template.html
    base2.html
    my/
        base3.html
base1.html

В template.html, следующие пути будут допустимы:

{% extends "./base2.html" %}
{% extends "../base1.html" %}
{% extends "./my/base3.html" %}

filter

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

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

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

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

firstof

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

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

{% firstof var1 var2 var3 %}

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

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

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

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

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

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

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

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

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

for

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

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

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

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

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

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

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

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

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

for … empty

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

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

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

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

if

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

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

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

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

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

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

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

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

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

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

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

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

{% if athlete_list and coach_list or cheerleader_list %}

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

if (athlete_list and coach_list) or cheerleader_list:
    ...

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

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

== оператор

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

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

!= оператор

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

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

< оператор

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

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

> оператор

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

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

<= оператор

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

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

>= оператор

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

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

in оператор

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

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

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

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

not in оператор

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

is оператор

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

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

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

is not оператор

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

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

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

Фильтры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ifchanged

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

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

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

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

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

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

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

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

include

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

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

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

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

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

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

{% include template_name %}

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

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

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

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

• Шаблон:

  {% include "name_snippet.html" %}
  

• Шаблон name_snippet.html:

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

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

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

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

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

load

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

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

{% load somelibrary package.otherlibrary %}

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

{% load foo bar from somelibrary %}

Дополнительную информацию см. в разделе Пользовательские библиотеки тегов и фильтров.

lorem

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

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

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

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

Примеры:

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

now

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

Пример:

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

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

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

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

It is {% now "SHORT_DATETIME_FORMAT" %}

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

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

regroup

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

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

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

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

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

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

{% regroup cities by country as country_list %}

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

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

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

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

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

{% regroup cities by country as country_list %}

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

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

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

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

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

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

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

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

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

Любой допустимый поиск шаблона является допустимым атрибутом группировки для тега regroup, включая методы, атрибуты, ключи словарей и элементы списков. Например, если поле «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>Gareth</h1>
<p class="odd">Harry</p>
<p class="even">John</p>
<p class="odd">Nick</p>

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

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

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

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

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

spaceless

Удаляет пробелы между HTML-тегами. Включает табуляцию и переводы строк.

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

{% spaceless %}
    <p>
        <a href="foo/">Foo</a>
    </p>
{% endspaceless %}

В этом примере будет возвращён следующий HTML:

<p><a href="foo/">Foo</a></p>

Удаляются только пробелы между тегами — не пробелы между тегами и текстом. В этом примере пробелы вокруг Hello не будут удалены:

{% spaceless %}
    <strong>
        Hello
    </strong>
{% endspaceless %}

templatetag

Выводит один из символов синтаксиса, используемых для создания тегов шаблонов.

Система шаблонов не имеет понятия «экранирования» отдельных символов. Однако вы можете использовать тег {% templatetag %} для отображения одной из комбинаций символов тегов шаблона.

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

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

The {% templatetag openblock %} characters open a block.

См. также тег verbatim для другого способа включения этих символов.

url

Возвращает абсолютный путь ссылки (URL без имени домена), соответствующий заданному представлению и необязательным параметрам. Любые специальные символы в полученном пути будут закодированы с использованием iri_to_uri().

Это способ вывода ссылок без нарушения принципа DRY, т.е. без необходимости жёсткого кодирования URL в шаблонах:

{% url 'some-url-name' v1 v2 %}

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

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

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

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

path("client/<int:id>/", app_views.client, name="app-views-client")

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

path("clients/", include("project_name.app_name.urls"))

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

{% url 'app-views-client' client.id %}

Тег шаблона выведет строку /clients/client/123/.

Обратите внимание, что если обратный URL, который вы пытаетесь получить, не существует, будет возбуждено исключение NoReverseMatch, что приведет к отображению страницы с ошибкой на вашем сайте.

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

{% url 'some-url-name' arg arg2 as the_url %}

<a href="{{ the_url }}">I'm linking to {{ the_url }}</a>

Область действия переменной, созданной с помощью синтаксиса as var, — это {% block %}, в котором появляется тег {% url %}.

Этот синтаксис {% url ... as var %} не приведет к ошибке, если представление отсутствует. На практике вы будете использовать его для ссылки на необязательные представления:

{% url 'some-url-name' as the_url %}
{% if the_url %}
  <a href="{{ the_url }}">Link to optional stuff</a>
{% endif %}

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

{% url 'myapp:view-name' %}

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

verbatim

Прекращает обработку содержимого этого тега шаблона движком шаблонов.

Часто используется для разрешения конфликта между слоем JavaScript-шаблонов и синтаксисом Django. Например:

{% verbatim %}
    {{if dying}}Still alive.{{/if}}
{% endverbatim %}

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

{% verbatim myblock %}
    Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}

widthratio

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

Например:

<img src="bar.png" alt="Bar"
     height="10" width="{% widthratio this_value max_value max_width %}">

Если this_value равно 175, max_value равно 200, и max_width равно 100, изображение в приведенном выше примере будет иметь ширину 88 пикселей (потому что 175/200 = 0,875; 0,875 * 100 = 87,5, что округляется до 88).

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

{% widthratio this_value max_value max_width as width %}
{% blocktranslate %}The width is: {{ width }}{% endblocktranslate %}

with

Кэширует сложную переменную под более простым именем. Это полезно при многократном обращении к «дорогостоящему» методу (например, методу, который обращается к базе данных).

Например:

{% with total=business.employees.count %}
    {{ total }} employee{{ total|pluralize }}
{% endwith %}

Заполненная переменная (в приведенном выше примере, total) доступна только между тегами {% with %} и {% endwith %}.

Вы можете назначить более одной переменной контекста:

{% with alpha=1 beta=2 %}
    ...
{% endwith %}

Справочник по встроенным фильтрам

add

Добавляет аргумент к значению.

Например:

{{ value|add:"2" }}

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

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

Например, если у нас есть:

{{ first|add:second }}

и first равно [1, 2, 3], а second равно [4, 5, 6], то выходной результат будет [1, 2, 3, 4, 5, 6].

addslashes

Добавляет косые черты перед кавычками. Полезно для экранирования строк в CSV, например.

Например:

{{ value|addslashes }}

Если value равно "I'm using Django", то выходной результат будет "I\'m using Django".

capfirst

Заглавная буква первой буквы значения. Если первая буква не является буквой, этот фильтр не оказывает влияния.

Например:

{{ value|capfirst }}

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

center

Центрирует значение в поле заданной ширины.

Например:

"{{ value|center:"15" }}"

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

cut

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

Например:

{{ value|cut:" " }}

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

date

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

Использует похожий формат, что и функция date() PHP с некоторыми отличиями.

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

Например:

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

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

{{ value|date:"SHORT_DATE_FORMAT" }}

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

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

{{ value|date }}

выводит 9 de Enero de 2008 (спецификатор формата DATE_FORMAT для локали es — r'j \d\e F \d\e Y'). Обе «d» и «e» экранированы обратным слэшем, так как в противном случае каждая из них — строка формата, которая отображает день и имя временной зоны соответственно.

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

{{ value|date:"D d M Y" }} {{ value|time:"H:i" }}

default

Если значение оценивается как False, используется заданное значение по умолчанию. В противном случае используется значение.

Например:

{{ value|default:"nothing" }}

Если value — "" (пустая строка), вывод будет nothing.

default_if_none

Если (и только если) значение — None, используется заданное значение по умолчанию. В противном случае используется значение.

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

Например:

{{ value|default_if_none:"nothing" }}

Если value — None, вывод будет nothing.

dictsort

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

Например:

{{ value|dictsort:"name" }}

Если value —

[
    {"name": "zed", "age": 19},
    {"name": "amy", "age": 22},
    {"name": "joe", "age": 31},
]

то вывод будет:

[
    {"name": "amy", "age": 22},
    {"name": "joe", "age": 31},
    {"name": "zed", "age": 19},
]

Можно также выполнять более сложные действия, такие как:

{% for book in books|dictsort:"author.age" %}
    * {{ book.title }} ({{ book.author.name }})
{% endfor %}

Если books —

[
    {"title": "1984", "author": {"name": "George", "age": 45}},
    {"title": "Timequake", "author": {"name": "Kurt", "age": 75}},
    {"title": "Alice", "author": {"name": "Lewis", "age": 33}},
]

то вывод будет:

* Alice (Lewis)
* 1984 (George)
* Timequake (Kurt)

dictsort также может сортировать список списков (или любой другой объект, реализующий __getitem__() ) по элементам в указанном индексе. Например:

{{ value|dictsort:0 }}

Если value —

[
    ("a", "42"),
    ("c", "string"),
    ("b", "foo"),
]

то выход будет:

[
    ("a", "42"),
    ("b", "foo"),
    ("c", "string"),
]

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

{{ values|dictsort:"0" }}

Сортировка по элементам по указанному индексу не поддерживается для словарей.

dictsortreversed

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

divisibleby

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

Например:

{{ value|divisibleby:"3" }}

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

escape

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

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

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

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

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

escapejs

Экранирует символы для использования в качестве целой строковой литералы JavaScript, внутри одинарных или двойных кавычек, как показано ниже. Этот фильтр не делает строку безопасной для использования в «литералах шаблонов JavaScript» (синтаксис JavaScript с обратными кавычками). Любые другие случаи, не перечисленные выше, не поддерживаются. В целом рекомендуется передавать данные с помощью атрибутов HTML data- или фильтра json_script, а не встраивать их в JavaScript.

Например:

<script>
let myValue = '{{ value|escapejs }}'

escapeseq

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

{% autoescape off %}
    {{ my_list|escapeseq|join:", " }}
{% endautoescape %}

filesizeformat

Форматирует значение как «человекочитаемый» размер файла (например, '13 KB', '4.1 MB', '102 bytes', и т.д.).

Например:

{{ value|filesizeformat }}

Если value равно 123456789, то выход будет 117.7 MB.

first

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

Например:

{{ value|first }}

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

floatformat

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

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

Особенно полезно передавать 0 (ноль) как аргумент, который округлит число с плавающей точкой до ближайшего целого числа.

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

Если аргумент, переданный в floatformat, имеет суффикс g, он принудительно включит группировку с разделителем тысяч (см. THOUSAND_SEPARATOR) для активного языка. Например, когда активный язык en (английский):

Вывод всегда локализован (независимо от тега {% localize off %}), если аргумент, переданный floatformat, не имеет суффикса u, который отключит локализованный вывод. Например, когда активный язык pl (польский):

Использование floatformat без аргумента эквивалентно использованию floatformat с аргументом -1.

force_escape

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

Например, если вы хотите экранировать элементы HTML <p>, созданные фильтром linebreaks:

{% autoescape off %}
    {{ body|linebreaks|force_escape }}
{% endautoescape %}

get_digit

Принимает целое число и возвращает запрашиваемую цифру, где 1 — самая правая цифра, 2 — вторая справа и т.д. Возвращает исходное значение для некорректного ввода (если вход или аргумент не целые числа, или если аргумент меньше 1). В противном случае выход всегда является целым числом.

Например:

{{ value|get_digit:"2" }}

Если value равно 123456789, то выход будет 8.

iriencode

Преобразует IRI (международный идентификатор ресурса) в строку, подходящую для включения в URL. Это необходимо, если вы пытаетесь использовать строки, содержащие не-ASCII-символы, в URL.

Безопасно использовать этот фильтр для строки, которая уже прошла через фильтр urlencode.

Например:

{{ value|iriencode }}

Если value является "?test=1&me=2", то выходной результат будет "?test=1&me=2".

join

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

Например:

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

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

json_script

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

Аргумент: необязательный HTML-«id» тега <script>.

Например:

{{ value|json_script:"hello-data" }}

Если value является словарем {'hello': 'world'}, то выходной результат будет:

<script id="hello-data" type="application/json">{"hello": "world"}</script>

Полученные данные можно получить в JavaScript так:

const value = JSON.parse(document.getElementById('hello-data').textContent);

Атаки XSS смягчаются путём экранирования символов «<», «>» и «&». Например, если value является {'hello': 'world</script>&amp;'}, выходной результат будет:

<script id="hello-data" type="application/json">{"hello": "world\\u003C/script\\u003E\\u0026amp;"}</script>

Это совместимо со строгими политиками Content Security Policy, запрещающими выполнение скриптов на странице. Это также поддерживает чистое разделение пассивных данных и исполняемого кода.

last

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

Например:

{{ value|last }}

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

length

Возвращает длину значения. Это работает как для строк, так и для списков.

Например:

{{ value|length }}

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

Фильтр возвращает 0 для неопределённой переменной.

length_is

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

Например:

{{ value|length_is:"4" }}

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

linebreaks

Заменяет переводы строк в простом тексте на соответствующий HTML; одна новая строка становится HTML-переводом строки (<br>) и новая строка, за которой следует пустая строка, становится разрывом абзаца (</p>).

Например:

{{ value|linebreaks }}

Если value является Joel\nis a slug, выходной результат будет <p>Joel<br>is a slug</p>.

linebreaksbr

Преобразует все переводы строк в куске простого текста в HTML-переводы строк (<br>).

Например:

{{ value|linebreaksbr }}

Если value является Joel\nis a slug, выходной результат будет Joel<br>is a slug.

linenumbers

Отображает текст с номерами строк.

Например:

{{ value|linenumbers }}

Если value является:

one
two
three

выходной результат будет:

1. one
2. two
3. three

ljust

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

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

Например:

"{{ value|ljust:"10" }}"

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

lower

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

Например:

{{ value|lower }}

Если value является Totally LOVING this Album!, выходной результат будет totally loving this album!.

make_list

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

Например:

{{ value|make_list }}

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

phone2numeric

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

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

Например:

{{ value|phone2numeric }}

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

pluralize

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

Пример:

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

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

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

Пример:

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

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

Пример:

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

pprint

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

random

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

Например:

{{ value|random }}

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

rjust

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

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

Например:

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

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

safe

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

{{ var|safe|escape }}

safeseq

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

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

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

slice

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

Использует тот же синтаксис, что и срезы списков Python. См. документацию Python для ознакомления.

Пример:

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

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

slugify

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

Например:

{{ value|slugify }}

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

stringformat

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

Например:

{{ value|stringformat:"E" }}

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

striptags

Делает все возможное, чтобы удалить все [X]HTML теги.

Например:

{{ value|striptags }}

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

time

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

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

Например:

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

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

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

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

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

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

Предполагая, что 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://, http://, или www.. Например, https://goo.gl/aia1t будет преобразовано, но goo.gl/aia1t — нет.

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

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

tz

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

См. Работа с часовыми поясами в шаблонах.

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

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

django.contrib.humanize

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

static

static

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

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

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

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

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

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

get_static_prefix

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

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

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

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

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

get_media_prefix

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

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

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