The Django Book：第10章 深入模板引擎
大多数时候你是以模板作者的角色来与Django的模板语言交互
本章更深的潜入到Django模板系统的五脏六腑，如果你需要扩展模板系统或者只是对它怎样工作好奇，读读它
如果你在另一个程序的一部分使用Django模板系统，即不使用该框架的其它部分，确认你阅读了本文档后面的配置部分

基础
模板是一个文本文档，或者一个普通使用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值替代变量"洞"并执行块标签来渲染context

使用模板对象
最低级的使用Python模板系统只需两步:
1，把原始模板代码编辑到一个Template对象
2，使用一个给定的context调用Template对象的render()方法

编译字符串
创建Template对象的最简单的方法是直接初始化它，构造函数使用原始模板代码作为它的参数:

>>> from django.template import Template
>>> t = Template("My name is {{ my_name }}.")
>>> print t
<django.template.Template object at 0x1150c70>

在幕后系统仅仅当你创建Template对象时解析一次你的原始代码，然后由于性能的关系模板在内部作为"节点"结构存储
甚至解析本身也是非常快的，大部分的解析通过调用一个单独而简短的正则表达式来处理

渲染context
一旦你拥有一个编译过的Template对象，你可以使用它渲染一个context或者很多context
Context构造函数使用一个映射变量名和变量值的字典作为它的可选参数
使用context调用Template对象的render()方法来"填充"模板:

>>> from django.template import Context, Template
>>> t = Template("My name is {{ my_name }}.")

>>> c = Context({"my_name": "Adrian"})
>>> t.render(c)
"My name is Adrian."

>>> c = Context({"my_name": "Dolores"})
>>> t.render(c)
"My name is Dolores."

变量名必须由字母A-Z,数字0-9，下划线或小数点组成
在模板渲染中小数点有特殊的意义，变量名中的小数点表示查询，当模板系统在变量名里遇到小数点时，它尝试一些
可能的选项，例如变量{{ foo.bar }}可能扩展为下面的任何一种:
字典查询:foo["bar"]
属性查询:foo.bar
方法调用:foo.bar()
列表索引查询:foo[bar]
模板系统使用可以工作的第一种查询方式，这是短路逻辑，下面是一些例子:

>>> from django.template import Context, Template
>>> t = Template("My name is {{ person.first_name }}.")

>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
>>> t.render(Context(d))
"My name is Joe."

>>> class Person:
...     def __init__(self, first_name, last_name):
...         self.first_name, self.last_name = first_name, last_name
...
>>> p = Person("Ron", "Nasty")
>>> t.render(Context({"person": p}))
"My name is Ron."

>>> class Person2:
...     def first_name(self):
...         return "Samantha"
...
>>> p = Person2()
>>> t.render(Context({"person": p}))
"My name is Samantha."

>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
>>> t.render(c)
"The first stooge in the list is Larry."

方法查询比其它查询类型稍微复杂一点，下面是需要记住的一些事情:
1，在方法查询时当方法触发一个异常，这个异常会一直传播，除非异常有一个值为True的silent_variable_failure属性
如果异常确实有这个属性，变量将会被渲染为空字符串，例如:

>>> t = Template("My name is {{ person.first_name }}.")

>>> class Person3:
...     def first_name(self):
...         raise AssertionError("foo")
...
>>> p = Person3()
>>> t.render(Context({"person": p}))
Traceback (most recent call last):
...
AssertionError: foo

>>> class SilentAssertionError(AssertionError):
...     silent_variable_failure = True
...
>>> class Person4:
...     def first_name(self):
...         raise SilentAssertionError("foo")
...
>>> p = PersonClass4()
>>> t.render(Context({"person": p}))
"My name is ."

注意所有的Django数据库API中的DoesNotExist异常的基类django.core.exceptions.ObjectDoesNotExist有这个属性并且
值为True，所有如果你通过Django模型对象使用Django模板，任何DoesNotExist异常都将会静静的失败
2，方法调用仅仅当方法没有必需的参数时才会工作，否则系统继续下一个查询类型(列表索引查询)
3，显然，一些方法有副作用，允许模板系统访问它们则是很愚蠢的安全漏洞
一个好例子是每个Django模型对象的delete()方法，模板系统不应该允许做像这样的事情:

I will now delete this valuable data. {{ data.delete }}

在方法上设置一个方法属性alters_data来预防这点，如果这个属性为True则模板系统不会执行这个方法:

def sensitive_function(self):
    self.database_record.delete()
sensitive_function.alters_data = True

例如，Django模型对象动态生成的delete()和save()方法会自动得到alters_data=True设置

如何处理非法变量
通常，如果变量不存在，模板系统会插入TEMPLATE_STRING_IF_INVALID设置，它默认为空
只有当TEMPLATE_STRING_IF_INVALID设置为默认值的时候适用于非法变量的过滤器才会被使用
如果TEMPLATE_STRING_IF_INVALID被设置为其它任何值，变量过滤器都会被忽略
这个行为对if，for和regroup模板标签稍微不同，如果非法变量提供给这些模板标签，变量将为被解析为None
过滤器在这些模板标签中会一直对非法变量适用

和Context对象玩玩
大多数时候你将通过传递给Context()一个完全赋值的字典来初始化Context对象，但是一旦它初始化了，你可以使用标准
字典语法对Context对象添加和删除项:

>>> c = Context({"foo": "bar"})
>>> c['foo']
'bar'
>>> del c['foo']
>>> c['foo']
''
>>> c['newvariable'] = 'hello'
>>> c['newvariable']
'hello'

而且，Context对象是一个stack，你可以push()和pop()额外的context到stack中去，所有的设置操作放在stack的最高
context里，得到操作时会搜索stack(自顶向下)直到发现值
如果你pop()的太多的话它将触发django.template.ContextPopException
这里是这些多级别工作的一个例子:

# Create a new blank context and set a simple value:
>>> c = Context()
>>> c['foo'] = 'first level'

# Push a new context onto the stack:
>>> c.push()
>>> c['foo'] = 'second level'

# The value of "foo" is now what we set at the second level:
>>> c['foo']
'second level'

# After popping a layer off, the old value is still there:
>>> c.pop()
>>> c['foo']
'first level'

# If we don't push() again, we'll overwrite existing values:
>>> c['foo'] = 'overwritten'
>>> c['foo']
'overwritten'

# There's only one context on the stack, so pop()ing will fail:
>>> c.pop()
Traceback (most recent call last):
...
django.template.ContextPopException

下面你会看到，把Context当成stack在一些自定义模板标签里非常易用

RequestContext和context处理器
Django有一个特殊的Context类，django.template.RequestContext，它比普通的django.template.Context稍微复杂一点
第一个区别是它把HttpRequest对象(参考附录8)作为它的第一个参数:

c = RequestContext(request, {
    'foo': 'bar',
})

第二个区别是它根据你的TEMPLATE_CONTEXT_PROCESSORS设置自动使用一些变量给context赋值
TEMPLATE_CONTEXT_PROCESSORS设置一些叫做context processors的元组，context processors使用request对象作为它们
的参数并且返回一个合并到context的项的字典，默认TEMPLATE_CONTEXT_PROCESSORS设置为:

("django.core.context_processors.auth",
 "django.core.context_processors.debug",
 "django.core.context_processors.i18n")

每个processor按顺序工作，即，如果一个processor添加一个变量到context里，第二个processor会添加一个同名的变量
第二个会覆盖第一个，默认processors在下面解释
你也可以给RequestContext传递一个额外processors的列表，使用可选的第三个参数processors
这个例子中RequestContext实例得到一个ip_address变量:

def ip_address_processor(request):
    return {'ip_address': request.META['REMOTE_ADDR']}

def some_view(request):
    # ...
    return RequestContext(request, {
        'foo': 'bar',
    }, processors=[ip_address_processor])

这里是每个默认processor做的事情:
django.core.context_processors.auth
如果TEMPLATE_CONTEXT_PROCESSORS包含这个processor，每个RequestContext将会包含下面三个变量:
user
一个表示当前登录的用户的django.contrib.auth.models.User实例或者如果客户没登录时表示一个AnonymousUser实例
messages
一个当前登录用户的messages列表(字符串)，在幕后它为每个request调用request.user.get_and_delete_messages()
这个方法在数据库收集和删除用户的messages，注意messages通过user.add_message()设置
perms
一个表示当前登录的用户的permissions的django.core.context_processors.PermWrapper实例
参考第12章关于users，permissions和messages的更多信息
django.core.context_processors.debug
这个processor把测试信息放到模板层，它在下面的前提下工作:
1，DEBUG设置为True
2，request来自于INTERNAL_IPS设置中的IP地址
如果这些条件都符合，则下面的变量将被设置:
debug
设置为True则你可以在模板中测试你是否处于DEBUG模式
sql_queries
一个{'sql': ..., 'time': ...}字典的列表，它表示目前为止在请求时发生的每一个SQL查询以及所用的时间
这个列表通过query排序
django.core.context_processors.i18n
如果这个processor允许使用，则每个RequestContext将包含下面两个变量:
LANGUAGES
LANGUAGES设置的值
LANGUAGE_CODE
表示request.LANGUAGE_CODE，如果它存在的话，否则将为LANGUAGE_CODE设置的值
附录5有更多关于这两个设置的信息
django.core.context_processors.request
如果允许使用它，则每个RequestContext将包含一个request变量，表示当前的HttpRequest对象
注意这个processor默认不允许使用，你将不得不自己激活它

载入模板
通常你会把模板存储在你的文件系统的文件中(或者在其它地方，如果你些了自定义的模板载入器)而不是自己使用低级
Template API，Django根据你的模板载入设置(参看下面的"载入器类型")在几个地方搜索模板目录，但是最基本的指定
模板目录的方式是使用TEMPLATE_DIRS设置，它应该被设置为一个包含你的模板目录的完整路径的列表或元组:

TEMPLATE_DIRS = (
    "/home/html/templates/lawrence.com",
    "/home/html/templates/default",
)

你的模板可以放在任何你需要的地方，只要目录和模板对于Web服务器可读，它们可以有一个你想要的后缀，例如.html
或者.txt或者根本没有后缀，注意这些路径应该使用Unix样式的前斜线，甚至在Windows上也如此

Python API
Django有两种从文件载入模板的方式:
django.template.loader.get_template(template_name)
get_template使用给定的名字返回编译过的模板(一个Template对象)
如果模板不存在则触发djang.template.TemplateDoesNotExist异常
django.template.loader.select_template(template_name_list)
select_template很像get_template，除了它使用模板名列表作为参数并返回列表中存在的第一个模板
例如，如果我们调用get_template('story_detail.html')并且设置了上面的TEMPLATE_DIRS，则下面是Django按顺序
查找的文件:
/home/html/templates/lawrence.com/story_detail.html
/home/html/templates/default/story_detail.html
如果你调用select_template(['story_253_detail.html', 'story_detail.html'])，则下面是Django查找的文件:
/home/html/templates/lawrence.com/story_253_detail.html
/home/html/templates/default/story_253_detail.html
/home/html/templates/lawrence.com/story_detail.html
/home/html/templates/default/story_detail.html
当Django找到一个存在的模板，它就是停止搜索
小贴士:
你可以使用select_template()来得到超级灵活的模板能力，例如，如果你写了一个新闻故事并想让一些故事拥有自定义
模板，你可以像这样使用select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])
这将允许你为一些单独的故事使用自定义模板，并给那些没有自定义模板的故事提供一个fallback模板

使用子目录
很可能需要也推荐在模板目录的子目录组织模板，习惯用法士给每个Django app创建子目录，并在子目录里创建子目录
使用你自己的智慧来做这件事，把所有的模板存放在根目录下会十分凌乱
为了载入一个子目录的模板，只需像这样使用一个斜线:

get_template('news/story_detail.html')

而且，使用UNIX风格的前斜线，甚至在Windows上也是这样

模板载入器
Django默认默认从文件系统载入模板，但是Django也有几个其它的知道怎样从其它源载入模板的模板载入器
这些其它的模板载入器默认不可用，但是你可以通过编辑TEMPLATE_LOADERS设置来激活它们
TEMPLATE_LOADERS应该是一个字符串的元组，其中每个字符串表示一个模板载入器，Django自带这些模板载入器:
django.template.loaders.filesystem.load_template_source
根据TEMPLATE_DIRS从文件系统载入模板，默认可用
django.template.loaders.app_directories.load_template_source
在文件系统中从Django的apps载入模板，对于INSTALLED_APPS中的每个app，载入器寻找templates子目录，如果该目录
存在，Django则会在该目录下寻找模板，这意味着你可以在单独的app里存储模板，这也让使用默认模板发布Django
apps很容易，例如，如果INSTALLED_APPS包含('myproject.polls', 'myproject.music')，则get_template('foo.html')
将会按下列顺序查找模板:
/path/to/myproject/polls/templates/foo.html
/path/to/myproject/music/templates/foo.html
注意载入器第一次import时使用了优化，它把INSTALLED_APPS的templates子目录列表缓存起来
该载入器默认可使用
django.template.loaders.eggs.load_template_source
和上面的app_directories很类似，但是它从Python的eggs而不是文件系统载入模板
该载入器默认不可用，如果你使用eggs发布你的app，则你需要激活它
Django根据TEMPLATE_LOADERS设置按顺序使用模板载入器，它将使用每个载入器寻找模板直到找到一个匹配的

扩展模板系统
尽管Django模板语言自带一些默认标签和过滤器，你可能想写你自己的，这是很容易的
首先，在Django的app包的合适位置创建一个templatetags包，它应该和models.py，views.py等在同一级，例如:

polls/
    models.py
    templatetags/
    views.py

添加两个文件到templatetags包，一个__init__.py文件(来告诉Python这是一个包含Python代码的模块)和一个包含你
自定义的标签/过滤器定义的文件，后者的文件名是你将在后面用来载入标签的名字，例如，如果你的自定义标签或者
过滤器在一个叫ppll_extras.py文件里，你可以在模板里做下面的事情:

{% load poll_extras %}

{% load %}标签查看你的INSTALLED_APPS设置并且只允许在已安装的Django apps里面载入模板库
这是一个安全特性，它允许你在一个单独的计算机里为许多模板库保存Python代码并且不需要对每个Django安装激活对
它们的访问，如果你写了一个不依赖于任何特殊的模型/视图的模板库，则有一个只包含了一个templatetags包的Django
app是可以的，对你在templatetags包里面放置了多少模块没有限制，只需记住{% load %}语句将为给定的Python模块名
载入标签/过滤器，而不是app名
一旦你创建了Python模块，你将只需写一点Python代码，这取决于你在写过滤器还是标签
为了让标签库合法，模块应该包含一个模块级的变量叫register，它是一个template.Library实例，所有的标签和过滤器
都在它里面注册，所以，在你的模块最顶端加上下面的代码:

from django import template

register = template.Library()

在幕后，你可以阅读Django默认过滤器和标签的源代码来作为例子，它们分别在django/template/defaultfilters.py和
django/template/defaulttags.py，而django.contrib也包含了许多例子

写自定义模板过滤器
自定义过滤器只是有一到两个参数的Python方法，参数为:
1，变量的值(输入)
2，参数的值，它可以有默认值，也可以空出来不要它
例如，在过滤器{{ var|foo:"bar" }}中，过滤器foo将被传入变量var和参数"bar"
过滤器方法应该一直返回一些东西，它们不应该触发异常而应该静静的失败，如果有错误，它们应该要么返回原始输入
或者要么返回一个空字符串，无论哪个都有意义，这里是一个过滤器定义的例子:

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

当你已经写好一个过滤器定义，你需要用你的Library实例注册它来让它对于Django的模板语言可用:

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

Library.filter()方法有两个参数:
1，filter的名字(字符串)
2，编译方法(一个Python方法，而不是方法名)
如果你使用Python2.4及以上，你可以把register.filter()当成装饰器来使用:

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

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

如果你像上面第二个例子一样不写name参数，Django将使用方法名作为过滤器名

写自定义模板标签
标签比过滤器更复杂一点，因为标签几乎可以做任何事情

快速概览
本章上面描述了模板系统怎样以两个步骤工作:编译和渲染，为了定义一个自定义模板标签，你需要告诉Django当它到达
你的标签时怎样管理这两步
当Django编译一个模板时，它把原始模板文本分开成一些"节点"，每个节点都是django.template.Node的实例并且有一个
render()方法，这样一个编译好的模板就是一个简单的Node对象的列表
当你对一个编译好的模板调用render()时，模板使用给定的context对它的节点列表中的每个Node调用render()方法
结果都被连接在一起来组成模板的输出，这样，为了定义一个自定义模板标签，你需要指定原始模板标签怎样转换成一个
Node(编译方法)和节点的render()方法做了些什么

写编译方法
对模板解析器遇到的每个模板标签，它都使用标签内容和解析器对象本身调用一个Python方法，这个方法负责根据标签
内容返回一个Node实例，例如，让我们写一个模板标签{% current_time %}来根据标签里给定的参数和strftime语法显示
当前的日期和时间并格式化它们(参考http://www.python.org/doc/current/lib/module-time.html#l2h-1941
关于strftime语法的信息)，在其它任何事情之前决定标签语法是个好注意，在我们这里的情况中则应该像这样:

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

注意，这个模板标签重复了，Django默认的{% now %}标签做了同样的任何并且有更简洁的语法，这个只是一个例子
为了解析它，方法应该得到参数并且创建一个Node对象:

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:
        raise template.TemplateSyntaxError("%r tag requires a single argument" % token.contents[0])
    return CurrentTimeNode(format_string[1:-1])

事实上这里有许多东西:
1，parser时模板解析对象，我们这个例子中不需要它
2，token.contents是标签的原始内容，在我们的例子中，它为'current_time "%Y-%m-%d %I:%M %p"'
3，token.split_contents()方法基于空格分开参数并且保持引号里的字符串在一起，最直接的token.contents.split()
不是很健壮，因为它会天真的分开所有的空格，包括引号字符串里的空格，一直使用token.split_contents()是个好主意
4，这个方法负责对任何语法错误使用有用信息触发django.template.TemplateSyntaxError异常
5，不要在你的错误信息里硬编码标签名，因为这会耦合标签名和你的方法，token.contents.split()[0]将一直是你的
标签名，甚至当标签没有参数时也是如此
6，方法返回一个包含节点需要知道的关于此标签的任何东西的CurrentTimeNode(我们下面将创建它)，在这里，它只是
传递"%Y-%m-%d %I:%M %p"参数，模板标签里开头和结尾的引号会通过format_string[1:-1]去掉
7，模板标签编译方法必须返回一个Node子类，所有其它任何返回值都是错误的
8，解析是非常低级的，我们已经在这个解析系统上通过写一些小框架来试验过了(使用例如EBNF语法的技术)，但是那些
试验让模板引擎非常变得慢，而低级解析是很快的

写模板节点
写自定义模板的第二步是定义一个含有render()方法的Node子类，继续上面的例子，我们需要定义CurrentTimeNode:

import datetime

class CurrentTimeNode(template.Node):

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

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

这两个方法(__init__和render)直接映射了模板处理的两个步骤(编译和渲染)，这样，初始化方法只需存储后面将使用的
字符串的格式，然后render()方法做真正的工作
像模板过滤器一样，这些渲染方法应该静静的失败而不是触发错误，模板标签允许触发错误的时候只在编译期间

注册标签
最后你需要使用你的模块的Library实例注册标签，上面在"写自定义过滤器"提到了:

register.tag('current_time', do_current_time)

tag()方法使用两个参数:
1，模板标签名(字符串)，如果空着不写，则将使用编译方法名
2，编译方法
类似过滤器注册，也可以在Python2.4及以上使用装饰器:

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

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

如果像上面第二个例子一样不写name参数，Django将使用方法名作为标签名

在context里设置变量
上面的例子简单的输出一个值，通常设置模板变量而不是输出值会更有用，这里是一个CurrentTimeNode的更新版本，设置
一个模板变量current_time而不是输出它:

class CurrentTimeNode2(template.Node):

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

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

注意render()返回空字符串，render()应该一直返回字符串输出，所以如果所有的模板标签做的都是设置变量，render()
应该返回一个空字符串，这里是你怎样使用新版本的标签:

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

但是CurrentTimeNode2有一个问题，变量名current_time是硬编码的，这意味着你将需要确认你的模板不会在别的地方
使用{{ current_time }}，因为{% current_time %}将盲目的覆盖掉这个变量值
一个更干净的解决方案是让模板标签指定输出变量名:

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

为了这样做你需要重整编译方法和Node类: