TemplateResponse and SimpleTemplateResponseLink to this heading#Standard HttpResponse objects are static structures.\nThey are provided with a block of pre-rendered content at time of\nconstruction, and while that content can be modified, it isn’t in a form that\nmakes it easy to perform modifications.
However, it can sometimes be beneficial to allow decorators or\nmiddleware to modify a response after it has been constructed by the\nview. For example, you may want to change the template that is used,\nor put additional data into the context.
\nTemplateResponse provides a way to do just that. Unlike basic\nHttpResponse objects, TemplateResponse objects retain\nthe details of the template and context that was provided by the view to\ncompute the response. The final output of the response is not computed until\nit is needed, later in the response process.
SimpleTemplateResponse objectsLink to this heading#The name of the template to be rendered. Accepts a backend-dependent\ntemplate object (such as those returned by\nget_template()), the name of a template,\nor a list of template names.
Example: ['foo.html', 'path/to/bar.html']
The context data to be used when rendering the template. It must be a\ndict.
Example: {'foo': 123}
The current rendered value of the response content, using the current\ntemplate and context data.
\nA boolean indicating whether the response content has been rendered.
\nInstantiates a SimpleTemplateResponse\nobject with the given template, context, content type, HTTP status, and\ncharset.
templateA backend-dependent template object (such as those returned by\nget_template()), the name of a template,\nor a list of template names.
contextA dict of values to add to the template context. By default,\nthis is an empty dictionary.
content_typeThe value included in the HTTP Content-Type header, including the\nMIME type specification and the character set encoding. If\ncontent_type is specified, then its value is used. Otherwise,\n'text/html' is used.
statusThe HTTP status code for the response.
\ncharsetThe charset in which the response will be encoded. If not given it will\nbe extracted from content_type, and if that is unsuccessful, the\nDEFAULT_CHARSET setting will be used.
usingThe NAME of a template engine to use for\nloading the template.
headersA dict of HTTP headers to add to the response.
Preprocesses context data that will be used for rendering a template.\nAccepts a dict of context data. By default, returns the same\ndict.
Override this method in order to customize the context.
\nResolves the template instance to use for rendering. Accepts a\nbackend-dependent template object (such as those returned by\nget_template()), the name of a template,\nor a list of template names.
Returns the backend-dependent template object instance to be rendered.
\nOverride this method in order to customize template loading.
\nAdd a callback that will be invoked after rendering has taken\nplace. This hook can be used to defer certain processing\noperations (such as caching) until after rendering has occurred.
\nIf the SimpleTemplateResponse\nhas already been rendered, the callback will be invoked\nimmediately.
When called, callbacks will be passed a single argument – the\nrendered SimpleTemplateResponse\ninstance.
If the callback returns a value that is not None, this will be\nused as the response instead of the original response object (and\nwill be passed to the next post rendering callback etc.)
Sets response.content to the result obtained by\nSimpleTemplateResponse.rendered_content, runs all post-rendering\ncallbacks, and returns the resulting response object.
render() will only have an effect the first time it is called. On\nsubsequent calls, it will return the result obtained from the first call.
TemplateResponse objectsLink to this heading#TemplateResponse is a subclass of\nSimpleTemplateResponse that knows about\nthe current HttpRequest.
Instantiates a TemplateResponse object\nwith the given request, template, context, content type, HTTP status, and\ncharset.
requestAn HttpRequest instance.
templateA backend-dependent template object (such as those returned by\nget_template()), the name of a template,\nor a list of template names.
contextA dict of values to add to the template context. By default,\nthis is an empty dictionary.
content_typeThe value included in the HTTP Content-Type header, including the\nMIME type specification and the character set encoding. If\ncontent_type is specified, then its value is used. Otherwise,\n'text/html' is used.
statusThe HTTP status code for the response.
\ncharsetThe charset in which the response will be encoded. If not given it will\nbe extracted from content_type, and if that is unsuccessful, the\nDEFAULT_CHARSET setting will be used.
usingThe NAME of a template engine to use for\nloading the template.
headersA dict of HTTP headers to add to the response.
Before a TemplateResponse instance can be\nreturned to the client, it must be rendered. The rendering process takes the\nintermediate representation of template and context, and turns it into the\nfinal byte stream that can be served to the client.
There are three circumstances under which a TemplateResponse will be\nrendered:
When the TemplateResponse instance is explicitly rendered, using\nthe SimpleTemplateResponse.render() method.
When the content of the response is explicitly set by assigning\nresponse.content.
After passing through template response middleware, but before\npassing through response middleware.
A TemplateResponse can only be rendered once. The first call to\nSimpleTemplateResponse.render() sets the content of the response;\nsubsequent rendering calls do not change the response content.
However, when response.content is explicitly assigned, the\nchange is always applied. If you want to force the content to be\nre-rendered, you can re-evaluate the rendered content, and assign\nthe content of the response manually:
# Set up a rendered TemplateResponse\n>>> from django.template.response import TemplateResponse\n>>> t = TemplateResponse(request, 'original.html', {})\n>>> t.render()\n>>> print(t.content)\nOriginal content\n\n# Re-rendering doesn't change content\n>>> t.template_name = 'new.html'\n>>> t.render()\n>>> print(t.content)\nOriginal content\n\n# Assigning content does change, no render() call required\n>>> t.content = t.rendered_content\n>>> print(t.content)\nNew content\nSome operations – such as caching – cannot be performed on an\nunrendered template. They must be performed on a fully complete and\nrendered response.
\nIf you’re using middleware, you can do that. Middleware provides\nmultiple opportunities to process a response on exit from a view. If\nyou put behavior in the response middleware, it’s guaranteed to execute\nafter template rendering has taken place.
\nHowever, if you’re using a decorator, the same opportunities do not\nexist. Any behavior defined in a decorator is handled immediately.
\nTo compensate for this (and any other analogous use cases),\nTemplateResponse allows you to register callbacks that will\nbe invoked when rendering has completed. Using this callback, you can\ndefer critical processing until a point where you can guarantee that\nrendered content will be available.
To define a post-render callback, define a function that takes\na single argument – response – and register that function with\nthe template response:
\nfrom django.template.response import TemplateResponse\n\ndef my_render_callback(response):\n # Do content-sensitive processing\n do_post_processing()\n\ndef my_view(request):\n # Create a response\n response = TemplateResponse(request, 'mytemplate.html', {})\n # Register the callback\n response.add_post_render_callback(my_render_callback)\n # Return the response\n return response\nmy_render_callback() will be invoked after the mytemplate.html\nhas been rendered, and will be provided the fully rendered\nTemplateResponse instance as an argument.
If the template has already been rendered, the callback will be\ninvoked immediately.
\nTemplateResponse and SimpleTemplateResponseLink to this heading#A TemplateResponse object can be used anywhere that a normal\ndjango.http.HttpResponse can be used. It can also be used as an\nalternative to calling render().
For example, the following view returns a TemplateResponse with a\ntemplate and a context containing a queryset:
from django.template.response import TemplateResponse\n\ndef blog_index(request):\n return TemplateResponse(request, 'entry_list.html', {'entries': Entry.objects.all()})\n