How to Add Template Tags to Django

Template tags are the tags you see in this format {% some_tag %} which allow you to insert dynamic content, logic, or other functionality. The cool thing about Django is you can actually create your own tags when the built-in tags aren't enough.

How to Create Your Own

The Template Tag Folder Structure

We need to create a templatetags folder to hold our tag files. I usually put my templatetags in my main project folder (the one with the settings.py file in it). These templatetags tend to be site-wide rather than app-specific, so it makes most sense to me to simply put it in my main folder.

You will put your tag files in the templatetags folder, and you'll also need to add the __init__.py file.

myapp/
├── templatetags/
│   ├── __init__.py
│   ├── tag_one.py
│   ├── tag_two.py
│   └── ...
├── settings.py
└── ...

Creating the Tag

Now that you have your templatetags folder and your __init__.py file inside, you can create your first tag file. For the example below, we'll call the file date_tags.py since we'll be creating tags around dates and date formatting.

Example Tag

Let's say we need to frequently output a specific registration date and we want them to all have the same format. Instead of using a filter on all of our tags throughout our template, we'll use a custom template tag so that all the logic can be found in one place.

We start with the imports (the template module will be required for all of your custom template tags, add other imports as needed). Then we set up our register variable which we can then use as a decorator.

# date_tags.py

from django import template
from django.utils import timezone

register = template.Library()

@register.simple_tag
def registration_date():
    date = timezone.now() # This is just for the example. You may hard-code a date or pull it from a model field
    return date.strftime('%B %d, %Y')

This registration_date could pull a date from a model or a settings file. In our case, we're just setting the date to always be the current date/time. Then it formats that date into our convention and returns it. Nice and simple!

Add Your File to the settings.py

Now that we have a file name for our tags, we still have one more step to make sure it's accessible. Open up your settings.py file and find the TEMPLATES setting.

Inside the OPTIONS key is the 'context_processors' by default. You may or may not see a libraries key after it. If you already have libraries, then simply add your template tag file to the dictionary, or just copy the whole line for libraries below into your settings file.

Don't forget to change myapp to whatever your app's folder name is.

TEMPLATES = [
    {
        ...
        'OPTIONS': {
            'context_processors': [
                ...
            ],
            'libraries': {
                'date_tags': 'myapp.templatetags.date_tags',
            }
        },
    },
]

Load and Use the Tag in a Template

We're now ready to load in our tag. We first have to add our file to the load tag, so that the template knows we're pulling in the tags from that templatetag file.

<!-- some_template.html -->

{% load date_tags %}

{% block content %}
    <p>Register by: {% registration_date %}</p>
{% endblock %}