Шаблоны

Синтаксис

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

Шаблон рендерится с контекстом. Рендеринг заменяет переменные их значениями, которые ищут в контексте, и выполняет теги. Всё остальное выводится как есть.

Синтаксис языка шаблонов Django включает четыре конструкции.

My first name is {{ first_name }}. My last name is {{ last_name }}.

My first name is John. My last name is Doe.

{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}

{% csrf_token %}

{% cycle 'odd' 'even' %}

{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

{{ django|title }}

The Web Framework For Perfectionists With Deadlines

{{ my_date|date:"Y-m-d" }}

{# this won't be rendered #}

Компоненты

Настройка

Движки шаблонов настраиваются с помощью параметра TEMPLATES. Это список конфигураций, по одной для каждого движка. Значение по умолчанию пустое. Значение, сгенерированное командой startproject, определяет более полезное значение:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            # ... some options here ...
        },
    },
]

BACKEND — это строка пути к классу движка шаблонов в формате Python, реализующего API бэкенда Django для шаблонов. Встроенные бэкенды — django.template.backends.django.DjangoTemplates и django.template.backends.jinja2.Jinja2.

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

• DIRS определяет список директорий, где движок должен искать исходные файлы шаблонов в порядке поиска.
• APP_DIRS указывает, должен ли движок искать шаблоны внутри установленных приложений. Каждый бэкенд определяет стандартное имя подкаталога внутри приложений, где должны храниться его шаблоны.

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

OPTIONS содержит параметры, специфичные для бэкенда.

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

Модуль django.template.loader определяет две функции для загрузки шаблонов.

get_template(template_name, using=None) [source]

Эта функция загружает шаблон с заданным именем и возвращает объект Template.

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

get_template() перебирает каждый движок шаблонов по порядку, пока один из них не выполнится успешно. Если шаблон не найден, генерируется исключение TemplateDoesNotExist. Если шаблон найден, но содержит неверный синтаксис, генерируется исключение TemplateSyntaxError.

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

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

select_template(template_name_list, using=None) [source]

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

Если загрузка шаблона завершается неудачей, могут быть сгенерированы следующие два исключения, определённые в django.template:

exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None) [source]

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

backend

Экземпляр бэкенда шаблона, из которого возникло исключение.

tried

Список источников, которые были проверены при поиске шаблона. Он представлен списком кортежей, содержащих (origin, status), где origin — объект происхождения, а status — строка с причиной, по которой шаблон не был найден.

chain

Список промежуточных исключений TemplateDoesNotExist, сгенерированных при попытке загрузки шаблона. Это используется функциями, такими как get_template(), которые пытаются загрузить заданный шаблон из нескольких движков.

exception TemplateSyntaxError(msg) [source]

Это исключение генерируется, когда шаблон был найден, но содержит ошибки.

Объекты Template, возвращаемые функциями get_template() и select_template(), должны предоставлять метод render() со следующим сигнатуром:

Template.render(context=None, request=None)

Отображает этот шаблон с заданным контекстом.

Если context предоставлен, он должен быть dict. Если он не предоставлен, движок отобразит шаблон с пустым контекстом.

Если request предоставлен, он должен быть HttpRequest. Тогда движок должен сделать его, а также маркер CSRF, доступным в шаблоне. Как это достигается, зависит от каждого бэкенда.

Вот пример алгоритма поиска. Для этого примера настройка TEMPLATES имеет следующий вид:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            "/home/html/example.com",
            "/home/html/default",
        ],
    },
    {
        "BACKEND": "django.template.backends.jinja2.Jinja2",
        "DIRS": [
            "/home/html/jinja2",
        ],
    },
]

Если вы вызовете get_template('story_detail.html'), вот файлы, которые Django будет искать в указанном порядке:

• /home/html/example.com/story_detail.html ('django' движок)
• /home/html/default/story_detail.html ('django' движок)
• /home/html/jinja2/story_detail.html ('jinja2' движок)

