Настраиваемый бэкенд шаблонов

Настраиваемые бэкенды

Вот как реализовать настраиваемый бэкенд шаблонов, чтобы использовать другую систему шаблонов. Бэкенд шаблонов — это класс, который наследует 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 имеет хуки для предоставления подробной информации при возникновении ошибки шаблона. Настраиваемые движки шаблонов могут использовать эти хуки для улучшения информации об ошибке, отображаемой пользователям. Доступны следующие хуки:

Посмертный анализ шаблона

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

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

Контекстная информация о строке

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

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

• 'name': Имя шаблона, в котором произошла ошибка.
• 'message': Сообщение об ошибке.
• 'source_lines': Строки перед, после и включая строку, на которой произошла ошибка. Это для контекста, поэтому оно не должно содержать более 20 строк.
• 'line': Номер строки, на которой произошла ошибка.
• '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,
}

API происхождения и интеграция с сторонними библиотеками

Шаблоны Django имеют объект Origin, доступный через атрибут template.origin. Это позволяет отображать отладочную информацию в посмертном анализе шаблона, а также в сторонних библиотеках, таких как Django Debug Toolbar.

Настраиваемые движки могут предоставлять свою информацию о template.origin, создав объект, который указывает следующие атрибуты:

• 'name': Полный путь к шаблону.
• 'template_name': Относительный путь к шаблону, переданный в методы загрузки шаблонов.
• 'loader_name': Необязательная строка, определяющая функцию или класс, используемый для загрузки шаблона, например, django.template.loaders.filesystem.Loader.