The Django Book

Template Language Review

MaxVAp <a href=”http://xsivwbewqmrn.com/“>xsivwbewqmrn</a>, [url=http://gncxzntjqedq.com/]gncxzntjqedq[/url], [link=http://fxbofzrzfowj.com/]fxbofzrzfowj[/link], http://mxccahhxsvoy.com/

First, lets quickly review a number of terms introduced in Chapter 4:

首先，让我们快速回顾一下第四章介�的若干专业术语

A template is a text document, or a normal Python string, that is marked up using the Django template language. A template can contain block tags and variables.

模� 是一个纯文本文件，或是一个用Django模�语言标记过的普通的Python字符串，一个模��以包�区�标签和��。

A block tag is a symbol within a template that does something. This definition is deliberately vague. For example, a block tag can produce content, serve as a control structure (an if statement or for loop), grab content from a database, or enable access to other template tags.

区�标签 是在一个模�里�起作用的的标记，这个定义故�说的很�糊，比如，一个 区�标签�以生�内容，�以作为一个控制结构（ if 语�或 for 循环）， �以获�数�库内容，或者访问其他的模�标签。

Block tags are surrounded by {% and %} :

区�标签被 {% 和 %} 包�：

{% if is_logged_in %}
  Thanks for logging in!
{% else %}
  Please log in.
{% endif %}

A variable is a symbol within a template that outputs a value.

�� 是一个在模�里用�输出值的标记。

Variable tags are surrounded by {{ and }} :

636Md6 <a href=”http://htvhlhufywbg.com/“>htvhlhufywbg</a>, [url=http://xborgohwkwvg.com/]xborgohwkwvg[/url], [link=http://wdnbqpxfpopl.com/]wdnbqpxfpopl[/link], http://lmksosgzadaw.com/

My first name is {{ first_name }}. My last name is {{ last_name }}.

A context is a name -> value mapping (similar to a Python dictionary) that is passed to a template.

context 是一个传递给模�的�称到值的映射（类似Python字典）。

A template renders a context by replacing the variable holes with values from the context and executing all block tags.

KeBCRa <a href=”http://samdayfjlhom.com/“>samdayfjlhom</a>, [url=http://tqpfosapplax.com/]tqpfosapplax[/url], [link=http://ttkbcaqikqzp.com/]ttkbcaqikqzp[/link], http://hdccvanbqbjx.com/

For more details about the basics of these terms, refer back to Chapter 4.

关于这些基本概念更详细的内容，请�考第四章。

The rest of this chapter discusses ways of extending the template engine. First, though, lets take a quick look at a few internals left out of Chapter 4 for simplicity.

本章的其余部分讨论了扩展模�引擎的方法。首先，我们快速的看一下第四章�留的内容。

RequestContext and Context Processors

RequestContext和Context处�器

When rendering a template, you need a context. Usually this is an instance of django.template.Context , but Django also comes with a special subclass, django.template.RequestContext , that acts slightly differently. RequestContext adds a bunch of variables to your template context by default things like the HttpRequest object or information about the currently logged-in user.

你需�一段context�解�模�。一般情况下，这是一个 django.template.Context 的实例，�过在Django中还�以用一个特殊的�类， django.template.RequestContext ，这个�用起��微有些��。 RequestContext 默认地在模�context中加入了一些��，如 HttpRequest 对象或当�登录用户的相关信�。

Use RequestContext when you dont want to have to specify the same set of variables in a series of templates. For example, consider these four views:

当你�想在一系例模�中都明确指定一些相�的��时，你应该使用 RequestContext 。例如，看下�的四个视图：

from django.template import loader, Context

def view_1(request):
    # ...
    t = loader.get_template('template1.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am view 1.'
    })
    return t.render(c)

def view_2(request):
    # ...
    t = loader.get_template('template2.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the second view.'
    })
    return t.render(c)

def view_3(request):
# ...
    t = loader.get_template('template3.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the third view.'
    })
    return t.render(c)

