Язык шаблонов Django ¶

Шаблоны ¶

Шаблон - это текстовый файл. Он может генерировать любой текстовый формат (HTML, XML, CSV и т. Д.).

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

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

{% extends "base_generic.html" %}

{% block title %}{{ section.title }}{% endblock %}

{% block content %}
<h1>{{ section.title }}</h1>

{% for story in story_list %}
<h2>
  <a href="{{ story.get_absolute_url }}">
    {{ story.headline|upper }}
  </a>
</h2>
<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

Переменные ¶

Переменные выглядят следующим образом : . Когда механизм шаблонов встречает переменную, он оценивает ее и заменяет результатом. Имена переменных могут содержать любой буквенно-цифровой символ, а также знак подчеркивания ( ), но не могут начинаться с подчеркивания. Точка ( ) также может быть частью имени переменной, но со специальным значением, как мы объясним ниже. Важно отметить, что в именах переменных нельзя использовать пробелы и знаки препинания .{{ variable }} "_" "."

Точка ( . ) используется для доступа к атрибутам переменной.

{% for k, v in defaultdict.items %}
    Do something with k and v here...
{% endfor %}

В приведенном выше примере будет заменен атрибутом объекта .{{ section.title }} title section

Если вы вызываете переменную, которая не существует, система шаблонов вставляет значение параметра string_if_invalid , которое '' по умолчанию (пустая строка).

Обратите внимание, что «bar» в выражении шаблона интерпретируется как буквальная строка, и даже если в контексте шаблона существует переменная «bar», она не будет вызываться.{{ foo.bar }}

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

Фильтры ¶

Вы можете изменить отображение переменных с помощью фильтров .

Фильтры выглядеть следующим образом : . Здесь отображается значение переменной после того, как оно было отфильтровано фильтром, преобразующим текст в нижний регистр. Используйте вертикальную полосу ( ), чтобы применить фильтр.{{ nom|lower }} {{ nom }} lower |

Фильтры можно связать. Результат одного фильтра применяется к следующему. - это распространенная идиома для экранирования текстового содержимого и последующего преобразования разрывов строк в теги .{{ text|escape|linebreaks }} <p>

Некоторые фильтры принимают параметры. Настройка фильтра следующим образом: . Это отображает первые 30 слов переменной .{{ bio|truncatewords:30 }} bio

Параметры фильтра, содержащие пробелы, должны быть заключены в кавычки; например, чтобы объединить список с помощью запятой и пробела, вам придется написать .{{ liste|join:", " }}

Django предоставляет около шестидесяти встроенных шаблонных фильтров. Все они описаны в встроенных фильтрах ссылки . Чтобы дать вам представление о том, что доступно, вот некоторые из наиболее часто используемых шаблонных фильтров:

default

Если переменная содержит значение false или пусто, этот фильтр использует указанное значение по умолчанию. В противном случае он использует значение переменной. Например :

{{ value|default:"nothing" }}

Если value не указан или пуст, в приведенном выше коде отображается "  nothing  ".

length

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

{{ value|length }}

Если value есть , то результат будет .['a', 'b', 'c', 'd'] 4

filesizeformat

Форматирует значение как удобочитаемый размер файла (например , и т. Д.). Например :'13 Kio' '4.1 Mio' '102 octets'

{{ value|filesizeformat }}

ЕСЛИ value содержит 123456789, результат будет .117.7 Mio

Это всего лишь несколько примеров; см. полный список в справочнике по встроенным фильтрам .

Вы также можете создавать свои собственные фильтры шаблонов; см. Пользовательские теги и фильтры шаблонов .

Теги ¶

Теги (метки на английском языке) выглядеть следующим образом : . Теги сложнее переменных: одни создают текст, другие управляют потоком, выполняя циклы или логику, а третьи загружают внешнюю информацию в шаблоны, чтобы переменные могли использовать их позже.{% tag %}

Некоторые теги требуют открывающего и закрывающего тегов (например ).{% tag %} ... contenu de la balise ... {% endtag %}

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

for

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

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

if , elif иelse

Оценивает переменную, и если эта переменная равна True , отображается содержимое блока:

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

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

{% if athlete_list|length > 1 %}
   Team: {% for athlete in athlete_list %} ... {% endfor %}
{% else %}
   Athlete: {{ athlete_list.0.name }}
{% endif %}

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

block и extends

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

Приведенные выше примеры - это лишь избранные из полного списка; полный список см. в справочнике по встроенным тегам .

Вы также можете создавать свои собственные теги шаблонов; см. Пользовательские теги и фильтры шаблонов .

