Ticket #5908: t5908.diff

django/template/defaulttags.py

@@ -66 +66 @@
         self.silent = silent
         self.escape = escape        # only while the "future" version exists
 
+    def reset(self, context):
+        context.render_context[self] = itertools_cycle(self.cyclevars)
+
     def render(self, context):
         if self not in context.render_context:
             # First time the node is rendered in template
@@ -80 +83 @@
             value = mark_safe(value)
         return render_value_in_context(value, context)
 
+class ResetCycleNode(Node):
+    def __init__(self, node):
+        self.node = node
+    def render(self, context):
+        self.node.reset(context)
+        return ''
+
 class DebugNode(Node):
     def render(self, context):
         from pprint import pformat
@@ -578 +588 @@
     # Ugly hack warning: This stuffs the named template dict into parser so
     # that names are only unique within each template (as opposed to using
     # a global variable, which would make cycle names have to be unique across
-    # *all* templates.
+    # *all* templates. Also keeps last node in the parser.
 
     args = token.split_contents()
 
@@ -623 +633 @@
     else:
         values = [parser.compile_filter(arg) for arg in args[1:]]
         node = CycleNode(values, escape=escape)
+    parser._lastCycleNode = node
     return node
 
 @register.tag
+def resetcycle(parser, token):
+    """
+    Resets a cycle tag.
+
+    If an argument is given, resets the last rendered cycle tag whose name
+    matches the argument, else resets last rendered unnamed cycle tag.
+
+    """
+    args = token.split_contents()
+
+    if len(args) > 2:
+        raise TemplateSyntaxError("%r tag accepts at most one argument."
+                                  % args[0])
+    if len(args) == 2:
+        name = args[1]
+        try:
+            return ResetCycleNode(parser._namedCycleNodes[name])
+        except AttributeError:
+            raise TemplateSyntaxError("No named cycles in template. "
+                                      "%r is not defined" % name)
+        except KeyError:
+            raise TemplateSyntaxError("Named cycle %r does not exist" % name)
+    try:
+        return ResetCycleNode(parser._lastCycleNode)
+    except AttributeError:
+        raise TemplateSyntaxError("No cycles in template.")
+
+@register.tag
 def csrf_token(parser, token):
     return CsrfTokenNode()
 

docs/ref/templates/builtins.txt

@@ -151 +151 @@
 Any HTML or Javascript code contained in the printed variable will be rendered
 as-is, which could potentially lead to security issues.
 
+You can use the `resetcycle`_ tag to reset a ``{% cycle %}`` tag to restart
+from its first value when it's next encountered.
+
 For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior
 old syntax from previous Django versions. You shouldn't use this in any new
 projects, but for the sake of the people who are still using it, here's what it
@@ -893 +896 @@
 ``{{ country.grouper }}`` will now display the value fields from the
 ``choices`` set rather than the keys.
 
+.. templatetag:: resetcycle
+
+resetcycle
+^^^^^^^^^^
+
+Resets a previous `cycle`_ so that it restarts from its first item at its next
+invocation.  Without arguments, ``{% resetcycle %}`` will reset the last
+``{% cycle %}`` defined in the template.
+
+Example usage::
+
+    {% for coach in coach_list %}
+        <h1>{{ coach.name }}</h1>
+        {% for athlete in coach.athlete_set.all %}
+            <p class="{% cycle 'odd' 'even' %}">{{ athlete.name }}</p>
+        {% endfor %}
+        {% resetcycle %}
+    {% endfor %}
+
+The athlete list for every coach starts with ``class="odd"``.  Without the
+``{% resetcycle %}`` tag, the first athlete of a coach might be rendered with
+``class="even"`` if the last athlete of the previous coach had ``class="odd"``.
+
+You can also reset named cycle tags::
+
+    {% for item in list %}
+        <p class="{% cycle 'odd' 'evn' as stripe %} {% cycle 'majr' 'minr' 'minr' 'minr' 'minr' as tick %}">
+            {{ item.data }}
+        </p>
+        {% ifchanged item.category %}
+            <h1>{{ item.category }}</h1>
+            {% if not forloop.first %}{% resetcycle tick %}{% endif %}
+        {% endifchanged %}
+    {% endfor %}
+
+In this example we have both the alternating odd/even rows and a "major" row
+every fifth row.  Only the five-row cycle is reset when a category changes.
+
 .. templatetag:: spaceless
 
 spaceless

docs/releases/1.6.txt

@@ -231 +231 @@
   `PIL`_ is pending deprecation (support to be removed in Django 1.8).
   To upgrade, you should **first** uninstall PIL, **then** install Pillow.
 
+* Added a :ttag:`resetcycle` template tag which allows the user to reset the
+  sequence of the :ttag:`cycle` template tag.
+
 .. _`Pillow`: https://pypi.python.org/pypi/Pillow
 .. _`PIL`: https://pypi.python.org/pypi/PIL
 

tests/template_tests/tests.py

@@ -819 +819 @@
             'cycle27': ('{% load cycle from future %}{% autoescape off %}{% cycle a b as ab %}{% cycle ab %}{% endautoescape %}', {'a': '<', 'b': '>'}, '<>'),
             'cycle28': ('{% load cycle from future %}{% cycle a|safe b as ab %}{% cycle ab %}', {'a': '<', 'b': '>'}, '<&gt;'),
 
+            ### RESETCYCLE TAG ########################################################
+            'resetcycle01': ("{% resetcycle %}", {}, template.TemplateSyntaxError),
+            'resetcycle02': ("{% resetcycle undefinedcycle %}", {}, template.TemplateSyntaxError),
+            'resetcycle04': ("{% cycle 'a' 'b' 'c' %}{% resetcycle undefinedcycle %}", {}, template.TemplateSyntaxError),
+            'resetcycle05': ("{% cycle 'a' 'b' 'c' as abc %}{% resetcycle undefinedcycle %}", {}, template.TemplateSyntaxError),
+            'resetcycle06': ("{% for i in test %}{% cycle 'a' 'b' %}{% resetcycle %}{% endfor %}", {'test': range(5)}, 'aaaaa'),
+            'resetcycle07': ("{% cycle 'a' 'b' 'c' as abc %}{% for i in test %}{% cycle abc %}{% cycle '-' '+' %}{% resetcycle %}{% endfor %}", {'test': range(5)}, 'ab-c-a-b-c-'),
+            'resetcycle08': ("{% cycle 'a' 'b' 'c' as abc %}{% for i in test %}{% resetcycle abc %}{% cycle abc %}{% cycle '-' '+' %}{% endfor %}", {'test': range(5)}, 'aa-a+a-a+a-'),
+            'resetcycle09': ("{% for i in outer %}{% for j in inner %}{% cycle 'a' 'b' %}{% endfor %}{% resetcycle %}{% endfor %}", {'outer': range(2), 'inner': range(3)}, 'abaaba'),
+            'resetcycle10': ("{% for i in outer %}{% cycle 'a' 'b' %}{% for j in inner %}{% cycle 'X' 'Y' %}{% endfor %}{% resetcycle %}{% endfor %}", {'outer': range(2), 'inner': range(3)}, 'aXYXbXYX'),
+            'resetcycle11': ("{% for i in test %}{% cycle 'X' 'Y' 'Z' as XYZ %}{% cycle 'a' 'b' 'c' as abc %}{% ifequal i 1 %}{% resetcycle abc %}{% endifequal %}{% endfor %}", {'test': range(5)}, 'XaYbZaXbYc'),
+            'resetcycle12': ("{% for i in test %}{% cycle 'X' 'Y' 'Z' as XYZ %}{% cycle 'a' 'b' 'c' as abc %}{% ifequal i 1 %}{% resetcycle XYZ %}{% endifequal %}{% endfor %}", {'test': range(5)}, 'XaYbXcYaZb'),
+
             ### EXCEPTIONS ############################################################
 
             # Raise exception for invalid template name