Cómo implementar un backend de plantillas personalizado

Backends personalizados

Aquí tienes cómo implementar un backend de plantillas personalizado para utilizar otro sistema de plantillas. Un backend de plantillas es una clase que hereda de django.template.backends.base.BaseEngine. Debe implementar get_template() y opcionalmente from_string(). Aquí tienes un ejemplo para una biblioteca de plantillas ficticia 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)

Consulte DEP 182 para obtener más información.

Integración de depuración para motores personalizados

La página de depuración de Django tiene hooks para proporcionar información detallada cuando se produce un error de plantilla. Los motores de plantillas personalizados pueden utilizar estos hooks para mejorar la información del seguimiento que aparece a los usuarios. Los siguientes hooks están disponibles:

Post mortem de plantillas

El postmortem aparece cuando se levanta TemplateDoesNotExist. Enumera las motores y cargadores de plantillas utilizados al intentar encontrar una plantilla determinada. Por ejemplo, si están configurados dos motores Django, el postmortem aparecerá así:

../_images/postmortem.png

Los motores personalizados pueden poblar el post mortem pasando los argumentos backend y tried cuando se levanta la excepción TemplateDoesNotExist. Los backends que utilizan el post mortem deben especificar un origen en el objeto de plantilla.

Información de línea contextual

Si ocurre un error durante la interpretación o renderizado de plantillas, Django puede mostrar la línea en la que ocurrió el error. Por ejemplo:

../_images/template-lines.png

Los motores personalizados pueden poblar esta información estableciendo una atributo template_debug en las excepciones levantadas durante la interpretación y renderizado. Este atributo es un dict con los siguientes valores:

  • 'nombre': El nombre de la plantilla en la que ocurrió la excepción.

  • 'mensaje': El mensaje de la excepción.

  • 'líneas de origen': Las líneas antes, después y incluyendo la línea en la que ocurrió el error. Esto es para contexto, por lo tanto no debe contener más de 20 líneas o así.

  • 'línea': El número de línea en la que ocurrió el error.

  • 'antes': El contenido en la línea del error antes del token que levantó el error.

  • 'durante': El token que levantó el error.

  • 'after': El contenido en la línea del error después del token que levantó el error.

  • 'total': El número de líneas en source_lines.

  • 'top': La línea donde comienza source_lines.

  • 'bottom': La línea donde termina source_lines.

Dado el error del template anterior, template_debug se vería así:

{
    "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,
}

Origen de la API y integración con terceros

Las plantillas Django tienen un objeto Origin disponible a través de la propiedad template.origin. Esto permite mostrar información de depuración en el postmortem de plantilla, así como en bibliotecas de terceros, como la Django Debug Toolbar.

Los motores personalizados pueden proporcionar su propia información template.origin creando un objeto que especifica las siguientes atributos:

  • 'name': El camino completo a la plantilla.

  • 'template_name': El camino relativo a la plantilla como se pasó a los métodos de carga de plantillas.

  • 'cargar_nombre': Una cadena opcional que identifica la función o clase utilizada para cargar el template, por ejemplo django.template.cargadores.filesystem.Loader.

« previous | up | next »