Django配置模板引擎

【图书介绍】《Django 5企业级Web应用开发实战（视频教学版）》_django 5企业级web应用开发实战(视频教学版)-CSDN博客

《Django 5企业级Web应用开发实战（视频教学版）》(王金柱)【摘要书评试读】- 京东图书 (jd.com)

本节主要介绍Django框架模板层中关于配置方面的内容，包括添加模板引擎支持、模板引擎用法、内置后端和自定义后端等方面。配置模板引擎是基于Django框架进行模板层开发的基础。

5.2.1 添加模板引擎支持

Django框架的模板引擎设置是使用TEMPLATES选项进行配置的。TEMPLATES选项是一个配置列表，每个模板引擎都需配置一个。在通过startproject命令创建的项目目录中，会自动生成一个名称为“settings.py”的设置文件，里面为设计人员默认配置好了一个TEMPLATES选项。

TEMPLATES选项的配置代码如下：

【代码5-1】

01  TEMPLATES = [
02      {
03          'BACKEND': 'django.template.backends.django.DjangoTemplates',
04          'DIRS': [],
05          'APP_DIRS': True,
06          'OPTIONS': {
07              # ... some options here ...
08          },
09      },
10  ]

【代码分析】

在第01行代码中，通过TEMPLATES定义了一个配置列表。

在第03行代码中，配置参数BACKEND定义了实现模板引擎类的后台路径。内置的模板引擎类后台路径为“django.template.backends.django.DjangoTemplates”和“django.template.backends.jinja2.Jinja2”。

在第04行代码中，配置参数DIRS定义了目录列表，引擎应在目录中按搜索顺序查找模板源文件。

在第05行代码中，配置参数APP_DIRS通知模板引擎是否应在已安装的应用程序内查找模板。每个后端应该为在内部存储其模板的应用程序中的子目录定义一个常规名称。另外，虽然不常见，但可以使用不同的选项配置同一后端的多个实例。在这种情况下，应该为每个引擎定义一个唯一的名称（Name）。

在第06行代码中，配置参数OPTIONS包含了一些特殊的后台配置。

下面，通过新建一个Django框架模板的项目（TmplSite），来查看项目默认配置的TEMPLATES模板参数的情况。

【代码5-2】

01  TEMPLATES = [
02      {
03          'BACKEND': 'django.template.backends.django.DjangoTemplates',
04          'DIRS': [],
05          'APP_DIRS': True,
06          'OPTIONS': {
07              'context_processors': [
08                  'django.template.context_processors.debug',
09                  'django.template.context_processors.request',
10                  'django.contrib.auth.context_processors.auth',
11                  'django.contrib.messages.context_processors.messages',
12              ],
13          },
14      },
15  ]

【代码分析】

这段实际的TEMPLATES模板配置参数与【代码5-1】基本吻合，区别就是在OPTIONS配置中添加了一些额外的参数。

5.2.2 模板引擎用法

在Django框架模板引擎的加载模块中，定义了两个函数来实现模板的加载功能，具体介绍如下：

1. get_template(template_name, using=None)函数

该函数的说明如下：

该函数通过给定的名称实现模板的加载，同时返回一个模板对象。其返回值的确切类型取决于加载模板的后端，每个后端都有自己模板类。
该函数按顺序使用每个模板引擎去查找指定模板，直到成功为止。如果找不到模板，则会引发TemplateDoesNotExist异常。如果模板被找到了却包含了无效语法，则会引发TemplateSyntaxError异常。
该函数搜索和加载模板的方式，依赖于每个引擎的后端和配置。

如果想将搜索限制在特定的模板引擎中，可在using参数中传递引擎的名称。

2. select_template(template_name_list, using=None)函数

该函数的说明如下：

该函数与get_template()函数基本一样，只不过它需要一个模板名称列表。
该函数会按给定的模板名称列表顺序查找模板，并返回找到的第一个存在的模板。
如果加载模板失败，则可能会引发django.template模块中定义的以下两个异常。

TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)异常：当找不到模板时，会引发此异常。其接收以下用在调试页面上的可选参数。

backend参数：表示来源自异常的模板后端实例。
tried参数：表示在查找模板时尝试过的来源列表。其格式为包含来源（origin）、状态（status）的元组列表，其中来源（origin）是一个类似origin的对象，而状态（status）是一个找不到模板原因的字符串。
chain参数：表示一个在尝试加载一个模板时被立即引发的TemplateDoesNotExist异常列表。其被诸如get_template()之类的函数所使用，这些函数尝试从多个引擎加载给定的模板。

TemplateSyntaxError(msg)异常，当找到模板但包含错误时会引发此异常。

通过get_template()函数和select_template()函数返回的模板对象，必须提供具有以下签名的render()方法。

方法名称：Template.render(context=None, request=None)

方法说明：该方法使用给定的上下文渲染此模板。如果提供了上下文，则必须是一个字典类型；如果未提供上下文，则引擎将使用空的上下文呈现模板；如果提供了请求，则其必须是一个HttpRequest对象。然后，模板引擎必须使其自身以及CSRF令牌在模板中可用。至于如何实现这一点，则取决于每个后端。

这里有一个关于搜索算法的代码示例，在该代码示例中将“TEMPLATES”选项设置如下：

【代码5-3】

01  TEMPLATES = [
02      {
03          'BACKEND': 'django.template.backends.django.DjangoTemplates',
04          'DIRS': [
05              '/home/html/example.com',
06              '/home/html/default',
07          ],
08      },
09      {
10          'BACKEND': 'django.template.backends.jinja2.Jinja2',
11          'DIRS': [
12              '/home/html/jinja2',
13          ],
14      },
15  ]

【代码分析】

如果尝试调用get_template('story_detail.html')方法，则Django框架模板引擎将按如下顺序查找文件：

/home/html/example.com/story_detail.html（'django' engine）
/home/html/default/story_detail.html（'django' engine）
/home/html/jinja2/story_detail.html（'jinja2' engine）

如果尝试调用“select_template(['story_123_detail.html', 'story_detail.html'])”方法，则Django框架模板引擎将按如下顺序查找文件：

/home/html/example.com/story_123_detail.html（'django' engine）
/home/html/default/story_123_detail.html（'django' engine）
/home/html/jinja2/story_123_detail.html（'jinja2' engine）
/home/html/example.com/story_detail.html（'django' engine）
/home/html/default/story_detail.html（'django' engine）
/home/html/jinja2/story_detail.html（'jinja2' engine）

当Django框架发现存在的模板时，将停止继续往下查找。

在每个包含模板的目录内，在其子目录中组织模板是可能的，或许也是更好的选择。在设计架构时采用的常规做法是，为每个Django框架应用创建一个子目录，并根据需要在这些子目录内创建下一级子目录。这样的做法其实是很明智的，因为将所有的模板存储在单个目录的根目录中是会很麻烦的。

【图书介绍】《Django 5企业级Web应用开发实战（视频教学版）》_django 5企业级web应用开发实战(视频教学版)-CSDN博客

《Django 5企业级Web应用开发实战（视频教学版）》(王金柱)【摘要书评试读】- 京东图书 (jd.com)