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

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

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