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.