Standard 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
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
¶SimpleTemplateResponse.
template_name
¶The name of the template to be rendered. Accepts a
Template
object, a path to a template or list
of template paths.
Example: ['foo.html', 'path/to/bar.html']
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}
SimpleTemplateResponse.
rendered_content
¶The current rendered value of the response content, using the current template and context data.
SimpleTemplateResponse.
is_rendered
¶A boolean indicating whether the response content has been rendered.
SimpleTemplateResponse.
__init__
(template, context=None, mimetype=None, status=None, content_type=None)¶Instantiates a
SimpleTemplateResponse
object
with the given template, context, MIME type and HTTP status.
template
Template
instances can also be used.context
Context
objects
are also accepted as context
values.status
content_type
mimetype
. Historically, this parameter was only called
mimetype
, 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,
DEFAULT_CONTENT_TYPE
is used.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 Context
instance containing the provided data.
Override this method in order to customize context instantiation.
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.
Template
instances may also be provided.
Returns the Template
instance to be
rendered.
Override this method in order to customize template rendering.
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 SimpleTemplateResponse
has already been rendered, the callback will be invoked
immediately.
When called, callbacks will be passed a single argument – the
rendered 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.)
SimpleTemplateResponse.render():
Sets response.content
to the result obtained by
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
¶TemplateResponse is a subclass of
SimpleTemplateResponse
that uses
a RequestContext
instead of
a Context
.
TemplateResponse.
__init__
(request, template, context=None, mimetype=None, status=None, content_type=None, current_app=None)¶Instantiates an TemplateResponse
object with the given
template, context, MIME type and HTTP status.
request
HttpRequest
instance.template
Template
instances can also be used.context
Context
objects
are also accepted as context
values.status
content_type
mimetype
. Historically, this parameter was only called
mimetype
, 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,
DEFAULT_CONTENT_TYPE
is used.current_app
Before a 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:
SimpleTemplateResponse.render()
method.response.content
.A TemplateResponse can only be rendered once. The first call to
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
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),
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
TemplateResponse
instance as an argument.
If the template has already been rendered, the callback will be invoked immediately.
A TemplateResponse object can be used anywhere that a normal
HttpResponse can be used. It can also be used as an alternative to
calling render_to_response()
.
For example, the following simple view returns a
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()})
Nov 29, 2016