Ticket #1105: improved_simple_tag.r7818.diff

django/django/template/__init__.py

@@ -792 +792 @@
         else:
             return force_unicode(output)
 
-def generic_tag_compiler(params, defaults, name, node_class, parser, token):
+def generic_tag_compiler(params, defaults, name, node_class, parser, token, takes_context=False, takes_nodelist=False):
     "Returns a template.Node subclass."
     bits = token.split_contents()[1:]
     bmax = len(params)
@@ -804 +804 @@
         else:
             message = "%s takes between %s and %s arguments" % (name, bmin, bmax)
         raise TemplateSyntaxError(message)
+    if takes_context:
+        node_class = curry(node_class, takes_context=takes_context) 
+    if takes_nodelist:
+        nodelist = parser.parse(('end%s' % name,)) 
+        parser.delete_first_token() 
+        node_class = curry(node_class, nodelist=nodelist) 
     return node_class(bits)
 
 class Library(object):
@@ -859 +865 @@
         self.filters[getattr(func, "_decorated_function", func).__name__] = func
         return func
 
-    def simple_tag(self,func):
-        params, xx, xxx, defaults = getargspec(func)
+    def simple_tag(self, compile_function=None, takes_context=None, takes_nodelist=None):
+        def dec(func):
+            params, xx, xxx, defaults = getargspec(func)
+            if takes_context and takes_nodelist:
+                if params[0] == 'context' and params[1] == 'nodelist':
+                    params = params[2:]
+                else:
+                    raise TemplateSyntaxError("Any tag function decorated both with takes_context=True and with takes_nodelist=True must have a first argument of 'context', and a second argument of 'nodelist'")
+            elif takes_nodelist:
+                if params[0] == 'nodelist':
+                    params = params[1:]
+                else:
+                    raise TemplateSyntaxError("Any tag function decorated with takes_nodelist=True must have a first argument of 'nodelist'")
+            elif 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 SimpleNode(Node):
-            def __init__(self, vars_to_resolve):
-                self.vars_to_resolve = map(Variable, vars_to_resolve)
+            class SimpleNode(Node):
+                def __init__(self, vars_to_resolve, takes_context=False, nodelist=None): 
+                    self.vars_to_resolve = map(Variable, vars_to_resolve)
+                    self.takes_context = takes_context
+                    if nodelist is not None:
+                        # Only save the 'nodelist' attribute if it's not None, so that it is picked by the Node.get_nodes_by_type() method.
+                        self.nodelist = nodelist
 
-            def render(self, context):
-                resolved_vars = [var.resolve(context) for var in self.vars_to_resolve]
-                return func(*resolved_vars)
+                def render(self, context):
+                    resolved_vars = [var.resolve(context) for var in self.vars_to_resolve]
+                    if self.takes_context and hasattr(self, 'nodelist'):
+                        func_args = [context, self.nodelist] + resolved_vars
+                    elif hasattr(self, 'nodelist'):
+                        func_args = [self.nodelist] + resolved_vars
+                    elif self.takes_context:
+                        func_args = [context] + resolved_vars
+                    else:
+                        func_args = resolved_vars
+                    return func(*func_args)
 
-        compile_func = curry(generic_tag_compiler, params, defaults, getattr(func, "_decorated_function", func).__name__, SimpleNode)
-        compile_func.__doc__ = func.__doc__
-        self.tag(getattr(func, "_decorated_function", func).__name__, compile_func)
-        return func
+            compile_func = curry(generic_tag_compiler, params, defaults, getattr(func, "_decorated_function", func).__name__, SimpleNode, takes_nodelist=takes_nodelist, takes_context=takes_context)
+            compile_func.__doc__ = func.__doc__
+            self.tag(getattr(func, "_decorated_function", func).__name__, compile_func)
+            return func
+        
+        if takes_context is not None or takes_nodelist is not None:
+            # Examples: @register.simple_tag(takes_context=True) or @register.simple_tag(takes_context=True, takes_nodelist=True)
+            return dec
+        elif compile_function is None:
+            # @register.simple_tag()
+            return dec
+        elif callable(compile_function):
+            # @register.simple_tag
+            return dec(compile_function)
+        else:
+            raise TemplateSyntaxError("Incorrect parameters for the simple_tag decorator.")
 
     def inclusion_tag(self, file_name, context_class=Context, takes_context=False):
         def dec(func):

django/tests/regressiontests/templates/tests.py

@@ -17 +17 @@
 from django.utils.safestring import mark_safe
 from django.utils.tzinfo import LocalTimezone
 
+from decorators import DecoratorsTest
 from unicode import unicode_tests
 from context import context_tests
 

django/tests/regressiontests/templates/decorators.py

@@ +1 @@
+from unittest import TestCase
+from unittest import TestCase
+from sys import version_info
+
+from django import template
+
+register = template.Library()
+
+# Very simple tag, with no parameters.
+def a_simple_tag_without_parameters(arg):
+    """Expected __doc__"""
+    return "Expected result"
+a_simple_tag_without_parameters.anything = "Expected __dict__"
+
+# Tag that takes the context.
+def a_simple_tag_with_context(context, arg):
+    """Expected __doc__"""
+    return "Expected result"
+a_simple_tag_with_context.anything = "Expected __dict__"
+
+# Tag that takes the inner block's node list.
+def a_simple_tag_with_nodelist(nodelist, arg):
+    """Expected __doc__"""
+    return "Expected result"
+a_simple_tag_with_nodelist.anything = "Expected __dict__"
+
+# Tag that takes both the context and the inner block's node list.
+def a_simple_tag_with_context_and_nodelist(context, nodelist, arg):
+    """Expected __doc__"""
+    return "Expected result"
+a_simple_tag_with_context_and_nodelist.anything = "Expected __dict__"
+
+# Tag that *wants* to take both the context and the inner block's node list, but that has arguments in wrong order.
+def a_simple_tag_with_context_and_nodelist_wrong_order(nodelist, context, arg):
+    """Expected __doc__"""
+    return "Expected result"
+a_simple_tag_with_context_and_nodelist_wrong_order.anything = "Expected __dict__"
+
+
+
+
+class DecoratorsTest(TestCase):
+    def verify_decorator(self, decorator, func_name):
+        # Only check __name__ on Python 2.4 or later since __name__ can't be
+        # assigned to in earlier Python versions.
+        if version_info[0] >= 2 and version_info[1] >= 4:
+            self.assertEquals(decorator.__name__, func_name)
+        self.assertEquals(decorator.__doc__, 'Expected __doc__')
+        self.assertEquals(decorator.__dict__['anything'], 'Expected __dict__')
+
+    def test_simple_tag(self):
+        # Test that the decorators preserve the decorated function's docstring, name and attributes.
+        decorator = register.simple_tag(a_simple_tag_without_parameters)
+        self.verify_decorator(decorator, 'a_simple_tag_without_parameters')
+        
+        decorator = register.simple_tag(takes_context=True)(a_simple_tag_with_context)
+        self.verify_decorator(decorator, 'a_simple_tag_with_context')
+        
+        decorator = register.simple_tag(takes_nodelist=True)(a_simple_tag_with_nodelist)
+        self.verify_decorator(decorator, 'a_simple_tag_with_nodelist')
+        
+        decorator = register.simple_tag(takes_context=True, takes_nodelist=True)(a_simple_tag_with_context_and_nodelist)
+        self.verify_decorator(decorator, 'a_simple_tag_with_context_and_nodelist')
+        
+        # Now test that 'context' and 'nodelist' arguments and their order are correct.
+        decorator = register.simple_tag(takes_context=True)
+        self.assertRaises(template.TemplateSyntaxError, decorator, a_simple_tag_without_parameters)
+        
+        decorator = register.simple_tag(takes_nodelist=True)
+        self.assertRaises(template.TemplateSyntaxError, decorator, a_simple_tag_without_parameters)
+        
+        decorator = register.simple_tag(takes_nodelist=True, takes_context=True)
+        self.assertRaises(template.TemplateSyntaxError, decorator, a_simple_tag_with_context_and_nodelist_wrong_order)

django/docs/templates_python.txt

@@ -1181 +1181 @@
     * 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.
+If your template tag needs to access the current context, you can use the
+``takes_context`` option as follows::
 
+    # The first argument *must* be called "context" here.
+    def current_time(context, format_string):
+        timezone = context['timezone']
+        ...
+
+    register.simple_tag(takes_context=True)(current_time)
+
+You can also use the decorator syntax if running in Python 2.4::
+
+    @register.simple_tag(takes_context=True)
+    def current_time(context, format_string):
+        ...
+
+For more information on how the ``takes_context`` option works, see the section
+on `inclusion tags`_.
+
+If your template is a simple block tag, you can use the ``takes_nodelist`` option as
+follows::
+
+    # The first argument *must* be called "nodelist".
+    def my_bock_tag(nodelist, an_argument):
+        ...
+    register.simple_tag(takes_nodelist=True)(my_bock_tag)
+
+In the above example, ``nodelist`` is a list of all nodes between 
+``{% my_bock_tag %}`` and ``{% endmy_bock_tag %}``, not counting 
+``{% my_bock_tag %}`` and ``{% endmy_bock_tag %}`` themselves.
+
+It is also possible to use both ``takes_context`` and ``takes_nodelist`` at the
+same time. For example::
+
+    # The first argument *must* be called "context" and the second one "nodelist".
+    def my_bock_tag(context, nodelist, an_argument):
+        timezone = context['timezone']
+        content = nodelist.render(context)
+        ...
+    register.simple_tag(takes_context=True, takes_nodelist=True)(my_bock_tag)
+
+If you need to create a more complex block tag, refer to the section on 
+`parsing until another block tag`_.
+
+_inclusion tags: #inclusion-tags
+_block tags: #parsing-until-another-block-tag
+
 Inclusion tags
 ~~~~~~~~~~~~~~