Ticket #14262: 14262.assignment_tag.diff

django/template/base.py

@@ -901 +901 @@
         else:
             raise TemplateSyntaxError("Invalid arguments provided to simple_tag")
 
+    def assignment_tag(self, func=None, takes_context=None):
+        def dec(func):
+            params, xx, xxx, defaults = getargspec(func)
+            if takes_context:
+                if params[0] == 'context':
+                    params = params[1:]
+                else:
+                    raise TemplateSyntaxError("Any tag function decorated with takes_context=True must have a first argument of 'context'")
+
+            class AssignmentNode(Node):
+                def __init__(self, params_vars, target_var):
+                    self.params_vars = map(Variable, params_vars)
+                    self.target_var = target_var
+
+                def render(self, context):
+                    resolved_vars = [var.resolve(context) for var in self.params_vars]
+                    if takes_context:
+                        func_args = [context] + resolved_vars
+                    else:
+                        func_args = resolved_vars
+                    context[self.target_var] = func(*func_args)
+                    return ''
+
+            def compile_func(parser, token):
+                bits = token.split_contents()
+                tag_name = bits[0]
+                bits = bits[1:]
+                params_max = len(params)
+                defaults_length = defaults and len(defaults) or 0
+                params_min = params_max - defaults_length
+                if (len(bits) < 2 or bits[-2] != 'as'):
+                    raise TemplateSyntaxError("'%s' tag takes at least 2 arguments and the second last argument must be 'as'" % tag_name)
+                params_vars = bits[:-2]
+                target_var = bits[-1]
+                if (len(params_vars) < params_min or len(params_vars) > params_max):
+                    if params_min == params_max:
+                        raise TemplateSyntaxError("%s takes %s arguments" % (tag_name, params_min))
+                    else:
+                        raise TemplateSyntaxError("%s takes between %s and %s arguments" % (tag_name, params_min, params_max))
+                return AssignmentNode(params_vars, target_var)
+            
+            compile_func.__doc__ = func.__doc__
+            self.tag(getattr(func, "_decorated_function", func).__name__, compile_func)
+            return func
+
+        if func is None:
+            # @register.assignment_tag(...)
+            return dec
+        elif callable(func):
+            # @register.assignment_tag
+            return dec(func)
+        else:
+            raise TemplateSyntaxError("Invalid arguments provided to assignment_tag")
+        
     def inclusion_tag(self, file_name, context_class=Context, takes_context=False):
         def dec(func):
             params, xx, xxx, defaults = getargspec(func)

docs/howto/custom-template-tags.txt

@@ -624 +624 @@
 Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
 resolve the string passed to it in the current context of the page.
 
+.. _howto-custom-template-tags-simple-tags:
+
 Shortcut for simple tags
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Many template tags take a number of arguments -- strings or a template variables
+Many template tags take a number of arguments -- strings or template variables
 -- and return a string after doing some processing based solely on
 the input argument and some external information. For example, the
 ``current_time`` tag we wrote above is of this variety: we give it a format
 string, it returns the time as a string.
 
-To ease the creation of the types of tags, Django provides a helper function,
+To ease the creation of this type of tags, Django provides a helper function,
 ``simple_tag``. This function, which is a method of
 ``django.template.Library``, takes a function that accepts any number of
 arguments, wraps it in a ``render`` function and the other necessary bits
@@ -681 +683 @@
         return your_get_current_time_method(timezone, format_string)
 
 For more information on how the ``takes_context`` option works, see the section
-on `inclusion tags`_.
+on :ref:`inclusion tags<howto-custom-template-tags-inclusion-tags>`.
+
+.. _howto-custom-template-tags-assignment-tags:
+
+Assignment tags
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.4
+
+Another common type of template tag is the type that fetches some data and
+stores it in a context variable. To ease the creation of this type of tags,
+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.
+
+Our earlier ``current_time`` function could thus be written like this::
+
+.. code-block:: python
+
+    def get_current_time(format_string):
+        return datetime.datetime.now().strftime(format_string)
+
+    register.assignment_tag(get_current_time)
+
+The decorator syntax also works::
+
+.. code-block:: python
+
+    @register.assignment_tag
+    def get_current_time(format_string):
+        ...
+
+You may then store the result in a template variable using the ``as`` argument
+followed by the variable name, and output it 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>
+
+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 get_current_time(context, format_string):
+        timezone = context['timezone']
+        return your_get_current_time_method(timezone, format_string)
+
+    register.assignment_tag(takes_context=True)(get_current_time)
+
+Or, using decorator syntax::
+
+    @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)
+
+For more information on how the ``takes_context`` option works, see the section
+on :ref:`inclusion tags<howto-custom-template-tags-inclusion-tags>`.
 
 .. _howto-custom-template-tags-inclusion-tags:
 

docs/releases/1.4.txt

@@ -37 +37 @@
 features you need in admin pages without having to lose HTML validity or
 override the provided templates to change the doctype.
 
+Assignment template tags
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new helper function,
+:ref:`assignment_tag<howto-custom-template-tags-assignment-tags>`, was added to
+``template.Library`` to ease the creation of template tags that store some
+data in a specified context variable.
+
 .. _backwards-incompatible-changes-1.4:
 
 Backwards incompatible changes in 1.4

tests/regressiontests/templates/custom.py

@@ +1 @@
+from __future__ import with_statement
+
 from django import template
 from django.utils.unittest import TestCase
 from templatetags import custom
