Django2.0手册: and



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 objects¶

class SimpleTemplateResponse[source]

Attributes¶

SimpleTemplateResponse.template_name

The name of the template to be rendered. Accepts a backend-dependent
template object (such as those returned by
get_template()), the name of a template,
or a list of template names.

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

SimpleTemplateResponse.context_data

The context data to be used when rendering the template. It must be a
dict.

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.

Methods¶

SimpleTemplateResponse.__init__(template, context=None, content_type=None, status=None, charset=None, using=None)[source]

Instantiates a SimpleTemplateResponse
object with the given template, context, content type, HTTP status, and
charset.

template
A backend-dependent template object (such as those returned by
get_template()), the name of a template,
or a list of template names.
context
A dict of values to add to the template context. By default,
this is an empty dictionary.
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,
DEFAULT_CONTENT_TYPE is used.
status
The HTTP status code for the response.
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
DEFAULT_CHARSET setting will be used.
using
The NAME of a template engine to use for
loading the template.
SimpleTemplateResponse.resolve_context(context)[source]

Preprocesses context data that will be used for rendering a template.
Accepts a dict of context data. By default, returns the same
dict.

Override this method in order to customize the context.

SimpleTemplateResponse.resolve_template(template)[source]

Resolves the template instance to use for rendering. Accepts a
backend-dependent template object (such as those returned by
get_template()), the name of a template,
or a list of template names.

Returns the backend-dependent template object instance to be rendered.

Override this method in order to customize template loading.

SimpleTemplateResponse.add_post_render_callback()[source]

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()[source]

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 objects¶

class TemplateResponse[source]

TemplateResponse is a subclass of
SimpleTemplateResponse that knows about
the current HttpRequest.

Methods¶

TemplateResponse.__init__(request, template, context=None, content_type=None, status=None, charset=None, using=None)[source]

Instantiates a TemplateResponse object
with the given request, template, context, content type, HTTP status, and
charset.

request
An HttpRequest instance.
template
A backend-dependent template object (such as those returned by
get_template()), the name of a template,
or a list of template names.
context
A dict of values to add to the template context. By default,
this is an empty dictionary.
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,
DEFAULT_CONTENT_TYPE is used.
status
The HTTP status code for the response.
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
DEFAULT_CHARSET setting will be used.
using
The NAME of a template engine to use for
loading the template.

The rendering process¶

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:

  • When the TemplateResponse instance is explicitly rendered, using
    the 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
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, it’s 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:

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
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
django.http.HttpResponse can be used. It can also be used as an
alternative to calling render().

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