1196 lines
47 KiB
Plaintext
1196 lines
47 KiB
Plaintext
====================================================
|
|
The Django template language: For Python programmers
|
|
====================================================
|
|
|
|
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: For template authors`_.
|
|
|
|
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.
|
|
|
|
.. _`The Django template language: For template authors`: ../templates/
|
|
|
|
Basics
|
|
======
|
|
|
|
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
|
|
=========================
|
|
|
|
Using the template system in Python is a two-step process:
|
|
|
|
* First, you compile the raw template code into a ``Template`` object.
|
|
* Then, you call the ``render()`` method of the ``Template`` object with a
|
|
given context.
|
|
|
|
Compiling a string
|
|
------------------
|
|
|
|
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>
|
|
|
|
.. admonition:: 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.
|
|
|
|
Rendering a 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 one (optional)
|
|
argument: a dictionary mapping variable names to variable values. 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:
|
|
|
|
* Dictionary lookup. Example: ``foo["bar"]``
|
|
* Attribute lookup. Example: ``foo.bar``
|
|
* Method call. Example: ``foo.bar()``
|
|
* List-index lookup. Example: ``foo[bar]``
|
|
|
|
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}))
|
|
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 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
|
|
|
|
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 ``''`` (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.
|
|
|
|
.. admonition:: 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.
|
|
|
|
Playing with Context objects
|
|
----------------------------
|
|
|
|
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()
|
|
Traceback (most recent call last):
|
|
...
|
|
django.template.ContextPopException
|
|
|
|
Using a ``Context`` as a stack comes in handy in some custom template tags, as
|
|
you'll see below.
|
|
|
|
Subclassing Context: RequestContext
|
|
-----------------------------------
|
|
|
|
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 takes
|
|
an `HttpRequest object`_ 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")
|
|
|
|
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):
|
|
# ...
|
|
return RequestContext(request, {
|
|
'foo': 'bar',
|
|
}, [ip_address_processor])
|
|
|
|
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:
|
|
|
|
.. _HttpRequest object: ../request_response/#httprequest-objects
|
|
.. _TEMPLATE_CONTEXT_PROCESSORS setting: ../settings/#template-context-processors
|
|
|
|
django.core.context_processors.auth
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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). See the `user authentication docs`.
|
|
|
|
* ``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()``. See the
|
|
`message docs`_ for more.
|
|
|
|
* ``perms`` -- An instance of
|
|
``django.core.context_processors.PermWrapper``, representing the
|
|
permissions that the currently logged-in user has. See the `permissions
|
|
docs`_.
|
|
|
|
.. _user authentication docs: ../authentication/#users
|
|
.. _message docs: ../authentication/#messages
|
|
.. _permissions docs: ../authentication/#permissions
|
|
|
|
django.core.context_processors.debug
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
django.core.context_processors.i18n
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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 the `internationalization docs`_ for more.
|
|
|
|
.. _LANGUAGES setting: ../settings/#languages
|
|
.. _LANGUAGE_CODE setting: ../settings/#language-code
|
|
.. _internationalization docs: ../i18n/
|
|
|
|
django.core.context_processors.request
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, 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.
|
|
|
|
Writing your own context processors
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
Loading templates
|
|
-----------------
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
.. admonition:: 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.
|
|
|
|
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``
|
|
|
|
Loader types
|
|
~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
``django.template.loaders.filesystem.load_template_source``
|
|
Loads templates from the filesystem, according to ``TEMPLATE_DIRS``.
|
|
|
|
``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, for this setting::
|
|
|
|
INSTALLED_APPS = ('myproject.polls', 'myproject.music')
|
|
|
|
...then ``get_template('foo.html')`` will look for templates in these
|
|
directories, 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.
|
|
|
|
``django.template.loaders.eggs.load_template_source``
|
|
Just like ``app_directories`` above, but it loads templates from Python
|
|
eggs rather than from the filesystem.
|
|
|
|
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
|
|
=============================
|
|
|
|
Although the Django template language comes with several default tags and
|
|
filters, you might want to write your own. It's easy to do.
|
|
|
|
First, create a ``templatetags`` package in the appropriate Django app's
|
|
package. It should be on the same level as ``models.py``, ``views.py``, etc. For
|
|
example::
|
|
|
|
polls/
|
|
models.py
|
|
templatetags/
|
|
views.py
|
|
|
|
Add two files to the ``templatetags`` package: an ``__init__.py`` file and a
|
|
file that will contain your custom tag/filter definitions. The name of the
|
|
latter file is the name you'll use to load the tags later. For example, if your
|
|
custom tags/filters are in a file called ``poll_extras.py``, you'd do the
|
|
following in a template::
|
|
|
|
{% load poll_extras %}
|
|
|
|
The ``{% load %}`` tag looks at your ``INSTALLED_APPS`` setting and only allows
|
|
the loading of template libraries within installed Django apps. This is a
|
|
security feature: It allows you to host Python code for many template libraries
|
|
on a single computer without enabling access to all of them for every Django
|
|
installation.
|
|
|
|
If you write a template library that isn't tied to any particular models/views,
|
|
it's perfectly OK to have a Django app package that only contains a
|
|
``templatetags`` package.
|
|
|
|
There's no limit on how many modules you put in the ``templatetags`` package.
|
|
Just keep in mind that a ``{% load %}`` statement will load tags/filters for
|
|
the given Python module name, not the name of the app.
|
|
|
|
Once you've created that Python module, you'll just have to write a bit of
|
|
Python code, depending on whether you're writing filters or tags.
|
|
|
|
To be a valid tag library, the module contain a module-level variable named
|
|
``register`` that is a ``template.Library`` instance, in which all the tags and
|
|
filters are registered. So, near the top of your module, put the following::
|
|
|
|
from django import template
|
|
|
|
register = template.Library()
|
|
|
|
.. admonition:: Behind the scenes
|
|
|
|
For a ton of examples, read the source code for Django's default filters
|
|
and tags. They're in ``django/template/defaultfilters.py`` and
|
|
``django/template/defaulttags.py``, respectively.
|
|
|
|
Writing custom template filters
|
|
-------------------------------
|
|
|
|
Custom filters are just Python functions that take one or two arguments:
|
|
|
|
* The value of the variable (input) -- not necessarily a string.
|
|
* The value of the argument -- this can have a default value, or be left
|
|
out altogether.
|
|
|
|
For example, in the filter ``{{ var|foo:"bar" }}``, the filter ``foo`` would be
|
|
passed the variable ``var`` and the argument ``"bar"``.
|
|
|
|
Filter functions should always return something. They shouldn't raise
|
|
exceptions. They should fail silently. In case of error, they should return
|
|
either the original input or an empty string -- whichever makes more sense.
|
|
|
|
Here's an example filter definition::
|
|
|
|
def cut(value, arg):
|
|
"Removes all values of arg from the given string"
|
|
return value.replace(arg, '')
|
|
|
|
And here's an example of how that filter would be used::
|
|
|
|
{{ somevariable|cut:"0" }}
|
|
|
|
Most filters don't take arguments. In this case, just leave the argument out of
|
|
your function. Example::
|
|
|
|
def lower(value): # Only one argument.
|
|
"Converts a string into all lowercase"
|
|
return value.lower()
|
|
|
|
When you've written your filter definition, you need to register it with
|
|
your ``Library`` instance, to make it available to Django's template language::
|
|
|
|
register.filter('cut', cut)
|
|
register.filter('lower', lower)
|
|
|
|
The ``Library.filter()`` method takes two arguments:
|
|
|
|
1. The name of the filter -- a string.
|
|
2. The compilation function -- a Python function (not the name of the
|
|
function as a string).
|
|
|
|
If you're using Python 2.4 or above, you can use ``register.filter()`` as a
|
|
decorator instead::
|
|
|
|
@register.filter(name='cut')
|
|
def cut(value, arg):
|
|
return value.replace(arg, '')
|
|
|
|
@register.filter
|
|
def lower(value):
|
|
return value.lower()
|
|
|
|
If you leave off the ``name`` argument, as in the second example above, Django
|
|
will use the function's name as the filter name.
|
|
|
|
Template filters which expect strings
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
If you are writing a template filter which only expects a string as the first
|
|
argument, you should use the included decorator ``stringfilter`` which will convert
|
|
an object to it's string value before being passed to your function::
|
|
|
|
from django import template
|
|
|
|
@template.stringfilter
|
|
def lower(value):
|
|
return value.lower()
|
|
|
|
Writing custom template tags
|
|
----------------------------
|
|
|
|
Tags are more complex than filters, because tags can do anything.
|
|
|
|
A quick overview
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Above, this document explained that the template system works in a two-step
|
|
process: compiling and rendering. To define a custom template tag, you specify
|
|
how the compilation works and how the rendering works.
|
|
|
|
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. A compiled template is, simply, a list of ``Node``
|
|
objects. When you call ``render()`` on a compiled template object, 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`_. 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>
|
|
|
|
.. _`strftime syntax`: http://www.python.org/doc/current/lib/module-time.html#l2h-1941
|
|
|
|
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]
|
|
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 CurrentTimeNode(format_string[1:-1])
|
|
|
|
Notes:
|
|
|
|
* ``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.
|
|
|
|
* The ``TemplateSyntaxError`` exceptions use the ``tag_name`` variable.
|
|
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`` with 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 in ``format_string[1:-1]``.
|
|
|
|
* The parsing is very low-level. The Django developers have 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. It's low-level because that's fastest.
|
|
|
|
Writing the renderer
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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``::
|
|
|
|
from django import template
|
|
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)
|
|
|
|
Notes:
|
|
|
|
* ``__init__()`` gets the ``format_string`` from ``do_current_time()``.
|
|
Always pass any options/parameters/arguments to a ``Node`` via its
|
|
``__init__()``.
|
|
|
|
* The ``render()`` method is where the work actually happens.
|
|
|
|
* ``render()`` should never raise ``TemplateSyntaxError`` or any other
|
|
exception. It should fail silently, just as template filters should.
|
|
|
|
Ultimately, this decoupling of compilation and rendering results in an
|
|
efficient template system, because a template can render multiple context
|
|
without having to be parsed multiple times.
|
|
|
|
Registering the tag
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Finally, register the tag with your module's ``Library`` instance, as explained
|
|
in "Writing custom template filters" above. Example::
|
|
|
|
register.tag('current_time', do_current_time)
|
|
|
|
The ``tag()`` method takes two arguments:
|
|
|
|
1. The name of the template tag -- a string. If this is left out, the
|
|
name of the compilation function will be used.
|
|
2. The compilation function -- a Python function (not the name of the
|
|
function as a string).
|
|
|
|
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.
|
|
|
|
Passing template variables to the tag
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Although you can pass any number of arguments to a template tag using
|
|
``token.split_contents()``, the arguments are all unpacked as
|
|
string literals. A little more work is required in order to dynamic content (a
|
|
template variable) to a template tag as an argument.
|
|
|
|
While the previous examples have formatted the current time into a string and
|
|
returned the string, suppose you wanted to pass in a ``DateTimeField`` from an
|
|
object and have the template tag format that date-time::
|
|
|
|
<p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
|
|
|
|
Initially, ``token.split_contents()`` will return three values:
|
|
|
|
1. The tag name ``format_time``.
|
|
2. The string "blog_entry.date_updated" (without the surrounding quotes).
|
|
3. The formatting string "%Y-%m-%d %I:%M %p". The return value from
|
|
``split_contents()`` will include the leading and trailing quotes for
|
|
string literals like this.
|
|
|
|
Now your tag should begin to look like this::
|
|
|
|
from django import template
|
|
def do_format_time(parser, token):
|
|
try:
|
|
# split_contents() knows not to split quoted strings.
|
|
tag_name, date_to_be_formatted, format_string = token.split_contents()
|
|
except ValueError:
|
|
raise template.TemplateSyntaxError, "%r tag requires exactly two arguments" % token.contents[0]
|
|
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 FormatTimeNode(date_to_be_formatted, format_string[1:-1])
|
|
|
|
You also have to change the renderer to retrieve the actual contents of the
|
|
``date_updated`` property of the ``blog_entry`` object. This can be
|
|
accomplished by using the ``resolve_variable()`` function in
|
|
``django.template``. You pass ``resolve_variable()`` the variable name and the
|
|
current context, available in the ``render`` method::
|
|
|
|
from django import template
|
|
from django.template import resolve_variable
|
|
import datetime
|
|
class FormatTimeNode(template.Node):
|
|
def __init__(self, date_to_be_formatted, format_string):
|
|
self.date_to_be_formatted = date_to_be_formatted
|
|
self.format_string = format_string
|
|
|
|
def render(self, context):
|
|
try:
|
|
actual_date = resolve_variable(self.date_to_be_formatted, context)
|
|
return actual_date.strftime(self.format_string)
|
|
except VariableDoesNotExist:
|
|
return ''
|
|
|
|
``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then
|
|
format it accordingly.
|
|
|
|
.. note::
|
|
The ``resolve_variable()`` function will throw a ``VariableDoesNotExist``
|
|
exception if it cannot resolve the string passed to it in the current
|
|
context of the page.
|
|
|
|
Shortcut for simple tags
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Many template tags take a number of arguments -- strings or a template variables
|
|
-- 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 any number of
|
|
arguments, 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 note about the ``simple_tag`` helper function:
|
|
* Checking for the required number of arguments, etc, 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.
|
|
* If the argument was a template variable, our function is passed the
|
|
current value of the variable, not the variable itself.
|
|
|
|
When your template tag does not need access to the current context, writing a
|
|
function to work with the input values and using the ``simple_tag`` helper is
|
|
the easiest way to create a new tag.
|
|
|
|
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 -- so they're a perfect case for using a small
|
|
template that is filled with details from the current object. (In the admin's
|
|
case, this is the ``submit_row`` tag.)
|
|
|
|
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 given ``Poll`` object, such as was
|
|
created in the tutorials_. 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, define the function that takes the argument and produces a dictionary of
|
|
data for the result. The important point here is we only need to return a
|
|
dictionary, not anything more complex. This will be used as a template context
|
|
for the template fragment. Example::
|
|
|
|
def show_results(poll):
|
|
choices = poll.choice_set.all()
|
|
return {'choices': choices}
|
|
|
|
Next, create the template used to render the tag's output. This template is a
|
|
fixed feature of the tag: the tag writer specifies it, not the template
|
|
designer. Following our example, the template is very simple::
|
|
|
|
<ul>
|
|
{% for choice in choices %}
|
|
<li> {{ choice }} </li>
|
|
{% endfor %}
|
|
</ul>
|
|
|
|
Now, 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 ``results.html`` in a directory that's searched by the template
|
|
loader, we'd register the tag like this::
|
|
|
|
# Here, register is a django.template.Library instance, as before
|
|
register.inclusion_tag('results.html')(show_results)
|
|
|
|
As always, Python 2.4 decorator syntax works as well, so we could have
|
|
written::
|
|
|
|
@register.inclusion_tag('results.html')
|
|
def show_results(poll):
|
|
...
|
|
|
|
...when first creating the function.
|
|
|
|
Sometimes, your inclusion tags might require a large number of arguments,
|
|
making it a pain for template authors to pass in all the arguments and remember
|
|
their order. 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::
|
|
|
|
# The first argument *must* be called "context" here.
|
|
def jump_link(context):
|
|
return {
|
|
'link': context['home_link'],
|
|
'title': context['home_title'],
|
|
}
|
|
# Register the custom tag as an inclusion tag with takes_context=True.
|
|
register.inclusion_tag('link.html', takes_context=True)(jump_link)
|
|
|
|
(Note that the first parameter to the function *must* be called ``context``.)
|
|
|
|
In that ``register.inclusion_tag()`` line, we specified ``takes_context=True``
|
|
and the name of the template. Here's what the template ``link.html`` might look
|
|
like::
|
|
|
|
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.
|
|
|
|
The ``takes_context`` parameter defaults to ``False``. When it's set to *True*,
|
|
the tag is passed the context object, as in this example. That's the only
|
|
difference between this case and the previous ``inclusion_tag`` example.
|
|
|
|
.. _tutorials: ../tutorial01/#creating-models
|
|
|
|
Setting a variable in the context
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The above example simply output a value. Generally, it's more flexible if your
|
|
template tags set template variables instead of outputting values. That way,
|
|
template authors can reuse 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. If all the template tag does is set a variable,
|
|
``render()`` should return the 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 ``Node``
|
|
class, like so::
|
|
|
|
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 ''
|
|
|
|
import re
|
|
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 not m:
|
|
raise template.TemplateSyntaxError, "%r tag had invalid arguments" % tag_name
|
|
format_string, var_name = m.groups()
|
|
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)
|
|
|
|
The difference here is that ``do_current_time()`` grabs the format string and
|
|
the variable name, passing both to ``CurrentTimeNode3``.
|
|
|
|
Parsing until another block tag
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Template tags can work in tandem. For instance, the standard ``{% comment %}``
|
|
tag hides everything until ``{% endcomment %}``. To create a template tag such
|
|
as 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.
|
|
|
|
In ``"nodelist = parser.parse(('endcomment',))"`` 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()``.
|
|
|
|
``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 %}``.
|
|
|
|
Usage::
|
|
|
|
{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}
|
|
|
|
As in the previous example, we'll use ``parser.parse()``. But this time, we
|
|
pass the resulting ``nodelist`` to the ``Node``::
|
|
|
|
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``.
|
|
|
|
.. _configuration:
|
|
|
|
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'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 the `settings file`_ documentation. 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.
|
|
|
|
.. _settings file: ../settings/#using-settings-without-the-django-settings-module-environment-variable
|
|
.. _settings documentation: ../settings/
|