def view_4(request):
    # ...
    t = loader.get_template('template4.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the fourth view.'
    })
    return t.render(c)

(Note that were deliberately not using the render_to_response() shortcut in these examples were manually loading the templates, constructing the context objects and rendering the templates. Were spelling out all of the steps for the purpose of clarity.)

（注�，在这些例�中，我们故� � 使用 render_to_response() 这个快�方法，而选择手动载入模�，手动构造context对象然�渲染模�。是为了能够清晰的说明所有步骤。）

Each view passes the same three variables app , user and ip_address to its template. Wouldnt it be nice if we could remove that redundancy?

�个视图都给模�传入了三个相�的��： app � user 和 ip_address 。如果我们能把这些冗余去掉会�会看起�更好？

RequestContext and context processors were created to solve this problem. Context processors let you specify a number of variables that get set in each context automatically without you having to specify the variables in each render_to_response() call. The catch is that you have to use RequestContext instead of Context when you render a template.

创建 RequestContext 和 context处�器 就是为了解决这个问题。Context处�器�许你设置一些��，它们会在�个context中自动被设置好，而�必�次调用 render_to_response() 时都指定。�点就是，当你渲染模�时，你�用 RequestContext 而�是 Context 。

The most low-level way of using context processors is to create some processors and pass them to RequestContext . Heres how the above example could be written with context processors:

最直接的�法是用context处�器�创建一些处�器并传递给 RequestContext 。上�的例��以用context processors改写如下：

from django.template import loader, RequestContext

def custom_proc(request):
    "A context processor that provides 'app', 'user' and 'ip_address'."
    return {
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR']
    }

def view_1(request):
    # ...
    t = loader.get_template('template1.html')
    c = RequestContext(request, {'message': 'I am view 1.'},
            processors=[custom_proc])
    return t.render(c)

def view_2(request):
    # ...
    t = loader.get_template('template2.html')
    c = RequestContext(request, {'message': 'I am the second view.'},
            processors=[custom_proc])
    return t.render(c)

def view_3(request):
    # ...
    t = loader.get_template('template3.html')
    c = RequestContext(request, {'message': 'I am the third view.'},
            processors=[custom_proc])
    return t.render(c)

def view_4(request):
    # ...
    t = loader.get_template('template4.html')
    c = RequestContext(request, {'message': 'I am the fourth view.'},
            processors=[custom_proc])
    return t.render(c)

Lets step through this code:

我们�通读一下代�：

• First, we define a function custom_proc . This is a context processor it takes an HttpRequest object and returns a dictionary of variables to use in the template context. Thats all it does.

• 首先，我们定义一个函数 custom_proc 。这是一个context处ç�†å™¨ï¼Œå®ƒæŽ¥æ”¶ä¸€ä¸ª HttpRequest 对象，然å�Žè¿”回一个字典，这个字典中包å�«äº†å�¯ä»¥åœ¨æ¨¡æ�¿context中使用的å�˜é‡�。它就å�šäº†è¿™ä¹ˆå¤šã€‚

• Weve changed the four view functions to use RequestContext instead of Context . There are two differences in how the context is constructed. One, RequestContext requires the first argument to be an HttpRequest object the one that was passed into the view function in the first place (request ). Two, RequestContext takes an optional processors argument, which is a list or tuple of context processor functions to use. Here, we pass in custom_proc , the custom processor we defined above.

• 我们在这四个视图函数中用 RequestContext 代替了 Context 。在context对象的构建上有两个ä¸�å�Œç‚¹ã€‚一， RequestContext 的第一个å�‚数需è¦�传递一个 HttpRequest 对象，就是传递给视图函数的第一个å�‚数（ request ）。二， RequestContext 有一个å�¯é€‰çš„å�‚æ•° processors ，这是一个包å�«context处ç�†å™¨å‡½æ•°çš„list或者tuple。在这里，我们传递了我们之å‰�定义的函数 curstom_proc 。

