Fixed #18651 -- Enabled optional assignments for simple_tag().

3 files changed, 34 insertions, 37 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index b13c8cb81a..e4fe6949ea 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -388,7 +388,7 @@ Simple tags
 .. method:: django.template.Library.simple_tag()
 
 Many template tags take a number of arguments -- strings or template variables
--- and return a string after doing some processing based solely on
+-- and return a result after doing some processing based solely on
 the input arguments and some external information. For example, a
 ``current_time`` tag might accept a format string and return the time as a
 string formatted accordingly.
@@ -459,6 +459,18 @@ positional arguments. For example:
 
     {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}
 
+.. versionadded:: 1.9
+
+It's possible to store the tag results in a template variable rather than
+directly outputting it. This is done by using the ``as`` argument followed by
+the variable name. Doing so enables you to output the content yourself where
+you see fit:
+
+.. code-block:: html+django
+
+    {% get_current_time "%Y-%m-%d %I:%M %p" as the_time %}
+    <p>The time is {{ the_time }}.</p>
+
 .. _howto-custom-template-tags-inclusion-tags:
 
 Inclusion tags
@@ -602,11 +614,15 @@ Assignment tags
 
 .. method:: django.template.Library.assignment_tag()
 
+.. deprecated:: 1.9
+
+    ``simple_tag`` can now store results in a template variable and should
+    be used instead.
+
 To ease the creation of tags setting a variable in the context, Django provides
 a helper function, ``assignment_tag``. This function works the same way as
-:ref:`simple_tag<howto-custom-template-tags-simple-tags>`, except that it
-stores the tag's result in a specified context variable instead of directly
-outputting it.
+:meth:`~django.template.Library.simple_tag` except that it stores the tag's
+result in a specified context variable instead of directly outputting it.
 
 Our earlier ``current_time`` function could thus be written like this::
 
@@ -622,38 +638,6 @@ followed by the variable name, and output it yourself where you see fit:
     {% get_current_time "%Y-%m-%d %I:%M %p" as the_time %}
     <p>The time is {{ the_time }}.</p>
 
-If your template tag needs to access the current context, you can use the
-``takes_context`` argument when registering your tag::
-
-    @register.assignment_tag(takes_context=True)
-    def get_current_time(context, format_string):
-        timezone = context['timezone']
-        return your_get_current_time_method(timezone, format_string)
-
-Note that the first parameter to the function *must* be called ``context``.
-
-For more information on how the ``takes_context`` option works, see the section
-on :ref:`inclusion tags<howto-custom-template-tags-inclusion-tags>`.
-
-``assignment_tag`` functions may accept any number of positional or keyword
-arguments. For example::
-
-    @register.assignment_tag
-    def my_tag(a, b, *args, **kwargs):
-        warning = kwargs['warning']
-        profile = kwargs['profile']
-        ...
-        return ...
-
-Then in the template any number of arguments, separated by spaces, may be
-passed to the template tag. Like in Python, the values for keyword arguments
-are set using the equal sign ("``=``") and must be provided after the
-positional arguments. For example:
-
-.. code-block:: html+django
-
-    {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile as the_result %}
-
 Advanced custom template tags
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 50782b363c..66477109ec 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -20,6 +20,8 @@ details on these changes.
 
 * The ``django.forms.extras`` package will be removed.
 
+* The ``assignment_tag`` helper will be removed.
+
 .. _deprecation-removed-in-2.0:
 
 2.0
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 8c7aff8fe1..db9b6c324d 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -137,7 +137,9 @@ Signals
 Templates
 ^^^^^^^^^
 
-* ...
+* Template tags created with the :meth:`~django.template.Library.simple_tag`
+  helper can now store results in a template variable by using the ``as``
+  argument.
 
 Requests and Responses
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -194,6 +196,15 @@ Miscellaneous
 Features deprecated in 1.9
 ==========================
 
+``assignment_tag()``
+~~~~~~~~~~~~~~~~~~~~
+
+Django 1.4 added the ``assignment_tag`` helper to ease the creation of
+template tags that store results in a template variable. The
+:meth:`~django.template.Library.simple_tag` helper has gained this same
+ability, making the ``assignment_tag`` obsolete. Tags that use
+``assignment_tag`` should be updated to use ``simple_tag``.
+
 Miscellaneous
 ~~~~~~~~~~~~~