Как реализовать собственный бэкенд шаблонов

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

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

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

Если ошибка возникает во время анализа или рендеринга шаблона, 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 Origin и интеграция сторонних разработчиков

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

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

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

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/5.2/howto/custom-template-backend/