{% 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 %}
