django/docs/ref/templates/api.txt

====================================================
The Django template language: For Python programmers
====================================================

.. currentmodule:: django.template

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:`/ref/templates/language`.

It assumes an understanding of templates, contexts, variables, tags, and
rendering. Start with the :ref:`introduction to the Django template language
<template-language-intro>` if you aren't familiar with these concepts.

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

Using the template system
=========================

.. class:: 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:: Template.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]``

Note that "bar" in a template expression like ``{{ foo.bar }}`` will be
interpreted as a literal string and not using the value of the variable "bar",
if one exists in the template context.

The template system uses the first lookup type that works. It's short-circuit
logic. Here are a few examples::

    >>> from django.template import Context, Template
    >>> t = Template("My name is {{ person.first_name }}.")
    >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
    >>> t.render(Context(d))
    "My name is Joe."

    >>> class PersonClass: pass
    >>> p = PersonClass()
    >>> p.first_name = "Ron"
    >>> p.last_name = "Nasty"
    >>> t.render(Context({"person": p}))
    "My name is Ron."

    >>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
    >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
    >>> t.render(c)
    "The first stooge in the list is Larry."

If any part of the variable is callable, the template system will try calling
it. Example::

    >>> class PersonClass2:
    ...     def name(self):
    ...         return "Samantha"
    >>> t = Template("My name is {{ person.name }}.")
    >>> t.render(Context({"person": PersonClass2}))
    "My name is Samantha."

Callable variables are slightly more complex than variables which only require
straight lookups. Here are some things to keep in mind:

* If the variable raises an exception when called, the exception will be
  propagated, unless the exception has an attribute
  ``silent_variable_failure`` whose value is ``True``. If the exception
  *does* have a ``silent_variable_failure`` attribute whose value is
  ``True``, the variable will render as the value of the
  ``string_if_invalid`` configuration option (an empty string, by default).
  Example::

    >>> t = Template("My name is {{ person.first_name }}.")
    >>> class PersonClass3:
    ...     def first_name(self):
    ...         raise AssertionError("foo")
    >>> p = PersonClass3()
    >>> t.render(Context({"person": p}))
    Traceback (most recent call last):
    ...
    AssertionError: foo

    >>> class SilentAssertionError(Exception):
    ...     silent_variable_failure = True
    >>> class PersonClass4:
    ...     def first_name(self):
    ...         raise SilentAssertionError
    >>> p = PersonClass4()
    >>> t.render(Context({"person": p}))
    "My name is ."

  Note that :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 the value of the ``string_if_invalid`` option.

.. _alters-data-description:

* 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
  ``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

* Occasionally you may want to turn off this feature for other reasons,
  and tell the template system to leave a variable uncalled no matter
  what.  To do so, set a ``do_not_call_in_templates`` attribute on the
  callable with the value ``True``.  The template system then will act as
  if your variable is not callable (allowing you to access attributes of
  the callable, for example).

.. _invalid-template-variables:

How invalid variables are handled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Generally, if a variable doesn't exist, the template system inserts the
value of the ``string_if_invalid`` configuration option, which is set to
``''`` (the empty string) by default.

Filters that are applied to an invalid variable will only be applied if
``string_if_invalid`` is set to ``''`` (the empty string). If
``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 ``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 ``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 ``string_if_invalid``, you will
    experience rendering problems with these templates and sites.

    Generally, ``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.

Limitations with string literals
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django's template language has no way to escape the characters used for its own
syntax. For example, the :ttag:`templatetag` tag is required if you need to
output character sequences like ``{%`` and ``%}``.

A similar issue exists if you want to include these sequences in template filter
or tag arguments. For example, when parsing a block tag, Django's template
parser looks for the first occurrence of ``%}`` after a ``{%``. This prevents
the use of ``"%}"`` as a string literal. For example, a ``TemplateSyntaxError``
will be raised for the following expressions::

  {% include "template.html" tvar="Some string literal with %} in it." %}

  {% with tvar="Some string literal with %} in it." %}{% endwith %}

The same issue can be triggered by using a reserved sequence in filter
arguments::

  {{ some.variable|default:"}}" }}

If you need to use strings with these sequences, store them in template
variables or use a custom template tag or filter to workaround the limitation.

Playing with Context objects
----------------------------

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

    >>> from django.template import Context
    >>> c = Context({"foo": "bar"})
    >>> c['foo']
    'bar'
    >>> del c['foo']
    >>> c['foo']
    ''
    >>> c['newvariable'] = 'hello'
    >>> c['newvariable']
    'hello'

.. method:: Context.pop()
.. method:: Context.push()
.. exception:: 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()
    {'foo': 'second level'}
    >>> c['foo']
    'first level'
    >>> c['foo'] = 'overwritten'
    >>> c['foo']
    'overwritten'
    >>> c.pop()
    Traceback (most recent call last):
    ...
    ContextPopException

.. versionadded:: 1.7

You can also use ``push()`` as a context manager to ensure a matching ``pop()``
is called.

    >>> c = Context()
    >>> c['foo'] = 'first level'
    >>> with c.push():
    >>>     c['foo'] = 'second level'
    >>>     c['foo']
    'second level'
    >>> c['foo']
    'first level'

All arguments passed to ``push()`` will be passed to the ``dict`` constructor
used to build the new context level.

    >>> c = Context()
    >>> c['foo'] = 'first level'
    >>> with c.push(foo='second level'):
    >>>     c['foo']
    'second level'
    >>> c['foo']
    'first level'

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

.. method:: Context.flatten()

.. versionadded:: 1.7

Using ``flatten()`` method you can get whole ``Context`` stack as one dictionary
including builtin variables.

    >>> c = Context()
    >>> c['foo'] = 'first level'
    >>> c.update({'bar': 'second level'})
    {'bar': 'second level'}
    >>> c.flatten()
    {'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}

A ``flatten()`` method is also internally used to make ``Context`` objects comparable.

    >>> c1 = Context()
    >>> c1['foo'] = 'first level'
    >>> c1['bar'] = 'second level'
    >>> c2 = Context()
    >>> c2.update({'bar': 'second level', 'foo': 'first level'})
    {'foo': 'first level', 'bar': 'second level'}
    >>> c1 == c2
    True

Result from ``flatten()`` can be useful in unit tests to compare ``Context``
against ``dict``::

    class ContextTest(unittest.TestCase):
        def test_against_dictionary(self):
            c1 = Context()
            c1['update'] = 'value'
            self.assertEqual(c1.flatten(), {
                'True': True, 'None': None, 'False': False,
                'update': 'value'})


.. _subclassing-context-requestcontext:

Subclassing Context: RequestContext
-----------------------------------

.. class:: 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 the ``'context_processors'`` option in the
:setting:`TEMPLATES` setting.

The ``'context_processors'`` option is a list 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. In the default generated
settings file, the default template engine contains the following context
processors::

    [
        'django.contrib.auth.context_processors.auth',
        'django.template.context_processors.debug',
        'django.template.context_processors.i18n',
        'django.template.context_processors.media',
        'django.template.context_processors.static',
        'django.template.context_processors.tz',
        'django.contrib.messages.context_processors.messages',
    ]

.. versionchanged:: 1.8

    Built-in template context processors were moved from
    ``django.core.context_processors`` to
    ``django.template.context_processors`` in Django 1.8.

In addition to these, ``RequestContext`` always uses
``django.template.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 in the ``'context_processors'`` option.

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

    Context processors are applied *after* the context itself is processed.
    This means that a context processor may overwrite variables you've
    supplied to your ``Context`` or ``RequestContext``, so take care
    to avoid variable names that overlap with those supplied by your
    context processors.

Also, you can give ``RequestContext`` a list of additional processors, using the
optional, third positional argument, ``processors``. In this example, the
``RequestContext`` instance gets a ``ip_address`` variable::

    from django.http import HttpResponse
    from django.template import RequestContext

    def ip_address_processor(request):
        return {'ip_address': request.META['REMOTE_ADDR']}

    def some_view(request):
        # ...
        c = RequestContext(request, {
            'foo': 'bar',
        }, [ip_address_processor])
        return HttpResponse(t.render(c))

.. note::

    If you're using Django's :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, use the :meth:`~django.shortcuts.render()` shortcut which is
    the same as a call to :func:`~django.shortcuts.render_to_response()` with a
    ``context_instance`` argument that forces the use of a ``RequestContext``.

.. _context-processors:

Context processors
------------------

Here's what each of the default processors does:

django.contrib.auth.context_processors.auth
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If this processor is enabled, every ``RequestContext`` will contain these
variables:

* ``user`` -- An ``auth.User`` instance representing the currently
  logged-in user (or an ``AnonymousUser`` instance, if the client isn't
  logged in).

* ``perms`` -- An instance of
  ``django.contrib.auth.context_processors.PermWrapper``, representing the
  permissions that the currently logged-in user has.

.. currentmodule:: django.template.context_processors

django.template.context_processors.debug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If this processor is enabled, 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 and lazily generated
  on access.

django.template.context_processors.i18n
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If this processor is enabled, 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.template.context_processors.media
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If this processor is enabled, every ``RequestContext`` will contain a variable
``MEDIA_URL``, providing the value of the :setting:`MEDIA_URL` setting.

django.template.context_processors.static
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. function:: static

If this processor is enabled, every ``RequestContext`` will contain a variable
``STATIC_URL``, providing the value of the :setting:`STATIC_URL` setting.

django.template.context_processors.csrf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This processor adds a token that is needed by the :ttag:`csrf_token` template
tag for protection against :doc:`Cross Site Request Forgeries
</ref/csrf>`.

django.template.context_processors.request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If this processor is enabled, 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 this processor is enabled, every ``RequestContext`` will contain these two
variables:

* ``messages`` -- A list of messages (as strings) that have been set
  via the :doc:`messages framework </ref/contrib/messages>`.
* ``DEFAULT_MESSAGE_LEVELS`` -- A mapping of the message level names to
  :ref:`their numeric value <message-level-constants>`.

.. versionchanged:: 1.7

       The ``DEFAULT_MESSAGE_LEVELS`` variable was added.

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 the
``'context_processors'`` option in your :setting:`TEMPLATES` 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:`DIRS
<TEMPLATES-DIRS>` option.

The DIRS option
~~~~~~~~~~~~~~~

.. versionchanged:: 1.8

    This value used to be defined by the ``TEMPLATE_DIRS`` setting.

Tell Django what your template directories are by using the :setting:`DIRS
<TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting in your settings
file. This should be set to a list of strings that contain full paths to your
template directory(ies). Example::

    TEMPLATES = [
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            '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.

.. _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 adding a ``'loaders'`` option to your ``DjangoTemplates`` backend in the
:setting:`TEMPLATES` setting. ``'loaders'`` should be a list of strings or
tuples, where each represents a template loader class. Here are the template
loaders that come with Django:

.. currentmodule:: django.template.loaders

``django.template.loaders.filesystem.Loader``

.. class:: filesystem.Loader

    Loads templates from the filesystem, according to
    :setting:`DIRS <TEMPLATES-DIRS>`.

    This loader is enabled by default. However it won't find any templates
    until you set :setting:`DIRS <TEMPLATES-DIRS>` to a non-empty list::

        TEMPLATES = [{
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [os.path.join(BASE_DIR, 'templates')],
        }]

``django.template.loaders.app_directories.Loader``

.. class:: 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 ``foo.html`` in these
    directories, in this order:

    * ``/path/to/myproject/polls/templates/``
    * ``/path/to/myproject/music/templates/``

    ... and will use the one it finds first.

    The order of :setting:`INSTALLED_APPS` is significant! For example, if you
    want to customize the Django admin, you might choose to override the
    standard ``admin/base_site.html`` template, from ``django.contrib.admin``,
    with your own ``admin/base_site.html`` in ``myproject.polls``. You must
    then make sure that your ``myproject.polls`` comes *before*
    ``django.contrib.admin`` in :setting:`INSTALLED_APPS`, otherwise
    ``django.contrib.admin``’s will be loaded first and yours will be ignored.

    Note that the loader performs an optimization when it first runs:
    it caches a list of which :setting:`INSTALLED_APPS` packages have a
    ``templates`` subdirectory.

    This loader is enabled if and only if :setting:`APP_DIRS
    <TEMPLATES-APP_DIRS>` is set::

        TEMPLATES = [{
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'APP_DIRS': True,
        }]


``django.template.loaders.eggs.Loader``

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

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

        TEMPLATES = [{
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [os.path.join(BASE_DIR, 'templates')],
            'OPTIONS': {
                '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.template.loaders.locmem.Loader``

.. versionadded:: 1.8

.. class:: locmem.Loader

    Loads templates from a Python dictionary. This is useful for testing.

    This loader takes a dictionary of templates as its first argument::

        TEMPLATES = [{
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'OPTIONS': {
                'loaders': [
                    ('django.template.loaders.locmem.Loader', {
                        'index.html': 'content here',
                    }),
                ],
            },
        }]

    This loader is disabled by default.

Django uses the template loaders in order according to the ``'loaders'``
option. It uses each loader until a loader finds a match.

.. _custom-template-loaders:

Custom loaders
~~~~~~~~~~~~~~

Custom ``Loader`` classes should inherit from
``django.template.loaders.base.Loader`` 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)``.

.. versionchanged:: 1.8

    ``django.template.loaders.base.Loader`` used to be defined at
    ``django.template.loader.BaseLoader``.

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

.. currentmodule:: django.template

Template origin
~~~~~~~~~~~~~~~

.. versionadded:: 1.7

When :setting:`TEMPLATE_DEBUG` is ``True`` template objects will have an
``origin`` attribute depending on the source they are loaded from.

.. class:: loader.LoaderOrigin

    Templates created from a template loader will use the
    ``django.template.loader.LoaderOrigin`` class.

    .. attribute:: name

        The path to the template as returned by the template loader.
        For loaders that read from the file system, this is the full
        path to the template.

    .. attribute:: loadname

        The relative path to the template as passed into the
        template loader.

.. class:: StringOrigin

    Templates created from a ``Template`` class will use the
    ``django.template.StringOrigin`` class.

    .. attribute:: source

        The string used to create the template.

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:`DIRS <TEMPLATES-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`. If you plan to use the :ttag:`url` template tag,
you will also need to set the :setting:`ROOT_URLCONF` setting. All available
settings are described in the :doc:`settings documentation </ref/settings>`,
and any setting starting with ``TEMPLATE_`` is of obvious interest.