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

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

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