• Each view no longer has to include app , user or ip_address in its context construction, because those are provided by custom_proc .

• æ¯�个视图的context结构里ä¸�å†�包å�« app ã€� user ã€� ip_address ç­‰å�˜é‡�，因为这些由 custom_proc 函数æ��供了。

• Each view still has the flexibility to introduce any custom template variables it might need. In this example, the message template variable is set differently in each view.

O5akXl <a href=”http://xrdylvofgyks.com/“>xrdylvofgyks</a>, [url=http://jpknyzrymcvm.com/]jpknyzrymcvm[/url], [link=http://kanomsrvtkmd.com/]kanomsrvtkmd[/link], http://avajxtraqqjg.com/

In Chapter 4, we introduced the render_to_response() shortcut, which saves you from having to call loader.get_template() , then create a Context , then call the render() method on the template. In order to demonstrate the lower-level workings of context processors, the above examples didnt use render_to_response() , . But its possible and preferable to use context processors with render_to_response() . Do this with the context_instance argument, like so:

在第四章，我们介�了 render_to_response() 这个快�方�，它�以�掉调用 loader.get_template() ,然�创建一个 Context 对象，最��调用模�对象的 render() 方法。为了讲解context处�器底层是如何工作的，在上�的例�中我们没有使用 render_to_response() 。但是建议选择 render_to_response() 作为context的处�器。�这样，使用 context_instance �数：

from django.shortcuts import render_to_response
from django.template import RequestContext

def custom_proc(request):
    "A context processor that provides 'app', 'user' and 'ip_address'."
    return {
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR']
    }

def view_1(request):
    # ...
    return render_to_response('template1.html',
        {'message': 'I am view 1.'},
        context_instance=RequestContext(request, processors=[custom_proc]))

def view_2(request):
    # ...
    return render_to_response('template2.html',
        {'message': 'I am the second view.'},
        context_instance=RequestContext(request, processors=[custom_proc]))

def view_3(request):
    # ...
    return render_to_response('template3.html',
        {'message': 'I am the third view.'},
        context_instance=RequestContext(request, processors=[custom_proc]))

def view_4(request):
    # ...
    return render_to_response('template4.html',
        {'message': 'I am the fourth view.'},
        context_instance=RequestContext(request, processors=[custom_proc]))

Here, weve trimmed down each views template rendering code to a single (wrapped) line.

在这，我们将�个视图的模�渲染代�写�了一个�行。

This is an improvement, but, evaluating the conciseness of this code, we have to admit were now almost overdosing on the other end of the spectrum. Weve removed redundancy in data (our template variables) at the cost of adding redundancy in code (in the processors call). Using context processors doesnt save you much typing if you have to type processors all the time.

虽然这是一�改进，但是，请考虑一下这段代�的简�性，我们现在�得�承认的是在 �外 一方�有些过分了。我们以代�冗余（在 processors 调用中）的代价消除了数�上的冗余（我们的模���）。由于你�得�一直键入 processors ，所以使用context处�器并没有�少太多的打字次数。

For that reason, Django provides support for global context processors. The TEMPLATE_CONTEXT_PROCESSORS setting designates which context processors should always be applied to RequestContext . This removes the need to specify processors each time you use RequestContext .

Django因此�供对 全局 context处�器的支�。 TEMPLATE_CONTEXT_PROCESSORS 指定了 总是 使用哪些 context processors 。这样就�去了�次使用 RequestContext 都指定 processors 的麻烦^_^。

By default, TEMPLATE_CONTEXT_PROCESSORS is set to the following:

ilR94N <a href=”http://bxcyktdovtcx.com/“>bxcyktdovtcx</a>, [url=http://svkmchcyqtpi.com/]svkmchcyqtpi[/url], [link=http://orlgauoznlpg.com/]orlgauoznlpg[/link], http://hcmltazhxlgv.com/

TEMPLATE_CONTEXT_PROCESSORS = (
    'django.core.context_processors.auth',
    'django.core.context_processors.debug',
    'django.core.context_processors.i18n',
    'django.core.context_processors.media',
)

