[1.2.X] Fixed #11152 - Add some classes to the template docs. Thanks adamv for the patch.

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.

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

The easiest way to create a ``Template`` object is by instantiating it

directly. The class lives at ``django.template.Template``. The constructor

directly. The class lives at :class:`django.template.Template`. The constructor

takes one argument -- the raw template code::

    >>> from django.template import Template

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

``django.template.Context``, and the constructor takes two (optional)

:class:`django.template.Context`, and the constructor takes two (optional)

arguments:

    * A dictionary mapping variable names to variable values.

        >>> t.render(Context({"person": p}))

        "My name is ."

      Note that ``django.core.exceptions.ObjectDoesNotExist``, which is the

      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

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

      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 ``delete()`` and

      ``save()`` methods on Django model objects get ``alters_data=True``

      automatically. Example::

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

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

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

    ...

    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.

.. versionadded:: 1.2

   In addition to these, ``RequestContext`` always uses

   ``'django.core.context_processors.csrf'``.  This is a security

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

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

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.

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_LOADERS` setting. It uses each loader until a loader finds a

match.

The ``render_to_string()`` shortcut

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

``django.template.loader``, which loads a template, renders it and

:mod:`django.template.loader`, which loads a template, renders it and

returns the resulting string::

    from django.template.loader import render_to_string

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

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

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 ``django.conf.settings.configure()`` with any

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)

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 ``django.template.context.Context`` object and returns a string

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

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 ``django.template.Template``. Custom ``Loader``

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:

the template source, and returns a tuple: ``(template, template_origin)``. Since

this is the method that actually instantiates the ``Template``, we'll need to

override it to use our custom template class instead. We can inherit from the

builtin ``django.template.loaders.app_directories.Loader`` to take advantage of

the ``load_template_source()`` method implemented there::

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