{% raw %}
第五章 定制模板过滤器和标签
------------------------
本章，我们会学习以下内容：
* 遵循模板过滤器和标签的约定
* 创建一个模板过滤器显示已经过去的天数
* 创建一个模板过滤器提取第一个媒体对象
* 创建一个模板过滤器使URL可读
* 创建一个模板标签在模板中载入一个QuerySet
* 创建一个模板标签为模板解析内容
* 创建一个模板标签修改request查询参数
## 简介
如你所知，Django有一个非常庞大的模板系统，特别是模板继承，
## 遵循模板过滤器和标签的约定
Custom template filters and tags can become a total mess if you don't have persistent guidelines to follow. Template filters and tags should serve template editors as much as possible. They should be both handy and flexible. In this recipe, we will look at some conventions that should be used when enhancing the functionality of the Django template system.
滤器和标签时会让你完全不知所措。模板过滤器和标签应该尽可能的服务于模板编辑器，而且它们都应该同时具有操作方便和灵活扩展的特性。在这个做法中，我们会见到一些在增强Django模板系统功能时所用到的几点约定。
### 如何做
扩张Django模板系统时遵循以下约定：
1. 当在视图，上下文处理器，或者模型方法中，页面更适合逻辑时，不要创建或者使用定制模板过滤器、标签。你的页面是上下文指定时，比如一个对象列表或者一个详细对象视图，载入视图中的对象。如果你需要在每一个页面都显示某些内容，可以创建一个上下文管理器。当你需要获取一个没有关联到模板上下文的对象的某些特性时，要用模型的定制方法而不是使用模板过滤器。
2. 使用 _tags后缀命名模板标签库。当你的app命名不同于模板标签库时，你可以避免模糊的包导入问题。
3. 例如，通过使用如下注释，在最后创建的库中，从标签中分离过滤器：
# -*- coding: UTF-8 -*-
from django import template
register = template.Library()
### FILTERS ###
# .. your filters go here ..
### TAGS ###
# .. your tags go here..
4. 通过下面的格式，创建的模板标签就可以被轻松记住：
for [app_name.model_name]：使用该格式以使用指定的模型
using [template_name]：使用该格式将一个模板的模板标签输出
limit [count]：使用该格式将结果限制为一个指定的数量
as [context_variable]：使用该结构可以将结构保存到一个在之后多次使用的上下文变量
5. 要尽量避免在模板标签中按位置地定义多个值除非它们都是不解自明的。否则，这会有可能使开发者迷惑。
6. 尽可能的使用更多的可理解的参数。没有引号的字符串应该当作需要解析的上下文变量或者可以提醒你关于模板标签组件的短语。
## 参见
The Creating a template filter to show how many days have passed recipe
The Creating a template filter to extract the first media object recipe
The Creating a template filter to humanize URLs recipe
The Creating a template tag to include a template if it exists recipe
The Creating a template tag to load a QuerySet in a template recipe
The Creating a template tag to parse content as a template recipe
The Creating a template tag to modify request query parameters recipe”
## 创建一个模板过滤器显示已经过去的天数
Not all people keep track of the date, and when talking about creation or modification dates of cutting-edge information, for many of us, it is more convenient to read the time difference, for example, the blog entry was posted three days ago, the news article was published today, and the user last logged in yesterday. In this recipe, we will create a template filter named days_since that converts dates to humanized time differences.
不是所有的人都持续关注时间，而且在谈论最新日期信息的新建和修改时，对于我们大多数人来说读取时间差是更为合适的一种选择，例如，博客内容在发布于三天之前，新的文章在今天发布了，而用户则是在昨天进行了最后的登陆行为。在这个做法中，我们将新一个称作days_since的可以转换日期到人类可读时间差的模板过滤器。
## 准备开始
Create the utils app and put it under `INSTALLED_APPS` in the settings, if you haven't done that yet. Then, create a Python package named templatetags inside this app (Python packages are directories with an empty ` __init__.py` file).
创建utils应用并将它放到settings文件中的`INSTALLED_APPS`下，要是你还没有按照我说的去做的话。然后，在这个应用里边创建一个名叫templatetags的Python文件夹（Python包是一个拥有内容为空的`__init__.py`文件）。
## 我该怎么做
使用下面的内容创建一个utility_tags.py文件：
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
from datetime import datetime
from django import template
from django.utils.translation import ugettext_lazy as _
from django.utils.timezone import now as tz_now
register = template.Library()
### FILTERS ###
@register.filter
def days_since(value):
""" Returns number of days between today and value."""
today = tz_now().date()
if isinstance(value, datetime.datetime):
value = value.date()
diff = today - value
if diff.days > 1:
return _("%s days ago") % diff.days
elif diff.days == 1:
return _("yesterday")
elif diff.days == 0:
return _("today")
else:
# Date is in the future; return formatted date.
return value.strftime("%B %d, %Y")
```
## 工作原理
If you use this filter in a template like the following, it will render something like yesterday or 5 days ago:
假如你在模板中使用了如下所示的过滤器，那么该过滤器会将日期渲染为比如，今天，或者五天前：
```python
“{% load utility_tags %}
{{ object.created|days_since }}
You can apply this filter to the values of the date and datetime types.
```
Each template-tag library has a register where filters and tags are collected. Django filters are functions registered by the `register.filter` decorator. By default, the filter in the template system will be named the same as the function or the other callable object. If you want, you can set a different name for the filter by passing name to the decorator, as follows:
每个模板标签库都有一个收集过滤器和标签的注册器。Django过滤器是通过装饰器`register.filter`注册过的函数。默认，模板系统中的过滤器的名称和函数或者其他可调用对象的名称相同。如下，如果你有需要的话，你可以通过传递名称到装饰器来为过滤器设置一个不同的名称：
```python
@register.filter(name="humanized_days_since")
def days_since(value):
...
```
The filter itself is quite self-explanatory. At first, the current date is read. If the given value of the filter is of the datetime type, the date is extracted. Then, the difference between today and the extracted value is calculated. Depending on the number of days, different string results are returned.
## 还有更多
This filter is easy to extend to also show the difference in time, such as just now, 7 minutes ago, or 3 hours ago. Just operate the datetime values instead of the date values.
## 参阅
The Creating a template filter to extract the first media object recipe
The Creating a template filter to humanize URLs recipe
## 创建一个模板过滤器以提取第一个媒体对象
Imagine that you are developing a blog overview page, and for each post, you want to show images, music, or videos in that page taken from the content. In such a case, you need to extract the `<img>`, `<object>`, and `<embed>` tags out of the HTML content of the post. In this recipe, we will see how to do this using regular expressions in the `get_first_media` filter.
## 准备开始吧
We will start with the `utils` app that should be set in `INSTALLED_APPS `in the settings and the `templatetags` package inside this app.
## 如何做
In the `utility_tags.py` file, add the following content:
在`utility_tags.py`文件中，添加以下内容：
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
import re
from django import template
from django.utils.safestring import mark_safe
register = template.Library()
### FILTERS ###
media_file_regex = re.compile(r"<object .+?</object>|"
r"<(img|embed) [^>]+>") )
@register.filter
def get_first_media(content):
""" Returns the first image or flash file from the html content """
m = media_file_regex.search(content)
media_tag = ""
if m:
media_tag = m.group()
return mark_safe(media_tag)
```
## 工作原理
While the HTML content in the database is valid, when you put the following code in the template, it will retrieve the `<object>`, `<img>`, or `<embed>` tags from the content field of the object, or an empty string if no media is found there:
```python
{% load utility_tags %}
{{ object.content|get_first_media }}
```
At first, we define the compiled regular expression as `media_file_regex`, then in the filter, we perform a search for that regular expression pattern. By default, the result will show the <, >, and & symbols escaped as `<`, `>`, and `&`; entities. But we use the `mark_safe` function that marks the result as safe HTML ready to be shown in the template without escaping.
## 还有更多
It is very easy to extend this filter to also extract the `<iframe>` tags (which are more recently being used by Vimeo and YouTube for embedded videos) or the HTML5 `<audio>` and `<video>` tags. Just modify the regular expression like this:
```python
media_file_regex = re.compile(r"<iframe .+?</iframe>|"
r"<audio .+?</ audio>|<video .+?</video>|"
r"<object .+?</object>|<(img|embed) [^>]+>") ”
```
## 参阅
The Creating a template filter to show how many days have passed recipe
The Creating a template filter to humanize URLs recipe
## 创建模板过滤器以人性化URL
Usually, common web users enter URLs into address fields without protocol and trailing slashes. In this recipe, we will create a humanize_url filter used to present URLs to the user in a shorter format, truncating very long addresses, just like what Twitter does with the links in tweets.
## 准备开始
As in the previous recipes, we will start with the `utils` app that should be set in `INSTALLED_APPS` in the settings, and should contain the `templatetags` package.
就像之前技巧中提到的，我们会从设置于`INSTALLED_APPS`中的`utils`应用开始，它应该包含一个`templatetags`包。
## 如何做
In the FILTERS section of the utility_tags.py template library in the utils app, let's add a filter named humanize_url and register it:
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
import re
from django import template
register = template.Library()
### FILTERS ###
@register.filter
def humanize_url(url, letter_count):
""" Returns a shortened human-readable URL """
letter_count = int(letter_count)
re_start = re.compile(r"^https?://")
re_end = re.compile(r"/$")
url = re_end.sub("", re_start.sub("", url))
if len(url) > letter_count:
url = u"%s…" % url[:letter_count - 1]
return url
```
## 工作原理
We can use the humanize_url filter in any template like this:
```python
{% load utility_tags %}
<a href="{{ object.website }}" target="_blank">
{{ object.website|humanize_url:30 }}
</a>
```
The filter uses regular expressions to remove the leading protocol and the trailing slash, and then shortens the URL to the given amount of letters, adding an ellipsis to the end if the URL doesn't fit into the specified letter count.
## 参见
The Creating a template filter to show how many days have passed recipe
The Creating a template filter to extract the first media object recipe
The Creating a template tag to include a template if it exists recipe
## 如果存在一个模板，创建一个模板标签以包含它
Django has the `{% include %}` template tag that renders and includes another template. However, in some particular situations, there is a problem that an error is raised if the template does not exist. In this recipe, we will show you how to create a `{% try_to_include %}` template tag that includes another template, but fails silently if there is no such template.
## 准备开始
We will start again with the utils app that should be installed and is ready for custom template tags.
## 如何做
Template tags consist of two things: the function parsing the arguments of the template tag and the node class that is responsible for the logic of the template tag as well as for the output. Perform the following steps:
模板标签由两个东西组成：解析模板标签参数对函数，以及能够良好输出的响应模板标签逻辑的节点类。记下来执行以下步骤：
1. First, let's create the function parsing the template-tag arguments:
首先，让我们来创建解析模板标签参数的函数：
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
from django import template
from django.template.loader import get_template
register = template.Library()
### TAGS ###
@register.tag
def try_to_include(parser, token):
"""Usage: {% try_to_include "sometemplate.html" %}
This will fail silently if the template doesn't exist.
If it does, it will be rendered with the current context.""”
try:
tag_name, template_name = token.split_contents()
except ValueError:
raise template.TemplateSyntaxError, \
"%r tag requires a single argument" % \token.contents.split()[0]
return IncludeNode(template_name)
```
2. Then, we need the node class in the same file, as follows:
```python
class IncludeNode(template.Node):
def __init__(self, template_name):
self.template_name = template_name
def render(self, context):
try:
# Loading the template and rendering it
template_name = template.resolve_variable(
self. template_name, context)
included_template = get_template(template_name).\
render(context)
except template.TemplateDoesNotExist:
included_template = ""
return included_template
```
The` {% try_to_include %}` template tag expects one argument, that is, `template_name`. So, in the `try_to_include` function, we are trying to assign the split contents of the token only to the `tag_name` variable (which is `"try_to_include"`) and the `template_name` variable. If this doesn't work, the template syntax error is raised. The function returns the `IncludeNode` object, which gets the `template_name` field for later usage.
` {% try_to_include %}`模板标签需要一个参数，即，`template_name`。因此，在函数`try_to_include`中，
In the render method of `IncludeNode`, we resolve the `template_name` variable. If a context variable was passed to the template tag, then its value will be used here for `template_name`. If a quoted string was passed to the template tag, then the content within quotes will be used for `template_name`.
Lastly, we try to load the template and render it with the current template context. If that doesn't work, an empty string is returned.
There are at least two situations where we could use this template tag:
When including a template whose path is defined in a model, as follows:
```python
{% load utility_tags %}
{% try_to_include object.template_path %}
```
When including a template whose path is defined with the {% with %} template tag somewhere high in the template context variable's scope. This is especially useful when you need to create custom layouts for plugins in the placeholder of a template in Django CMS:
```python
#templates/cms/start_page.html
{% with editorial_content_template_path="cms/plugins/editorial_content/start_page.html" %}
{% placeholder "main_content" %}
{% endwith %}
#templates/cms/plugins/editorial_content.html
{% load utility_tags %}
{% if editorial_content_template_path %}
{% try_to_include editorial_content_template_path %}
{% else %}
<div>
<!-- Some default presentation of
editorial content plugin -->
</div>
{% endif %}
```
## 还有更多
You can use the `{% try_to_include %}` tag as well as the default` {% include %} `tag to include templates that extend other templates. This has a beneficial use for large-scale portals where you have different kinds of lists in which complex items share the same structure as widgets but have a different source of data.
For example, in the artist list template, you can include the artist item template as follows:
```python
{% load utility_tags %}
{% for object in object_list %}
{% try_to_include "artists/includes/artist_item.html" %}
{% endfor %}
```
This template will extend from the item base as follows:
```python
{# templates/artists/includes/artist_item.html #}
{% extends "utils/includes/item_base.html" %}
{% block item_title %}
{{ object.first_name }} {{ object.last_name }}
{% endblock %}
```
The item base defines the markup for any item and also includes a Like widget, as follows:
```python
{# templates/utils/includes/item_base.html #}
{% load likes_tags %}
<h3>{% block item_title %}{% endblock %}</h3>
{% if request.user.is_authenticated %}
{% like_widget for object %}
{% endif %}
```
## 参阅
The Creating templates for Django CMS recipe in Chapter 7, Django CMS
The Writing your own CMS plugin recipe in Chapter 7, Django CMS
The Implementing a Like recipe in Chapter 4, Templates and JavaScript
The Creating a template tag to load a QuerySet in a template recipe
The Creating a template tag to parse content as a template recipe
The Creating a template tag to modify request query parameters recipe
## 创建一个模板标签以载入模板中的Queryset
Most often, the content that should be shown in a web page will have to be defined in the view. If this is the content to show on every page, it is logical to create a context processor. Another situation is when you need to show additional content such as the latest news or a random quote on some specific pages, for example, the start page or the details page of an object. In this case, you can load the necessary content with the `{% get_objects %}` template tag, which we will implement in this recipe.
## 准备开始
Once again, we will start with the `utils` app that should be installed and ready for custom template tags.
我们会再一次从安装好的`utils`应用开始，为定制模板标签做好准备。
## 如何做
Template tags consist of function parsing arguments passed to the tag and a node class that renders the output of the tag or modifies the template context. Perform the following steps:
模板标签由解析传递到标签的参数的函数组成，而节点类会传递外部的标签或者修改模板上下文。要达成模板，需执行以下步骤：
1. First, let's create the function parsing the template-tag arguments, as follows:
首选，让我们来创建函数去解析模板标签参数，一如下面内容所示：
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
from django.db import models
from django import template
register = template.Library()
### TAGS ###
@register.tag
def get_objects(parser, token):
"""
Gets a queryset of objects of the model specified by app and
model names
Usage:
{% get_objects [<manager>.]<method> from <app_name>.<model_name> [limit <amount>] as <var_name> %}
Example:
{% get_objects latest_published from people.Person limit 3 as people %}
{% get_objects site_objects.all from news.Article limit 3 as articles %}
{% get_objects site_objects.all from news.Article as articles %}
"""
amount = None
try:
tag_name, manager_method, str_from, appmodel, str_limit,\
amount, str_as, var_name = token.split_contents()
except ValueError:
try:
tag_name, manager_method, str_from, appmodel, str_as,\
var_name = token.split_contents()
except ValueError:
raise template.TemplateSyntaxError, \
"get_objects tag requires a following syntax: "
"{% get_objects [<manager>.]<method> from "\
"<app_ name>.<model_name>"\
" [limit <amount>] as <var_name> %}"
try:
app_name, model_name = appmodel.split(".")
except ValueError:
raise template.TemplateSyntaxError, \
"get_objects tag requires application name and "\
"model name separated by a dot"
model = models.get_model(app_name, model_name)
return ObjectsNode(model, manager_method, amount, var_name)
```
2. 如下，接着在同样的文件中创建节点类：
```python
class ObjectsNode(template.Node):
def __init__(self, model, manager_method, amount, var_name):
self.model = model
self.manager_method = manager_method
self.amount = amount
self.var_name = var_name
def render(self, context):
if "." in self.manager_method:
manager, method = self.manager_method.split(".")
else:
manager = "_default_manager"
method = self.manager_method
qs = getattr( qs = getattr(
getattr(self.model, manager),
method,
self.model._default_manager.none,
)()
if self.amount:
amount = template.resolve_variable(self.amount,
context)
context[self.var_name] = qs[:amount]
else:
context[self.var_name] = qs
return "
```
## 工作原理
The `{% get_objects %}` template tag loads a `QuerySet` defined by the `manager` method from a specified app and model, limits the result to the specified amount, and saves the result to a context variable.
This is the simplest example of how to use the template tag that we have just created. It will load five news articles in any template using the following snippet:
```python
{% load utility_tags %}
{% get_objects all from news.Article limit 5 as latest_articles %}
{% for article in latest_articles %}
<a href="{{ article.get_url_path }}">{{ article.title }}</a>
{% endfor %}
```
This is using the all method of the default `objects` manager of the `Article` model, and will sort the articles by the `ordering` attribute defined in the `Meta` class.
A more advanced example would be required to create a custom manager with a custom method to query objects from the database. A manager is an interface that provides database query operations to models. Each model has at least one manager called `objects` by default. As an example, let's create the `Artist` model, which has a `draft` or `published` status, and a new manager, `custom_manager`, which allows you to select random published artists:
更高级的一个例子是，按要求使用定制方法查询数据库对象以创建一个定制的管理器。管理器是一个提供对模型进行数据库查询操作的接口。例如，我们创建`Artist`模型，它含有一个`draft`或者`published`状态，新的管理器`custom_manager`允许你随机地选择一位艺术工作者：
```python
#artists/models.py
# -*- coding: UTF-8 -*-
from django.db import models
from django.utils.translation import ugettext_lazy as _
STATUS_CHOICES = (
('draft', _("Draft"),
('published', _("Published"),
)
class ArtistManager(models.Manager):
def random_published(self):
return self.filter(status="published").order_by('?')
class Artist(models.Model):
# ...
status = models.CharField(_("Status"), max_length=20, choices=STATUS_CHOICES)
custom_manager = ArtistManager()
```
To load a random published artist, you add the following snippet to any template:
```python
{% load utility_tags %}
{% get_objects custom_manager.random_published from artists.Artist limit 1 as random_artists %}
{% for artist in random_artists %}
{{ artist.first_name }} {{ artist.last_name }}
{% endfor %}
```
Let's look at the code of the template tag. In the parsing function, there is one of two formats expected: with the limit and without it. The string is parsed, the model is recognized, and then the components of the template tag are passed to the `ObjectNode` class.
让我来看看那模板标签的代码。在解析函数中，有两种格式的一种是需要的：有限制的，或者干脆就没有。只要字符串被解析出来，模型就会识别它，然后模板标签的组件被传递到`ObjectNode`类。
In the render method of the node class, we check the manager's name and its method's name. If this is not defined, `_default_manager` will be used, which is, in most cases, the same as objects. After that, we call the manager method and fall back to empty QuerySet if the method doesn't exist. If the limit is defined, we resolve the value of it and limit the `QuerySet`. Lastly, we save the `QuerySet` to the context variable.
## 参阅
The Creating a template tag to include a template if it exists recipe
The Creating a template tag to parse content as a template recipe
The Creating a template tag to modify request query parameters recipe
## 创建模板标签并将内容解析为模板
In this recipe, we will create a template tag named {% parse %}, which allows you to put template snippets into the database. This is valuable when you want to provide different content for authenticated and non-authenticated users, when you want to include a personalized salutation, or when you don't want to hardcode media paths in the database.
## 准备开始
No surprise, we will start with the `utils` app that should be installed and ready for custom template tags.
你不必如此讶异，我们依旧从安装好的`utils`应用开始，并为定制模板标签做好准备。
## 工作原理
Template tags consist of two things: the function parsing the arguments of the template tag and the node class that is responsible for the logic of the template tag as well as for the output. Perform the following steps:
1. First, let's create the function parsing the template-tag arguments, as follows:
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
from django import template
register = template.Library()
### TAGS ###
@register.tag
def parse(parser, token):
"""
Parses the value as a template and prints it or saves to a
variable
Usage:
{% parse <template_value> [as <variable>] %}
Examples:
{% parse object.description %}
{% parse header as header %}
{% parse "{{ MEDIA_URL }}js/" as js_url %}
"""
bits = token.split_contents()
tag_name = bits.pop(0)
try:
template_value = bits.pop(0)
var_name = None
if len(bits) == 2:
bits.pop(0) # remove the word "as"
var_name = bits.pop(0)
except ValueError:
raise template.TemplateSyntaxError, \
"parse tag requires a following syntax: "\
"{% parse <template_value> [as <variable>] %}"
return ParseNode(template_value, var_name)
```
2. Then, we create the node class in the same file, as follows:
```pytho
class ParseNode(template.Node):
def __init__(self, template_value, var_name):
self.template_value = template_value
self.var_name = var_name
def render(self, context):
template_value = template.resolve_variable(
self.template_value, context)
t = template.Template(template_value)
context_vars = {}
for d in list(context):
for var, val in d.items():
context_vars[var] = val
result = t.render(template.RequestContext(
context['request'], context_vars))
if self.var_name:
context[self.var_name] = result
return ""
return result
```
## 工作原理
The `{% parse %}` template tag allows you to parse a value as a template and to render it immediately or to save it as a context variable.
If we have an object with a description field, which can contain template variables or logic, then we can parse it and render it using the following code:
```python
{% load utility_tags %}
{% parse object.description %}
It is also possible to define a value to parse using a quoted string like this:
{% load utility_tags %}
{% parse "{{ STATIC_URL }}site/img/" as img_path %}
<img src="{{ img_path }}someimage.png" alt="" />
```
Let's have a look at the code of the template tag. The parsing function checks the arguments of the template tag bit by bit. At first, we expect the name parse, then the template value, then optionally the word as, and lastly the context variable name. The template value and the variable name are passed to the ParseNode class. The render method of that class at first resolves the value of the template variable and creates a template object out of it. Then, it renders the template with all the context variables. If the variable name is defined, the result is saved to it; otherwise, the result is shown immediately.
## 参阅
The Creating a template tag to include a template if it exists recipe
The Creating a template tag to load a QuerySet in a template recipe
The Creating a template tag to modify request query parameters recipe
## 创建一个模板标签以修改request查询参数
Django has a convenient and flexible system to create canonical, clean URLs just by adding regular expression rules in the URL configuration files. But there is a lack of built-in mechanisms to manage query parameters. Views such as search or filterable object lists need to accept query parameters to drill down through filtered results using another parameter or to go to another page. In this recipe, we will create a template tag named `{% append_to_query %}`, which lets you add, change, or remove parameters of the current query.
## 准备开始
Once again, we start with the utils app that should be set in INSTALLED_APPS and should contain the templatetags package.
Also, make sure that you have the request context processor set for the TEMPLATE_CONTEXT_PROCESSORS setting, as follows:
```python
#settings.py
TEMPLATE_CONTEXT_PROCESSORS = (
"django.contrib.auth.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media",
"django.core.context_processors.static",
"django.core.context_processors.tz",
"django.contrib.messages.context_processors.messages",
"django.core.context_processors.request",
)
```
## 如何做
For this template tag, we will be using the simple_tag decorator that parses the components and requires you to define just the rendering function, as follows:
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
import urllib
from django import template
from django.utils.encoding import force_str
register = template.Library()
### TAGS ###
@register.simple_tag(takes_context=True)
def append_to_query(context, **kwargs):
""" Renders a link with modified current query parameters """
query_params = context['request'].GET.copy()
for key, value in kwargs.items():
query_params[key] = value
query_string = u""
if len(query_params):
query_string += u"?%s" % urllib.urlencode([
(key, force_str(value)) for (key, value) in
query_params. iteritems() if value
“
```
For this template tag, we will be using the simple_tag decorator that parses the components and requires you to define just the rendering function, as follows:
```python
#utils/templatetags/utility_tags.py
# -*- coding: UTF-8 -*-
import urllib
from django import template
from django.utils.encoding import force_str
register = template.Library()
### TAGS ###
@register.simple_tag(takes_context=True)
def append_to_query(context, **kwargs):
""" Renders a link with modified current query parameters """
query_params = context['request'].GET.copy()
for key, value in kwargs.items():
query_params[key] = value
query_string = u""
if len(query_params):
query_string += u"?%s" % urllib.urlencode([
(key, force_str(value)) for (key, value) in
query_params. iteritems() if value
]).replace('&', '&')
return query_string
```
## 工作原理
The `{% append_to_query %}` template tag reads the current query parameters from the `request.GET` dictionary-like QueryDict object to a new dictionary named query_params, and loops through the keyword parameters passed to the template tag updating the values. Then, the new query string is formed, all spaces and special characters are URL-encoded, and ampersands connecting query parameters are escaped. This new query string is returned to the template.
To read more about `QueryDict` objects, refer to the official Django documentation:
https://docs.djangoproject.com/en/1.6/ref/request-response/#querydict-objects
Let's have a look at an example of how the `{% append_to_query %}` template tag can be used. If the current URL is `http://127.0.0.1:8000/artists/?category=fine-art&page=1`, we can use the following template tag to render a link that goes to the next page:
```python
{% load utility_tags %}
<a href="{% append_to_query page=2 %}">2</a>
```
The following is the output rendered, using the preceding template tag:
```python
<a href="?category=fine-art&page=2">2</a>
```
Or we can use the following template tag to render a link that resets pagination and goes to another category:
```python
{% load utility_tags i18n %}
<a href="{% append_to_query category="sculpture" page="" %}">{% trans "Sculpture" %}</a>
```
The following is the output rendered, using the preceding template tag:
```python
<a href="?category=sculpture">Sculpture</a>
```
## 参阅
The Filtering object lists recipe in Chapter 3, Forms and Views
The Creating a template tag to include a template if it exists recipe
The Creating a template tag to load a QuerySet in a template recipe
The Creating a template tag to parse content as a template recipe
{% endraw %}
