From 3f528e10d50ff7ba19a8a9e6cb2f9417a1e7f270 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Mon, 24 Jan 2011 14:24:35 +0000
Subject: Fixed #15012 -- Added post-rendering callbacks to TemplateResponse so
 that decorators (in particular, the cache decorator) can defer processing
 until after rendering has occurred. Thanks to Joshua Ginsberg for the draft
 patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15295 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/ref/template-response.txt | 59 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt
index d4fe2c4ef2..90da00220e 100644
--- a/docs/ref/template-response.txt
+++ b/docs/ref/template-response.txt
@@ -55,7 +55,6 @@ Attributes
 
     A boolean indicating whether the response content has been rendered.
 
-
 Methods
 -------
 
@@ -106,6 +105,20 @@ Methods
 
     Override this method in order to customize template rendering.
 
+.. method:: SimpleTemplateResponse.add_post_rendering_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 :class:`~django.template.response.SimpleTemplateResponse`
+    has already been rendered, the callback will be invoked
+    immediately.
+
+    When called, callbacks will be passed a single argument -- the
+    rendered :class:`~django.template.response.SimpleTemplateResponse`
+    instance.
+
 .. method:: SimpleTemplateResponse.render():
 
     Sets :attr:`response.content` to the result obtained by
@@ -211,6 +224,50 @@ the content of the response manually::
     >>> 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 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),
+:class:`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
+:class:`TemplateResponse` instance as an argument.
+
+If the template has already been rendered, the callback will be
+invoked immediately.
+
 Using TemplateResponse and SimpleTemplateResponse
 =================================================
 
-- 
cgit v1.3