This document explains the Django template system from a technical perspective – how it works and how to extend it. If you’re just looking for reference on the language syntax, see The Django template language.
If you’re looking to use the Django template system as part of another application – i.e., without the rest of the framework – make sure to read the configuration section later in this document.
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 or variables.
A block tag is a symbol within a template that does something.
This definition is deliberately vague. For example, a block tag can output 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 "%}".
Example template with block tags:
{% 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 "}}".
Example template with variables:
My first name is {{ first_name }}. My last name is {{ last_name }}.
A context is a "variable name" -> "variable value" mapping 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.
Using the template system in Python is a two-step process:
The easiest way to create a Template object is by instantiating it directly. The class lives at django.template.Template. The constructor takes one argument -- the raw template code:
>>> from django.template import Template
>>> t = Template("My name is {{ my_name }}.")
>>> print t
<django.template.Template instance>
Behind the scenes
The system only parses your raw template code once -- when you create the Template object. From then on, it's stored internally as a "node" structure for performance.
Even the parsing itself is quite fast. Most of the parsing happens via a single call to a single, short, regular expression.
Once you have a compiled Template object, you can render a context -- or multiple contexts -- with it. The Context class lives at django.template.Context, and the constructor takes two (optional) arguments:
Call the Template object's render() method with the context to "fill" the template:
>>> from django.template import Context, Template
>>> t = Template("My name is {{ my_name }}.")
>>> c = Context({"my_name": "Adrian"})
>>> t.render(c)
"My name is Adrian."
>>> c = Context({"my_name": "Dolores"})
>>> t.render(c)
"My name is Dolores."
Variable names must consist of any letter (A-Z), any digit (0-9), an underscore or a dot.
Dots have a special meaning in template rendering. A dot in a variable name signifies lookup. Specifically, when the template system encounters a dot in a variable name, it tries the following lookups, in this order:
The template system uses the first lookup type that works. It's short-circuit logic.
Here are a few examples:
>>> from django.template import Context, Template
>>> t = Template("My name is {{ person.first_name }}.")
>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
>>> t.render(Context(d))
"My name is Joe."
>>> class PersonClass: pass
>>> p = PersonClass()
>>> p.first_name = "Ron"
>>> p.last_name = "Nasty"
>>> t.render(Context({"person": p}))
"My name is Ron."
>>> class PersonClass2:
... def first_name(self):
... return "Samantha"
>>> p = PersonClass2()
>>> t.render(Context({"person": p}))
"My name is Samantha."
>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
>>> t.render(c)
"The first stooge in the list is Larry."
Method lookups are slightly more complex than the other lookup types. Here are some things to keep in mind:
If, during the method lookup, a method raises an exception, the exception will be propagated, unless the exception has an attribute silent_variable_failure whose value is True. If the exception does have a silent_variable_failure attribute, the variable will render as an empty string. Example:
>>> t = Template("My name is {{ person.first_name }}.")
>>> class PersonClass3:
... def first_name(self):
... raise AssertionError, "foo"
>>> p = PersonClass3()
>>> t.render(Context({"person": p}))
...
AssertionError: foo
>>> class SilentAssertionError(Exception):
... silent_variable_failure = True
>>> class PersonClass4:
... def first_name(self):
... raise SilentAssertionError
>>> p = PersonClass4()
>>> t.render(Context({"person": p}))
"My name is ."
Note that django.core.exceptions.ObjectDoesNotExist, which is the base class for all Django database API DoesNotExist exceptions, has silent_variable_failure = True. So if you're using Django templates with Django model objects, any DoesNotExist exception will fail silently.
A method call will only work if the method has no required arguments. Otherwise, the system will move to the next lookup type (list-index lookup).
Obviously, some methods have side effects, and it'd be either foolish or a security hole to allow the template system to access them.
A good example is the delete() method on each Django model object. The template system shouldn't be allowed to do something like this:
I will now delete this valuable data. {{ data.delete }}
To prevent this, set a function attribute alters_data on the method. The template system won't execute a method if the method has alters_data=True set. The dynamically-generated delete() and save() methods on Django model objects get alters_data=True automatically. Example:
def sensitive_function(self):
self.database_record.delete()
sensitive_function.alters_data = True
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 '' (the empty string). 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.
If TEMPLATE_STRING_IF_INVALID contains a '%s', the format marker will be replaced with the name of the invalid variable.
For debug purposes only!
While TEMPLATE_STRING_IF_INVALID can be a useful debugging tool, it is a bad idea to turn it on as a 'development default'.
Many templates, including those in the Admin site, rely upon the silence of the template system when a non-existent variable is encountered. If you assign a value other than '' to TEMPLATE_STRING_IF_INVALID, you will experience rendering problems with these templates and sites.
Generally, TEMPLATE_STRING_IF_INVALID should only be enabled in order to debug a specific template problem, then cleared once debugging is complete.
Most of the time, you'll instantiate Context objects by passing in a fully-populated dictionary to Context(). But you can add and delete items from a Context object once it's been instantiated, too, using standard dictionary syntax:
>>> c = Context({"foo": "bar"})
>>> c['foo']
'bar'
>>> del c['foo']
>>> c['foo']
''
>>> c['newvariable'] = 'hello'
>>> c['newvariable']
'hello'
A Context object is a stack. That is, you can push() and pop() it. If you pop() too much, it'll raise django.template.ContextPopException:
>>> c = Context()
>>> c['foo'] = 'first level'
>>> c.push()
>>> c['foo'] = 'second level'
>>> c['foo']
'second level'
>>> c.pop()
>>> c['foo']
'first level'
>>> c['foo'] = 'overwritten'
>>> c['foo']
'overwritten'
>>> c.pop()
...
django.template.ContextPopException
Using a Context as a stack comes in handy in some custom template tags, as you'll see below.
Django comes with a special Context class, django.template.RequestContext, that acts slightly differently than the normal django.template.Context. The first difference is that it takes an HttpRequest as its first argument. For example:
c = RequestContext(request, {
'foo': 'bar',
})
The second difference is that it automatically populates the context with a few variables, according to your TEMPLATE_CONTEXT_PROCESSORS setting.
The TEMPLATE_CONTEXT_PROCESSORS setting is a tuple of callables -- called context processors -- that take a request object as their argument and return a dictionary of items to be merged into the context. By default, TEMPLATE_CONTEXT_PROCESSORS is set to:
("django.core.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media")
Each processor is applied in order. That means, 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. The default processors are explained below.
Also, you can give RequestContext a list of additional processors, using the optional, third positional argument, processors. In this example, the RequestContext instance gets a ip_address variable:
def ip_address_processor(request):
return {'ip_address': request.META['REMOTE_ADDR']}
def some_view(request):
# ...
c = RequestContext(request, {
'foo': 'bar',
}, [ip_address_processor])
return HttpResponse(t.render(c))
Note
If you're using Django's render_to_response() shortcut to populate a template with the contents of a dictionary, your template will be passed a Context instance by default (not a RequestContext). To use a RequestContext in your template rendering, pass an optional third argument to render_to_response(): a RequestContext instance. Your code might look like this:
def some_view(request):
# ...
return render_to_response('my_template.html',
my_data_dictionary,
context_instance=RequestContext(request))
Here's what each of the default processors does:
If TEMPLATE_CONTEXT_PROCESSORS contains this processor, every RequestContext will contain these three variables:
user -- An auth.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.message_set.create.
perms -- An instance of django.core.context_processors.PermWrapper, representing the permissions that the currently logged-in user has.
If TEMPLATE_CONTEXT_PROCESSORS contains this processor, every RequestContext will contain these two variables -- but only if your DEBUG setting is set to True and the request's IP address (request.META['REMOTE_ADDR']) is in the INTERNAL_IPS setting:
If TEMPLATE_CONTEXT_PROCESSORS contains this processor, every RequestContext will contain these two variables:
See Internationalization for more.
If TEMPLATE_CONTEXT_PROCESSORS contains this processor, every RequestContext will contain a variable MEDIA_URL, providing the value of the MEDIA_URL setting.
If TEMPLATE_CONTEXT_PROCESSORS contains this processor, every RequestContext will contain a variable request, which is the current HttpRequest. Note that this processor is not enabled by default; you'll have to activate it.
A context processor has a very simple interface: It's just a Python function that takes one argument, an HttpRequest object, and returns a dictionary that gets added to the template context. Each context processor must return a dictionary.
Custom context processors can live anywhere in your code base. All Django cares about is that your custom context processors are pointed-to by your TEMPLATE_CONTEXT_PROCESSORS setting.
Generally, you'll store templates in files on your filesystem rather than using the low-level Template API yourself. Save templates in a directory specified as a template directory.
Django searches for template directories in a number of places, depending on your template-loader settings (see "Loader types" below), but the most basic way of specifying template directories is by using the TEMPLATE_DIRS setting.
Tell Django what your template directories are by using the TEMPLATE_DIRS setting in your settings file. This should be set to a list or tuple of strings that contain full paths to your template directory(ies). Example:
TEMPLATE_DIRS = (
"/home/html/templates/lawrence.com",
"/home/html/templates/default",
)
Your templates can go anywhere you want, as long as the directories and templates are readable by the Web server. They can have any extension you want, such as .html or .txt, or they can have no extension at all.
Note that these paths should use Unix-style forward slashes, even on Windows.
Django has two ways to load templates from files:
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:
If you call select_template(['story_253_detail.html', 'story_detail.html']), here's what Django will look for:
When Django finds a template that exists, it stops looking.
Tip
You can use select_template() for super-flexible "templatability." For example, if you've written a news story and want some stories to have custom templates, use something like select_template(['story_%s_detail.html' % story.id, 'story_detail.html']). That'll allow you to use a custom template for an individual story, with a fallback template for stories that don't have custom templates.
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:
By default, Django uses a filesystem-based template loader, 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. Here are the template loaders that come with Django:
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, for this setting:
INSTALLED_APPS = ('myproject.polls', 'myproject.music')
...then get_template('foo.html') will look for templates in these directories, in this order:
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.
Just like app_directories above, but it loads templates from Python eggs rather than from the filesystem.
This loader is disabled by default.
Django uses the template loaders in order according to the TEMPLATE_LOADERS setting. It uses each loader until a loader finds a match.
To cut down on the repetitive nature of loading and rendering templates, Django provides a shortcut function which largely automates the process: render_to_string() in django.template.loader, which loads a template, renders it and returns the resulting string:
from django.template.loader import render_to_string
rendered = render_to_string('my_template.html', { 'foo': 'bar' })
The render_to_string shortcut takes one required argument -- template_name, which should be the name of the template to load and render -- and two optional arguments:
See also the render_to_response() shortcut, which calls render_to_string and feeds the result into an HttpResponse suitable for returning directly from a view.
Note
This section is only of interest to people trying to use the template system as an output component in another application. If you're using the template system as part of a Django application, nothing here applies 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 you're using the template system independently of the rest of Django, the environment variable approach isn't 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 in Using settings without setting DJANGO_SETTINGS_MODULE. Simply import the appropriate pieces of the templating system and then, before you call any of the templating 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're 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 the settings documentation, and any setting starting with TEMPLATE_ is of obvious interest.
Sep 20, 2009