大多數時候你是以模板作者的角色來與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類:
- 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):
- context[self.var_name] = datetime.datetime.now().strftime(self.format_string)
- return ''
- def do_current_time(parser, token):
- # This version uses a regular expression to parse tag contents.
- try:  
安徽新華電腦學校專業職業規劃師為你提供更多幫助【在線咨詢】