django “如何”系列4：如何编写自定义模板标签和过滤器
django的模板系统自带了一系列的内建标签和过滤器，一般情况下可以满足你的要求，如果觉得需更精准的模板标签或者过滤器，你可以自己编写模板标签和过滤器，然后使用{% load %}标签使用他们。
代码布局
自定义标签和过滤器必须依赖于一个django app，也就是说，自定义标签和过滤器是绑定app的。该app应该包含一个templatetags目录，这个目录一个和model.py，views.py在同一个层级，记得在该目录下建立一个__init__.py文件一遍django知道这是一个python包。在该目录下，你可以新建一个python模块文件，文件名不要和其他app中的冲突就好。例如：
polls/ models.py templatetags/ __init__.py poll_extras.py views.py
然后在你的模板文件中你可以这样使用你的自定义标签和过滤器：
{% load poll_extras %}
注意事项：
- 包含templatetags目录的app一定要在INSTALLED_APPS列表里面
- {% load %}load的是模块名，而不是app名
- 记得使用 from django import template ，register=template.Library()注册
编写自定义模板过滤器
自定义过滤器就是接受一个或者连个参数的python函数。例如{{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): # 只有一个参数 return value.lower()
注册自定义的过滤器
一旦定义好你的过滤器，你需要注册这个过滤器，有两种方式，一种是上面提到的template.Library()，另一种是装饰器
#第一种方法 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()
stringfilter
如果你的模板过滤器只希望接受字符串作为第一个参数，那么你可以是用stringfilter装饰器，这样的话，在传参进你的函数之前，该参数的值会被转换成对应字符串值
from django import template from django.template.defaultfilters import stringfilter register = template.Library() @register.filter @stringfilter def lower(value): return value.lower()
过滤器和自动转义
当你编写一个过滤器的时候，考虑一下该过滤器如何和django的自动转义行为“协作”。注意到三种类型的字符串可以被传进模板代码中。
- 原始字符串（raw strings）：本地的str或者unicode。在输出的时候，如果可以自动转义的话会被转义的，否则就会保持不变
- 安全字符串（safe strings）：在输出的时候已经被标识为安全的。任何可能的转义都已经被转义了。
- 被标记为需要转义的字符串：在输出的时候总是要被转义
模板过滤器代码分为下面两种情况：
- 你的过滤器没有任何的HTML不安全字符（<>,"&)，在这种情况下，你可以是用is_safe=True来装饰你的过滤器函数，is_safe默认为False
@register.filter(is_safe=True) def myfilter(value): return value
- 同样的，你的过滤器代码可以人为的注意 任何必须的转义。为了标识一个输出时安全的，我们可以使用django.utils.safestring.mark_safe()函数。如果你需要知道你的过滤器目前的自动转义状态，在你注册过滤器函数的时候设置needs_autoescape标识为True（默认为False），这个标识告诉django，你的过滤器函数想要一个额外的关键字参数autoescape，如果auto-escape有效则返回真，否则返回False
from django.utils.html import conditional_escape from django.utils.safestring import mark_safe @register.filter(needs_autoescape=True) def initial_letter_filter(text, autoescape=None): first, other = text[0], text[1:] if autoescape: esc = conditional_escape else: esc = lambda x: x result = '<strong>%s</strong>%s' % (esc(first), esc(other)) return mark_safe(result)
在这个例子中，needs_autoescape标识和autoescape关键字参数意味着我们的函数可以知道当这个过滤器被调用的时候，自动转义是否生效，我们使用autoescape去决定我们是否要使用condition_escape，也因此，在最后我们使用mark_safe告诉我们的模板系统这个已经不需要进一步的转义了
过滤器和时区
如果哦你编写一个自定义的过滤器去操作一个datetime对象，你可以使用expects_localtime，并将其设置为真
@register.filter(expects_localtime=True) def businesshours(value): try: return 9 <= value.hour < 17 except AttributeError: return ''
如果这个标识为真，那么如果哦你的第一个参数是一个datetime类型数据，那么django会在将value的值传参进去之前将其转成当前时区的值
编写自定义模板标签
标签比过滤器复杂的多，因为标签可以做任何事情。
快速回顾
模板系统工作有两个流程：编译和渲染。去定义一个模板标签，你需要知道如何去编译和如何去渲染。当django编译一个模板的时候，它会把原始的模板文本分割成一个个节点，每个节点都是django.template.Node实例并且有一个render()方法。一个编译好的模板是一个Node对象的列表。当你在一个已经编译好的模板对象调用render方法时，模板会对node列表中的每一个Node调用render方法（使用给定的上下文），结果会被级联在一起去组成模板的输出。因此，定义一个模板标签，你需要知道一个原始的模板标签是如何被转换成一个Node，以及这个node的render方法要做什么。
编写编译函数
模板解析器每遇到一个模板标签，它会和标签内容和解析器对象本省一起去调用一个python函数，这个函数应该返回一个基于标签内容的Node实例。举个例子，让我们写一个标签{% current_time %}，这个标签会展示当前的日期时间，格式根据参数来决定，参数格式都是strftime()的。首先决定一个标签的语法是很重要的，在我们的例子中，这个标签大概是这样的：
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>
这个函数的解析器应该获取到这些参数并且创建一个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.split()[0]) if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")): raise template.TemplateSyntaxError("%r tag's argument should be in quotes" % tag_name) return CurrentTimeNode(format_string[1:-1])
tips：
- parser是模板解析器对象
- token.contents是标签的原始内容，在我们的例子中时'current_time "%Y-%m-%d %I:%M %p"'
- token.split_contents()方法把参数按空格分开，同时保留引号之间的内容，如果使用token.contents.split()的话，这个函数会将所有空格都分开，所以建议还是使用token.split_contents()
- 这个函数会引发django.template.TemplateSymtaxError，并附有有用的信息
- TemplateSyntaxError异常使用tag_name变量，所以不要在你的错误信息里面硬编码标签名，因为token.contents.spilt()[0]永远是你的标签名
- 这个函数返回一个包括所有有关这个标签的内容的CurrentTimeNode对象，所以你只需把参数穿进去就可以了
- 这个解析过程是非常底层的，所以直接用就好了，因为底层所以快速。
编写渲染器
编写自定义标签的第二步是定义一个Node的子类并且定义一个render方法
from django import template 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)
tips：
- __init__()从上面的do_current_time()中获取format_string，记得只通过__init__()函数传参
- render()方法才是真正做事情的
- render函数不会抛出任何异常，只会默默的失败（如果发生异常的话）
最终，编译和渲染的非耦合组成了一个有效的模板系统，因为一个模板可以渲染多个上下文而不用多次解析。
自动转义注意事项
模板标签的输出并不会自动的执行自动转义过滤器的，所以当你编写一个模板标签的时候你需要注意这些事情：
如果render函数在一个上下文变量里面存储结果（而不是一个字符串），你需要注意正确的使用mark_safe()，当该变量已经是最终渲染了，你需要给它打上标识，以防会受到自动转义的影响。
并且，你的模板标签新建一个用于进一步渲染的上下文，记得把自动转义属性设置为当前上下文的值。Context的 __init__()方法接受一个autoescape的参数
def render(self, context): # ... new_context = Context({'var': obj}, autoescape=context.autoescape) # ... Do something with new_context ...
这不是一个很常用的情景，但是当你自己渲染一个模板的时候会很有用
def render(self, context): t = template.loader.get_template('small_fragment.html') return t.render(Context({'var': obj}, autoescape=context.autoescape))
如果我们不传这个参数的时候，结果可能是永远都是自动转义的，即使这个标签实在{% autoescape off %}块里面。
线程安全考虑
一旦一个节点被解析，render方法会被调用任意次，由于django有时运行在多线程的环境，单个节点可能会被两个独立的请求的不同上下文同时渲染，因此，保证你的模板标签线程安全是很重要的
为了保证你的模板标签是线程安全的，你应该永远不要存储信息在节点本身。举个例子，django提供一个内建的cycle模板标签，这个标签每次渲染的时候都会循环一个给定字符串的列表
{% for o in some_list %} <tr class="{% cycle 'row1' 'row2' %}> ... </tr> {% endfor %}
一个朴素的CycleNode的实现可能想这样：
class CycleNode(Node): def __init__(self, cyclevars): self.cycle_iter = itertools.cycle(cyclevars) def render(self, context): return self.cycle_iter.next()
但，假设我们有两个模板，同时渲染上面那个小模板：
- 线程1执行第一次循环迭代，CycleNode.render()返回row1
- 线程2执行第一次循环迭代，CycleNode.render()返回row2
- 线程1执行第二次循环迭代，CycleNode.render()返回row1
- 线程2执行第二次循环迭代，CycleNode.render()返回row2
CycleNode是可以迭代的，但却是全局迭代，由于线程1和线程2是关联的，所以它们总是返回相同的值，显然这不是我们想要的结果。
解决这个问题，django提供了一个正在被渲染的模板的上下文关联的render_context，这个render_context就像一个python字典一样，并且应该在render方法被调用之间保存Node状态
让我们使用render_context重新实现CycleNode吧
class CycleNode(Node): def __init__(self, cyclevars): self.cyclevars = cyclevars def render(self, context): if self not in context.render_context: context.render_context[self] = itertools.cycle(self.cyclevars) cycle_iter = context.render_context[self] return cycle_iter.next()
注册标签
和过滤器注册差不多
register.tag('current_time', do_current_time) @register.tag(name="current_time") def do_current_time(parser, token): ... @register.tag def shout(parser, token): ...
给标签传模板变量
尽管你可以是用token.split_contents()传入任意个参数，但考虑一个参数是一个模板变量的情况（这是一个动态的情况）
假如我们有一个这样的标签，接受一个给定的日期和指定格式，返回用指定格式格式化的日期，像这样：
<p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
现在你的解析器大概是这样的
from django import template def do_format_time(parser, token): try: # split_contents() knows not to split quoted strings. tag_name, date_to_be_formatted, format_string = token.split_contents() except ValueError: raise template.TemplateSyntaxError("%r tag requires exactly two arguments" % token.contents.split()[0]) if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")): raise template.TemplateSyntaxError("%r tag's argument should be in quotes" % tag_name) return FormatTimeNode(date_to_be_formatted, format_string[1:-1])
然后FormatTimeNode大概就要这样子了
class FormatTimeNode(template.Node): def __init__(self, date_to_be_formatted, format_string): self.date_to_be_formatted = template.Variable(date_to_be_formatted) self.format_string = format_string def render(self, context): try: actual_date = self.date_to_be_formatted.resolve(context) return actual_date.strftime(self.format_string) except template.VariableDoesNotExist: return ''
简单的标签
很多的标签接受很多的参数-字符串或者模板变量-返回一个字符串或者空串，为了减轻这类简单的标签的创建，django提供了一个简单有效的函数simple_tag。这个函数，是django.template.Library的一个方法，接受一个 可以接受任意个参数的函数 ，然后把这个函数包装成一个render函数，以及其他必要的注册等步奏。
比如之前的current_time函数我们这里可以这样写
def current_time(format_string): return datetime.datetime.now().strftime(format_string) register.simple_tag(current_time) #或者这样 @register.simple_tag def current_time(format_string): ...
如果你的模板标签需要访问当前上下文的话，你可以使用takes_context参数，像下面这样：
# The first argument *must* be called "context" here. def current_time(context, format_string): timezone = context['timezone'] return your_get_current_time_method(timezone, format_string) register.simple_tag(takes_context=True)(current_time) #或者这样 @register.simple_tag(takes_context=True) def current_time(context, format_string): timezone = context['timezone'] return your_get_current_time_method(timezone, format_string)
或者你想重命名你的标签，你可以这样来指定
register.simple_tag(lambda x: x - 1, name='minusone') #或者这样 @register.simple_tag(name='minustwo') def some_function(value): return value - 2
simple_tag还可以接受关键字参数
@register.simple_tag def my_tag(a, b, *args, **kwargs): warning = kwargs['warning'] profile = kwargs['profile'] ... return ...
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}
包含标签
另外一类标签是通过渲染其他的模板来展示内容的，这类标签的用途在于一些相似的内容的展示，并且返回的内容是渲染其他模板得到的内容，这类标签称为“包含标签”。最好我们通过一个例子来阐述。
我们即将写一个标签，这个标签将输出给定Poll对象的选择的列表，我们可以这样使用这个标签
{% show_results poll %}
输出大概是这样的
<ul> <li>First choice</li> <li>Second choice</li> <li>Third choice</li> </ul>
下面我们看看怎么实现吧。首先定义一个接受一个poll参数的函数，这个函数返回该poll对象的choices
def show_results(poll): choices = poll.choice_set.all() return {'choices': choices}
然后我们创建一个要被渲染的模板用于输出
<ul> {% for choice in choices %} <li> {{ choice }} </li> {% endfor %} </ul>
最后是使用inclusion_tag函数注册
register.inclusion_tag('results.html')(show_results) #或者这样 @register.inclusion_tag('results.html') def show_results(poll): ...
如果你要使用上下文的话，可以使用takes_context参数，如果你使用了takes_context，这个标签是没有必须参数，不过底层的python函数需要接受一个context的首参（第一个参数必须为context）
#第一个参数必须为context def jump_link(context): return { 'link': context['home_link'], 'title': context['home_title'], } # Register the custom tag as an inclusion tag with takes_context=True. register.inclusion_tag('link.html', takes_context=True)(jump_link)
link.html可以是这样的
Jump directly to <a href="{{ link }}">{{ title }}</a>.
那么你可以这样来使用这个标签，不需要带任何的参数
{% jump_link %}
和simple_tag一样，inclusion_tag可以接受关键字参数
在上下文中设置变量
到现在为止，所有的模板标签只是输出一个值，现在我们考虑一下给标签设置变量吧，这样，模板的作者可以重用这些你的标签产生的值。
想要在上下文中设置变量，只需要在render方法中给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 ''
注意到这个标签是返回一个空串，使用如下：
{% current_time "%Y-%M-%d %I:%M %p" %}<p>The time is {{ current_time }}.</p>
注意事项：
作用范围：上下文中的模板变量仅仅在当前块代码中生效（如果有多个层次的块的话），这是为了预防块之间的变量冲突
覆盖问题：由于变量名是硬编码的，所有同名的变量都会被覆盖，所以强烈建议使用别名as，但是要使用as的话，编译函数和结点类都要重新定义如下
{% current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>
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 ''
import re
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:
raise template.TemplateSyntaxError("%r tag requires arguments" % token.contents.split()[0])
m = re.search(r'(.*?) as (\w+)', arg)
if not m:
raise template.TemplateSyntaxError("%r tag had invalid arguments" % tag_name)
format_string, var_name = m.groups()
if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
raise template.TemplateSyntaxError("%r tag's argument should be in quotes" % tag_name)
return CurrentTimeNode3(format_string[1:-1], var_name)
赋值标签
上面的设置一个变量是不是有点麻烦呢？于是django提供了一个有用的函数assignment_tag，这个函数和simple_tag一样，不同之处是这个函数返回的不是一个值，而是一个变量名而已
成对标签（解析直到遇到块标签）
目前我们自定义的标签都是单个标签，其实标签可以串联使用，例如标准的{% comment %}会配合{% endcomment %}使用，要编写这样的标签，请使用parser.parse()
这是一个简化的{% comment %}标签的实现：
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对象的列表，包含 解析器在碰到 元组里任何一个块标签之前 碰到的所有的Node对象。比如
nodelist = parser.parse(('endcomment',))会返回{% comment %}和{% endcomment %}标签之间的所有节点，不包含{% comment %}和{% endcomment %}
在parser.parse()被调用之后，解析器还没有解析{% endcomment %}，所以需要调用parser.delete_first_token()
由于comment成对标签不必返回任何内容，所以CommentNode.render()仅仅返回一个空串
如果你的成对标签需要返回内容，可以参考下面这个例子，我们以{% upper %}为例子：
{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}
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()
如果还想了解更多的复杂的例子，你可以去看一下djang/template/defaulttags.py里面的内容，看看{% if %}{% endif %}这些标签是怎么实现的