lib/django-1.5/docs/ref/template-response.txt

===========================================
TemplateResponse and SimpleTemplateResponse
===========================================

.. module:: django.template.response
   :synopsis: Classes dealing with lazy-rendered HTTP responses.

Standard :class:`~django.http.HttpResponse` objects are static structures.
They are provided with a block of pre-rendered content at time of
construction, and while that content can be modified, it isn't in a form that
makes it easy to perform modifications.

However, it can sometimes be beneficial to allow decorators or
middleware to modify a response *after* it has been constructed by the
view. For example, you may want to change the template that is used,
or put additional data into the context.

TemplateResponse provides a way to do just that. Unlike basic
:class:`~django.http.HttpResponse` objects, TemplateResponse objects retain
the details of the template and context that was provided by the view to
compute the response. The final output of the response is not computed until
it is needed, later in the response process.

SimpleTemplateResponse objects
==============================

.. class:: SimpleTemplateResponse()

Attributes
----------

.. attribute:: SimpleTemplateResponse.template_name

    The name of the template to be rendered. Accepts a
    :class:`~django.template.Template` object, a path to a template or list
    of template paths.

    Example: ``['foo.html', 'path/to/bar.html']``

.. attribute:: SimpleTemplateResponse.context_data

    The context data to be used when rendering the template. It can be
    a dictionary or a context object.

    Example: ``{'foo': 123}``

.. attribute:: SimpleTemplateResponse.rendered_content

    The current rendered value of the response content, using the current
    template and context data.

.. attribute:: SimpleTemplateResponse.is_rendered

    A boolean indicating whether the response content has been rendered.

Methods
-------

.. method:: SimpleTemplateResponse.__init__(template, context=None, content_type=None, status=None)

    Instantiates a
    :class:`~django.template.response.SimpleTemplateResponse` object
    with the given template, context, content type, and HTTP status.

    ``template``
        The full name of a template, or a sequence of template names.
        :class:`~django.template.Template` instances can also be used.

    ``context``
        A dictionary of values to add to the template context. By default,
        this is an empty dictionary. :class:`~django.template.Context` objects
        are also accepted as ``context`` values.

    ``status``
        The HTTP Status code for the response.

    ``content_type``

        .. versionchanged:: 1.5

        Historically, this parameter was only called ``mimetype`` (now
        deprecated), but since this is actually the value included in the HTTP
        ``Content-Type`` header, it can also include the character set
        encoding, which makes it more than just a MIME type specification. If
        ``mimetype`` is specified (not ``None``), that value is used.
        Otherwise, ``content_type`` is used. If neither is given,
        :setting:`DEFAULT_CONTENT_TYPE` is used.


.. method:: SimpleTemplateResponse.resolve_context(context)

    Converts context data into a context instance that can be used for
    rendering a template. Accepts a dictionary of context data or a
    context object. Returns a :class:`~django.template.Context`
    instance containing the provided data.

    Override this method in order to customize context instantiation.

.. method:: SimpleTemplateResponse.resolve_template(template)

    Resolves the template instance to use for rendering. Accepts a
    path of a template to use, or a sequence of template paths.
    :class:`~django.template.Template` instances may also be provided.
    Returns the :class:`~django.template.Template` instance to be
    rendered.

    Override this method in order to customize template rendering.

.. method:: SimpleTemplateResponse.add_post_render_callback()

    Add a callback that will be invoked after rendering has taken
    place. This hook can be used to defer certain processing
    operations (such as caching) until after rendering has occurred.

    If the :class:`~django.template.response.SimpleTemplateResponse`
    has already been rendered, the callback will be invoked
    immediately.

    When called, callbacks will be passed a single argument -- the
    rendered :class:`~django.template.response.SimpleTemplateResponse`
    instance.

    If the callback returns a value that is not ``None``, this will be
    used as the response instead of the original response object (and
    will be passed to the next post rendering callback etc.)

.. method:: SimpleTemplateResponse.render()

    Sets ``response.content`` to the result obtained by
    :attr:`SimpleTemplateResponse.rendered_content`, runs all post-rendering
    callbacks, and returns the resulting response object.

    ``render()`` will only have an effect the first time it is called. On
    subsequent calls, it will return the result obtained from the first call.


TemplateResponse objects
========================

.. class:: TemplateResponse()

    ``TemplateResponse`` is a subclass of
    :class:`~django.template.response.SimpleTemplateResponse` that uses
    a :class:`~django.template.RequestContext` instead of
    a :class:`~django.template.Context`.