Если вы вызовете select_template(['story_253_detail.html', 'story_detail.html']), вот что Django будет искать:

• /home/html/example.com/story_253_detail.html ('django' движок)
• /home/html/default/story_253_detail.html ('django' движок)
• /home/html/jinja2/story_253_detail.html ('jinja2' движок)
• /home/html/example.com/story_detail.html ('django' движок)
• /home/html/default/story_detail.html ('django' движок)
• /home/html/jinja2/story_detail.html ('jinja2' движок)

Когда Django найдёт существующий шаблон, поиск прекращается.

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

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

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

get_template("news/story_detail.html")

Используя тот же параметр TEMPLATES, что и выше, Django будет пытаться загрузить следующие шаблоны:

• /home/html/example.com/news/story_detail.html ('django' движок)
• /home/html/default/news/story_detail.html ('django' движок)
• /home/html/jinja2/news/story_detail.html ('jinja2' движок)

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

render_to_string(template_name, context=None, request=None, using=None) [source]

render_to_string() загружает шаблон, как и get_template(), и сразу же вызывает его метод render(). Она принимает следующие аргументы.

template_name

Имя шаблона для загрузки и отображения. Если это список имён шаблонов, Django использует select_template() вместо get_template() для поиска шаблона.

context

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

request

Необязательный HttpRequest, который будет доступен во время процесса отображения шаблона.

using

Необязательное имя бэкенда шаблона NAME. Поиск шаблона будет ограничен этим движком.

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

from django.template.loader import render_to_string

rendered = render_to_string("my_template.html", {"foo": "bar"})

См. также render() — функцию-обёртку, которая вызывает render_to_string() и передаёт результат в HttpResponse, подходящий для возврата из представления.

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

engines

Движки шаблонов доступны в django.template.engines:

from django.template import engines

django_engine = engines["django"]
template = django_engine.from_string("Hello {{ name }}!")

Ключ поиска — 'django' в данном примере — это имя бэкенда движка NAME.

Встроенные бэкэнды

class DjangoTemplates [source]

Установите BACKEND на 'django.template.backends.django.DjangoTemplates', чтобы настроить движок шаблонов Django.

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

DjangoTemplates движки принимают следующие OPTIONS:

• 'autoescape': логическое значение, которое управляет включением автоэскейпинга HTML.

  По умолчанию равно True.

  Предупреждение

  Устанавливайте это значение только в False, если вы используете шаблоны, не являющиеся HTML!

• 'context_processors': список пунктированных путей Python к вызовам, которые используются для заполнения контекста при отрисовке шаблона с запросом. Эти вызовы принимают объект запроса в качестве аргумента и возвращают dict элементов, которые будут объединены в контекст.

  По умолчанию пустой список.

  См. RequestContext для получения дополнительной информации.

• 'debug': логическое значение, которое включает/отключает режим отладки шаблонов. Если он равен True, страница ошибок отобразит подробный отчёт об исключении, возникшем во время отрисовки шаблона. Этот отчёт содержит соответствующий фрагмент шаблона с выделенной строкой.

  По умолчанию принимает значение настройки DEBUG.

• 'loaders': список пунктированных путей Python к классам загрузчиков шаблонов. Каждый класс загрузчика шаблонов знает, как импортировать шаблоны из определённого источника. Допускается использование кортежа вместо строки. Первый элемент кортежа должен содержать имя класса загрузчика, а последующие элементы передаются классу загрузчика при инициализации.

  Значение по умолчанию зависит от значений DIRS и APP_DIRS.

  См. Типы загрузчиков для получения подробностей.

• 'string_if_invalid': строковое представление вывода, которое система шаблонов должна использовать для недопустимых (например, неверно написанных) переменных.

  По умолчанию пустая строка.

  См. Как обрабатываются недопустимые переменные для получения подробностей.

• 'file_charset': кодировка символов, используемая для чтения файлов шаблонов на диске.

  По умолчанию 'utf-8'.

• 'libraries': словарь меток и пунктированных путей Python к модулям тегов шаблонов для регистрации в движке шаблонов. Это можно использовать для добавления новых библиотек или предоставления альтернативных меток для существующих. Например:

  OPTIONS = {
      "libraries": {
          "myapp_tags": "path.to.myapp.tags",
          "admin.urls": "django.contrib.admin.templatetags.admin_urls",
      },
  }
  

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

• 'builtins': список пунктированных путей Python к модулям тегов шаблонов для добавления в встроенные. Например:

  OPTIONS = {
      "builtins": ["myapp.builtins"],
  }
  

  Теги и фильтры из встроенных библиотек могут быть использованы без предварительного вызова тега {% load %}.

class Jinja2 [source]

Требуется установка Jinja2:

$ python -m pip install Jinja2

...\> py -m pip install Jinja2

Установите BACKEND на 'django.template.backends.jinja2.Jinja2', чтобы настроить движок Jinja2.

Когда APP_DIRS имеет значение True, движки шаблонов ищут шаблоны в подкаталоге jinja2 установленных приложений.

Самый важный элемент в OPTIONS — 'environment'. Это пунктированный путь Python к вызываемому объекту, возвращающему среду Jinja2. По умолчанию это 'jinja2.Environment'. Django вызывает этот вызываемый объект и передаёт другие опции в качестве ключевых аргументов. Более того, Django добавляет значения по умолчанию, отличающиеся от значений Jinja2 для нескольких опций:

• 'autoescape': True
• 'loader': загрузчик, настроенный для DIRS и APP_DIRS
• 'auto_reload': settings.DEBUG
• 'undefined': DebugUndefined if settings.DEBUG else Undefined

Jinja2 движки также принимают следующие OPTIONS:

• 'context_processors': список пунктированных путей Python к вызываемым объектам, используемым для заполнения контекста при отрисовке шаблона с запросом. Эти вызываемые объекты принимают объект запроса в качестве аргумента и возвращают dict элементов, которые будут объединены в контекст.

  По умолчанию пустой список.

  Использование обработчиков контекста с шаблонами Jinja2 не рекомендуется.

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

  {{ function(request) }}
  

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

  Исходный случай использования добавления обработчиков контекста для шаблонов Jinja2 включал:

  • Выполнение дорогостоящего вычисления, зависящего от запроса.
  • Необходимость результата во всех шаблонах.
  • Использование результата несколько раз в каждом шаблоне.

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

Конфигурация по умолчанию намеренно сведена к минимуму. Если шаблон отрисовывается с запросом (например, при использовании render()), бэкенд Jinja2 добавляет в контекст глобальные переменные request, csrf_input и csrf_token. Помимо этого, этот бэкенд не создаёт среду в стиле Django. Он не знает о фильтрах и тегах Django. Чтобы использовать специфичные для Django API, вы должны их настроить в среде.

Например, вы можете создать myproject/jinja2.py с этим содержимым:

from django.templatetags.static import static
from django.urls import reverse

from jinja2 import Environment


def environment(**options):
    env = Environment(**options)
    env.globals.update(
        {
            "static": static,
            "url": reverse,
        }
    )
    return env

и установить опцию 'environment' на 'myproject.jinja2.environment'.

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

<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">

<a href="{{ url('admin:index') }}">Administration</a>

Концепции тегов и фильтров существуют как в языке шаблонов Django, так и в Jinja2, но используются по-разному. Поскольку Jinja2 поддерживает передачу аргументов в вызываемые объекты в шаблонах, многие функции, требующие тега или фильтра в шаблонах Django, могут быть реализованы вызовом функции в шаблонах Jinja2, как показано в примере выше. Глобальное пространство имён Jinja2 устраняет необходимость в обработчиках контекста шаблонов Django. Язык шаблонов Django не имеет эквивалента тестам Jinja2.