模板语言回顾

首先，让我们快速回顾一下第四章介绍的若干专业术语

模板 是一个纯文本文件，或是一个用Django模板语言标记过的普通的Python字符串，一个模板可以包含区块标签和变量。

区块标签 是在一个模板里面起作用的的标记，这个定义故意说的很含糊，比如，一个 区块标签可以生成内容，可以作为一个控制结构（ if 语句或 for 循环）， 可以获取数据库内容，或者访问其他的模板标签。

区块标签被 {% 和 %} 包含：

{% if is_logged_in %}
  Thanks for logging in!
{% else %}
  Please log in.
{% endif %}

变量 是一个在模板里用来输出值的标记。

变量标签被 {{ 和 }} 包含：

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 。例如，看下面的四个视图：

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)

def view_3(request):
# ...
    t = loader.get_template('template3.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the third view.'
    })
    return t.render(c)

def view_4(request):
    # ...
    t = loader.get_template('template4.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the fourth 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改写如下：

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)

def view_3(request):
    # ...
    t = loader.get_template('template3.html')
    c = RequestContext(request, {'message': 'I am the third view.'},
            processors=[custom_proc])
    return t.render(c)

def view_4(request):
    # ...
    t = loader.get_template('template4.html')
    c = RequestContext(request, {'message': 'I am the fourth view.'},
            processors=[custom_proc])
    return t.render(c)

我们来通读一下代码：

• 首先，我们定义一个函数 custom_proc 。这是一个context处理器，它接收一个 HttpRequest 对象，然后返回一个字典，这个字典中包含了可以在模板context中使用的变量。它就做了这么多。

• 我们在这四个视图函数中用 RequestContext 代替了 Context 。在context对象的构建上有两个不同点。一， RequestContext 的第一个参数需要传递一个 HttpRequest 对象，就是传递给视图函数的第一个参数（ request ）。二， RequestContext 有一个可选的参数 processors ，这是一个包含context处理器函数的list或者tuple。在这里，我们传递了我们之前定义的函数 curstom_proc 。

• 每个视图的context结构里不再包含 app 、 user 、 ip_address 等变量，因为这些由 custom_proc 函数提供了。

O5akXl <a href=”http://xrdylvofgyks.com/“>xrdylvofgyks</a>, [url=http://jpknyzrymcvm.com/]jpknyzrymcvm[/url], [link=http://kanomsrvtkmd.com/]kanomsrvtkmd[/link], http://avajxtraqqjg.com/

在第四章，我们介绍了 render_to_response() 这个快捷方式，它可以省掉调用 loader.get_template() ,然后创建一个 Context 对象，最后再调用模板对象的 render() 方法。为了讲解context处理器底层是如何工作的，在上面的例子中我们没有使用 render_to_response() 。但是建议选择 render_to_response() 作为context的处理器。像这样，使用 context_instance 参数：

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]))

def view_3(request):
    # ...
    return render_to_response('template3.html',
        {'message': 'I am the third view.'},
        context_instance=RequestContext(request, processors=[custom_proc]))

def view_4(request):
    # ...
    return render_to_response('template4.html',
        {'message': 'I am the fourth view.'},
        context_instance=RequestContext(request, processors=[custom_proc]))

在这，我们将每个视图的模板渲染代码写成了一个单行。

虽然这是一种改进，但是，请考虑一下这段代码的简洁性，我们现在不得不承认的是在 另外 一方面有些过分了。我们以代码冗余（在 processors 调用中）的代价消除了数据上的冗余（我们的模板变量）。由于你不得不一直键入 processors ，所以使用context处理器并没有减少太多的打字次数。

Django因此提供对 全局 context处理器的支持。 TEMPLATE_CONTEXT_PROCESSORS 指定了 总是 使用哪些 context processors 。这样就省去了每次使用 RequestContext 都指定 processors 的麻烦^_^。

ilR94N <a href=”http://bxcyktdovtcx.com/“>bxcyktdovtcx</a>, [url=http://svkmchcyqtpi.com/]svkmchcyqtpi[/url], [link=http://orlgauoznlpg.com/]orlgauoznlpg[/link], http://hcmltazhxlgv.com/