Methods
-------

.. method:: TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, current_app=None)

    Instantiates an ``TemplateResponse`` object with the given
    template, context, MIME type and HTTP status.

    ``request``
        An :class:`~django.http.HttpRequest` instance.

    ``template``
        The full name of a template, or a sequence of template names.
        :class:`~django.template.Template` instances can also be used.

    ``context``
        A dictionary of values to add to the template context. By default,
        this is an empty dictionary. :class:`~django.template.Context` objects
        are also accepted as ``context`` values. If you pass a
        :class:`~django.template.Context` instance or subclass, it will be used
        instead of creating a new :class:`~django.template.RequestContext`.

    ``status``
        The HTTP Status code for the response.

    ``content_type``

        .. versionchanged:: 1.5

        Historically, this parameter was only called ``mimetype`` (now
        deprecated), but since this is actually the value included in the HTTP
        ``Content-Type`` header, it can also include the character set
        encoding, which makes it more than just a MIME type specification. If
        ``mimetype`` is specified (not ``None``), that value is used.
        Otherwise, ``content_type`` is used. If neither is given,
        :setting:`DEFAULT_CONTENT_TYPE` is used.

    ``current_app``
        A hint indicating which application contains the current view. See the
        :ref:`namespaced URL resolution strategy <topics-http-reversing-url-namespaces>`
        for more information.


The rendering process
=====================

Before a :class:`~django.template.response.TemplateResponse` instance can be
returned to the client, it must be rendered. The rendering process takes the
intermediate representation of template and context, and turns it into the
final byte stream that can be served to the client.

There are three circumstances under which a ``TemplateResponse`` will be
rendered:

* When the ``TemplateResponse`` instance is explicitly rendered, using
  the :meth:`SimpleTemplateResponse.render()` method.

* When the content of the response is explicitly set by assigning
  ``response.content``.

* After passing through template response middleware, but before
  passing through response middleware.

A ``TemplateResponse`` can only be rendered once. The first call to
:meth:`SimpleTemplateResponse.render` sets the content of the response;
subsequent rendering calls do not change the response content.

However, when ``response.content`` is explicitly assigned, the
change is always applied. If you want to force the content to be
re-rendered, you can re-evaluate the rendered content, and assign
the content of the response manually::

    # Set up a rendered TemplateResponse
    >>> t = TemplateResponse(request, 'original.html', {})
    >>> t.render()
    >>> print(t.content)
    Original content

    # Re-rendering doesn't change content
    >>> t.template_name = 'new.html'
    >>> t.render()
    >>> print(t.content)
    Original content

    # Assigning content does change, no render() call required
    >>> t.content = t.rendered_content
    >>> print(t.content)
    New content

Post-render callbacks
---------------------

Some operations -- such as caching -- cannot be performed on an
unrendered template. They must be performed on a fully complete and
rendered response.

If you're using middleware, the solution is easy. Middleware provides
multiple opportunities to process a response on exit from a view. If
you put behavior in the Response middleware is guaranteed to execute
after template rendering has taken place.

However, if you're using a decorator, the same opportunities do not
exist. Any behavior defined in a decorator is handled immediately.

To compensate for this (and any other analogous use cases),
:class:`TemplateResponse` allows you to register callbacks that will
be invoked when rendering has completed. Using this callback, you can
defer critical processing until a point where you can guarantee that
rendered content will be available.

To define a post-render callback, just define a function that takes
a single argument -- response -- and register that function with
the template response::

    def my_render_callback(response):
        # Do content-sensitive processing
        do_post_processing()

    def my_view(request):
        # Create a response
        response = TemplateResponse(request, 'mytemplate.html', {})
        # Register the callback
        response.add_post_render_callback(my_render_callback)
        # Return the response
        return response

``my_render_callback()`` will be invoked after the ``mytemplate.html``
has been rendered, and will be provided the fully rendered
:class:`TemplateResponse` instance as an argument.

If the template has already been rendered, the callback will be
invoked immediately.

Using TemplateResponse and SimpleTemplateResponse
=================================================

A TemplateResponse object can be used anywhere that a normal
HttpResponse can be used. It can also be used as an alternative to
calling :func:`~django.shortcuts.render_to_response()`.

For example, the following simple view returns a
:class:`TemplateResponse()` with a simple template, and a context
containing a queryset::

    from django.template.response import TemplateResponse

    def blog_index(request):
        return TemplateResponse(request, 'entry_list.html', {'entries': Entry.objects.all()})