Creating custom template tags and filter in Django

Introduction

Creating custom tags and filter in Django templates is pretty simple. It acts like a custom function that can be used in Django templates. The situation may occur where you need to split a string or you need to access array elements using a variable as an index, then you have to create custom tags and filter (acts as a function) in Django templates.

You will find that built-in function, such as, split() is there in Python but you won’t be able to use this function directly in Django template. So in this situation you have to create a custom tags or function in Django template.

Prerequisites

Python version – 3.6.5/3.8.5, Django version – 2.2/3.0.8

Project Configuration

You generally create a Django project and under your Django project you have one or more applications.

Let’s say you have created Django project called myproject and you have also created an app called myapp under myproject. You may check the documentation for creating Django project and apps under project.

I assume you have the required configurations for your myapp in myproject/myproject/settings.py file in INSTALLED_APPS section as below:

INSTALLED_APPS = [
    'myapp.apps.MyappConfig',
	...
]

The myapp.apps.MyappConfig is formed as a dotted notation from myproject/myapp/apps.py, where you will find the class name as MyappConfig that has name myapp.

Creating Custom Tags and Filter

Let’s say you want to split a string in Django template file but Django does not provide any built-in function, though Python has split() function but it cannot be directly used in Django template file.

Therefore you will need to create custom tag, which will act as a custom function for the Django template.

Now create a directory called templatetags under myproject/myapp directory. Put empty __init__.py file under the directory templatetags to ensure that the directory is treated as a Python package.

Your custom tags and filters will live in a module inside the templatetags directory.

Now create a file called myapp_tags.py under templatetags directory and put the below source code into it.

from django import template

register = template.Library()

@register.filter(name='split')
def split(str, key):
    return str.split(key)

To be a valid tag library, the module must contain a module-level variable named register that is a template.Library() instance, in which all the tags and filters are registered. So I have used the below two lines to register the custom tags:

from django import template

register = template.Library()

Then I have defined the split(str, key) function that basically uses Python’s built-in split(key) function to return the split string into array of strings.

Loading Custom Tags

Now load your custom tags and filter into Django template file using the following line:

{% load myapp_tags %}

Notice myapp_tags is the name of the file.

Usage of the Custom Tags

Let’s say you want to split a string by ‘.‘, then following code written into Django template will help you:

{% with string|split:'.' as strs %}
     {% for str in strs %}
         {{ str }}
     {% endfor %}
 {% endwith %}

First I split the string by separator dot (.) and capture into strs variable. Then I iterate strs array using for loop and capture each value into str variable and print the value of the str.

Note that you must restart the server in order to reflect the changes.

That’s all about how to create custom tag and filter in Django framework.

Leave a Reply

Your email address will not be published. Required fields are marked *