TEMPLATE_CONTEXT_PROCESSORS = (
    'django.core.context_processors.auth',
    'django.core.context_processors.debug',
    'django.core.context_processors.i18n',
    'django.core.context_processors.media',
)

这个设置是一个可调用函数的Tuple，其中的每个函数使用了和上文中我们的 custom_proc 相同的接口：接收一个request对象作为参数，返回一个包含了将被合并到context中的项的字典。请注意 TEMPLATE_CONTEXT_PROCESSORS 中的值是以 strings 的形式给出的，这意味着这些处理器必须在你的python路径中的某处（这样你才能在设置中引用它们）

RkbRhS <a href=”http://ssvglzgqktrs.com/“>ssvglzgqktrs</a>, [url=http://tzwexwjpftqx.com/]tzwexwjpftqx[/url], [link=http://siituwbkjtet.com/]siituwbkjtet[/link], http://nyplxetpyqkq.com/

Django提供了几个简单的context处理器，有些在默认情况下被启用的。

模板加载的内幕

一般说来，你会把模板以文件的方式存储在文件系统中，但是你也可以使用自定义的 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

zS7gE0 <a href=”http://xihwijxziqzw.com/“>xihwijxziqzw</a>, [url=http://latxmxlseqcl.com/]latxmxlseqcl[/url], [link=http://fwlitcrfihxf.com/]fwlitcrfihxf[/link], http://yxtsdtenuwcv.com/

请注意加载器在首次被导入的时候会执行一个优化：它会缓存一个列表，这个列表包含了 INSTALLED_APPS 中带有 templates 子目录的包。

这个加载器默认启用。

django.template.loaders.eggs.load_template_source : 这个加载器类似 app_directories ，只不过它从Python eggs而不是文件系统中加载模板。这个加载器默认被禁用；如果你使用eggs来发布你的应用，那么你就需要启用它。

Django按照 TEMPLATE_LOADERS 设置中的顺序使用模板加载器。它逐个使用每个加载器直至找到一个匹配的模板。

扩展模板系统

既然你已经对模板系统的内幕了解多了一些，让我们来看看如何使用自定义的代码来拓展这个系统吧。

绝大部分的模板定制是以自定义标签/过滤器的方式来完成的。尽管Django模板语言自带了许多内建标签和过滤器，但是你可能还是需要组建你自己的标签和过滤器库来满足你的需要。幸运的是，定义你自己的功能非常容易。

books/
    __init__.py
    models.py
    templatetags/
    views.py

{% load poll_extras %}

from django import template

register = template.Library()

def cut(value, arg):
    "Removes all values of arg from the given string"
    return value.replace(arg, '')

{{ somevariable|cut:"0" }}

def lower(value): # Only one argument.
    "Converts a string into all lowercase"
    return value.lower()

register.filter('cut', cut)
register.filter('lower', lower)

@register.filter(name='cut')
def cut(value, arg):
    return value.replace(arg, '')

@register.filter
def lower(value):
    return value.lower()

from django import template

register = template.Library()

@register.filter(name='cut')
def cut(value, arg):
    return value.replace(arg, '')

<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>

from django import template

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.contents[0]
        raise template.TemplateSyntaxError(msg)
    return CurrentTimeNode(format_string[1:-1])

import datetime

