Tutorial: Django Template Tags

Introduction

In the Python Web Framework Django, template tags can be used to modify data that is about to be output in a Django template file. In this tutorial we will learn how to create and use our own template tags in a Django application.

Setting Up

Template tag definitions are stored in Django apps. The template tags in each app should be relevant to the models and views in that app. You shouldn’t have one app that stores every single template tag you use throughout your website. Each app can contain a directory called templatetags and assuming the app is added to settings.INSTALLED_APPS, Django will automatically search that appname/templatetags/ directory for template tag definitions. Remember to put an __init__.py file in each templatetags directory because the template tags inside them are imported.

Example

In an application I worked on recently I needed to display some data about a World Of Warcraft character such as their race, class and gender. The information about the character was stored in a database table and was referenced like so:
Image may be NSFW.
Clik here to view.
This means that if the character was a Male Orc Shaman, then the gender column would read 0, the race column would read 2 and the class column would read 64. If I were to output this information on the screen, the numbers wouldn’t mean anything to anybody. In order to turn those numbers into something meaningful (an actual word for the gender/race/class) I would either need to manipulate the data in the appropriate Django view, or in the template. Writing a template tag to do this is quick, easy and gives a tidy result so I decided to do this.

Usage Example

If we had a Django template with information about the Male Orc Shaman stored in the character object.

{{ character.class }}

Would output 64. However using the template tag (that we are about to write)..

 {% load char_utils %}
{{ character.class|class_name }}

would output Shaman. Notice the {% load char_utils %}. char_utils refers to the name of the python file we define the template tags in (appname/templatetags/char_utils.py).

Writing the Template Tag

We will define the template tags in the file *appname*/templatetags/char_utils.py. At the top of this file we need to import the django.template module and set up Django’s template tag registry.

from django import template

register = template.Library()

Template tag definitions are just standard Python functions. The argument the function accepts is what the template tag is applied to (in the above example class_name was applied to character.class). Our template tags will accept one parameter, the numerical id (eg 64 for Shaman) and will turn that number into the appropriate name.

def race_name(id):
    races = {

    1 : 'human',
    2 : 'orc',
    4 : 'dwarf',
    5 : 'undead',
    6 : 'tauren',
    8 : 'nightelf',
    16 : 'undead',
    32 : 'tauren',
    64 : 'gnome',
    128 : 'troll',
    512 : 'bloodelf',
    1024 : 'draenai',

    }

    return races.get(id)

def class_name(id):

    classes = {

    1 : 'warrior',
    2 : 'paladin',
    4 : 'hunter',
    6 : 'deathknight',
    8 : 'rogue',
    16 : 'priest',
    32 : 'deathknight',
    64 : 'shaman',
    128 : 'mage',
    256 : 'warlock',
    1024 : 'druid',
    }

    return classes.get(id)

def gender_name(id):

    genders = {
    0 : 'male',
    1 : 'female',
    }

    return genders.get(id)

Finally we need to register the template tags with Django so that it knows that we want to use them.

register.filter('race_name', race_name)
register.filter('class_name', class_name)
register.filter('gender_name', gender_name)

The template tags will now work. If you have any questions or feedback please leave them in the comments below.