Sep 18 2008

Simplifying Django Template Extensions

Tags: Python, Django, Technical

Since DjangoCon, there seems to be a fair amount of discussion centered around the comparison of, drawbacks of, and paths to improving Django's templating engine.

This write is not intended to be a discussion on the principals or philosophies of Django's approach to templates verses the alternatives. I will, however, that I fully understand and appreciate the desire for the separation of concerns (i.e., developer vs. designer), although working mostly as a team of one, I personally find this approach to be a bit restricting. I don't know that "jumping ship" to Jinja is necessarily the best option for me. Instead, finding ways to improve Django templates and contributing back to the Django community feels right to me.

Having said that, I must admit that I find writing template extensions to be the single most tedious and cumbersome aspects of using Django. It feels like I am constantly repeating myself - DRY alert! - by writing new template tags: start by writing the micro-parser for the tag syntax, follow that by creating the wrapper Node class extension, and only then getting to the point where I can actually write the business or domain-specific logic that is needed. I am forever looking up references and consulting past work because there seems to be nothing intuitive or natural about the process. This is major put-off, and instead I would find myself putting the work of populating my context data into the individual views - which also didn't seem very DRY, nor very reusable.

I've seen a few suggestions for patches to help minimize the effort required to extend tags template. Until one of these patches - past, present, or future - finds it's way into trunk - or a release, in many developer's situation - I thought that I would share a solution that I have been using for awhile now that can be used in the interim.

Rather than list all the source code here, I've zipped up a simple project that exposes a Library extension and a sample application that takes advantage of it using various examples. The download can be found here.

The basic idea is this: provide an means of accessing something (a queryset, any arbitrary Python object) and injecting it into the template context as a named variable via a simple function that has been automagically been made into a new template tag by way of smart decorator. For flexibility, passing arguments into the function is an optional feature. I like to think of these new template-tagged functions as tag getters.

A somewhat contrived example might help to illustrate. First, the template code itself: I want to be able to retrieve a list of active users, possibly filtered. Currently, my most direct option would be to perform the query within the view and pass along the resulting queryset to the template through the Context instance. It's easy to see that this can become quite irksome: perhaps I have multiple views where this is necessary, or the variations on the filter are specific enough to make it overly complex to all the possible results to the template in manner where it can be consumed in a sensible fashion

Consider the following example that filters active users by applying some regular expressions (I warned that this would be contrived):

1
2
3
4
5
6
7
{% get_active_users as active_users using "^L" "(x|z)" %}
<p>Active users: {{ active_users.count }}</p>
<ul>
    {% for active_user in active_users %}
    <li>{{ active_user.get_full_name }}</li>
    {% endfor %}
</ul>

Get me the active users whose first or last name begins with L or contains either x or z (note: I could have easily done this by using a single regex argument, but I wanted to show multiple arguments being passed). The result, in this case a queryset, is assigned to the variable active_users. using and the subsequent arguments are optional in this case, as we'll see shortly.

Creating the get_active_users template tag is very simple and pretty much only requires thought to be given to the actual problem of user retrieval, allowing the developer to bypass most of the mechanics and build up of necessary template extension foo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import operator
from django.db.models import Q
from django.contrib.auth.models import User
from template_utils import GetterLibrary
register = GetterLibrary()
@register.getter_tag
def get_active_users(*regex_filters):
    qs = User.objects.filter(is_active=True)
    if regex_filters:
        filter_by = [
            Q(first_name__regex=regex_filter) | Q(last_name__regex=regex_filter)
            for regex_filter in regex_filters
        ]
        qs = qs.filter(reduce(operator.or_, filter_by))
    return qs

So, we have a shortcut to producing a new template involving really only three steps, 2 of which we would have had to do regardles:

  1. template_utils.GetterLibrary is a simple class derived from django.template.Library. I have point out here that my naming skills are lame at best, so please forbear from snickering - I welcome suggestions for a better choice of labels. GetterLibrary does everything we know and love from the base Library class, plus:

  2. The getter_tag decorator method of the GetterLibrary instance, which provides the bit of function-to-tag automation, and:

  3. Our "worker" function, whose sole job is to return any result we wish to assign to our new context variable.

There are several more examples to be found in the test project, so please download it it and poke about through the code and demo app.