Комментарии ¶

Прокомментировать некоторые линии в шаблоне, используйте комментарий синтаксис: .{# #}

Например, этот шаблон создает контент 'hello' :

{# greeting #}hello

Комментарий может содержать любой код шаблона, действительный или нет. Например :

{# {% if foo %}bar{% else %} #}

Этот синтаксис можно использовать только для однострочных комментариев (разрывы строк между разделителями {# и не допускаются #} ). Если вам нужно закомментировать несколько строк шаблона, обратитесь к тегу comment .

Наследование шаблонов ¶

Самая мощная, но и самая сложная часть шаблонизатора Django - это наследование шаблонов. Это наследование позволяет вам создать базовый «скелетный» шаблон, содержащий все общие элементы вашего сайта, и определить блоки, которые дочерние шаблоны могут переопределить.

Давайте рассмотрим наследование шаблонов на примере:

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="style.css">
    <title>{% block title %}My amazing site{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
        {% endblock %}
    </div>

    <div id="content">
        {% block content %}{% endblock %}
    </div>
</body>
</html>

Этот шаблон, который мы назовем, base.html определяет скелет HTML-документа, который можно использовать для страницы с двумя столбцами. Задача «дочерних» шаблонов - заполнить пустые блоки содержимым.

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

Дочерний шаблон может выглядеть так:

{% extends "base.html" %}

{% block title %}My amazing blog{% endblock %}

{% block content %}
{% for entry in blog_entries %}
    <h2>{{ entry.title }}</h2>
    <p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}

Тег extends является здесь ключевым. Он сообщает механизму шаблонов, что этот шаблон «расширяет» другой шаблон. Когда механизм шаблонов оценивает его, он сначала получает родительский объект, в данном случае «base.html».

На данный момент, шаблон двигатель замечает три метки block из base.html и заменяет эти блоки с содержимым шаблона ребенка. В зависимости от значения blog_entries результат может выглядеть так:

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="style.css">
    <title>My amazing blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>
    </div>

    <div id="content">
        <h2>Entry one</h2>
        <p>This is my first entry.</p>

        <h2>Entry two</h2>
        <p>This is my second entry.</p>
    </div>
</body>
</html>

Обратите внимание: поскольку дочерний шаблон не определял блок sidebar , используется значение из родительского шаблона. Содержимое родительского тега шаблона всегда используется как содержимое по умолчанию.{% block %}

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

• Создайте шаблон, base.html содержащий основной вид сайта.
• Создайте шаблон base_NOMSECTION.html для каждого раздела сайта. Например base_actualites.html , base_sports.html . Все эти шаблоны расширяют base.html и содержат определенный стиль и внешний вид раздела.
• Создавайте индивидуальные шаблоны для каждого типа страницы, например для новостной статьи или сообщения в блоге. Эти шаблоны расширяют шаблон раздела, в котором они появляются.

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

Вот несколько советов по наследованию:

• Если вы используете в шаблоне, это должен быть первый тег в этом шаблоне. В противном случае наследование шаблона работать не будет.{% extends %}

• Не экономьте на тегах в основных шаблонах. Помните, что дочерние шаблоны не должны переопределять все родительские блоки, поэтому вы можете поместить контент общего назначения в некоторые блоки и переопределить только то, что необходимо в дочерних шаблонах. Лучше иметь слишком много точек вставки, чем их кончать.{% block %}

• Если вы обнаружите, что дублируете контент более чем в одном шаблоне, это, вероятно, означает, что вам следует поместить это содержимое в один из родительских шаблонов.{% block %}

• Если вам нужно реплицировать содержимое родительского блока шаблона, переменная сделает свое дело. Это полезно, когда вы хотите дополнить содержимое родительского блока, а не просто перезаписать его. Данные, вставленные с помощью , не экранируются автоматически (см. Следующий раздел ), так как при необходимости они уже были экранированы в родительском шаблоне.{{ block.super }} {{ block.super }}

• Используя то же имя шаблона, от которого вы наследуете, его можно использовать для наследования шаблона одновременно с его переопределением. В сочетании с этим это может быть мощным способом внесения небольших изменений. См. Полный пример в разделе « Расширение переопределенного шаблона» в инструкции по переопределению шаблонов .{% extends %} {{ block.super }}

• Переменные, созданные вне блока с использованием синтаксиса тега шаблона, не могут использоваться внутри блока. Например, этот шаблон вообще ничего не выдаст:{% block %} as

  {% translate "Title" as title %}
  {% block content %}{{ title }}{% endblock %}
  

• Для лучшей читаемости вы можете дать своему тегу имя . Например :{% endblock %}

  {% block content %}
  ...
  {% endblock content %}
  

  В больших шаблонах этот метод позволяет лучше увидеть, какой тег закрывает этот тег.{% block %}

Наконец, обратите внимание, что вы не можете определить несколько тегов block с одним и тем же именем в одном шаблоне. Это ограничение существует, потому что маяк block работает "в обоих" направлениях. То есть тег block не только определяет пустоту, которую нужно заполнить, он также определяет контент, который заполняет эту пустоту в родительском элементе . Если бы block в шаблоне было два тега с одинаковыми именами, родительский элемент этого шаблона не знал бы, из какого блока следует учитывать содержимое.

Автоматический переход в HTML ¶

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

Hello, {{ name }}

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

<script>alert('hello')</script>

При таком значении имени шаблон будет создан следующим образом:

Hello, <script>alert('hello')</script>

… Это означает, что браузер будет отображать окно предупреждения JavaScript!

Точно так же, что, если имя содержит такой символ '<' ?

<b>username

Это приводит к отображению такого результата шаблона:

Hello, <b>username

… Что сделало бы остальную часть веб-страницы жирной!

Ясно, что не следует слепо доверять данным, отправляемым пользователями, вставляя их непосредственно на свои веб-страницы, поскольку злоумышленник может использовать этот вид недостатка с плохой точки зрения. Этот тип уязвимости безопасности называется атакой с использованием межсайтовых сценариев (XSS).

Чтобы избежать этой проблемы, у вас есть два варианта:

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

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

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

Мы повторяем здесь, что это поведение активно по умолчанию. Если вы используете систему шаблонов Django, вы защищены.

This will be escaped: {{ data }}
This will not be escaped: {{ data|safe }}

This will be escaped: <b>
This will not be escaped: <b>

{% autoescape off %}
    Hello {{ name }}
{% endautoescape %}

Auto-escaping is on by default. Hello {{ name }}

{% autoescape off %}
    This will not be auto-escaped: {{ data }}.

    Nor this: {{ other_data }}
    {% autoescape on %}
        Auto-escaping applies again: {{ name }}
    {% endautoescape %}
{% endautoescape %}

{% autoescape off %}
<h1>{% block title %}{% endblock %}</h1>
{% block content %}
{% endblock %}
{% endautoescape %}

{% extends "base.html" %}
{% block title %}This & that{% endblock %}
{% block content %}{{ greeting }}{% endblock %}

<h1>This &amp; that</h1>
<b>Hello!</b>

{{ data|default:"This is a string literal." }}

{{ data|default:"3 < 2" }}

{{ data|default:"3 < 2" }}  {# Bad! Don't do this. #}

Доступ к вызовам методов ¶

Большинство вызовов методов, связанных с объектами, также доступны из шаблонов. Это означает, что шаблоны не только имеют доступ к атрибутам класса (например, именам полей) или переменным, передаваемым из представлений. Например, ORM Django предлагает синтаксис entry_set для получения коллекции объектов, связанных внешним ключом. Итак, учитывая модель «комментариев» с отношением внешнего ключа к модели «задачи», вы можете просмотреть все комментарии, относящиеся к данной задаче, следующим образом:

{% for comment in task.comment_set.all %}
    {{ comment }}
{% endfor %}

Точно так же объекты QuerySets предоставляют метод count() для подсчета количества содержащихся в них объектов. Таким образом, вы можете получить количество всех комментариев, относящихся к текущей задаче, с помощью:

{{ task.comment_set.all.count }}

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

class Task(models.Model):
    def foo(self):
        return "bar"

{{ task.foo }}

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

Пользовательские библиотеки тегов и фильтры ¶

Некоторые приложения содержат собственные библиотеки тегов и фильтров. Чтобы получить к нему доступ из шаблона, убедитесь, что приложение находится в INSTALLED_APPS (мы добавили бы 'django.contrib.humanize' для этого примера), затем используйте тег load в шаблоне:

{% load humanize %}

{{ 45000|intcomma }}

Выше тег load загружает библиотеку тегов humanize , которая затем позволяет использовать фильтр intcomma в шаблоне. Если этот параметр django.contrib.admindocs включен, вы можете обратиться к разделу документации вашего интерфейса администрирования, чтобы найти список настраиваемых библиотек в вашей установке.

Тег load принимает несколько имен библиотек, разделенных пробелами. Пример:

{% load humanize i18n %}

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