Recursion in Django templates

When I first designed Undefined Fire v4 seven months ago I had planned to use a category tree to categorize all the articles instead of using the tagging system that is now used. This category tree system required the use of a recursive template system to be displayed correctly, unfortunately Django does not have this functionality so I did what any good developer would do—I wrote my own implementation.

Below is the template tag code that I came up with, just download the file and save it in your application’s “templatetags/” directory.

v1.1 Update (20/04/08): Added the ability to recurse single elements as well as automatic skipping of empty elements.
Download
Recurse Template Tag <Python: recurse.py> 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
###############################################################################
# Recurse template tag for Django v1.1
# Copyright (C) 2008 Lucas Murray
# http://www.undefinedfire.com
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser General Public License for more details.
###############################################################################

from django import template

register = template.Library()

class RecurseNode(template.Node):
    def __init__(self, var, name, child, nodeList):
        self.var = var
        self.name = name
        self.child = child
        self.nodeList = nodeList

    def __repr__(self):
        return '<RecurseNode>'

    def renderCallback(self, context, vals, level):
        output = []
        try:
            if len(vals):
                pass
        except:
            vals = [vals]
        if len(vals):
            if 'loop' in self.nodeList:
                output.append(self.nodeList['loop'].render(context))
            for val in vals:
                context.push()
                context['level'] = level
                context[self.name] = val
                if 'child' in self.nodeList:
                    output.append(self.nodeList['child'].render(context))
                    child = self.child.resolve(context)
                    if child:
                        output.append(self.renderCallback(context, child, level + 1))
                if 'endloop' in self.nodeList:
                    output.append(self.nodeList['endloop'].render(context))
                else:
                    output.append(self.nodeList['endrecurse'].render(context))
                context.pop()
            if 'endloop' in self.nodeList:
                output.append(self.nodeList['endrecurse'].render(context))
        return ''.join(output)

    def render(self, context):
        vals = self.var.resolve(context)
        output = self.renderCallback(context, vals, 1)
        return output

def do_recurse(parser, token):
    bits = list(token.split_contents())
    if len(bits) != 6 and bits[2] != 'with' and bits[4] != 'as':
        raise template.TemplateSyntaxError, "Invalid tag syxtax expected '{% recurse [childVar] with [parents] as [parent] %}'"
    child = parser.compile_filter(bits[1])
    var = parser.compile_filter(bits[3])
    name = bits[5]

    nodeList = {}
    while len(nodeList) < 4:
        temp = parser.parse(('child','loop','endloop','endrecurse'))
        tag = parser.tokens[0].contents
        nodeList[tag] = temp
        parser.delete_first_token()
        if tag == 'endrecurse':
            break

    return RecurseNode(var, name, child, nodeList)
do_recurse = register.tag('recurse', do_recurse)

Unlike other developer’s implementations this one allows the recursive element to be embedded in the same file as the main template instead of forcing the designer to use a separate file. Another benefit is that the template file is only loaded and parsed once, making is theoretically slightly more efficient as well (I haven’t actually confirmed this though).

Most of the tags are self explanatory, the only one that may cause confusion is the main {% recurse %} one. The format for this tag is {% recurse [children] with [parent] as [child] %} where “[children]” is the property that contains the children of the current element, “[parent]” is your starting element and “[child]” is the variable named used in the loop.

Here is an example of how you can implement a category tree using this template tag. As you can see it’s fairly simple and with a couple of modifications can be used for just about anything.

Example Usage <HTML+Django/Jinja> 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{% load recurse %}

... Headers and stuff ...

{% recurse category.category_set.all with categories as category %}
<ul>
    {% loop %}
    <li>
        <h{{ level }}>{{ category.title }}</h{{ level }}>
        {% child %}
    </li>
    {% endloop %}
</ul>
{% endrecurse %}

... The rest of the page ...

Comments

Now usually this is the place where you can submit your own reactions the the stuff I talked about above but due to time issues and my lazy personality I haven’t actually written the comment system yet. I will eventually get around to finishing it once I get my reader count back up to what it was in the early days but until then feel free to contact me with your response.