TemplateResponse and SimpleTemplateResponse

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

class SimpleTemplateResponse

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.

SimpleTemplateResponse.``__init__(template, context=None, content_type=None, status=None, charset=None, using=None)

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 ), 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, is used.

  status

  The HTTP status code for the response.

  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 will be used.

  using

  用于加载模板的模板引擎的 :setting:`NAME ` 。

SimpleTemplateResponse.``resolve_context(context)

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

Override this method in order to customize the context.

SimpleTemplateResponse.``resolve_template(template)

Resolves the template instance to use for rendering. Accepts a backend-dependent template object (such as those returned by ), 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()

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

class TemplateResponse

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

TemplateResponse.``__init__(request, template, context=None, content_type=None, status=None, charset=None, using=None)

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

• request

  template

  A backend-dependent template object (such as those returned by ), the name of a template, or a list of template names.

  context

  A 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, 'text/html' 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

  用于加载模板的模板引擎的 :setting:NAME ` 。

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 method.
• 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:

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, you can do that. 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), 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, define a function that takes a single argument — response — and register that function with the template 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.

For example, the following view returns a with a template and a context containing a queryset: