mirror of
https://github.com/django/django.git
synced 2025-11-03 21:25:09 +00:00
5f2542f12a
Thanks to Simon Charette, Aymeric Augustin, and Tim Graham for reviews and contributions.
301 lines
11 KiB
Text
301 lines
11 KiB
Text
===========================================
|
|
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, charset=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``
|
|
The value included in the HTTP ``Content-Type`` header, including the
|
|
MIME type specification and the character set encoding. If
|
|
``content_type`` is specified, then its value is used. Otherwise,
|
|
:setting:`DEFAULT_CONTENT_TYPE` is used.
|
|
|
|
``charset``
|
|
The charset in which the response will be encoded. If not given it will
|
|
be extracted from ``content_type``, and if that is unsuccessful, the
|
|
:setting:`DEFAULT_CHARSET` setting will be used.
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
The ``charset`` parameter was added.
|
|
|
|
.. 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, charset=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``
|
|
The value included in the HTTP ``Content-Type`` header, including the
|
|
MIME type specification and the character set encoding. If
|
|
``content_type`` is specified, then its value is used. Otherwise,
|
|
: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.
|
|
|
|
``charset``
|
|
The charset in which the response will be encoded. If not given it will
|
|
be extracted from ``content_type``, and if that is unsuccessful, the
|
|
:setting:`DEFAULT_CHARSET` setting will be used.
|
|
|
|
.. versionadded:: 1.8
|
|
|
|
The ``charset`` parameter was added.
|
|
|
|
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
|
|
>>> from django.template.response import 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::
|
|
|
|
from django.template.response import TemplateResponse
|
|
|
|
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()})
|