The Django Book

How invalid variables are handled

Generally, if a variable doesn’t exist, the template system inserts the value of the TEMPLATE_STRING_IF_INVALID setting, which is set to the empty string by default.

Filters that are applied to an invalid variable will only be applied if TEMPLATE_STRING_IF_INVALID is set to its default value. If TEMPLATE_STRING_IF_INVALID is set to any other value, variable filters will be ignored.

This behavior is slightly different for the if, for and regroup template tags. If an invalid variable is provided to one of these template tags, the variable will be interpreted as None. Filters are always applied to invalid variables within these template tags.

django.core.context_processors.auth

If TEMPLATE_CONTEXT_PROCESSORS contains this processor, every RequestContext will contain these three variables:

user

A djangol.contrib.auth.models.User instance representing the currently logged-in user (or an AnonymousUser instance, if the client isn’t logged in).

messages

A list of messages (as strings) for the currently logged-in user. Behind the scenes, this calls request.user.get_and_delete_messages() for every request. That method collects the user’s messages and deletes them from the database.

Note that messages are set with user.add_message().

perms

An instance of django.core.context_processors.PermWrapper, representing the permissions that the currently logged-in user has.

See Chapter XXX for more on users, permissions, and messages.

django.core.context_processors.debug

This processor pushed debugging information down to the template layer. If it is enabled, it will only actually operate if:

• the DEBUG setting is True, and
• the request came from an IP address in the INTERNAL_IPS setting.

If those conditions are met, the following variables will be set:

debug

Set to True; you can use this in templates to test whether you’re in DEBUG mode.

sql_queries

A list of {'sql': ..., 'time': ...} dictionaries, representing every SQL query that has happened so far during the request and how long it took. The list is in order by query.

django.core.context_processors.i18n

If this processor is enabled this processor, every RequestContext will contain these two variables:

LANGUAGES

The value of the LANGUAGES setting.

LANGUAGE_CODE

request.LANGUAGE_CODE, if it exists. Otherwise, the value of the LANGUAGE_CODE setting

Appendix XXX has more information about these two settings.

django.core.context_processors.request

If enabled, every RequestContext will contain a variable request, which is the current HttpRequest object. Note that this processor is not enabled by default; you’ll have to activate it.

The Python API

Django has two ways to load templates from files:

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 doesn’t exist, it raises django.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.

For example, if you call get_template('story_detail.html') and have the above TEMPLATE_DIRS setting, here are the files Django will look for, in order:

• /home/html/templates/lawrence.com/story_detail.html
• /home/html/templates/default/story_detail.html

If you call select_template(['story_253_detail.html', 'story_detail.html']), here’s what Django will look for:

• /home/html/templates/lawrence.com/story_253_detail.html
• /home/html/templates/default/story_253_detail.html
• /home/html/templates/lawrence.com/story_detail.html
• /home/html/templates/default/story_detail.html

When Django finds a template that exists, it stops looking.

Using subdirectories

It’s possible — and preferable — to organize templates in subdirectories of the template directory. The convention is to make a subdirectory for each Django app, with subdirectories within those subdirectories as needed.

Do this for your own sanity. Storing all templates in the root level of a single directory gets messy.

To load a template that’s within a subdirectory, just use a slash, like so:

get_template('news/story_detail.html')

Using the same TEMPLATE_DIRS setting from above, this example get_template() call will attempt to load the following templates:

• /home/html/templates/lawrence.com/news/story_detail.html
• /home/html/templates/default/news/story_detail.html

Again, use UNIX-style forward slashes, even on Windows.

Template loaders

By default, Django loads templates from the filesystem, but Django comes with a few other template loaders which know how to load templates from other sources.

Some of these other loaders are disabled by default, but you can activate them by editing your 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

Loads templates from the filesystem, according to TEMPLATE_DIRS.

This loader is enabled by default.

django.template.loaders.app_directories.load_template_source

Loads templates from Django apps on the filesystem. For each app in INSTALLED_APPS, the loader looks for a templates subdirectory. If the directory exists, Django looks for templates in there.

This means you can store templates with your individual apps. This also makes it easy to distribute Django apps with default templates.

For example, if INSTALLED_APPS contains ('myproject.polls', 'myproject.music'), then get_template('foo.html') will look for templates in 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

Just like app_directories above, but it loads templates from Python eggs rather than from the filesystem.

This loader is disabled by default; you’ll need to enable it if you’re using eggs to distribute your app.

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

A quick overview

Above, this chapter describes how the template system works in a two-step process: compiling and rendering. To define a custom template tag, you need to tell Django how to manage both steps when it gets to your tag.

