Fixed #14908 -- Added a 'takes_context' argument to simple_tag. Thanks to Julien Phalip for driving the issue and providing the final patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14987 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 27 insertions, 5 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 95ce274460..246bb67af0 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -669,9 +669,27 @@ A couple of things to note about the ``simple_tag`` helper function:
     * If the argument was a template variable, our function is passed the
       current value of the variable, not the variable itself.
 
-When your template tag does not need access to the current context, writing a
-function to work with the input values and using the ``simple_tag`` helper is
-the easiest way to create a new tag.
+.. versionadded:: 1.3
+
+If your template tag needs to access the current context, you can use the
+``takes_context`` argument when registering your tag::
+
+    # The first argument *must* be called "context" here.
+    def current_time(context, format_string):
+        timezone = context['timezone']
+        return your_get_current_time_method(timezone)
+
+    register.simple_tag(takes_context=True)(current_time)
+
+Or, using decorator syntax::
+
+    @register.simple_tag(takes_context=True)
+    def current_time(context, format_string):
+        timezone = context['timezone']
+        return your_get_current_time_method(timezone)
+
+For more information on how the ``takes_context`` option works, see the section
+on `inclusion tags`_.
 
 .. _howto-custom-template-tags-inclusion-tags:
 
diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index f1a33b434c..06c39c756e 100644
--- a/docs/releases/1.3.txt
+++ b/docs/releases/1.3.txt
@@ -184,12 +184,16 @@ requests. These include:
 
     * Support for _HTTPOnly cookies.
 
-    * mail_admins() and mail_managers() now support easily attaching
-      HTML content to messages.
+    * :meth:`mail_admins()` and :meth:`mail_managers()` now support
+      easily attaching HTML content to messages.
 
     * Error emails now include more of the detail and formatting of
       the debug server error page.
 
+    * :meth:`simple_tag` now accepts a :attr:`takes_context` argument,
+      making it easier to write simple template tags that require
+      access to template context.
+
 .. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly
 
 .. _backwards-incompatible-changes-1.3: