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類: