Шаблоны¶

Конфигурация¶

Механизмы шаблонов настраиваются с помощью параметра TEMPLATES. Это список конфигураций, по одной для каждого двигателя. Значение по умолчанию пусто. Файл settings.py, созданный командой 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)[исходный код]¶

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

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

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

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

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

select_template(template_name_list, using=None)[исходный код]¶

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

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

exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)[исходный код]¶

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

backend

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

tried

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

chain

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

exception TemplateSyntaxError(msg)[исходный код]¶

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

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

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

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

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

Если указан запрос, это должен быть 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' engine)
• /home/html/default/story_detail.html ('django' engine)
• /home/html/jinja2/story_detail.html ('jinja2' engine)

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

• /home/html/example.com/story_253_detail.html ('django' engine)
• /home/html/default/story_253_detail.html ('django' engine)
• /home/html/jinja2/story_253_detail.html ('jinja2' engine)
• /home/html/example.com/story_detail.html ('django' engine)
• /home/html/default/story_detail.html ('django' engine)
• /home/html/jinja2/story_detail.html ('jinja2' engine)

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

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

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

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

get_template('news/story_detail.html')

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

• /home/html/example.com/news/story_detail.html ('django' engine)
• /home/html/default/news/story_detail.html ('django' engine)
• /home/html/jinja2/news/story_detail.html ('jinja2' engine)

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

render_to_string(template_name, context=None, request=None, using=None)[исходный код]¶

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[исходный код]¶

Установите BACKEND на django.template.backends.django.DjangoTemplates, чтобы настроить механизм шаблонов Django.

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

Механизмы DjangoTemplates принимают следующее OPTIONS:

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

  По умолчанию это True.

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

  Установите значение False, только если вы визуализируете шаблоны, отличные от HTML!

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

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

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

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

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

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

  Значение по умолчанию зависит от значений 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 к модулям тегов шаблона, которые нужно добавить в built-ins. Например:

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

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

class Jinja2[исходный код]¶

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

$ pip install Jinja2

...\> pip install Jinja2

Установите BACKEND на 'django.template.backends.jinja2.Jinja2' для настройки движка Jinja2.

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

Самая важная запись в OPTIONS - 'nvironment'. Это пунктирный путь 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. Чтобы использовать API, специфичные для Django, вы должны настроить их в среде.

Например, вы можете создать 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 не имеет эквивалента тестов Jinja2.

Пользовательские бэкенды¶

Вот как реализовать собственный шаблонный бэкэнд, чтобы использовать другую систему шаблонов. Бэкэнд шаблона - это класс, унаследованный от django.template.backends.base.BaseEngine. Он должен реализовывать get_template() и, необязательно, from_string(). Вот пример вымышленной библиотеки шаблонов foobar:

from django.template import TemplateDoesNotExist, TemplateSyntaxError
from django.template.backends.base import BaseEngine
from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy

import foobar


class FooBar(BaseEngine):

    # Name of the subdirectory containing the templates for this engine
    # inside an installed application.
    app_dirname = 'foobar'

    def __init__(self, params):
        params = params.copy()
        options = params.pop('OPTIONS').copy()
        super().__init__(params)

        self.engine = foobar.Engine(**options)

    def from_string(self, template_code):
        try:
            return Template(self.engine.from_string(template_code))
        except foobar.TemplateCompilationFailed as exc:
            raise TemplateSyntaxError(exc.args)

    def get_template(self, template_name):
        try:
            return Template(self.engine.get_template(template_name))
        except foobar.TemplateNotFound as exc:
            raise TemplateDoesNotExist(exc.args, backend=self)
        except foobar.TemplateCompilationFailed as exc:
            raise TemplateSyntaxError(exc.args)


class Template:

    def __init__(self, template):
        self.template = template

    def render(self, context=None, request=None):
        if context is None:
            context = {}
        if request is not None:
            context['request'] = request
            context['csrf_input'] = csrf_input_lazy(request)
            context['csrf_token'] = csrf_token_lazy(request)
        return self.template.render(context)

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

Интеграция отладки для пользовательских движков¶

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

Шаблон postmortem¶

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

Пользовательские движки могут заполнять постмортем, передавая аргументы backend и tried при вызове TemplateDoesNotExist. Бэкэнды, использующие postmortem должны указывать источник в объекте шаблона.

Информация о контекстной строке¶

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

Пользовательские механизмы могут заполнить эту информацию, установив атрибут template_debug для исключений, возникающих во время синтаксического анализа и рендеринга. Этот атрибут представляет собой dict со следующими значениями:

• 'name': имя шаблона, в котором произошло исключение.
• 'message': сообщение об исключении.
• 'source_lines': строки до, после и включая строку, в которой произошло исключение. Это для контекста, поэтому он не должен содержать более 20 строк или около того.
• 'строка': номер строки, в которой произошло исключение.
• 'before': содержимое строки ошибки перед токеном, вызвавшим ошибку.
• 'during': токен, вызвавший ошибку.
• 'after': содержимое строки ошибки после токена, вызвавшего ошибку.
• 'total': количество строк в source_lines.
• 'top': номер строки, с которой начинается source_lines.
• 'bottom': номер строки, на которой заканчивается source_lines.

Учитывая указанную выше ошибку шаблона, template_debug будет выглядеть так:

{
    'name': '/path/to/template.html',
    'message': "Invalid block tag: 'syntax'",
    'source_lines': [
        (1, 'some\n'),
        (2, 'lines\n'),
        (3, 'before\n'),
        (4, 'Hello {% syntax error %} {{ world }}\n'),
        (5, 'some\n'),
        (6, 'lines\n'),
        (7, 'after\n'),
        (8, ''),
    ],
    'line': 4,
    'before': 'Hello ',
    'during': '{% syntax error %}',
    'after': ' {{ world }}\n',
    'total': 9,
    'bottom': 9,
    'top': 1,
}

Синтаксис¶

Шаблон 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 #}

Составные части¶