This setting is a tuple of callables that use the same interface as our custom_proc function above functions that take a request object as their argument and return a dictionary of items to be merged into the context. Note that the values in TEMPLATE_CONTEXT_PROCESSORS are specified as strings , which means the processors are required to be somewhere on your Python path (so you can refer to them from the setting).

这个设置是一个�调用函数的Tuple，其中的�个函数使用了和上文中我们的 custom_proc 相�的接�：接收一个request对象作为�数，返回一个包�了将被�并到context中的项的字典。请注� TEMPLATE_CONTEXT_PROCESSORS 中的值是以 strings 的形�给出的，这�味�这些处�器必须在你的python路径中的�处（这样你�能在设置中引用它们）

Each processor is applied in order. That is, if one processor adds a variable to the context and a second processor adds a variable with the same name, the second will override the first.

RkbRhS <a href=”http://ssvglzgqktrs.com/“>ssvglzgqktrs</a>, [url=http://tzwexwjpftqx.com/]tzwexwjpftqx[/url], [link=http://siituwbkjtet.com/]siituwbkjtet[/link], http://nyplxetpyqkq.com/

Django provides a number of simple context processors, including the ones that are enabled by default:

Django�供了几个简�的context处�器，有些在默认情况下被�用的。

Inside Template Loading

模�加载的内幕

Generally, youll store templates in files on your filesystem, but you can use custom template loaders to load templates from other sources.

一般说�，你会把模�以文件的方�存储在文件系统中，但是你也�以使用自定义的 template loaders 从其他��加载模�。

Django has two ways to load templates:

Django有两�方法加载模�

• django.template.loader.get_template(template_name) : get_template returns the compiled template (a Template object) for the template with the given name. If the template doesnt exist, a TemplateDoesNotExist exception will be raised.

• django.template.loader.get_template(template_name) ： get_template æ ¹æ�®ç»™å®šçš„模æ�¿å��称返回一个已编译的模æ�¿ï¼ˆä¸€ä¸ª Template 对象）。如果模æ�¿ä¸�存在，就触å�‘ TemplateDoesNotExist 的异常。

• django.template.loader.select_template(template_name_list) : select_template is just like get_template , except it takes a list of template names. Of the list, it returns the first template that exists. If none of the templates exist, a TemplateDoesNotExist exception will be raised.

• django.template.loader.select_template(template_name_list) ： select_template 很åƒ� get_template ，ä¸�过它是以模æ�¿å��称的列表作为å�‚数的，并且它返回第一个存在的模æ�¿ã€‚如果模æ�¿éƒ½ä¸�存在，将会触å�‘ TemplateDoesNotExist 异常。

As covered in Chapter 4, each of these functions by default uses your TEMPLATE_DIRS setting to load templates. Internally, however, these functions actually delegate to a template loader for the heavy lifting.

正如在第四章中所�到的，默认情况下这些函数使用 TEMPLATE_DIRS 的设置�载入模�。但是，在内部这些函数�以指定一个模�加载器�完�这些��的任务。

Some of loaders are disabled by default, but you can activate them by editing the TEMPLATE_LOADERS setting. TEMPLATE_LOADERS should be a tuple of strings, where each string represents a template loader. These template loaders ship with Django:

一些加载器默认被�用，但是你�以通过编辑 TEMPLATE_LOADERS 设置�激活它们。 TEMPLATE_LOADERS 应当是一个字符串的元组，其中�个字符串都表示一个模�加载器。这些模�加载器�Django一起�布。

django.template.loaders.filesystem.load_template_source : This loader loads templates from the filesystem, according to TEMPLATE_DIRS . It is enabled by default.

django.template.loaders.filesystem.load_template_source : 这个加载器根� TEMPLATE_DIRS 的设置从文件系统加载模�。在默认情况下这个加载器被�用.

django.template.loaders.app_directories.load_template_source : This loader loads templates from Django applications on the filesystem. For each application in INSTALLED_APPS , the loader looks for a templates subdirectory. If the directory exists, Django looks for templates there.

django.template.loaders.app_directories.load_template_source : 这个加 载器从文件系统上的Django应用中加载模�。对 INSTALLED_APPS 中的�个应用，这个加 载器会查找一个 templates �目录。如果这个目录存在，Django就在那里寻找模�。

This means you can store templates with your individual applications, making it easy to distribute Django applications with default templates. For example, if INSTALLED_APPS contains ('myproject.polls', 'myproject.music') , then get_template('foo.html') will look for templates in this order:

这�味�你�以把模�和你的应用一起�存，从而使得Django应用更容易和默认模�一起�布。例如，如果 INSTALLED_APPS 包� ('myproject.polls','myproject.music') ，那么 get_template('foo.html') 会按这个顺�查找模�：

• /path/to/myproject/polls/templates/foo.html

• /path/to/myproject/polls/templates/foo.html

• /path/to/myproject/music/templates/foo.html

zS7gE0 <a href=”http://xihwijxziqzw.com/“>xihwijxziqzw</a>, [url=http://latxmxlseqcl.com/]latxmxlseqcl[/url], [link=http://fwlitcrfihxf.com/]fwlitcrfihxf[/link], http://yxtsdtenuwcv.com/

Note that the loader performs an optimization when it is first imported: it caches a list of which INSTALLED_APPS packages have a templates subdirectory.

请注�加载器在首次被导入的时候会执行一个优化：它会缓存一个列表，这个列表包�了 INSTALLED_APPS 中带有 templates �目录的包。

This loader is enabled by default.

这个加载器默认�用。

django.template.loaders.eggs.load_template_source : This loader is just like app_directories , except it loads templates from Python eggs rather than from the filesystem. This loader is disabled by default; youll need to enable it if youre using eggs to distribute your application.

django.template.loaders.eggs.load_template_source : 这个加载器类似 app_directories ，��过它从Python eggs而�是文件系统中加载模�。这个加载器默认被�用；如果你使用eggs��布你的应用，那么你就需��用它。

Django uses the template loaders in order according to the TEMPLATE_LOADERS setting. It uses each loader until a loader finds a match.

Django按照 TEMPLATE_LOADERS 设置中的顺�使用模�加载器。它�个使用�个加载器直至找到一个匹�的模�。

Extending the Template System

扩展模�系统

Now that you understand a bit more about the internals of the template system, lets look at how to extend the system with custom code.

既然你已�对模�系统的内幕了解多了一些，让我们�看看如何使用自定义的代��拓展这个系统�。

Most template customization comes in the form of custom template tags and/or filters. Although the Django template language comes with many built-in tags and filters, youll probably assemble your own libraries of tags and filters that fit your own needs. Fortunately, its quite easy to define your own functionality.

�大部分的模�定制是以自定义标签/过滤器的方��完�的。尽管Django模�语言自带了许多内建标签和过滤器，但是你�能还是需�组建你自己的标签和过滤器库�满足你的需�。幸�的是，定义你自己的功能�常容易。

books/
    __init__.py
    models.py
    templatetags/
    views.py

{% load poll_extras %}

from django import template

register = template.Library()

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()

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()

from django import template

register = template.Library()

@register.filter(name='cut')
def cut(value, arg):
    return value.replace(arg, '')

<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>

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:
        msg = '%r tag requires a single argument' % token.contents[0]
        raise template.TemplateSyntaxError(msg)
    return CurrentTimeNode(format_string[1:-1])

import datetime

