How to implement a custom template backend
Django Docs · نسخهٔ 33d2e5948a0b · BSD-3-Clause
==========================================
How to implement a custom template backend
Custom backends
Here's how to implement a custom template backend in order to use another template system. A template backend is a class that inherits `django.template.backends.base.BaseEngine. It must implement get_template() and optionally from_string(). Here's an example for a fictional foobar` template library::
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)
See DEP 182_ for more information.
Debug integration for custom engines
The Django debug page has hooks to provide detailed information when a template error arises. Custom template engines can use these hooks to enhance the traceback information that appears to users. The following hooks are available:
Template postmortem
The postmortem appears when ~django.template.TemplateDoesNotExist is raised. It lists the template engines and loaders that were used when trying to find a given template. For example, if two Django engines are configured, the postmortem will appear like:
Custom engines can populate the postmortem by passing the `backend and tried arguments when raising ~django.template.TemplateDoesNotExist. Backends that use the postmortem :ref:should specify an origin <template-origin-api>` on the template object.
Contextual line information
If an error happens during template parsing or rendering, Django can display the line the error happened on. For example:
Custom engines can populate this information by setting a `template_debug attribute on exceptions raised during parsing and rendering. This attribute is a dict` with the following values:
- `
'name'`: The name of the template in which the exception occurred.
- `
'message'`: The exception message.
- `
'source_lines'`: The lines before, after, and including the line the
exception occurred on. This is for context, so it shouldn't contain more than 20 lines or so.
- `
'line'`: The line number on which the exception occurred.
- `
'before'`: The content on the error line before the token that raised the
error.
- `
'during'`: The token that raised the error.
- `
'after'`: The content on the error line after the token that raised the
error.
- `
'total': The number of lines insource_lines`.
- `
'top': The line number wheresource_lines` starts.
- `
'bottom': The line number wheresource_lines` ends.
Given the above template error, `template_debug` would look like::
{ "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, }
Origin API and 3rd-party integration
Django templates have an ~django.template.base.Origin object available through the `template.origin attribute. This enables debug information to be displayed in the template postmortem <template-postmortem>, as well as in 3rd-party libraries, like the :pypi:Django Debug Toolbar <django-debug-toolbar>`.
Custom engines can provide their own `template.origin` information by creating an object that specifies the following attributes:
- `
'name'`: The full path to the template.
- `
'template_name'`: The relative path to the template as passed into the
template loading methods.
- `
'loader_name'`: An optional string identifying the function or class used
to load the template, e.g. `django.template.loaders.filesystem.Loader`.