Template Language Review

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.

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.

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 }} :

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.

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

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

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.

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:

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

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?

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.

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:

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.

• 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.

• Each view no longer has to include app , user or ip_address in its context construction, because those are provided by 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.

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:

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.

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 .

By default, TEMPLATE_CONTEXT_PROCESSORS is set to the following:

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

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.

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

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.

Django has two ways to load templates:

• 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.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.

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.

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:

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.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.

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:

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

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

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.

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 uses the template loaders in order according to the TEMPLATE_LOADERS setting. It uses each loader until a loader finds a match.

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.

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.

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

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 .

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.

If the loader is unable to load a template, it should raise 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.

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:

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 .

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.

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.

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:

• 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 .

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.

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.

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.

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.

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.

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.

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