class CurrentTimeNode(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        return now.strftime(self.format_string)

register.tag('current_time', do_current_time)

@register.tag(name="current_time")
def do_current_time(parser, token):
    # ...

@register.tag
def shout(parser, token):
    # ...

class CurrentTimeNode2(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        context['current_time'] = now.strftime(self.format_string)
        return ''

{% current_time2 "%Y-%M-%d %I:%M %p" %}
<p>The time is {{ current_time }}.</p>

{% get_current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>

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):
        now = datetime.datetime.now()
        context[self.var_name] = now.strftime(self.format_string)
        return ''

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:
        msg = '%r tag requires arguments' % token.contents[0]
        raise template.TemplateSyntaxError(msg)

    m = re.search(r'(.*?) as (\w+)', arg)
    if m:
        fmt, var_name = m.groups()
    else:
        msg = '%r tag had invalid arguments' % tag_name
        raise template.TemplateSyntaxError(msg)

    if not (fmt[0] == fmt[-1] and fmt[0] in ('"', "'")):
        msg = "%r tag's argument should be in quotes" % tag_name
        raise template.TemplateSyntaxError(msg)

    return CurrentTimeNode3(fmt[1:-1], var_name)

def do_comment(parser, token):
    nodelist = parser.parse(('endcomment',))
    parser.delete_first_token()
    return CommentNode()

class CommentNode(template.Node):
    def render(self, context):
        return ''

{% upper %}
    This will appear in uppercase, {{ your_name }}.
{% endupper %}

@register.tag
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()

def current_time(format_string):
    return datetime.datetime.now().strftime(format_string)

register.simple_tag(current_time)

@register.simple_tag
def current_time(token):
    ...

{% show_results poll %}

<ul>
  <li>First choice</li>
  <li>Second choice</li>
  <li>Third choice</li>
</ul>

def show_books_for_author(author):
    books = author.book_set.all()
    return {'books': books}

<ul>
{% for book in books %}
    <li> {{ book }} </li>
{% endfor %}
</ul>

register.inclusion_tag('books/books_for_author.html')(show_books_for_author)

@register.inclusion_tag('books/books_for_author.html')
def show_books_for_author(show_books_for_author):
    ...

@register.inclusion_tag('link.html', takes_context=True)
def jump_link(context):
    return {
        'link': context['home_link'],
        'title': context['home_title'],
    }

Jump directly to <a href="{{ link }}">{{ title }}</a>.

{% jump_link %}

Writing Custom Template Loaders

编写自定义模�加载器

Djangos built-in template loaders (described in the Inside Template Loading section above) will usually cover all your template-loading needs, but its pretty easy to write your own if you need special loading logic. For example, you could load templates from a database, or directly from a Subversion repository using Subversions Python bindings, or (as shown shortly) from a ZIP archive.

Djangos 内置的模�加载器（在先�的模�加载内幕章节有�述）通常会满足你的所有的模�加载需求，但是如果你有特殊的加载需求的�，编写自己的模�加载器也会相当简�。比如：你�以从数�库加载模�，或者使用 Subversions的Python实现直接从Subversion库加载模�，�或者（��展示）从zip文件加载模�。

A template loaderthat is, each entry in the TEMPLATE_LOADERS setting is expected to be a callable with this interface:

一个模�加载器，也就是 TEMPLATE_LOADERS 中的�一项，都�能被下�这个接�所调用：

load_template_source(template_name, template_dirs=None)

The template_name argument is the name of the template to load (as passed to loader.get_template() or loader.select_template() ), and template_dirs is an optional list of directories to search instead of TEMPLATE_DIRS .

�数 template_name 是所加载模�的�称 (和传递给 loader.get_template() 或者 loader.select_template() 一样), 而 template_dirs 是一个�选的包�除去 TEMPLATE_DIRS 之外的�索目录列表。

If a loader is able to successfully load a template, it should return a tuple: (template_source, template_path) . Here, template_source is the template string that will be compiled by the template engine, and template_path is the path the template was loaded from. That path might be shown to the user for debugging purposes, so it should quickly identify where the template was loaded from.

如果加载器能够�功加载一个模�, 它应当返回一个元组： (template_source, template_path) 。在这里的 template_source 就是将被模�引擎编译的的模�字符串，而 template_path 是被加载的模�的路径。由于那个路径�能会出于调试目的显示给用户，因此它应当很快的指明模�从哪里加载而�。

If the loader is unable to load a template, it should raise django.template.TemplateDoesNotExist .

如果加载器加载模�失败，那么就会触� django.template.TemplateDoesNotExist 异常。

Each loader function should also have an is_usable function attribute. This is a Boolean that informs the template engine whether this loader is available in the current Python installation. For example, the eggs loader (which is capable of loading templates from Python eggs) sets is_usable to False if the pkg_resources module isnt installed, because pkg_resources is necessary to read data from eggs.

�个加载函数都应该有一个�为 is_usable 的函数属性。这个属性是一个布尔值，用于告知模�引擎这个加载器是�在当�安装的Python中�用。例如，如果 pkg_resources 模�没有安装的�，eggs加载器（它能够从python eggs中加载模�）就应该把 is_usable 设为 False ，因为必须通过 pkg_resources �能从eggs中读�数�。

An example should help clarify all of this. Heres a template loader function that can load templates from a ZIP file. It uses a custom setting, TEMPLATE_ZIP_FILES , as a search path instead of TEMPLATE_DIRS , and it expects each item on that path to be a ZIP file containing templates:

一个例��以清晰地�明一切。这儿是一个模�加载函数，它�以从ZIP文件中加载模�。它使用了自定义的设置 TEMPLATE_ZIP_FILES ��代了 TEMPLATE_DIRS 用作查找路径，并且它�设在此路径上的�一个文件都是包�模�的ZIP文件：

import zipfile
from django.conf import settings
from django.template import TemplateDoesNotExist

def load_template_source(template_name, template_dirs=None):
    """Template loader that loads templates from a ZIP file."""

    template_zipfiles = getattr(settings, "TEMPLATE_ZIP_FILES", [])

    # Try each ZIP file in TEMPLATE_ZIP_FILES.
    for fname in template_zipfiles:
        try:
            z = zipfile.ZipFile(fname)
            source = z.read(template_name)
        except (IOError, KeyError):
            continue
        z.close()
        # We found a template, so return the source.
        template_path = "%s:%s" % (fname, template_name)
        return (source, template_path)

    # If we reach here, the template couldn't be loaded
    raise TemplateDoesNotExist(template_name)

# This loader is always usable (since zipfile is included with Python)
load_template_source.is_usable = True

The only step left if we want to use this loader is to add it to the TEMPLATE_LOADERS setting. If we put this code in a package called mysite.zip_loader , then we add mysite.zip_loader.load_template_source to TEMPLATE_LOADERS .

我们�想使用它，还差最�一步，就是把它加入到 TEMPLATE_LOADERS 。如果我们把这部分代�放到一个�� mysite.zip_loader 的包中，我们就需�把 mysite.zip_loader.load_template_source 加入到 TEMPLATE_LOADERS 中去。

Using the Built-in Template Reference

使用内置的模��考

Djangos admin interface includes a complete reference of all template tags and filters available for a given site. Its designed to be a tool that Django programmers give to template developers. To see it, go to the admin interface and click the Documentation link at the upper right of the page.

Django管�界�包�一个完整的�考资料，里�有所有的�以在特定网站上使用的模�标签和过滤器。它设计的�衷是Django程�员�供给模�开�人员的一个工具。你�以点击管�页��上角的文档链接�查看这些资料。

The reference is divided into four sections: tags, filters, models, and views. The tags and filters sections describe all the built-in tags (in fact, the tag and filter references in Chapter 4 come directly from those pages) as well as any custom tag or filter libraries available.

�考说明分为4个部分：标签�过滤器�模型和视图。 标签 和 过滤器 部分�述了所有内置的标签（实际上，第4章中用到的标签和过滤器都直接��于那几页）以�一些�用的自定义标签和过滤器库。

The views page is the most valuable. Each URL in your site has a separate entry here. If the related view includes a docstring, clicking the URL will show you the following:

视图 页�是最有价值的。网站中的�个URL都在这儿有独立的入�。如果相关的视图包�一个 文档字符串， 点击URL，你就会看到：

• The name of the view function that generates that view

• 生æˆ�本视图的视图函数的å��å­—

• A short description of what the view does

• 视图功能的一个简短æ��è¿°

• The context, or a list of variables available in the views template

• 上下文或一个视图模æ�¿ä¸­å�¯ç”¨çš„å�˜é‡�的列表

• The name of the template or templates that are used for that view

• 视图使用的模æ�¿çš„å��å­—

For a detailed example of view documentation, read the source code for Djangos generic object_list view, which is in django/views/generic/list_detail.py .

�想查看关于视图文档的更详细的例�，请阅读Django的通用 object_list 视图部分的�代�，它�于 django/views/generic/list_detail.py 文件中。

Because Django-powered sites usually use database objects, the models pages describe each type of object in the system along with all the fields available on that object.

通常情况下，由Django构建的网站都会使用数�库对象， 模型 页��述了系统中所有类型的对象，以�该对象对应的所有�用字段。

Taken together, the documentation pages should tell you every tag, filter, variable, and object available to you in a given template.

总之，这些文档告诉你在模�中的所有�用的标签�过滤器���和对象。

Configuring the Template System in Standalone Mode

�置独立模�下的模�系统

Note

备注

This section is only of interest to people trying to use the template system as an output component in another application. If you are using the template system as part of a Django application, the information presented here doesnt apply to you.

这部分�针对于对在其他应用中使用模版系统作为输出组件感兴趣的人。如果你是在Django应用中使用模版系统，请略过此部分。

Normally, Django will load all the configuration information it needs from its own default configuration file, combined with the settings in the module given in the DJANGO_SETTINGS_MODULE environment variable. But if youre using the template system independently of the rest of Django, the environment variable approach isnt very convenient, because you probably want to configure the template system in line with the rest of your application rather than dealing with settings files and pointing to them via environment variables.

通常，Django会从它的默认�置文件和由 DJANGO_SETTINGS_MODULE 环境��所指定的模�中加载它需�的所有�置信�。但是当你想在�Django应用中使用模版系统的时候，采用环境��并�是很好的方法。比起为模版系统�独采用�置文件并用环境���指�它，你�能更希望能够在你的应用中采用一致的�置方法��置模版系统和其他部分

To solve this problem, you need to use the manual configuration option described fully Appendix E. In a nutshell, you need to import the appropriate pieces of the template system and then, before you call any of the template functions, call django.conf.settings.configure() with any settings you wish to specify.

为了解决这个问题，你需�使用附录E中所�述的手动�置选项。简��说，你需�引入�适的模�系统，并且在调用任何模�函数 之� 调用 django.conf.settings.configure() �指定任何你想�的设置。

You might want to consider setting at least TEMPLATE_DIRS (if you are going to use template loaders), DEFAULT_CHARSET (although the default of utf-8 is probably fine), and TEMPLATE_DEBUG . All available settings are described in Appendix E, and any setting starting with TEMPLATE_ is of obvious interest.

你�能会考虑至少�设置 TEMPLATE_DIRS （如果你打算使用模�加载器）， DEFAULT_CHARSET （尽管默认的 utf-8 编�相当好用），以� TEMPLATE_DEBUG 。所有�用的选项都在附录E中详细�述，所有以 TEMPLATE_ 开头的选项都�能使你感兴趣的。

Whats Next

接下�？

So far this book has assumed that the content youre displaying is HTML. This isnt a bad assumption for a book about Web development, but at times youll want to use Django to output other data formats.

迄今为止，本书�定您想展示的内容为HTML。对于一个有关Web开�的书�说，这�是一个 �好的�设，但有时你想用Django输出其他数�格�。

The next chapter describes how you can use Django to produce images, PDFs, and any other data format you can imagine.

下一章将讲解如何使用Django生�图��PDF�还有你�以想到的其他数�格�。