@@ -78 +80 @@
         self.verify_tag(custom.inclusion_explicit_no_context, 'inclusion_explicit_no_context')
         self.verify_tag(custom.inclusion_no_params_with_context, 'inclusion_no_params_with_context')
         self.verify_tag(custom.inclusion_params_and_context, 'inclusion_params_and_context')
+        
+    def test_assignment_tags(self):
+        c = template.Context({'value': 42})
+
+        t = template.Template('{% load custom %}{% assignment_no_params as var %}The result is: {{ var }}')
+        self.assertEqual(t.render(c), u'The result is: assignment_no_params - Expected result')
+
+        t = template.Template('{% load custom %}{% assignment_one_param 37 as var %}The result is: {{ var }}')
+        self.assertEqual(t.render(c), u'The result is: assignment_one_param - Expected result: 37')
+
+        t = template.Template('{% load custom %}{% assignment_explicit_no_context 37 as var %}The result is: {{ var }}')
+        self.assertEqual(t.render(c), u'The result is: assignment_explicit_no_context - Expected result: 37')
+
+        t = template.Template('{% load custom %}{% assignment_no_params_with_context as var %}The result is: {{ var }}')
+        self.assertEqual(t.render(c), u'The result is: assignment_no_params_with_context - Expected result (context value: 42)')
+
+        t = template.Template('{% load custom %}{% assignment_params_and_context 37 as var %}The result is: {{ var }}')
+        self.assertEqual(t.render(c), u'The result is: assignment_params_and_context - Expected result (context value: 42): 37')
+
+        with self.assertRaises(template.TemplateSyntaxError) as context_manager: 
+            template.Template('{% load custom %}{% assignment_one_param 37 %}The result is: {{ var }}')
+        self.assertEqual(context_manager.exception.message, "'assignment_one_param' tag takes at least 2 arguments and the second last argument must be 'as'")
+        
+        with self.assertRaises(template.TemplateSyntaxError) as context_manager:
+            template.Template('{% load custom %}{% assignment_one_param 37 as %}The result is: {{ var }}')
+        self.assertEqual(context_manager.exception.message, "'assignment_one_param' tag takes at least 2 arguments and the second last argument must be 'as'")
+        
+        with self.assertRaises(template.TemplateSyntaxError) as context_manager:
+            template.Template('{% load custom %}{% assignment_one_param 37 ass var %}The result is: {{ var }}')
+        self.assertEqual(context_manager.exception.message, "'assignment_one_param' tag takes at least 2 arguments and the second last argument must be 'as'")
+        
+    def test_assignment_tag_registration(self):
+        # Test that the decorators preserve the decorated function's docstring, name and attributes.
+        self.verify_tag(custom.assignment_no_params, 'assignment_no_params')
+        self.verify_tag(custom.assignment_one_param, 'assignment_one_param')
+        self.verify_tag(custom.assignment_explicit_no_context, 'assignment_explicit_no_context')
+        self.verify_tag(custom.assignment_no_params_with_context, 'assignment_no_params_with_context')
+        self.verify_tag(custom.assignment_params_and_context, 'assignment_params_and_context')
+
+    def test_assignment_tag_missing_context(self):
+        # That the 'context' parameter must be present when takes_context is True
+        def an_assignment_tag_without_parameters(arg):
+            """Expected __doc__"""
+            return "Expected result"
+
+        register = template.Library()
+        decorator = register.assignment_tag(takes_context=True)
+        
+        with self.assertRaises(template.TemplateSyntaxError) as context_manager:
+            decorator(an_assignment_tag_without_parameters)
+        self.assertEqual(context_manager.exception.message, "Any tag function decorated with takes_context=True must have a first argument of 'context'")

tests/regressiontests/templates/templatetags/custom.py

@@ -69 +69 @@
     return {"result" : "inclusion_params_and_context - Expected result (context value: %s): %s" % (context['value'], arg)}
 inclusion_params_and_context.anything = "Expected inclusion_params_and_context __dict__"
 
+@register.assignment_tag
+def assignment_no_params():
+    """Expected assignment_no_params __doc__"""
+    return "assignment_no_params - Expected result"
+assignment_no_params.anything = "Expected assignment_no_params __dict__"
+
+@register.assignment_tag
+def assignment_one_param(arg):
+    """Expected assignment_one_param __doc__"""
+    return "assignment_one_param - Expected result: %s" % arg
+assignment_one_param.anything = "Expected assignment_one_param __dict__"
+
+@register.assignment_tag(takes_context=False)
+def assignment_explicit_no_context(arg):
+    """Expected assignment_explicit_no_context __doc__"""
+    return "assignment_explicit_no_context - Expected result: %s" % arg
+assignment_explicit_no_context.anything = "Expected assignment_explicit_no_context __dict__"
+
+@register.assignment_tag(takes_context=True)
+def assignment_no_params_with_context(context):
+    """Expected assignment_no_params_with_context __doc__"""
+    return "assignment_no_params_with_context - Expected result (context value: %s)" % context['value']
+assignment_no_params_with_context.anything = "Expected assignment_no_params_with_context __dict__"
+
+@register.assignment_tag(takes_context=True)
+def assignment_params_and_context(context, arg):
+    """Expected assignment_params_and_context __doc__"""
+    return "assignment_params_and_context - Expected result (context value: %s): %s" % (context['value'], arg)
+assignment_params_and_context.anything = "Expected assignment_params_and_context __dict__"