# 第九章：模板高级进阶
# 第九章：模板高级进阶
虽然大多数和Django模板语言的交互都是模板作者的工作，但你可能想定制和扩展模板引擎，让它做一些它不能做的事情，或者是以其他方式让你的工作更轻松。
本章深入探讨Django的模板系统。 如果你想扩展模板系统或者只是对它的工作原理感觉到好奇，本章涉及了你需要了解的东西。 它也包含一个自动转意特征，如果你继续使用django，随着时间的推移你一定会注意这个安全考虑。
如果你想把Django的模版系统作为另外一个应用程序的一部分（就是说，仅使用Django的模板系统而不使用Django框架的其他部分），那你一定要读一下“配置独立模式下的模版系统”这一节。
## 模板语言回顾
首先，让我们快速回顾一下第四章介绍的若干专业术语：
> *模板* 是一个纯文本文件，或是一个用Django模板语言标记过的普通的Python字符串。 模板可以包含模板标签和变量。
>
> *模板标签* 是在一个模板里面起作用的的标记。 这个定义故意搞得模糊不清。 例如，一个模版标签能够产生作为控制结构的内容（一个 `if`语句或`for` 循环), 可以获取数据库内容，或者访问其他的模板标签。
>
> 区块标签被 `{%` 和 `%}` 包围：
```
<pre class="calibre9">```
{% if is_logged_in %}
Thanks for logging in!
{% else %}
Please log in.
{% endif %}
```
```
> *变量* 是一个在模板里用来输出值的标记。
>
> 变量标签被 `{{` 和 `}}` 包围：
```
<pre class="calibre9">```
My first name is {{ first_name }}. My last name is {{ last_name }}.
```
```
> *context* 是一个传递给模板的名称到值的映射（类似Python字典）。
>
> 模板 *渲染* 就是是通过从context获取值来替换模板中变量并执行所有的模板标签。
关于这些基本概念更详细的内容，请参考第四章。
本章的其余部分讨论了扩展模板引擎的方法。 首先，我们快速的看一下第四章遗留的内容。
## RequestContext和Context处理器
你需要一段context来解析模板。 一般情况下，这是一个 `django.template.Context` 的实例，不过在Django中还可以用一个特殊的子类， `django.template.RequestContext` ，这个用起来稍微有些不同。 `RequestContext` 默认地在模板context中加入了一些变量，如 `HttpRequest` 对象或当前登录用户的相关信息。
当你不想在一系例模板中都明确指定一些相同的变量时，你应该使用 `RequestContext` 。 例如，考虑这两个视图：
```
<pre class="calibre9">```
from django.template import loader, Context
def view_1(request):
# ...
t = loader.get_template('template1.html')
c = Context({
'app': 'My app',
'user': request.user,
'ip_address': request.META['REMOTE_ADDR'],
'message': 'I am view 1.'
})
return t.render(c)
def view_2(request):
# ...
t = loader.get_template('template2.html')
c = Context({
'app': 'My app',
'user': request.user,
'ip_address': request.META['REMOTE_ADDR'],
'message': 'I am the second view.'
})
return t.render(c)
```
```
（注意，在这些例子中，我们故意 *不* 使用 `render_to_response()` 这个快捷方法，而选择手动载入模板，手动构造context对象然后渲染模板。 是为了能够清晰的说明所有步骤。）
每个视图都给模板传入了三个相同的变量：`app`、`user`和`ip_address`。 如果我们把这些冗余去掉会不会更好？
创建 `RequestContext` 和 **context处理器** 就是为了解决这个问题。 Context处理器允许你设置一些变量，它们会在每个context中自动被设置好，而不必每次调用 `render_to_response()` 时都指定。 要点就是，当你渲染模板时，你要用 `RequestContext` 而不是 `Context` 。
最直接的做法是用context处理器来创建一些处理器并传递给 `RequestContext` 。上面的例子可以用context processors改写如下：
```
<pre class="calibre9">```
from django.template import loader, RequestContext
def custom_proc(request):
"A context processor that provides 'app', 'user' and 'ip_address'."
return {
'app': 'My app',
'user': request.user,
'ip_address': request.META['REMOTE_ADDR']
}
def view_1(request):
# ...
t = loader.get_template('template1.html')
c = RequestContext(request, {'message': 'I am view 1.'},
processors=[custom_proc])
return t.render(c)
def view_2(request):
# ...
t = loader.get_template('template2.html')
c = RequestContext(request, {'message': 'I am the second view.'},
processors=[custom_proc])
return t.render(c)
```
```
我们来通读一下代码：
- 首先，我们定义一个函数 `custom_proc` 。这是一个context处理器，它接收一个 `HttpRequest` 对象，然后返回一个字典，这个字典中包含了可以在模板context中使用的变量。 它就做了这么多。
- 我们在这两个视图函数中用 `RequestContext` 代替了 `Context` 。在context对象的构建上有两个不同点。 一， `RequestContext` 的第一个参数需要传递一个 `HttpRequest` 对象，就是传递给视图函数的第一个参数（ `request` ）。二， `RequestContext` 有一个可选的参数 `processors` ，这是一个包含context处理器函数的列表或者元组。 在这里，我们传递了我们之前定义的处理器函数 `curstom_proc` 。
- 每个视图的context结构里不再包含 `app` 、 `user` 、 `ip_address` 等变量，因为这些由 `custom_proc` 函数提供了。
- 每个视图 *仍然* 具有很大的灵活性，可以引入我们需要的任何模板变量。 在这个例子中， `message` 模板变量在每个视图中都不一样。
在第四章，我们介绍了 `render_to_response()` 这个快捷方式，它可以简化调用 `loader.get_template()` ,然后创建一个 `Context` 对象，最后再调用模板对象的 `render()`过程。 为了讲解context处理器底层是如何工作的，在上面的例子中我们没有使用 `render_to_response()` 。但是建议选择 `render_to_response()` 作为context的处理器。这就需要用到`context_instance`参数：
```
<pre class="calibre9">```
from django.shortcuts import render_to_response
from django.template import RequestContext
def custom_proc(request):
"A context processor that provides 'app', 'user' and 'ip_address'."
return {
'app': 'My app',
'user': request.user,
'ip_address': request.META['REMOTE_ADDR']
}
def view_1(request):
# ...
return render_to_response('template1.html',
{'message': 'I am view 1.'},
context_instance=RequestContext(request, processors=[custom_proc]))
def view_2(request):
# ...
return render_to_response('template2.html',
{'message': 'I am the second view.'},
context_instance=RequestContext(request, processors=[custom_proc]))
```
```
在这，我们将每个视图的模板渲染代码写成了一个单行。
虽然这是一种改进，但是，请考虑一下这段代码的简洁性，我们现在不得不承认的是在 *另外* 一方面有些过分了。 我们以代码冗余（在 `processors` 调用中）的代价消除了数据上的冗余（我们的模板变量）。 由于你不得不一直键入 `processors` ，所以使用context处理器并没有减少太多的输入量。
Django因此提供对 *全局* context处理器的支持。 `TEMPLATE_CONTEXT_PROCESSORS` 指定了哪些`context processors`*总是*默认被使用。这样就省去了每次使用 `RequestContext` 都指定 `processors` 的麻烦。
默认情况下， `TEMPLATE_CONTEXT_PROCESSORS` 设置如下：
```
<pre class="calibre9">```
TEMPLATE_CONTEXT_PROCESSORS = (
'django.core.context_processors.auth',
'django.core.context_processors.debug',
'django.core.context_processors.i18n',
'django.core.context_processors.media',
)
```
```
这个设置项是一个可调用函数的元组，其中的每个函数使用了和上文中我们的 `custom_proc` 相同的接口，它们以request对象作为参数，返回一个会被合并传给context的字典： 接收一个request对象作为参数，返回一个包含了将被合并到context中的项的字典。
每个处理器将会按照顺序应用。 也就是说如果你在第一个处理器里面向context添加了一个变量，而第二个处理器添加了同样名字的变量，那么第二个将会覆盖第一个。
Django提供了几个简单的context处理器，有些在默认情况下被启用的。
### django.core.context\_processors.auth
如果 `TEMPLATE_CONTEXT_PROCESSORS` 包含了这个处理器，那么每个 `RequestContext` 将包含这些变量：
- `user` ：一个 `django.contrib.auth.models.User` 实例，描述了当前登录用户（或者一个 `AnonymousUser` 实例，如果客户端没有登录）。
- `messages` ：一个当前登录用户的消息列表（字符串）。 在后台，对每一个请求，这个变量都调用 `request.user.get_and_delete_messages()` 方法。 这个方法收集用户的消息然后把它们从数据库中删除。
- `perms` ： `django.core.context_processors.PermWrapper` 的一个实例，包含了当前登录用户有哪些权限。
关于users、permissions和messages的更多内容请参考第14章。
### django.core.context\_processors.debug
这个处理器把调试信息发送到模板层。 如果`TEMPLATE_CONTEXT_PROCESSORS`包含这个处理器，每一个`RequestContext`将包含这些变量：
- `debug` ：你设置的 `DEBUG` 的值（ `True` 或 `False` ）。你可以在模板里面用这个变量测试是否处在debug模式下。
- `sql_queries` ：包含类似于 [``](#id3){‘sql’: …, ‘time’: `` 的字典的一个列表， 记录了这个请求期间的每个SQL查询以及查询所耗费的时间。 这个列表是按照请求顺序进行排列的。
System Message: WARNING/2 (`<string>`, line 315); *backlink*
Inline literal start-string without end-string.
由于调试信息比较敏感，所以这个context处理器只有当同时满足下面两个条件的时候才有效：
- `DEBUG` 参数设置为 `True` 。
- 请求的ip应该包含在 `INTERNAL_IPS` 的设置里面。
细心的读者可能会注意到`debug`模板变量的值永远不可能为`False`，因为如果`DEBUG`是`False`，那么`debug`模板变量一开始就不会被RequestContext所包含。
### django.core.context\_processors.i18n
如果这个处理器启用，每个 `RequestContext` 将包含下面的变量：
- `LANGUAGES` ： `LANGUAGES` 选项的值。
- `LANGUAGE_CODE` ：如果 `request.LANGUAGE_CODE` 存在，就等于它；否则，等同于 `LANGUAGE_CODE` 设置。
附录E提供了有关这两个设置的更多的信息。
### django.core.context\_processors.request
如果启用这个处理器，每个 `RequestContext` 将包含变量 `request` ， 也就是当前的 `HttpRequest` 对象。 注意这个处理器默认是不启用的，你需要激活它。
如果你发现你的模板需要访问当前的`HttpRequest`你就需要使用它:
```
<pre class="calibre9">```
{{ request.REMOTE_ADDR }}
```
```
### 写Context处理器的一些建议
编写处理器的一些建议：
- 使每个context处理器完成尽可能小的功能。 使用多个处理器是很容易的，所以你可以根据逻辑块来分解功能以便将来复用。
- 要注意 `TEMPLATE_CONTEXT_PROCESSORS` 里的context processor 将会在基于这个settings.py的*每个* 模板中有效，所以变量的命名不要和模板的变量冲突。 变量名是大小写敏感的，所以processor的变量全用大写是个不错的主意。
- 不论它们存放在哪个物理路径下，只要在你的Python搜索路径中，你就可以在 `TEMPLATE_CONTEXT_PROCESSORS` 设置里指向它们。 建议你把它们放在应用或者工程目录下名为 `context_processors.py` 的文件里。
## html自动转意
从模板生成html的时候，总是有一个风险——变量包了含会影响结果html的字符。 例如，考虑这个模板片段：
```
<pre class="calibre9">```
Hello, {{ name }}.
```
```
一开始，这看起来是显示用户名的一个无害的途径，但是考虑如果用户输入如下的名字将会发生什么：
```
<pre class="calibre9">```
<script>alert('hello')</script>
```
```
用这个用户名，模板将被渲染成：
```
<pre class="calibre9">```
Hello, <script>alert('hello')</script>
```
```
这意味着浏览器将弹出JavaScript警告框！
类似的，如果用户名包含`小于`符号，就像这样：
用户名
那样的话模板结果被翻译成这样：
```
<pre class="calibre9">```
Hello, <b>username
```
```
页面的剩余部分变成了粗体！
显然，用户提交的数据不应该被盲目信任，直接插入到你的页面中。因为一个潜在的恶意的用户能够利用这类漏洞做坏事。 这类漏洞称为被跨域脚本 (XSS) 攻击。 关于安全的更多内容，请看20章
为了避免这个问题，你有两个选择：
- 一是你可以确保每一个不被信任的变量都被`escape`过滤器处理一遍，把潜在有害的html字符转换为无害的。 这是最初几年Django的默认方案，但是这样做的问题是它把责任推给*你*（开发者、模版作者）自己，来确保把所有东西转意。 很容易就忘记转意数据。
- 二是，你可以利用Django的自动html转意。 这一章的剩余部分描述自动转意是如何工作的。
在django里默认情况下，每一个模板自动转意每一个变量标签的输出。 尤其是这五个字符。
- [``](#id5)`\\ ```
System Message: WARNING/2 (`<string>`, line 491); *backlink*
Inline literal start-string without end-string.
- \> 被转换为>
- `'`（单引号）被转换为`'`
- `"`(双引号)被转换为`"`
- `&` is converted to `&`
另外，我强调一下这个行为默认是开启的。 如果你正在使用django的模板系统，那么你是被保护的。
### 如何关闭它
如果你不想数据被自动转意，在每一站点级别、每一模板级别或者每一变量级别你都有几种方法来关闭它。
为什么要关闭它？ 因为有时候模板变量包含了一些原始html数据，在这种情况下我们不想它们的内容被转意。 例如，你可能在数据库里存储了一段被信任的html代码，并且你想直接把它嵌入到你的模板里。 或者，你可能正在使用Django的模板系统生成非html文本，比如一封e-mail。
#### 对于单独的变量
用safe过滤器为单独的变量关闭自动转意：
```
<pre class="calibre9">```
This will be escaped: {{ data }}
This will not be escaped: {{ data|safe }}
```
```
你可以把*safe*当做*safe from further escaping*的简写，或者*当做可以被直接译成HTML的内容*。在这个例子里，如果`数据`包含`''`，那么输出会变成：
```
<pre class="calibre9">```
This will be escaped: <b>
This will not be escaped: <b>
```
```
#### 对于模板块
为了控制模板的自动转意,用标签autoescape来包装整个模板(或者模板中常用的部分),就像这样：
```
<pre class="calibre9">```
{% autoescape off %}
Hello {{ name }}
{% endautoescape %}
```
```
autoescape 标签有两个参数on和off 有时,你可能想阻止一部分自动转意,对另一部分自动转意。 这是一个模板的例子：
```
<pre class="calibre9">```
Auto-escaping is on by default. Hello {{ name }}
{% autoescape off %}
This will not be auto-escaped: {{ data }}.
Nor this: {{ other_data }}
{% autoescape on %}
Auto-escaping applies again: {{ name }}
{% endautoescape %}
{% endautoescape %}
```
```
auto-escaping 标签的作用域不仅可以影响到当前模板还可以通过include标签作用到其他标签,就像block标签一样。 例如：
```
<pre class="calibre9">```
# base.html
{% autoescape off %}
<h1>{% block title %}{% endblock %}</h1>
{% block content %}
{% endblock %}
{% endautoescape %}
# child.html
{% extends "base.html" %}
{% block title %}This & that{% endblock %}
{% block content %}{{ greeting }}{% endblock %}
```
```
由于在base模板中自动转意被关闭,所以在child模板中自动转意也会关闭.因此,在下面一段HTML被提交时,变量greeting的值就为字符串Hello!
```
<pre class="calibre9">```
<h1>This & that</h1>
<b>Hello!</b>
```
```
### 备注
通常,模板作者没必要为自动转意担心. 基于Pyhton的开发者(编写VIEWS视图和自定义过滤器)只需要考虑哪些数据不需要被转意,适时的标记数据,就可以让它们在模板中工作。
如果你正在编写一个模板而不知道是否要关闭自动转意,那就为所有需要转意的变量添加一个escape过滤器。 当自动转意开启时，使用escape过滤器似乎会两次转意数据，但其实没有任何危险。因为escape过滤器不作用于被转意过的变量。
### 过滤器参数里的字符串常量的自动转义
就像我们前面提到的,过滤器也可以是字符串.
```
<pre class="calibre9">```
{{ data|default:"This is a string literal." }}
```
```
所有字符常量没有经过转义就被插入模板,就如同它们都经过了safe过滤。 这是由于字符常量完全由模板作者决定,因此编写模板的时候他们会确保文本的正确性。
这意味着你必须这样写
```
<pre class="calibre9">```
{{ data|default:"3 < 2" }}
```
```
而不是这样
```
<pre class="calibre9">```
{{ data|default:"3 < 2" }} <-- Bad! Don't do this.
```
```
这点对来自变量本身的数据不起作用。 如果必要,变量内容会自动转义,因为它们不在模板作者的控制下。
## 模板加载的内幕
一般说来，你会把模板以文件的方式存储在文件系统中，但是你也可以使用自定义的 *template loaders* 从其他来源加载模板。
Django有两种方法加载模板
- `django.template.loader.get_template(template_name)` ： `get_template` 根据给定的模板名称返回一个已编译的模板（一个 `Template` 对象）。 如果模板不存在，就触发 `TemplateDoesNotExist` 的异常。
- `django.template.loader.select_template(template_name_list)` ： `select_template` 很像 `get_template` ，不过它是以模板名称的列表作为参数的。 它会返回列表中存在的第一个模板。 如果模板都不存在，将会触发`TemplateDoesNotExist`异常。
正如在第四章中所提到的，默认情况下这些函数使用 `TEMPLATE_DIRS` 的设置来载入模板。 但是，在内部这些函数可以指定一个模板加载器来完成这些繁重的任务。
一些加载器默认被禁用，但是你可以通过编辑 `TEMPLATE_LOADERS` 设置来激活它们。 `TEMPLATE_LOADERS` 应当是一个字符串的元组，其中每个字符串都表示一个模板加载器。 这些模板加载器随Django一起发布。
> `django.template.loaders.filesystem.load_template_source` : 这个加载器根据 `TEMPLATE_DIRS` 的设置从文件系统加载模板。它默认是可用的。
>
> `django.template.loaders.app_directories.load_template_source` : 这个加 载器从文件系统上的Django应用中加载模板。 对 `INSTALLED_APPS` 中的每个应用，这个加载器会查找`templates` 子目录。 如果这个目录存在，Django就在那里寻找模板。
>
> 这意味着你可以把模板和你的应用一起保存，从而使得Django应用更容易和默认模板一起发布。 例如，如果 `INSTALLED_APPS` 包含 `('myproject.polls','myproject.music')` ，那么 `get_template('foo.html')` 会按这个顺序查找模板：
>
> - `/path/to/myproject/polls/templates/foo.html`
>
> - `/path/to/myproject/music/templates/foo.html`
>
> 请注意加载器在首次被导入的时候会执行一个优化： 它会缓存一个列表，这个列表包含了 `INSTALLED_APPS` 中带有 `templates` 子目录的包。
>
> 这个加载器默认启用。
>
> `django.template.loaders.eggs.load_template_source` : 这个加载器类似 `app_directories` ，只不过它从Python eggs而不是文件系统中加载模板。 这个加载器默认被禁用；如果你使用eggs来发布你的应用，那么你就需要启用它。 Python eggs可以将Python代码压缩到一个文件中。
Django按照 `TEMPLATE_LOADERS` 设置中的顺序使用模板加载器。 它逐个使用每个加载器直至找到一个匹配的模板。
## 扩展模板系统
既然你已经对模板系统的内幕多了一些了解，让我们来看看如何使用自定义的代码来扩展这个系统吧。
绝大部分的模板定制是以自定义标签/过滤器的方式来完成的。 尽管Django模板语言自带了许多内建标签和过滤器，但是你可能还是需要组建你自己的标签和过滤器库来满足你的需要。 幸运的是，定义你自己的功能非常容易。
### 创建一个模板库
不管是写自定义标签还是过滤器，第一件要做的事是创建**模板库**（Django能够导入的基本结构）。
创建一个模板库分两步走：
> 第一，决定模板库应该放在哪个Django应用下。 如果你通过 `manage.py startapp` 创建了一个应用，你可以把它放在那里，或者你可以为模板库单独创建一个应用。 我们更推荐使用后者，因为你的filter可能在后来的工程中有用。
>
> 无论你采用何种方式，请确保把你的应用添加到 `INSTALLED_APPS` 中。 我们稍后会解释这一点。
>
> 第二，在适当的Django应用包里创建一个 `templatetags` 目录。 这个目录应当和 `models.py` 、 `views.py` 等处于同一层次。 例如：
```
<pre class="calibre9">```
books/
__init__.py
models.py
templatetags/
views.py
```
```
> 在 `templatetags` 中创建两个空文件： 一个 `__init__.py` （告诉Python这是 一个包含了Python代码的包）和一个用来存放你自定义的标签/过滤器定义的文件。 第二个文件的名字稍后将用来加载标签。 例如，如果你的自定义标签/过滤器在一个叫作 `poll_extras.py` 的文件中，你需要在模板中写入如下内容：
```
<pre class="calibre9">```
{% load poll_extras %}
```
```
> `{% load %}` 标签检查 `INSTALLED_APPS` 中的设置，仅允许加载已安装的Django应用程序中的模板库。 这是一个安全特性；它可以让你在一台电脑上部署很多的模板库的代码，而又不用把它们暴露给每一个Django安装。
如果你写了一个不和任何特定模型/视图关联的模板库，那么得到一个仅包含 `templatetags` 包的Django应用程序包是完全正常的。 对于在 `templatetags` 包中放置多少个模块没有做任何的限制。 需要了解的是：`{%load%}`语句是通过指定的Python模块名而不是应用名来加载标签/过滤器的。
一旦创建了Python模块，你只需根据是要编写过滤器还是标签来相应的编写一些Python代码。
作为合法的标签库，模块需要包含一个名为`register`的模块级变量。这个变量是`template.Library`的实例，是所有注册标签和过滤器的数据结构。 所以，请在你的模块的顶部插入如下语句：
```
<pre class="calibre9">```
from django import template
register = template.Library()
```
```
注意
请阅读Django默认的过滤器和标签的源码，那里有大量的例子。 他们分别为： `django/template/defaultfilters.py` 和 django/template/defaulttags.py 。django.contrib中的某些应用程序也包含模板库。
创建 `register` 变量后，你就可以使用它来创建模板的过滤器和标签了。
### 自定义模板过滤器
自定义过滤器就是有一个或两个参数的Python函数:
- (输入)变量的值
- 参数的值， 可以是默认值或者完全留空
例如，在过滤器 `{{ var|foo:"bar" }}` 中 ，过滤器 `foo` 会被传入变量 `var` 和默认参数 `bar`。
过滤器函数应该总有返回值。 而且不能触发异常，它们都应该静静地失败。 如果出现错误，应该返回一个原始输入或者空字符串，这会更有意义。
这里是一些定义过滤器的例子：
```
<pre class="calibre9">```
def cut(value, arg):
"Removes all values of arg from the given string"
return value.replace(arg, '')
```
```
下面是一个可以用来去掉变量值空格的过滤器例子：
```
<pre class="calibre9">```
{{ somevariable|cut:" " }}
```
```
大多数过滤器并不需要参数。 下面的例子把参数从你的函数中拿掉了：
```
<pre class="calibre9">```
def lower(value): # Only one argument.
"Converts a string into all lowercase"
return value.lower()
```
```
当你定义完过滤器后，你需要用 `Library` 实例来注册它，这样就能通过Django的模板语言来使用了：
```
<pre class="calibre9">```
register.filter('cut', cut)
register.filter('lower', lower)
```
```
`Library.filter()` 方法需要两个参数：
- 过滤器的名称（一个字串）
- 过滤器函数本身
如果你使用的是Python 2.4或者更新的版本，你可以使用装饰器`register.filter()`：
```
<pre class="calibre9">```
@register.filter(name='cut')
def cut(value, arg):
return value.replace(arg, '')
@register.filter
def lower(value):
return value.lower()
```
```
如果你想第二个例子那样不使用 `name` 参数，那么Django会把函数名当作过滤器的名字。
下面是一个完整的模板库的例子，它包含一个 `cut` 过滤器：
```
<pre class="calibre9">```
from django import template
register = template.Library()
@register.filter(name='cut')
def cut(value, arg):
return value.replace(arg, '')
```
```
### 自定义模板标签
标签要比过滤器复杂些，因为标签几乎能做任何事情。
第四章描述了模板系统的两步处理过程： 编译和呈现。 为了自定义一个模板标签，你需要告诉Django当遇到你的标签时怎样进行这个过程。
当Django编译一个模板时，它将原始模板分成一个个 *节点* 。每个节点都是 `django.template.Node` 的一个实例，并且具备 `render()` 方法。 于是，一个已编译的模板就是 `节点` 对象的一个列表。 例如，看看这个模板：
```
<pre class="calibre9">```
Hello, {{ person.name }}.
{% ifequal name.birthday today %}
Happy birthday!
{% else %}
Be sure to come back on your birthday
for a splendid surprise message.
{% endifequal %}
```
```
被编译的模板表现为节点列表的形式：
- 文本节点： `"Hello, "`
- 变量节点： `person.name`
- 文本节点: `".\n\n"`
- IfEqual节点: `name.birthday`和`today`
当你调用一个已编译模板的 `render()` 方法时，模板就会用给定的context来调用每个在它的节点列表上的所有节点的 `render()` 方法。 这些渲染的结果合并起来，形成了模板的输出。 因此，要自定义模板标签，你需要指明原始模板标签如何转换成`节点`（编译函数）和节点的`render()`方法完成的功能 。
在下面的章节中，我们将详细解说写一个自定义标签时的所有步骤。
### 编写编译函数
当遇到一个模板标签（template tag）时，模板解析器就会把标签包含的内容，以及模板解析器自己作为参数调用一个python函数。 这个函数负责返回一个和当前模板标签内容相对应的节点（Node）的实例。
例如，写一个显示当前日期的模板标签：{% current\_time %}。该标签会根据参数指定的 strftime 格式（参见：`http://www.djangoproject.com/r/python/strftime/`）显示当前时间。首先确定标签的语法是个好主意。 在这个例子里，标签应该这样使用：
```
<pre class="calibre9">```
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>
```
```
注意
没错, 这个模板标签是多余的，Django默认的 `{% now %}` 用更简单的语法完成了同样的工作。 这个模板标签在这里只是作为一个例子。
这个函数的分析器会获取参数并创建一个 `Node` 对象:
```
<pre class="calibre9">```
from django import template
register = template.Library()
def do_current_time(parser, token):
try:
# split_contents() knows not to split quoted strings.
tag_name, format_string = token.split_contents()
except ValueError:
msg = '%r tag requires a single argument' % token.split_contents()[0]
raise template.TemplateSyntaxError(msg)
return CurrentTimeNode(format_string[1:-1])
```
```
这里需要说明的地方很多：
- 每个标签编译函数有两个参数，`parser`和`token`。`parser`是模板解析器对象。 我们在这个例子中并不使用它。 `token`是正在被解析的语句。
- `token.contents` 是包含有标签原始内容的字符串。 在我们的例子中，它是 `'current_time "%Y-%m-%d %I:%M %p"'` 。
- `token.split_contents()` 方法按空格拆分参数同时保证引号中的字符串不拆分。 应该避免使用 `token.contents.split()` （仅使用Python的标准字符串拆分）。 它不够健壮，因为它只是简单的按照所有空格进行拆分，包括那些引号引起来的字符串中的空格。
- 这个函数可以抛出 `django.template.TemplateSyntaxError` ，这个异常提供所有语法错误的有用信息。
- 不要把标签名称硬编码在你的错误信息中，因为这样会把标签名称和你的函数耦合在一起。 `token.split_contents()[0]`*总是*记录标签的名字，就算标签没有任何参数。
- 这个函数返回一个 `CurrentTimeNode` （稍后我们将创建它），它包含了节点需要知道的关于这个标签的全部信息。 在这个例子中，它只是传递了参数 `"%Y-%m-%d %I:%M %p"` 。模板标签开头和结尾的引号使用 `format_string[1:-1]` 除去。
- 模板标签编译函数 *必须* 返回一个 `Node` 子类，返回其它值都是错的。
### 编写模板节点
编写自定义标签的第二步就是定义一个拥有 `render()` 方法的 `Node` 子类。 继续前面的例子，我们需要定义 `CurrentTimeNode` ：
```
<pre class="calibre9">```
import datetime
class CurrentTimeNode(template.Node):
def __init__(self, format_string):
self.format_string = str(format_string)
def render(self, context):
now = datetime.datetime.now()
return now.strftime(self.format_string)
```
```
这两个函数（ `__init__()` 和 `render()` ）与模板处理中的两步（编译与渲染）直接对应。 这样，初始化函数仅仅需要存储后面要用到的格式字符串，而 `render()` 函数才做真正的工作。
与模板过滤器一样，这些渲染函数应该静静地捕获错误，而不是抛出错误。 模板标签只允许在编译的时候抛出错误。
### 注册标签
最后，你需要用你模块的`Library` 实例注册这个标签。 注册自定义标签与注册自定义过滤器非常类似（如前文所述）。 只需实例化一个 `template.Library` 实例然后调用它的 `tag()` 方法。 例如：
```
<pre class="calibre9">```
register.tag('current_time', do_current_time)
```
```
`tag()` 方法需要两个参数:
- 模板标签的名字（字符串）。
- 编译函数。
和注册过滤器类似，也可以在Python2.4及其以上版本中使用 `register.tag`装饰器：
```
<pre class="calibre9">```
@register.tag(name="current_time")
def do_current_time(parser, token):
# ...
@register.tag
def shout(parser, token):
# ...
```
```
如果你像在第二个例子中那样忽略 `name` 参数的话，Django会使用函数名称作为标签名称。
### 在上下文中设置变量
前一节的例子只是简单的返回一个值。 很多时候设置一个模板变量而非返回值也很有用。 那样，模板作者就只能使用你的模板标签所设置的变量。
要在上下文中设置变量，在 `render()` 函数的context对象上使用字典赋值。 这里是一个修改过的 `CurrentTimeNode` ，其中设定了一个模板变量 `current_time` ，并没有返回它：
```
<pre class="calibre9">```
class CurrentTimeNode2(template.Node):
def __init__(self, format_string):
self.format_string = str(format_string)
def render(self, context):
now = datetime.datetime.now()
context['current_time'] = now.strftime(self.format_string)
return ''
```
```
(我们把创建函数`do_current_time2`和注册给`current_time2`模板标签的工作留作读者练习。)
注意 `render()` 返回了一个空字符串。 `render()` 应当总是返回一个字符串，所以如果模板标签只是要设置变量， `render()` 就应该返回一个空字符串。
你应该这样使用这个新版本的标签：
```
<pre class="calibre9">```
{% current_time2 "%Y-%M-%d %I:%M %p" %}
<p>The time is {{ current_time }}.</p>
```
```
但是 `CurrentTimeNode2` 有一个问题: 变量名 `current_time` 是硬编码的。 这意味着你必须确定你的模板在其它任何地方都不使用 `{{ current_time }}` ，因为 `{% current_time2 %}` 会盲目的覆盖该变量的值。
一种更简洁的方案是由模板标签来指定需要设定的变量的名称，就像这样：
```
<pre class="calibre9">```
{% get_current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>
```
```
为此，你需要重构编译函数和 `Node` 类，如下所示：
```
<pre class="calibre9">```
import re
class CurrentTimeNode3(template.Node):
def __init__(self, format_string, var_name):
self.format_string = str(format_string)
self.var_name = var_name
def render(self, context):
now = datetime.datetime.now()
context[self.var_name] = now.strftime(self.format_string)
return ''
def do_current_time(parser, token):
# This version uses a regular expression to parse tag contents.
try:
# Splitting by None == splitting by spaces.
tag_name, arg = token.contents.split(None, 1)
except ValueError:
msg = '%r tag requires arguments' % token.contents[0]
raise template.TemplateSyntaxError(msg)
m = re.search(r'(.*?) as (\w+)', arg)
if m:
fmt, var_name = m.groups()
else:
msg = '%r tag had invalid arguments' % tag_name
raise template.TemplateSyntaxError(msg)
if not (fmt[0] == fmt[-1] and fmt[0] in ('"', "'")):
msg = "%r tag's argument should be in quotes" % tag_name
raise template.TemplateSyntaxError(msg)
return CurrentTimeNode3(fmt[1:-1], var_name)
```
```
现在 `do_current_time()` 把格式字符串和变量名传递给 `CurrentTimeNode3` 。
### 分析直至另一个模板标签
模板标签可以像包含其它标签的块一样工作（想想 `{% if %}` 、 `{% for %}` 等）。 要创建一个这样的模板标签，在你的编译函数中使用 `parser.parse()` 。
标准的 `{% comment %}` 标签是这样实现的：
```
<pre class="calibre9">```
def do_comment(parser, token):
nodelist = parser.parse(('endcomment',))
parser.delete_first_token()
return CommentNode()
class CommentNode(template.Node):
def render(self, context):
return ''
```
```
`parser.parse()` 接收一个包含了需要分析的模板标签名的元组作为参数。 它返回一个`django.template.NodeList`实例，它是一个包含了所有*Node*对象的列表，这些对象是解析器在解析到任一元组中指定的标签之前遇到的内容.
因此在前面的例子中， `nodelist` 是在 `{% comment %}` 和 `{% endcomment %}` 之间所有节点的列表，不包括 `{% comment %}` 和 `{% endcomment %}` 自身。
在 `parser.parse()` 被调用之后，分析器还没有清除 `{% endcomment %}` 标签，因此代码需要显式地调用 `parser.delete_first_token()` 来防止该标签被处理两次。
之后 `CommentNode.render()` 只是简单地返回一个空字符串。 在 `{% comment %}` 和 `{% endcomment %}` 之间的所有内容都被忽略。
### 分析直至另外一个模板标签并保存内容
在前一个例子中， `do_comment()` 抛弃了`{% comment %}` 和 `{% endcomment %}` 之间的所有内容。当然也可以修改和利用下标签之间的这些内容。
例如，这个自定义模板标签`{% upper %}`，它会把它自己和`{% endupper %}`之间的内容变成大写：
```
<pre class="calibre9">```
{% upper %}
This will appear in uppercase, {{ user_name }}.
{% endupper %}
```
```
就像前面的例子一样，我们将使用 `parser.parse()` 。这次，我们将产生的 `nodelist` 传递给 `Node` ：
```
<pre class="calibre9">```
def do_upper(parser, token):
nodelist = parser.parse(('endupper',))
parser.delete_first_token()
return UpperNode(nodelist)
class UpperNode(template.Node):
def __init__(self, nodelist):
self.nodelist = nodelist
def render(self, context):
output = self.nodelist.render(context)
return output.upper()
```
```
这里唯一的一个新概念是 `UpperNode.render()` 中的 `self.nodelist.render(context)` 。它对节点列表中的每个 `Node` 简单的调用 `render()` 。
更多的复杂渲染示例请查看 `django/template/defaulttags.py` 中的 `{% if %}` 、 `{% for %}` 、 `{% ifequal %}` 和 `{% ifchanged %}` 的代码。
### 简单标签的快捷方式
许多模板标签接收单一的字符串参数或者一个模板变量引用，然后独立地根据输入变量和一些其它外部信息进行处理并返回一个字符串。 例如，我们先前写的`current_time`标签就是这样一个例子。 我们给定了一个格式化字符串，然后它返回一个字符串形式的时间。
为了简化这类标签，Django提供了一个帮助函数`simple_tag`。这个函数是`django.template.Library`的一个方法，它接受一个只有一个参数的函数作参数，把它包装在render函数和之前提及过的其他的必要单位中，然后通过模板系统注册标签。
我们之前的的 `current_time` 函数于是可以写成这样：
```
<pre class="calibre9">```
def current_time(format_string):
try:
return datetime.datetime.now().strftime(str(format_string))
except UnicodeEncodeError:
return ''
register.simple_tag(current_time)
```
```
在Python 2.4中，也可以使用装饰器语法：
```
<pre class="calibre9">```
@register.simple_tag
def current_time(token):
# ...
```
```
有关 `simple_tag` 辅助函数，需要注意下面一些事情：
- 传递给我们的函数的只有（单个）参数。
- 在我们的函数被调用的时候，检查必需参数个数的工作已经完成了，所以我们不需要再做这个工作。
- 参数两边的引号（如果有的话）已经被截掉了，所以我们会接收到一个普通Unicode字符串。
### 包含标签
另外一类常用的模板标签是通过渲染 *其他* 模板显示数据的。 比如说，Django的后台管理界面，它使用了自定义的模板标签来显示新增/编辑表单页面下部的按钮。 那些按钮看起来总是一样的，但是链接却随着所编辑的对象的不同而改变。 这就是一个使用小模板很好的例子，这些小模板就是当前对象的详细信息。
这些排序标签被称为 *包含标签* 。如何写包含标签最好通过举例来说明。 让我们来写一个能够产生指定`作者`对象的书籍清单的标签。 我们将这样利用标签：
```
<pre class="calibre9">```
{% books_for_author author %}
```
```
结果将会像下面这样：
```
<pre class="calibre9">```
<ul>
<li>The Cat In The Hat</li>
<li>Hop On Pop</li>
<li>Green Eggs And Ham</li>
</ul>
```
```
首先，我们定义一个函数，通过给定的参数生成一个字典形式的结果。 需要注意的是，我们只需要返回字典类型的结果就行了，不需要返回更复杂的东西。 这将被用来作为模板片段的内容：
```
<pre class="calibre9">```
def books_for_author(author):
books = Book.objects.filter(authors__id=author.id)
return {'books': books}
```
```
接下来，我们创建用于渲染标签输出的模板。 在我们的例子中，模板很简单：
```
<pre class="calibre9">```
<ul>
{% for book in books %}
<li>{{ book.title }}</li>
{% endfor %}
</ul>
```
```
最后，我们通过对一个 `Library` 对象使用 `inclusion_tag()` 方法来创建并注册这个包含标签。
在我们的例子中，如果先前的模板在 `polls/result_snippet.html` 文件中，那么我们这样注册标签：
```
<pre class="calibre9">```
register.inclusion_tag('book_snippet.html')(books_for_author)
```
```
Python 2.4装饰器语法也能正常工作，所以我们可以这样写：
```
<pre class="calibre9">```
@register.inclusion_tag('book_snippet.html')
def books_for_author(author):
# ...
```
```
有时候，你的包含标签需要访问父模板的context。 为了解决这个问题，Django为包含标签提供了一个 `takes_context` 选项。 如果你在创建模板标签时，指明了这个选项，这个标签就不需要参数，并且下面的Python函数会带一个参数： 就是当这个标签被调用时的模板context。
例如，你正在写一个包含标签，该标签包含有指向主页的 `home_link` 和 `home_title` 变量。 Python函数会像这样：
```
<pre class="calibre9">```
@register.inclusion_tag('link.html', takes_context=True)
def jump_link(context):
return {
'link': context['home_link'],
'title': context['home_title'],
}
```
```
（注意函数的第一个参数 *必须* 是 `context` 。）
模板 `link.html` 可能包含下面的东西：
```
<pre class="calibre9">```
Jump directly to <a href="{{ link }}">{{ title }}</a>.
```
```
然后您想使用自定义标签时，就可以加载它的库，然后不带参数地调用它，就像这样：
```
<pre class="calibre9">```
{% jump_link %}
```
```
## 编写自定义模板加载器
Djangos 内置的模板加载器（在先前的模板加载内幕章节有叙述）通常会满足你的所有的模板加载需求，但是如果你有特殊的加载需求的话，编写自己的模板加载器也会相当简单。 比如：你可以从数据库中，或者利用Python的绑定直接从Subversion库中，更或者从一个ZIP文档中加载模板。
模板加载器，也就是 `TEMPLATE_LOADERS` 中的每一项，都要能被下面这个接口调用：
```
<pre class="calibre9">```
load_template_source(template_name, template_dirs=None)
```
```
参数 `template_name` 是所加载模板的名称 (和传递给 `loader.get_template()` 或者 `loader.select_template()` 一样), 而 `template_dirs` 是一个可选的代替`TEMPLATE_DIRS`的搜索目录列表。
如果加载器能够成功加载一个模板, 它应当返回一个元组： `(template_source, template_path)` 。在这里的 `template_source` 就是将被模板引擎编译的的模板字符串，而 `template_path` 是被加载的模板的路径。 由于那个路径可能会出于调试目的显示给用户，因此它应当很快的指明模板从哪里加载。
如果加载器加载模板失败，那么就会触发 `django.template.TemplateDoesNotExist` 异常。
每个加载函数都应该有一个名为 `is_usable` 的函数属性。 这个属性是一个布尔值，用于告知模板引擎这个加载器是否在当前安装的Python中可用。 例如，如果 `pkg_resources` 模块没有安装的话，eggs加载器（它能够从python eggs中加载模板）就应该把 `is_usable` 设为 `False` ，因为必须通过 `pkg_resources` 才能从eggs中读取数据。
一个例子可以清晰地阐明一切。 这儿是一个模板加载函数，它可以从ZIP文件中加载模板。 它使用了自定义的设置 `TEMPLATE_ZIP_FILES` 来取代了 `TEMPLATE_DIRS` 用作查找路径，并且它假设在此路径上的每一个文件都是包含模板的ZIP文件：
```
<pre class="calibre9">```
from django.conf import settings
from django.template import TemplateDoesNotExist
import zipfile
def load_template_source(template_name, template_dirs=None):
"Template loader that loads templates from a ZIP file."
template_zipfiles = getattr(settings, "TEMPLATE_ZIP_FILES", [])
# Try each ZIP file in TEMPLATE_ZIP_FILES.
for fname in template_zipfiles:
try:
z = zipfile.ZipFile(fname)
source = z.read(template_name)
except (IOError, KeyError):
continue
z.close()
# We found a template, so return the source.
template_path = "%s:%s" % (fname, template_name)
return (source, template_path)
# If we reach here, the template couldn't be loaded
raise TemplateDoesNotExist(template_name)
# This loader is always usable (since zipfile is included with Python)
load_template_source.is_usable = True
```
```
我们要想使用它，还差最后一步，就是把它加入到 `TEMPLATE_LOADERS` 。 如果我们将这个代码放入一个叫mysite.zip\_loader的包中，那么我们要把mysite.zip\_loader.load\_template\_source加到TEMPLATE\_LOADERS中。
## 配置独立模式下的模板系统
注意：
这部分只针对于对在其他应用中使用模版系统作为输出组件感兴趣的人。 如果你是在Django应用中使用模版系统，请略过此部分。
通常，Django会从它的默认配置文件和由 `DJANGO_SETTINGS_MODULE` 环境变量所指定的模块中加载它需要的所有配置信息。 （这点在第四章的”特殊的Python命令提示行”一节解释过。）但是当你想在非Django应用中使用模版系统的时候，采用环境变量并不方便，因为你可能更想同其余的应用一起配置你的模板系统，而不是处理配置文件并通过环境变量指向他们。
为了解决这个问题，你需要使用附录D中所描述的手动配置选项。概括的说，你需要导入正确的模板中的片段，然后在你访问任一个模板函数之前，首先用你想指定的配置访问Django.conf.settings.configure()。
你可能会考虑至少要设置 `TEMPLATE_DIRS` （如果你打算使用模板加载器）， `DEFAULT_CHARSET` （尽管默认的 `utf-8` 编码相当好用），以及 `TEMPLATE_DEBUG` 。所有可用的选项在附录D中都有详细描述，所有以 `TEMPLATE_` 开头的选项都可能使你感兴趣。
## 接下来做什么？
延续本章的高级话题，下一章 会继续讨论Django模版的高级用法。
