TemplateResponse and SimpleTemplateResponse

Standard HttpResponse objects are static structures.They are provided with a block of pre-rendered content at time ofconstruction, and while that content can be modified, it isn’t in a form thatmakes it easy to perform modifications.

However, it can sometimes be beneficial to allow decorators ormiddleware to modify a response after it has been constructed by theview. 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 basicHttpResponse objects, TemplateResponse objects retainthe details of the template and context that was provided by the view tocompute the response. The final output of the response is not computed untilit is needed, later in the response process.

SimpleTemplateResponse objects

• class SimpleTemplateResponse

Attributes

• SimpleTemplateResponse.template_name
• The name of the template to be rendered. Accepts a backend-dependenttemplate object (such as those returned byget_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 adict.

Example: {'foo': 123}

• SimpleTemplateResponse.rendered_content

• The current rendered value of the response content, using the currenttemplate 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)

• Instantiates a SimpleTemplateResponseobject with the given template, context, content type, HTTP status, andcharset.

  • template
  • A backend-dependent template object (such as those returned byget_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 theMIME type specification and the character set encoding. Ifcontent_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 willbe extracted from content_type, and if that is unsuccessful, theDEFAULT_CHARSET setting will be used.
  • using
  • The NAME of a template engine to use forloading the template.
• SimpleTemplateResponse.resolvecontext(_context)
• Preprocesses context data that will be used for rendering a template.Accepts a dict of context data. By default, returns the samedict.

Override this method in order to customize the context.

• SimpleTemplateResponse.resolvetemplate(_template)
• Resolves the template instance to use for rendering. Accepts abackend-dependent template object (such as those returned byget_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()
• Add a callback that will be invoked after rendering has takenplace. This hook can be used to defer certain processingoperations (such as caching) until after rendering has occurred.

If the SimpleTemplateResponsehas already been rendered, the callback will be invokedimmediately.

When called, callbacks will be passed a single argument – therendered SimpleTemplateResponseinstance.

If the callback returns a value that is not None, this will beused as the response instead of the original response object (andwill be passed to the next post rendering callback etc.)

• SimpleTemplateResponse.render()
• Sets response.content to the result obtained bySimpleTemplateResponse.rendered_content, runs all post-renderingcallbacks, and returns the resulting response object.

render() will only have an effect the first time it is called. Onsubsequent calls, it will return the result obtained from the first call.

TemplateResponse objects

• class TemplateResponse
• TemplateResponse is a subclass ofSimpleTemplateResponse that knows aboutthe current HttpRequest.

Methods

• TemplateResponse.init(request, template, context=None, content_type=None, status=None, charset=None, using=None)

• Instantiates a TemplateResponse objectwith the given request, template, context, content type, HTTP status, andcharset.

  • request
  • An HttpRequest instance.
  • template
  • A backend-dependent template object (such as those returned byget_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 theMIME type specification and the character set encoding. Ifcontent_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 willbe extracted from content_type, and if that is unsuccessful, theDEFAULT_CHARSET setting will be used.
  • using
  • The NAME of a template engine to use forloading the template.

The rendering process

Before a TemplateResponse instance can bereturned to the client, it must be rendered. The rendering process takes theintermediate representation of template and context, and turns it into thefinal byte stream that can be served to the client.

There are three circumstances under which a TemplateResponse will berendered:

• When the TemplateResponse instance is explicitly rendered, usingthe SimpleTemplateResponse.render() method.
• When the content of the response is explicitly set by assigningresponse.content.
• After passing through template response middleware, but beforepassing through response middleware.A TemplateResponse can only be rendered once. The first call toSimpleTemplateResponse.render() sets the content of the response;subsequent rendering calls do not change the response content.

However, when response.content is explicitly assigned, thechange is always applied. If you want to force the content to bere-rendered, you can re-evaluate the rendered content, and assignthe 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 anunrendered template. They must be performed on a fully complete andrendered response.

If you’re using middleware, you can do that. Middleware providesmultiple opportunities to process a response on exit from a view. Ifyou put behavior in the response middleware, it’s guaranteed to executeafter template rendering has taken place.

However, if you’re using a decorator, the same opportunities do notexist. 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 willbe invoked when rendering has completed. Using this callback, you candefer critical processing until a point where you can guarantee thatrendered content will be available.

To define a post-render callback, define a function that takesa single argument – response – and register that function withthe 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.htmlhas been rendered, and will be provided the fully renderedTemplateResponse instance as an argument.

If the template has already been rendered, the callback will beinvoked immediately.

Using TemplateResponse and SimpleTemplateResponse

A TemplateResponse object can be used anywhere that a normaldjango.http.HttpResponse can be used. It can also be used as analternative to calling render().

For example, the following view returns a TemplateResponse with atemplate 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()})