mirror of
https://github.com/django/django.git
synced 2024-12-25 10:35:48 +00:00
861 lines
34 KiB
Plaintext
861 lines
34 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 :doc:`/topics/templates`.
|
|
|
|
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.
|
|
|
|
.. _configuration: `configuring the template system in standalone mode`_
|
|
|
|
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:
|
|
|
|
.. code-block:: html+django
|
|
|
|
{% 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:
|
|
|
|
.. code-block:: html+django
|
|
|
|
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
|
|
=========================
|
|
|
|
.. class:: django.template.Template
|
|
|
|
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 :class:`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
|
|
-------------------
|
|
|
|
.. method:: render(context)
|
|
|
|
Once you have a compiled ``Template`` object, you can render a context -- or
|
|
multiple contexts -- with it. The ``Context`` class lives at
|
|
:class:`django.template.Context`, and the constructor takes two (optional)
|
|
arguments:
|
|
|
|
* A dictionary mapping variable names to variable values.
|
|
|
|
* The name of the current application. This application name is used
|
|
to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`.
|
|
If you're not using namespaced URLs, you can ignore this argument.
|
|
|
|
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."
|
|
|
|
Variables and lookups
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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:
|
|
|
|
* Dictionary lookup. Example: ``foo["bar"]``
|
|
* Attribute lookup. 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."
|
|
|
|
>>> 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."
|
|
|
|
.. versionchanged:: 1.3
|
|
Previously, only variables that originated with an attribute lookup would
|
|
be called by the template system. This change was made for consistency
|
|
across lookup types.
|
|
|
|
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 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 :exc:`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 an empty string.
|
|
|
|
* 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 :meth:`~django.db.models.Model.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
|
|
:setting:`TEMPLATE_STRING_IF_INVALID`, unconditionally. The
|
|
dynamically-generated :meth:`~django.db.models.Model.delete` and
|
|
:meth:`~django.db.models.Model.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
|
|
|
|
* .. versionadded:: 1.4
|
|
Occasionally you may want to turn off this feature for other reasons,
|
|
and tell the template system to leave a variable un-called 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).
|
|
|
|
.. _invalid-template-variables:
|
|
|
|
How invalid variables are handled
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Generally, if a variable doesn't exist, the template system inserts the
|
|
value of the :setting:`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
|
|
:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If
|
|
:setting:`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 :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will
|
|
be replaced with the name of the invalid variable.
|
|
|
|
.. admonition:: For debug purposes only!
|
|
|
|
While :setting:`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
|
|
:setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering
|
|
problems with these templates and sites.
|
|
|
|
Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled
|
|
in order to debug a specific template problem, then cleared
|
|
once debugging is complete.
|
|
|
|
Builtin variables
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Every context contains ``True``, ``False`` and ``None``. As you would expect,
|
|
these variables resolve to the corresponding Python objects.
|
|
|
|
.. versionadded:: 1.5
|
|
Before Django 1.5, these variables weren't a special case, and they
|
|
resolved to ``None`` unless you defined them in the context.
|
|
|
|
Playing with Context objects
|
|
----------------------------
|
|
|
|
.. class:: django.template.Context
|
|
|
|
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'
|
|
|
|
.. method:: pop()
|
|
.. method:: push()
|
|
.. exception:: django.template.ContextPopException
|
|
|
|
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
|
|
|
|
.. method:: update(other_dict)
|
|
|
|
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.
|
|
|
|
.. _subclassing-context-requestcontext:
|
|
|
|
Subclassing Context: RequestContext
|
|
-----------------------------------
|
|
|
|
.. class:: django.template.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 it takes an
|
|
:class:`~django.http.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 :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
|
|
|
|
The :setting:`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,
|
|
:setting:`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.contrib.messages.context_processors.messages")
|
|
|
|
.. versionadded:: 1.2
|
|
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 :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
|
|
|
|
.. versionadded:: 1.2
|
|
The ``'messages'`` context processor was added. For more information, see
|
|
the :doc:`messages documentation </ref/contrib/messages>`.
|
|
|
|
.. versionchanged:: 1.2
|
|
The auth context processor was moved in this release from its old location
|
|
``django.core.context_processors.auth`` to
|
|
``django.contrib.auth.context_processors.auth``.
|
|
|
|
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.
|
|
|
|
.. admonition:: When context processors are applied
|
|
|
|
When you use ``RequestContext``, the variables you supply directly
|
|
are added first, followed any variables supplied by context
|
|
processors. This means that a context processor may overwrite a
|
|
variable you've supplied, so take care to avoid variable names
|
|
which 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::
|
|
|
|
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 :func:`~django.shortcuts.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
|
|
:func:`~django.shortcuts.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:
|
|
|
|
django.contrib.auth.context_processors.auth
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If :setting:`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).
|
|
|
|
* ``perms`` -- An instance of
|
|
``django.contrib.auth.context_processors.PermWrapper``, representing the
|
|
permissions that the currently logged-in user has.
|
|
|
|
.. versionchanged:: 1.2
|
|
This context processor was moved in this release from
|
|
``django.core.context_processors.auth`` to its current location.
|
|
|
|
.. versionchanged:: 1.3
|
|
Prior to version 1.3, ``PermWrapper`` was located in
|
|
``django.contrib.auth.context_processors``.
|
|
|
|
|
|
django.core.context_processors.debug
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
|
|
``RequestContext`` will contain these two variables -- but only if your
|
|
:setting:`DEBUG` setting is set to ``True`` and the request's IP address
|
|
(``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting:
|
|
|
|
* ``debug`` -- ``True``. You can use this in templates to test whether
|
|
you're in :setting:`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 :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
|
|
``RequestContext`` will contain these two variables:
|
|
|
|
* ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting.
|
|
* ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise,
|
|
the value of the :setting:`LANGUAGE_CODE` setting.
|
|
|
|
See :doc:`/topics/i18n/index` for more.
|
|
|
|
django.core.context_processors.media
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
|
|
``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
|
|
value of the :setting:`MEDIA_URL` setting.
|
|
|
|
django.core.context_processors.static
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. function:: django.core.context_processors.static
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
|
|
``RequestContext`` will contain a variable ``STATIC_URL``, providing the
|
|
value of the :setting:`STATIC_URL` setting.
|
|
|
|
django.core.context_processors.csrf
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. versionadded:: 1.2
|
|
|
|
This processor adds a token that is needed by the :ttag:`csrf_token` template
|
|
tag for protection against :doc:`Cross Site Request Forgeries
|
|
</ref/contrib/csrf>`.
|
|
|
|
django.core.context_processors.request
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
|
|
``RequestContext`` will contain a variable ``request``, which is the current
|
|
:class:`~django.http.HttpRequest`. Note that this processor is not enabled by default;
|
|
you'll have to activate it.
|
|
|
|
django.contrib.messages.context_processors.messages
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
|
|
``RequestContext`` will contain a single additional variable:
|
|
|
|
* ``messages`` -- A list of messages (as strings) that have been set
|
|
via the user model (using ``user.message_set.create``) or through
|
|
the :doc:`messages framework </ref/contrib/messages>`.
|
|
|
|
.. versionadded:: 1.2
|
|
This template context variable was previously supplied by the ``'auth'``
|
|
context processor. For backwards compatibility the ``'auth'`` context
|
|
processor will continue to supply the ``messages`` variable until Django
|
|
1.4. If you use the ``messages`` variable, your project will work with
|
|
either (or both) context processors, but it is recommended to add
|
|
``django.contrib.messages.context_processors.messages`` so your project
|
|
will be prepared for the future upgrade.
|
|
|
|
Writing your own context processors
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A context processor has a very simple interface: It's just a Python function
|
|
that takes one argument, an :class:`~django.http.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
|
|
:setting:`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 :setting:`TEMPLATE_DIRS`
|
|
setting.
|
|
|
|
The TEMPLATE_DIRS setting
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Tell Django what your template directories are by using the
|
|
:setting:`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.
|
|
|
|
.. _ref-templates-api-the-python-api:
|
|
|
|
The Python API
|
|
~~~~~~~~~~~~~~
|
|
|
|
Django has two ways to load templates from files:
|
|
|
|
.. function:: 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``.
|
|
|
|
.. function:: 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 :setting:`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 :setting:`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``
|
|
|
|
.. _template-loaders:
|
|
|
|
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.
|
|
|
|
Some of these other loaders are disabled by default, but you can activate them
|
|
by editing your :setting:`TEMPLATE_LOADERS` setting. :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:
|
|
|
|
.. versionchanged:: 1.2
|
|
Template loaders were based on callables (usually functions) before Django
|
|
1.2, starting with the 1.2 release there is a new class-based API, all the
|
|
loaders described below implement this new API.
|
|
|
|
``django.template.loaders.filesystem.Loader``
|
|
Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
|
|
This loader is enabled by default.
|
|
|
|
``django.template.loaders.app_directories.Loader``
|
|
Loads templates from Django apps on the filesystem. For each app in
|
|
:setting:`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 :setting:`INSTALLED_APPS` packages have a
|
|
``templates`` subdirectory.
|
|
|
|
This loader is enabled by default.
|
|
|
|
``django.template.loaders.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``
|
|
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 :ref:`template tag thread safety
|
|
considerations<template_tag_thread_safety>`.
|
|
|
|
This loader is disabled by default.
|
|
|
|
Django uses the template loaders in order according to the
|
|
:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
|
|
match.
|
|
|
|
The ``render_to_string`` shortcut
|
|
===================================
|
|
|
|
.. function:: django.template.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
|
|
:mod:`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:
|
|
|
|
dictionary
|
|
A dictionary to be used as variables and values for the
|
|
template's context. This can also be passed as the second
|
|
positional argument.
|
|
|
|
context_instance
|
|
An instance of ``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 :func:`~django.shortcuts.render_to_response()` shortcut, which
|
|
calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
|
|
suitable for returning directly from a view.
|
|
|
|
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 :envvar:`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 :ref:`settings-without-django-settings-module`. Simply import the appropriate
|
|
pieces of the templating system and then, *before* you call any of the
|
|
templating functions, call :func:`django.conf.settings.configure()` with any
|
|
settings you wish to specify. You might want to consider setting at least
|
|
:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
|
|
:setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
|
|
and :setting:`TEMPLATE_DEBUG`. All available settings are described in the
|
|
:doc:`settings documentation </ref/settings>`, and any setting starting with
|
|
``TEMPLATE_`` is of obvious interest.
|
|
|
|
.. _topic-template-alternate-language:
|
|
|
|
Using an alternative template language
|
|
======================================
|
|
|
|
.. versionadded:: 1.2
|
|
|
|
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
|
|
<http://jinja.pocoo.org/2/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
|
|
allows us to use third-party template libraries without giving up useful Django
|
|
features like the Django ``Context`` object and handy shortcuts like
|
|
:func:`~django.shortcuts.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 :class:`~django.template.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 :class:`~django.template.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 :class:`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.
|