====================================================

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."

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 :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 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 :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 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

      :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

.. _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.

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

-----------------------------------

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.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 ``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:

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).

    * ``messages`` -- A list of messages (as strings) that have been set

      via the :doc:`messages framework </ref/contrib/messages>`.

    * ``perms`` -- An instance of

      ``django.core.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.2

   Prior to version 1.2, the ``messages`` variable was a lazy accessor for

   ``user.get_and_delete_messages()``. It has been changed to include any

   messages added via the :doc:`messages framework </ref/contrib/messages>`.

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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.0

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.csrf

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.2

This processor adds a token that is needed by the ``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