{"title":"How to implement a custom template backend","version":"4.0","locale":"en","docname":"howto/custom-template-backend","url":"/en/4.0/howto/custom-template-backend/","canonical":"https://djangodocs.dev/en/4.0/howto/custom-template-backend/","summary":"Custom backends Link to this heading # Here’s how to implement a custom template backend in order to use another template system. A template backend is a class that…","html":"

How to implement a custom template backendLink to this heading#

\n
\n

Custom backendsLink to this heading#

\n

Here’s how to implement a custom template backend in order to use another\ntemplate system. A template backend is a class that inherits\ndjango.template.backends.base.BaseEngine. It must implement\nget_template() and optionally from_string(). Here’s an example for a\nfictional foobar template library:

\n
Code
from django.template import TemplateDoesNotExist, TemplateSyntaxError\nfrom django.template.backends.base import BaseEngine\nfrom django.template.backends.utils import csrf_input_lazy, csrf_token_lazy\n\nimport foobar\n\n\nclass FooBar(BaseEngine):\n\n    # Name of the subdirectory containing the templates for this engine\n    # inside an installed application.\n    app_dirname = 'foobar'\n\n    def __init__(self, params):\n        params = params.copy()\n        options = params.pop('OPTIONS').copy()\n        super().__init__(params)\n\n        self.engine = foobar.Engine(**options)\n\n    def from_string(self, template_code):\n        try:\n            return Template(self.engine.from_string(template_code))\n        except foobar.TemplateCompilationFailed as exc:\n            raise TemplateSyntaxError(exc.args)\n\n    def get_template(self, template_name):\n        try:\n            return Template(self.engine.get_template(template_name))\n        except foobar.TemplateNotFound as exc:\n            raise TemplateDoesNotExist(exc.args, backend=self)\n        except foobar.TemplateCompilationFailed as exc:\n            raise TemplateSyntaxError(exc.args)\n\n\nclass Template:\n\n    def __init__(self, template):\n        self.template = template\n\n    def render(self, context=None, request=None):\n        if context is None:\n            context = {}\n        if request is not None:\n            context['request'] = request\n            context['csrf_input'] = csrf_input_lazy(request)\n            context['csrf_token'] = csrf_token_lazy(request)\n        return self.template.render(context)\n
\n

See DEP 182 for more information.

\n
\n
\n

Debug integration for custom enginesLink to this heading#

\n

The Django debug page has hooks to provide detailed information when a template\nerror arises. Custom template engines can use these hooks to enhance the\ntraceback information that appears to users. The following hooks are available:

\n
\n

Template postmortemLink to this heading#

\n

The postmortem appears when TemplateDoesNotExist is\nraised. It lists the template engines and loaders that were used when trying to\nfind a given template. For example, if two Django engines are configured, the\npostmortem will appear like:

\n\"/en/4.0/_images/postmortem.png\"\n

Custom engines can populate the postmortem by passing the backend and\ntried arguments when raising TemplateDoesNotExist.\nBackends that use the postmortem should specify an origin on the template object.

\n
\n
\n

Contextual line informationLink to this heading#

\n

If an error happens during template parsing or rendering, Django can display\nthe line the error happened on. For example:

\n\"/en/4.0/_images/template-lines.png\"\n

Custom engines can populate this information by setting a template_debug\nattribute on exceptions raised during parsing and rendering. This attribute is\na dict with the following values:

\n\n

Given the above template error, template_debug would look like:

\n
Code
{\n    'name': '/path/to/template.html',\n    'message': "Invalid block tag: 'syntax'",\n    'source_lines': [\n        (1, 'some\\n'),\n        (2, 'lines\\n'),\n        (3, 'before\\n'),\n        (4, 'Hello {% syntax error %} {{ world }}\\n'),\n        (5, 'some\\n'),\n        (6, 'lines\\n'),\n        (7, 'after\\n'),\n        (8, ''),\n    ],\n    'line': 4,\n    'before': 'Hello ',\n    'during': '{% syntax error %}',\n    'after': ' {{ world }}\\n',\n    'total': 9,\n    'bottom': 9,\n    'top': 1,\n}\n
\n
\n
\n

Origin API and 3rd-party integrationLink to this heading#

\n

Django templates have an Origin object available\nthrough the template.origin attribute. This enables debug information to be\ndisplayed in the template postmortem, as well as\nin 3rd-party libraries, like the Django Debug Toolbar.

\n

Custom engines can provide their own template.origin information by\ncreating an object that specifies the following attributes:

\n\n
\n
","rootId":"how-to-implement-a-custom-template-backend","toc":[{"title":"Custom backends","anchor":"custom-backends","children":[]},{"title":"Debug integration for custom engines","anchor":"debug-integration-for-custom-engines","children":[{"title":"Template postmortem","anchor":"template-postmortem","children":[]},{"title":"Contextual line information","anchor":"contextual-line-information","children":[]},{"title":"Origin API and 3rd-party integration","anchor":"origin-api-and-3rd-party-integration","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"“How-to” guides","url":"/en/4.0/howto/"}],"prev":{"docname":"howto/custom-lookups","title":"How to write custom lookups","url":"/en/4.0/howto/custom-lookups/"},"next":{"docname":"howto/custom-template-tags","title":"How to create custom template tags and filters","url":"/en/4.0/howto/custom-template-tags/"},"formats":{"html":"/en/4.0/howto/custom-template-backend/","markdown":"/en/4.0/howto/custom-template-backend.md","json":"/en/4.0/howto/custom-template-backend.json"},"source":"https://github.com/django/django/blob/stable/4.0.x/docs/howto/custom-template-backend.txt","official":"https://docs.djangoproject.com/en/4.0/howto/custom-template-backend/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}