When Django compiles a template, it splits the raw template text into ‘’nodes’‘. Each node is an instance of django.template.Node and has a render() method. Thus, a compiled template is simply a list of Node objects.

When you call render() on a compiled template, the template calls render() on each Node in its node list, with the given context. The results are all concatenated together to form the output of the template.

Thus, to define a custom template tag, you specify how the raw template tag is converted into a Node (the compilation function), and what the node’s render() method does.

Writing the compilation function

For each template tag the template parser encounters, it calls a Python function with the tag contents and the parser object itself. This function is responsible for returning a Node instance based on the contents of the tag.

For example, let’s write a template tag, {% current_time %}, that displays the current date/time, formatted according to a parameter given in the tag, in strftime syntax (see http://www.python.org/doc/current/lib/module-time.html#l2h-1941). It’s a good idea to decide the tag syntax before anything else. In our case, let’s say the tag should be used like this:

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

The parser for this function should grab the parameter and create a Node object:

from django import template

def do_current_time(parser, token):
    try:
        # split_contents() knows not to split quoted strings.
        tag_name, format_string = token.split_contents()
    except ValueError:
        raise template.TemplateSyntaxError("%r tag requires a single argument" % token.contents[0])
    return CurrentTimeNode(format_string[1:-1])

There’s actually a lot going here:

• parser is the template parser object. We don’t need it in this example.
• token.contents is a string of the raw contents of the tag. In our example, it’s 'current_time "%Y-%m-%d %I:%M %p"'.
• The token.split_contents() method separates the arguments on spaces while keeping quoted strings together. The more straightforward token.contents.split() wouldn’t be as robust, as it would naively split on all spaces, including those within quoted strings. It’s a good idea to always use token.split_contents().
• This function is responsible for raising django.template.TemplateSyntaxError, with helpful messages, for any syntax error.
• Don’t hard-code the tag’s name in your error messages, because that couples the tag’s name to your function. token.contents.split()[0] will ‘’always’’ be the name of your tag — even when the tag has no arguments.
• The function returns a CurrentTimeNode (which we’ll create below) containing everything the node needs to know about this tag. In this case, it just passes the argument — "%Y-%m-%d %I:%M %p". The leading and trailing quotes from the template tag are removed with format_string[1:-1].
• Template tag compilation functions must return a Node subclass; any other return value is an error.
• The parsing is very low-level. We’ve experimented with writing small frameworks on top of this parsing system (using techniques such as EBNF grammars) but those experiments made the template engine too slow. Low level is fast.

Writing the template node

The second step in writing custom tags is to define a Node subclass that has a render() method. Continuing the above example, we need to define CurrentTimeNode:

import datetime

class CurrentTimeNode(template.Node):

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

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

These two functions (__init__ and render) map directly to the two steps in template processing (compilation and rendering). Thus, the initialization function only needs to store the format string for later use, and the render() function does the real work.

Like template filters, these rendering functions should fail silently instead of raising errors. The only time that template tags are allowed to raise errors is at compilation time.

Registering the tag

Finally, you need to register the tag with your module’s Library instance, as explained in “Writing custom template filters” above:

register.tag('current_time', do_current_time)

The tag() method takes two arguments:

1. The name of the template tag (string). If this is left out, the name of the compilation function will be used.
2. The compilation function.

As with filter registration, it is also possible to use this as a decorator in Python 2.4 and above:

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

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

If you leave off the name argument, as in the second example above, Django will use the function’s name as the tag name.

Setting a variable in the context

The above example simply output a value. Often it’s useful to set template variables instead of outputting values. That way, template authors can simply use the values that your template tags create.

To set a variable in the context, just use dictionary assignment on the context object in the render() method. Here’s an updated version of CurrentTimeNode that sets a template variable current_time instead of outputting it:

class CurrentTimeNode2(template.Node):

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

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

Note that render() returns the empty string; render() should always return string output, so if all the template tag does is set a variable, render() should return an empty string.

Here’s how you’d use this new version of the tag:

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

But, there’s a problem with CurrentTimeNode2: the variable name current_time is hard-coded. This means you’ll need to make sure your template doesn’t use {{ current_time }} anywhere else, because the {% current_time %} will blindly overwrite that variable’s value.

A cleaner solution is to make the template tag specify the name of the output variable, like so:

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

To do that, you’ll need to refactor both the compilation function and the Node class, like so:

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):
        context[self.var_name] = datetime.datetime.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:
        raise template.TemplateSyntaxError("%r tag requires arguments" % token.contents[0])

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

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

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

Now, do_current_time() grabs the format string and the variable name, passing both to CurrentTimeNode3.

Parsing until another block tag

Template tags can work as blocks containing other tags. For example, the standard {% comment %} tag hides everything until {% endcomment %}.

To create a template tag like this, use parser.parse() in your compilation function.

Here’s how the standard {% comment %} tag is implemented:

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

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

parser.parse() takes a tuple of names of block tags to parse until. It returns an instance of django.template.NodeList, which is a list of all Node objects that the parser encountered before it encountered any of the tags named in the tuple.

So in the above example, nodelist is a list of all nodes between the {% comment %} and {% endcomment %}, not counting {% comment %} and {% endcomment %} themselves.

After parser.parse() is called, the parser hasn’t yet “consumed” the {% endcomment %} tag, so the code needs to explicitly call parser.delete_first_token() to prevent that tag from being processed twice.

Then, CommentNode.render() simply returns an empty string. Anything between {% comment %} and {% endcomment %} is ignored.

Parsing until another block tag and saving contents

In the previous example, do_comment() discarded everything between {% comment %} and {% endcomment %}. Instead of doing that, it’s possible to do something with the code between block tags.

For example, here’s a custom template tag, {% upper %}, that capitalizes everything between itself and {% endupper %}:

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

As in the previous example, we’ll use parser.parse(). This time, we pass the resulting nodelist to the Node:

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

The only new concept here is the self.nodelist.render(context) in UpperNode.render().

For more examples of complex rendering, see the source code for {% if %}, {% for %}, {% ifequal %} and {% ifchanged %}. They live in django/template/defaulttags.py.

Shortcut for simple tags

Many template tags take a single argument — a string or a template variable reference — and return a string after doing some processing based solely on the input argument and some external information. For example, the current_time tag we wrote above is of this variety: we give it a format string, it returns the time as a string.

To ease the creation of the types of tags, Django provides a helper function, simple_tag. This function, which is a method of django.template.Library, takes a function that accepts one argument, wraps it in a render function and the other necessary bits mentioned above and registers it with the template system.

Our earlier current_time function could thus be written like this:

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

register.simple_tag(current_time)

In Python 2.4, the decorator syntax also works:

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

A couple of things to notice about the simple_tag helper function:

• Only the (single) argument is passed into our function.
• Checking for the required number of arguments has already been done by the time our function is called, so we don’t need to do that.
• The quotes around the argument (if any) have already been stripped away, so we just receive a plain string.

Inclusion tags

Another common type of template tag is the type that displays some data by rendering another template.

For example, Django’s admin interface uses custom template tags to display the buttons along the bottom of the “add/change” form pages. Those buttons always look the same, but the link targets change depending on the object being edited. They’re a perfect case for using a small template that is filled with details from the current object.

These sorts of tags are called inclusion tags.

Writing inclusion tags is probably best demonstrated by example. Let’s write a tag that outputs a list of choices for a simple multiple-choice Poll object. We’ll use the tag like this:

{% show_results poll %}

…and the output will be something like this:

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

First, we define the function that takes the argument and produces a dictionary of data for the result. Notice that we only need to return a dictionary, not anything more complex. This will be used as the context for the template fragment:

def show_results(poll):
    choices = poll.choice_set.all()
    return {'choices': choices}

Next, we create the template used to render the tag’s output. Following our example, the template is very simple:

<ul>
{% for choice in choices %}
    <li> {{ choice }} </li>
{% endfor %}
</ul>

Finally, we create and register the inclusion tag by calling the inclusion_tag() method on a Library object.

Following our example, if the above template is in a file called polls/result_snippet.html, we’d register the tag like this:

register.inclusion_tag('polls/result_snippet.html')(show_results)

As always, Python 2.4 decorator syntax works as well, so we could have instead written:

@register.inclusion_tag('results.html')
def show_results(poll):
    ...

Sometimes, your inclusion tags need access to the context in the parent template.

To solve this, Django provides a takes_context option for inclusion tags. If you specify takes_context in creating a template tag, the tag will have no required arguments, and the underlying Python function will have one argument — the template context as of when the tag was called.

For example, say you’re writing an inclusion tag that will always be used in a context that contains home_link and home_title variables that point back to the main page. Here’s what the Python function would look like:

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

The template link.html might contain:

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

Then, any time you want to use that custom tag, load its library and call it without any arguments, like so:

{% jump_link %}

Note that when you’re using takes_context=True, there’s no need to pass arguments to the template tag. It automatically gets access to the context.