class CurrentTimeNode(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        return now.strftime(self.format_string)

register.tag('current_time', do_current_time)

@register.tag(name="current_time")
def do_current_time(parser, token):
    # ...

@register.tag
def shout(parser, token):
    # ...

class CurrentTimeNode2(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        context['current_time'] = now.strftime(self.format_string)
        return ''

{% current_time2 "%Y-%M-%d %I:%M %p" %}
<p>The time is {{ current_time }}.</p>

{% get_current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>

import re

class CurrentTimeNode3(template.Node):

    def __init__(self, format_string, var_name):
        self.format_string = 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)

def do_comment(parser, token):
    nodelist = parser.parse(('endcomment',))
    parser.delete_first_token()
    return CommentNode()

class CommentNode(template.Node):
    def render(self, context):
        return ''

{% upper %}
    This will appear in uppercase, {{ your_name }}.
{% endupper %}

@register.tag
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()

def current_time(format_string):
    return datetime.datetime.now().strftime(format_string)

register.simple_tag(current_time)

@register.simple_tag
def current_time(token):
    ...

{% show_results poll %}

<ul>
  <li>First choice</li>
  <li>Second choice</li>
  <li>Third choice</li>
</ul>

def show_books_for_author(author):
    books = author.book_set.all()
    return {'books': books}

<ul>
{% for book in books %}
    <li> {{ book }} </li>
{% endfor %}
</ul>

register.inclusion_tag('books/books_for_author.html')(show_books_for_author)

@register.inclusion_tag('books/books_for_author.html')
def show_books_for_author(show_books_for_author):
    ...

@register.inclusion_tag('link.html', takes_context=True)
def jump_link(context):
    return {
        'link': context['home_link'],
        'title': context['home_title'],
    }

Jump directly to <a href="{{ link }}">{{ title }}</a>.

{% jump_link %}

编写自定义模板加载器

Djangos 内置的模板加载器（在先前的模板加载内幕章节有叙述）通常会满足你的所有的模板加载需求，但是如果你有特殊的加载需求的话，编写自己的模板加载器也会相当简单。比如：你可以从数据库加载模板，或者使用 Subversions的Python实现直接从Subversion库加载模板，再或者（稍后展示）从zip文件加载模板。

一个模板加载器，也就是 TEMPLATE_LOADERS 中的每一项，都要能被下面这个接口所调用：

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文件：

import zipfile
from django.conf import settings
from django.template import TemplateDoesNotExist

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程序员提供给模板开发人员的一个工具。你可以点击管理页面右上角的文档链接来查看这些资料。

参考说明分为4个部分：标签、过滤器、模型和视图。 标签 和 过滤器 部分描述了所有内置的标签（实际上，第4章中用到的标签和过滤器都直接来源于那几页）以及一些可用的自定义标签和过滤器库。

视图 页面是最有价值的。网站中的每个URL都在这儿有独立的入口。如果相关的视图包含一个 文档字符串， 点击URL，你就会看到：

• 生成本视图的视图函数的名字

• 视图功能的一个简短描述

• 上下文或一个视图模板中可用的变量的列表

• 视图使用的模板的名字

要想查看关于视图文档的更详细的例子，请阅读Django的通用 object_list 视图部分的源代码，它位于 django/views/generic/list_detail.py 文件中。

通常情况下，由Django构建的网站都会使用数据库对象， 模型 页面描述了系统中所有类型的对象，以及该对象对应的所有可用字段。

总之，这些文档告诉你在模板中的所有可用的标签、过滤器、变量和对象。

配置独立模式下的模板系统

备注

这部分只针对于对在其他应用中使用模版系统作为输出组件感兴趣的人。如果你是在Django应用中使用模版系统，请略过此部分。

通常，Django会从它的默认配置文件和由 DJANGO_SETTINGS_MODULE 环境变量所指定的模块中加载它需要的所有配置信息。但是当你想在非Django应用中使用模版系统的时候，采用环境变量并不是很好的方法。比起为模版系统单独采用配置文件并用环境变量来指向它，你可能更希望能够在你的应用中采用一致的配置方法来配置模版系统和其他部分

为了解决这个问题，你需要使用附录E中所描述的手动配置选项。简单来说，你需要引入合适的模板系统，并且在调用任何模板函数 之前 调用 django.conf.settings.configure() 来指定任何你想要的设置。

你可能会考虑至少要设置 TEMPLATE_DIRS （如果你打算使用模板加载器）， DEFAULT_CHARSET （尽管默认的 utf-8 编码相当好用），以及 TEMPLATE_DEBUG 。所有可用的选项都在附录E中详细描述，所有以 TEMPLATE_ 开头的选项都可能使你感兴趣的。

接下来？

迄今为止，本书假定您想展示的内容为HTML。对于一个有关Web开发的书来说，这不是一个 不好的假设，但有时你想用Django输出其他数据格式。

下一章将讲解如何使用Django生成图像、PDF、还有你可以想到的其他数据格式。