Django内置后端和自定义后端

在Django框架中，默认设置了两个模板引擎的内置后端，分别定义为DjangoTemplates和Jinja2。

1. DjangoTemplates

DjangoTemplates通过将BACKEND属性定义为django.template.backends.django.DjangoTemplates来配置Django模板引擎。

当APP_DIRS属性为True时，DjangoTemplates引擎会在已安装的应用程序的templates子目录中查找模板。注意，保留“templates”这个通用名称，是为了向后进行兼容。

DjangoTemplates引擎接收下面的OPTIONS参数：

• autoescape：一个布尔值，用于控制是否启用HTML自动转义。其默认值为True。
• context_processors：一个指向可调用对象的Python路径列表，这些模板用于在使用请求展现模板时填充上下文。这些可调用对象以请求对象为参数，并返回要合并到上下文中的字典。其默认值为一个空的列表。
• debug：一个布尔值，用于开启/关闭模板调试模式。如果其值为True，则错误页面将显示有关模板渲染期间引发的任何异常的详细报告。此报告包含模板的相关摘要，并突出显示了相应的行。其默认值为DEBUG设置的值。
• loaders：一个模板加载器类的Python路径列表。每个Loader类都知道如何从特定来源导入模板。还可以使用元组代替字符串。元组中的第一项应该是Loader类的名称，随后的项将在初始化期间传递给Loader类。其默认值取决于DIRS和APP_DIRS属性的值。
• string_if_invalid：一个字符串输出，模板系统应将其以字符串形式用于无效（例如拼写错误）变量。其默认值为一个空的字符串。
• file_charset：用于读取磁盘上的模板文件的字符集。其默认值为FILE_CHARSET。
• libraries：一个字典类型，用于向模板引擎注册模板标签模块和Python路径的模板标签模块。该参数能添加新库或为现有库提供备用标签。请看下面的代码示例：

OPTIONS={'libraries': {'myapp_tags': 'path.to.myapp.tags','admin.urls': 'django.contrib.admin.templatetags.admin_urls',},
}

• builtins：一个用于模板标记模块的Python路径列表，可以添加到内置模块中。请看下面的代码示例：

OPTIONS={'builtins': ['myapp.builtins'],
}

2. Jinja2

Jinja2通过将BACKEND属性定义为django.template.backends.jinja2.Jinja2来配置Django模板引擎。

当APP_DIRS属性为True时，Jinja2引擎在已安装应用程序的jinja2子目录中查找模板。

在OPTIONS中，最重要的入口是“环境”，这是返回Jinja2环境的可调用对象的Python路径，其默认值为“jinja2.Environment”。Django框架调用该可调用对象并将其他选项作为关键字参数传递。此外，Django框架在一些选项中添加了如下与Jinja2不同的默认值：

• autoescape：True。
• loader：一个为DIRS和APP_DIRS属性配置的加载程序。
• auto_reload：settings.DEBUG。
• undefined：DebugUndefined if settings.DEBUG else Undefined。

另外，Jinja2引擎还接收以下OPTIONS参数：

• context_processors：一个指向可调用对象的Python路径列表，这些模板用于在使用请求展现模板时填充上下文。这些可调用对象以请求对象为参数，并返回要合并到上下文中的字典。其默认值为一个空的列表。

默认配置被有意地保持为最小配置，如果模板是通过请求展现的（例如使用render()函数时），则Jinja2后端会将全局请求csrf_input和csrf_token添加到上下文中。除此之外，此后端不会创建Django风格的环境，且不了解Django过滤器和标签。为了使用特定于Django框架的API，必须将其配置到环境中。

请看下面的例子，首先使用以下内容创建myproject/jinja2.py文件。

【代码5-7】

01  from django.contrib.staticfiles.storage import staticfiles_storage
02  from django.urls import reverse
03  
04  from jinja2 import Environment
05  
06  def environment(**options):
07      env = Environment(**options)
08      env.globals.update({
09          'static': staticfiles_storage.url,
10          'url': reverse,
11      })
12      return env

然后，将“环境”选项设置为myproject.jinja2.environment，并在Jinja2模板中使用以下代码进行构造：

【代码5-8】

01  <img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">
02  <a href="{{ url('admin:index') }}">Administration</a>

在Django框架中，标签和过滤器的概念在Django模板语言和Jinja2中都存在，但是用法不同。由于Jinja2支持将参数传递给模板中的可调用对象，因此只需在Jinja2模板中调用一个函数，即可实现许多需要Django模板中的模板标签或过滤器的功能（如上例所示）。另外，Django模板语言没有等效的Jinja2测试。

在Django框架中，还设置了一种自定义后端。一个自定义后端是一个继承自django.template. backends.base.BaseEngine的类，必须实现get_template()函数方法和可选的from_string()函数方法。

下面，请看一个自定义的foobar模板库的示例。

【代码5-9】

01  from django.template import TemplateDoesNotExist, TemplateSyntaxError
02  from django.template.backends.base import BaseEngine
03  from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy
04  
05  import foobar
06  
07  class FooBar(BaseEngine):
08  
09      # 包含该模板引擎的模板的子目录名称
10      # 在已安装的应用程序内
11      app_dirname = 'foobar'
12  
13      def __init__(self, params):
14          params = params.copy()
15          options = params.pop('OPTIONS').copy()
16          super().__init__(params)
17  
18          self.engine = foobar.Engine(**options)
19  
20      def from_string(self, template_code):
21          try:
22            return Template(self.engine.from_string(template_code))
23          except foobar.TemplateCompilationFailed as exc:
24              raise TemplateSyntaxError(exc.args)
25  
26      def get_template(self, template_name):
27          try:
28              return Template(self.engine.get_template(template_name))
29          except foobar.TemplateNotFound as exc:
30              raise TemplateDoesNotExist(exc.args, backend=self)
31          except foobar.TemplateCompilationFailed as exc:
32              raise TemplateSyntaxError(exc.args)
33  
34  class Template:
35  
36      def __init__(self, template):
37          self.template = template
38  
39      def render(self, context=None, request=None):
40          if context is None:
41              context = {}
42          if request is not None:
43              context['request'] = request
44              context['csrf_input'] = csrf_input_lazy(request)
45              context['csrf_token'] = csrf_token_lazy(request)
46          return self.template.render(context)