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:
Template
object.render()
method of the Template
object with a
given context.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.
render
(context)¶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 (but they must not start with an underscore) or a dot.
Dots have a special meaning in template rendering. A dot in a variable name signifies a lookup. Specifically, when the template system encounters a dot in a variable name, it tries the following lookups, in this order:
foo["bar"]
foo.bar
foo[bar]
Note that “bar” in a template expression like {{ foo.bar }}
will be
interpreted as a literal string and not using the value of the variable “bar”,
if one exists in the template context.
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."
>>> 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."
If any part of the variable is callable, the template system will try calling it. Example:
>>> class PersonClass2:
... def name(self):
... return "Samantha"
>>> t = Template("My name is {{ person.name }}.")
>>> t.render(Context({"person": PersonClass2}))
"My name is Samantha."
Callable variables are slightly more complex than variables which only require straight lookups. Here are some things to keep in mind:
If the variable raises an exception when called, 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 whose value is
True
, the variable will render as the value of the
TEMPLATE_STRING_IF_INVALID
setting (an empty string, by default).
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}))
Traceback (most recent call last):
...
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 variable can only be called if it has no required arguments. Otherwise,
the system will return the value of TEMPLATE_STRING_IF_INVALID
.
Obviously, there can be side effects when calling some variables, 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 an alters_data
attribute on the callable
variable. The template system won’t call a variable if it has
alters_data=True
set, and will instead replace the variable with
TEMPLATE_STRING_IF_INVALID
, unconditionally. 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
Occasionally you may want to turn off this feature for other reasons,
and tell the template system to leave a variable uncalled no matter
what. To do so, set a do_not_call_in_templates
attribute on the
callable with the value True
. The template system then will act as
if your variable is not callable (allowing you to access attributes of
the callable, for example).
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.
Every context contains True
, False
and None
. As you would expect,
these variables resolve to the corresponding Python objects.
Django’s template language has no way to escape the characters used for its own
syntax. For example, the templatetag
tag is required if you need to
output character sequences like {%
and %}
.
A similar issue exists if you want to include these sequences in template filter
or tag arguments. For example, when parsing a block tag, Django’s template
parser looks for the first occurrence of %}
after a {%
. This prevents
the use of "%}"
as a string literal. For example, a TemplateSyntaxError
will be raised for the following expressions:
{% include "template.html" tvar="Some string literal with %} in it." %}
{% with tvar="Some string literal with %} in it." %}{% endwith %}
The same issue can be triggered by using a reserved sequence in filter arguments:
{{ some.variable|default:"}}" }}
If you need to use strings with these sequences, store them in template variables or use a custom template tag or filter to workaround the limitation.
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:
>>> from django.template import Context
>>> c = Context({"foo": "bar"})
>>> c['foo']
'bar'
>>> del c['foo']
>>> c['foo']
Traceback (most recent call last):
...
KeyError: 'foo'
>>> c['newvariable'] = 'hello'
>>> c['newvariable']
'hello'
Context.
get
(key, otherwise=None)¶Returns the value for key
if key
is in the context, else returns
otherwise
.
Context.
pop
()¶Context.
push
()¶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()
{'foo': 'second level'}
>>> c['foo']
'first level'
>>> c['foo'] = 'overwritten'
>>> c['foo']
'overwritten'
>>> c.pop()
Traceback (most recent call last):
...
ContextPopException
You can also use push()
as a context manager to ensure a matching pop()
is called.
>>> c = Context()
>>> c['foo'] = 'first level'
>>> with c.push():
... c['foo'] = 'second level'
... c['foo']
'second level'
>>> c['foo']
'first level'
All arguments passed to push()
will be passed to the dict
constructor
used to build the new context level.
>>> c = Context()
>>> c['foo'] = 'first level'
>>> with c.push(foo='second level'):
... c['foo']
'second level'
>>> c['foo']
'first level'
In addition to push()
and pop()
, the Context
object also defines an update()
method. This works like push()
but takes a dictionary as an argument and pushes that dictionary onto
the stack instead of an empty one.
>>> c = Context()
>>> c['foo'] = 'first level'
>>> c.update({'foo': 'updated'})
{'foo': 'updated'}
>>> c['foo']
'updated'
>>> c.pop()
{'foo': 'updated'}
>>> c['foo']
'first level'
Using a Context
as a stack comes in handy in some custom template tags, as
you’ll see below.
Context.
flatten
()¶Using flatten()
method you can get whole Context
stack as one dictionary
including builtin variables.
>>> c = Context()
>>> c['foo'] = 'first level'
>>> c.update({'bar': 'second level'})
{'bar': 'second level'}
>>> c.flatten()
{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}
A flatten()
method is also internally used to make Context
objects comparable.
>>> c1 = Context()
>>> c1['foo'] = 'first level'
>>> c1['bar'] = 'second level'
>>> c2 = Context()
>>> c2.update({'bar': 'second level', 'foo': 'first level'})
{'foo': 'first level', 'bar': 'second level'}
>>> c1 == c2
True
Result from flatten()
can be useful in unit tests to compare Context
against dict
:
class ContextTest(unittest.TestCase):
def test_against_dictionary(self):
c1 = Context()
c1['update'] = 'value'
self.assertEqual(c1.flatten(), {
'True': True, 'None': None, 'False': False,
'update': 'value'})
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.contrib.auth.context_processors.auth",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media",
"django.core.context_processors.static",
"django.core.context_processors.tz",
"django.contrib.messages.context_processors.messages")
In addition to these, RequestContext
always uses
django.core.context_processors.csrf
. This is a security
related context processor required by the admin and other contrib apps, and,
in case of accidental misconfiguration, it is deliberately hardcoded in and
cannot be turned off by the TEMPLATE_CONTEXT_PROCESSORS
setting.
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.
When context processors are applied
Context processors are applied after the context itself is processed.
This means that a context processor may overwrite variables you’ve
supplied to your Context
or RequestContext
, so take care
to avoid variable names that overlap with those supplied by your
context processors.
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:
from django.http import HttpResponse
from django.template import RequestContext
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, use the render()
shortcut which is
the same as a call to render_to_response()
with a
context_instance
argument that forces the use of a RequestContext
.
Here’s what each of the default processors does:
If TEMPLATE_CONTEXT_PROCESSORS
contains this processor, every
RequestContext
will contain these variables:
user
– An auth.User
instance representing the currently
logged-in user (or an AnonymousUser
instance, if the client isn’t
logged in).perms
– An instance of
django.contrib.auth.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:
debug
– 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.If TEMPLATE_CONTEXT_PROCESSORS
contains 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.See Internationalization and localization 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.
static
()¶If TEMPLATE_CONTEXT_PROCESSORS
contains this processor, every
RequestContext
will contain a variable STATIC_URL
, providing the
value of the STATIC_URL
setting.
This processor adds a token that is needed by the csrf_token
template
tag for protection against Cross Site Request Forgeries.
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.
If TEMPLATE_CONTEXT_PROCESSORS
contains this processor, every
RequestContext
will contain these two variables:
messages
– A list of messages (as strings) that have been set
via the messages framework.DEFAULT_MESSAGE_LEVELS
– A mapping of the message level names to
their numeric value.The DEFAULT_MESSAGE_LEVELS
variable was added.
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.template.loader
has two functions to load templates from files:
get_template
(template_name[, dirs])[source]¶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
.
To override the TEMPLATE_DIRS
setting, use the dirs
parameter. The dirs
parameter may be a tuple or list.
The dirs
parameter was added.
select_template
(template_name_list[, dirs])[source]¶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.
To override the TEMPLATE_DIRS
setting, use the dirs
parameter. The dirs
parameter may be a tuple or list.
The dirs
parameter was added.
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.
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:
/home/html/templates/lawrence.com/news/story_detail.html
/home/html/templates/default/news/story_detail.html
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
class. Here are the template loaders that come with Django:
django.template.loaders.filesystem.Loader
filesystem.
Loader
¶Loads templates from the filesystem, according to TEMPLATE_DIRS
.
This loader is enabled by default.
django.template.loaders.app_directories.Loader
app_directories.
Loader
¶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 foo.html
in these
directories, in this order:
/path/to/myproject/polls/templates/
/path/to/myproject/music/templates/
... and will use the one it finds first.
The order of INSTALLED_APPS
is significant! For example, if you
want to customize the Django admin, you might choose to override the
standard admin/base_site.html
template, from django.contrib.admin
,
with your own admin/base_site.html
in myproject.polls
. You must
then make sure that your myproject.polls
comes before
django.contrib.admin
in INSTALLED_APPS
, otherwise
django.contrib.admin
’s will be loaded first and yours will be ignored.
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.Loader
eggs.
Loader
¶Just like app_directories
above, but it loads templates from Python
eggs rather than from the filesystem.
This loader is disabled by default.
django.template.loaders.cached.Loader
cached.
Loader
¶By default, the templating system will read and compile your templates every time they need to be rendered. While the Django templating system is quite fast, the overhead from reading and compiling templates can add up.
The cached template loader is a class-based loader that you configure with
a list of other loaders that it should wrap. The wrapped loaders are used to
locate unknown templates when they are first encountered. The cached loader
then stores the compiled Template
in memory. The cached Template
instance is returned for subsequent requests to load the same template.
For example, to enable template caching with the filesystem
and
app_directories
template loaders you might use the following settings:
TEMPLATE_LOADERS = (
('django.template.loaders.cached.Loader', (
'django.template.loaders.filesystem.Loader',
'django.template.loaders.app_directories.Loader',
)),
)
Note
All of the built-in Django template tags are safe to use with the
cached loader, but if you’re using custom template tags that come from
third party packages, or that you wrote yourself, you should ensure
that the Node
implementation for each tag is thread-safe. For more
information, see template tag thread safety
considerations.
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.
When TEMPLATE_DEBUG
is True
template objects will have an
origin
attribute depending on the source they are loaded from.
loader.
LoaderOrigin
¶Templates created from a template loader will use the
django.template.loader.LoaderOrigin
class.
name
¶The path to the template as returned by the template loader. For loaders that read from the file system, this is the full path to the template.
loadname
¶The relative path to the template as passed into the template loader.
render_to_string
shortcut¶loader.
render_to_string
(template_name, dictionary=None, context_instance=None)¶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 (or a list of template names, in which case Django will use
the first template in the list that exists) – and two optional arguments:
Context
or a subclass (e.g., an
instance of RequestContext
) to use as the
template’s context. This can also be passed as the third positional argument.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
. If you plan to use the url
template tag,
you will also need to set the ROOT_URLCONF
setting. All available
settings are described in the settings documentation,
and any setting starting with TEMPLATE_
is of obvious interest.
The Django Template
and Loader
classes implement a simple API for
loading and rendering templates. By providing some simple wrapper classes that
implement this API we can use third party template systems like Jinja2 or Cheetah. This
allows us to use third-party template libraries without giving up useful Django
features like the Django Context
object and handy shortcuts like
render_to_response()
.
The core component of the Django templating system is the Template
class.
This class has a very simple interface: it has a constructor that takes a single
positional argument specifying the template string, and a render()
method
that takes a Context
object and returns a string
containing the rendered response.
Suppose we’re using a template language that defines a Template
object with
a render()
method that takes a dictionary rather than a Context
object.
We can write a simple wrapper that implements the Django Template
interface:
import some_template_language
class Template(some_template_language.Template):
def render(self, context):
# flatten the Django Context into a single dictionary.
context_dict = {}
for d in context.dicts:
context_dict.update(d)
return super(Template, self).render(context_dict)
That’s all that’s required to make our fictional Template
class compatible
with the Django loading and rendering system!
The next step is to write a Loader
class that returns instances of our custom
template class instead of the default Template
. Custom Loader
classes should inherit from django.template.loader.BaseLoader
and override
the load_template_source()
method, which takes a template_name
argument,
loads the template from disk (or elsewhere), and returns a tuple:
(template_string, template_origin)
.
The load_template()
method of the Loader
class retrieves the template
string by calling load_template_source()
, instantiates a Template
from
the template source, and returns a tuple: (template, template_origin)
. Since
this is the method that actually instantiates the Template
, we’ll need to
override it to use our custom template class instead. We can inherit from the
builtin django.template.loaders.app_directories.Loader
to take advantage
of the load_template_source()
method implemented there:
from django.template.loaders import app_directories
class Loader(app_directories.Loader):
is_usable = True
def load_template(self, template_name, template_dirs=None):
source, origin = self.load_template_source(template_name, template_dirs)
template = Template(source)
return template, origin
Finally, we need to modify our project settings, telling Django to use our custom loader. Now we can write all of our templates in our alternative template language while continuing to use the rest of the Django templating system.
Feb 24, 2017