Create Custom Template Tags in Django: A complete guide

As a Django web developer, there’s nothing quite like the feeling of having everything organized, in its place, and ready to be customized. Custom template tags provide a way to encapsulate repetitive template logic into reusable, modular code that can be easily accessed across your templates.

Before, I would find myself writing HTML code that was cluttered and hard to read when working on a large Django project that had huge number of templates. It was difficult to maintain the code. Up until, I learned to create my own custom template tags. They were easy to make and my templates became much more organized, readable, and maintainable.

In this article, I’ll be sharing my experience and the knowledge I’ve gained about custom template tags in Django. We’ll cover everything from what custom template tags are, how to create them, and how to use them in templates. By the end of this guide, you’ll have a solid understanding of custom template tags in Django, and be able to use them to improve your Django code.

What are template tags in Django?

Template tags in Django are a way to add logic to your templates (.html files). They are written in Python code and are used to perform dynamic actions such as adding custom logic within a template that is not within the capabilities of a normal .html file. Template tags can take arguments, access data from the context, and return values to be included in the template output.

Django template tags allow developers to abstract complex logic and use that logic in template files.

Some examples of what you can do with template tags in Django include:

• Displaying a formatted date or time
• Perform extra programming on a server before sending data to the client
• Conditionally rendering content or data based on certain conditions
• Accessing and processing data from the context to display in the template

In short, template tags solve a variety of problems that arise when building web applications.

They allow

• Breaking complex logic into small and reusable units,
• Simplify your templates and make your code more maintainable,
• Provide a convenient way to extend the functionality of your templates.

What are custom template tags in Django?

Custom template tags in Django are a feature that allows developers to create their own custom tags that can be used in Django templates. These tags encapsulate complex logic to be reused across multiple templates.

Creating custom template tags helps create implement complex logic such as conditional statements in a template file while helping maintain code readability and organization, and reducing the amount of repetitive code.

Custom template tags can be used to:

• Display content in a specific way,
• Access context data and display it based on conditions,
• Display data retrieved from the database, and
• Perform any processing necessary to generate the desired output in a .html file.

This makes it possible to create custom tags that handle specific functionality and provide a way to access that functionality in a consistent manner across multiple templates.

Custom template tags are defined in a Django app. They are created using Python in a Python module. Custom template tags can access context data and perform any necessary processing to generate the desired output, which is then passed back to the template for display.

What are the different types of custom template tags in Django?

In Django, you have access to three main types of custom template tags:

1. Simple tags
2. Inclusion tags

Let’s see in detail, what each tag is and what it does.

What is a simple tag?

A simple tag in Django is a type of custom template tag that takes some data from the context variable, processes it, and returns a string that can be inserted into a template (.html file).

Simple tags do not render a template of their own and are designed to simply process some data and return string data to a .html file.

Because of that, simple tags are used when you want to process simple calculations, format data, etc. Typically, simple tags are designed to handle tasks that do not require complex template rendering.

Here is a simple example of a simple_tag used to display the current date and time on a web page.

# create the code for your simple_tag in your Python module like this
from django import template
from datetime import datetime


register = template.Library()

@register.simple_tag()
def current_time_tag():
    return str(datetime.now().time())

# Then use the simple tag in your template like this
You are accessing this page at: {% current_time %}

# The simple tag will display a simple string showing the current time you're accessing that particular web page.

It is as simple as that!

What is an inclusion tag?

An inclusion tag in Django is a type of custom template tag that takes some data from the context and uses the data to render a template. The rendered result can then be inserted into the template. and returns a string that can be inserted into a template (.html file).

Inclusion tags do render a template of their own and are designed to handle complex processing that require a template to be rendered. It is a powerful approach to encapsulating complex logic into reusable code.

Rendering a template in an inclusion tag in Django refers to the process of using data from the context variable and generating the output in the form of HTML content that can be inserted into the template using the custom tag.

For example, consider a website with a header that is the same on every page. Instead of duplicating the header code on each page, you could create an inclusion tag that you can use in each of your pages.

Here’s an example:

# Let's say this is your header code
    <header>
        <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
            <a href="/contact">Contact</a>
        </nav>
    </header>

# In your Python module with custom template tags, you can create an inclusion tag like this:

    from django import template

    register = template.Library()

    @register.inclusion_tag('header.html')
    def header_tag():
        return {}

# Then, in your templates, you can render the header code like this:
    {% load header_tag %}
    <html>
    <body>
        {% header_tag %}
        <!-- other content -->
    </body>
    </html>

The result:

Why create custom template tags in Django?

Custom template tags provide a powerful way for Django web developers to extend the functionality of the Django template system. By creating custom tags, you can encapsulate complex logic and computation, and reuse that logic across multiple templates in your Django project.

8 benefits of using custom template tags in Django

Here are 8 reasons why creating custom template tags in Django is important:

1. Code reusability: Custom template tags provide a way to reuse some blocks of code across multiple template files helping you avoid redundancy.
2. Custom template tags help encapsulate complex logic into reusable and organized blocks of code.
3. Through encapsulation, you achieve better organization of your code, which in the end helps maintain readability. With custom template tags, you can be able to scan, understand, and maintain your codebase easily.
4. You can use inclusion tags to create a consistent layout or interface across your Django web application.
5. Customize the output of a template upon accessing data from the context variable.
6. Create reusable components such as navigation menus. These reusable components can be easily included across multiple .html files of your Django project.
7. Enhance your template files with custom functionality such as performing calculations and data processing. Client applications can then access the processed data from the server.
8. Optimize the performance of your application by reducing the amount of processing required by the template system.

We’ve talked much about custom template tags, let’s see how to create these custom tags in your Django projects.

How to create custom template tags in Django

Before you start creating your custom template tags, you need to do two things:

1. Set up the environment for creating Django custom template tags.
2. Create custom template tags in Python modules.

Setting up the environment for creating custom template tags

This is the first step in the process of creating custom template tags in Django. The process involve preparing the development environment by creating a Django application, a templatetags directory, an __init__.py file, and registering the application in the INSTALLED_APPS setting.

Here are the detailed steps to setting up your Django project for creating custom template tags:

1. Create a Django app
2. Create templatetags directory inside your app directory
3. Add __init__.py file in the templatetags directory
4. Register your Django application in your main project settings.py file

Step 1: Create a Django application

Because a Django project can have multiple apps, it’s best practice to create separate Django apps with their own custom template tags.

Navigate into your project root directory and create an app using the following command:

python manage.py startapp your_app_name

# here's the command for creating an app called blog
python manage.py startapp blog

Step 2: Create templatetags directory inside app-level directory

Where you have your app’s files, e.g views.py, models.py, and admin.py, create a new custom tags directory called templatetags. Here’s a simple command to do that:

mkdir your_app_name/templatetags

# for the blog app, use
mkdir blog/templatetags

Step 3: Create an empty __init__.py inside templatetags directory

Create an empty __init__.py file in the templatetags directory you created to make it the directory to be recognized as a Python package. This is necessary so that Django can recognize the directory as a valid location for storing modules hosting custom template tags.

To create __init__.py file, navigate into the directory and create the file using the following command:

# navigate into the directory
cd app_name/templatetags

# Create the file
touch __init__.py file

# Here's a simple command to do that for our blog app
touch blog/templatetags/__init__.py

Step 4: Register your new Django app inside settings.py file

To use custom template tags in a Django project, your application that contains the custom tags library must be registered in the INSTALLED_APPS setting in the project’s settings.py file.

To do that, open the settings.py file located in the project directory and configure your INSTALLED_APPS list like this:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # new line
    'name_of_the_app_here',
]


# for our Django app example, you INSTALLED_APPS list should look like this:
# Application definition

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # new line
    'blog',
]

These steps ensure that custom template tags can be properly loaded and used in Django templates. They set the foundation for creating custom template tags in Django and are crucial for ensuring that custom tags can be properly loaded and used in your templates.

Creating a custom template tag step by step

After setting up your development environment, let’s actually create a custom template tag from start to finish. This section is crucial as it provides a hands-on approach to creating custom template tags, allowing you to apply the concepts learned in the previous sections and see the results in action.

Creating a custom template tag in Django involves several steps, starting with defining a Python function that takes arguments, performs the desired logic, and returns the desired output. The function is created inside a Python module.

Steps to take to create a custom template tag in Django

Here are the steps to create a custom template tag in Django:

1. Create a Python module within the templatetags directory. The module will hold the custom template tag names and logic.
2. Import the necessary modules including django.template
3. Define the custom template tag using the def keyword
4. Decorate the template tag function with either @register.simple_tag or @register.inclusion_tag decorators
5. Save your Python file and test it

Here are the steps showing how to create an example template tag in detail:

Step I> Create a custom template tags library inside templatetags directory

Within the templatetags directory you created earlier, add a new Python file using a name that is conventional to the type of logic you want to implement. In short, give it any name you wish and you will remember.

Here is how to do it:

touch app_name/templatetags/your_module_name

For our Django blog application, here is an example of a custom template tags module for listing all the latest featured posts. Based on the context, the files name for the module should be latest_posts.py

So,

touch blog/templatetags/latests_posts.py

After creating the file, open it using your favorite code editor or IDE.

code blog/templatetags/latests_posts.py

Step II> Import the necessary module that include django.template

In your new Python module, import the necessary modules that will be used in your file. The default must-have module should be django.template. If you are accessing data from the database, you may also need to import the necessary Django app models here.

Here’s how to import the django.template module:

from django import template

For our Django blog app, we’ll need to import eh BlogPost class from the app models.py

from blog.models import BlogPost

Also, create the register object by instantiating it from django.template.Library

Here’s how to do it:

After importing the necessary moduels add the following line of code in your custom temlplate tags module.

register = template.Library()

Step III> Define the custom template tag using the Python function syntax

Define your custom template tag function providing the necessary arguments, the logic, and the desired output.

Here’s the syntax using Python function syntax for creating a custom template tag:

def your_custom_tag_name(arguments):
    ...
    # your logic here
    ...
    return something

For our Django blog app that retrieves the latest blog posts, here’s how the custom template tag would look like:

def get_latest_posts(count=10):
    return BlogPost.objects.order_by('-published_date')[:count]
    

The function above retrieves the latest 10 blog posts.

Step IV> Decorate your custom template tag with the appropriate decorator

After creating your custom template tag logic, decorate the function with @register.simple_tag or @register.inclusion_tag decorators. Depending on the custom tag type, you can any of the decorators.

To decorate your function, just add @register.your_docorator before the function is declared. Here’s an example.

@register.simple_tag
def your_custom_tag_name(arguments):
    ...
    # your logic here
    ...
    return something

For the blog app, here’s how to decorate the get_latest_posts custom function to make it a custom template tag:

@register.simple_tag
def get_latest_posts(count=10):
    return BlogPost.objects.order_by('-published_date')[:count]

Step V: Save your Python file and perform some tests to ensure it works

Save your python module while checking that you do not have typos and syntax errors.

With that, you should have created a custom template tag that can be used in your templates.

How to create a simple_tag in Django?

Here are the steps to create a simple tag in Django:

1. Import the necessary modules including django.template
2. Instantiate django.template.Library and assign it to the variable, register.
3. Define the custom template tag function providing the necessary arguments, desired logic, and the return data.
4. Decorate your custom template tag function with the @register.simple_tag decorator.

Creating a simple_tag decorator is as easy as that.

How to create an inclusion_tag in Django?

Here are the steps to create a simple tag in Django:

1. Import the necessary modules including django.template
2. Instantiate django.template.Library and assign it to the variable, register.
3. Define the custom template tag function providing the necessary arguments, desired logic, and the return data.
4. Decorate your custom template tag function with the @register.inclusion_tag decorator.

That’s how you create an inclusion_tag in Django.

How to register a tag in Django?

In Django, you can register a custom template tag by decorating a function with the appropriate decorator, such as @register.simple_tag or @register.inclusion_tag.

Here’s how it works in simple steps:

1. Import the django.template library and the register object from django.template.library.
2. Define a function that implements the logic you want your custom template tag to perform.
3. Decorate the function with either the @register.simple_tag or @register.inclusion_tag decorator.
4. The custom tag is now registered and can be used in your Django templates by loading the custom tag library using the {% load %} tag.

If you encounter any problems with loading and registering your custom template tags, be sure to check this article, especially when you get: “Did you forget to register or load this tag?“

How to use custom template tags in templates

Now that you have created a custom template tag, this section shows you how to use the template tags in your Django templates.

So, you will need to create the templates and then using your custom template tags in those templates.

1. Creating the templates where you will use your custom template tags.
2. Using your custom template tags in your Django templates.

Create templates in Django?

Follow these steps to create a template file in Django:

1. Inside your Django app directory, create a new directory called ‘templates’ using the command: mkdir your_app_name/templates
2. Inside your_app_name directory, create a new .html file using the following syntax: `touch your_app_name/templates/new_file.html
3. Create a view that uses the template file you have created

To learn more about Django templates, here is another article I have written for you.

How to use custom template tags in Django templates?

After creating your Django template file, follow these steps to load the custom library and the custom template tags in your .html file:

Step #1: Load the custom tag library in the template file by using the {% load %} tag

Open your .html file and add the following line at the top:

{% load your_module_name %}

For our blog application, you can load the Python module using the following code:

{% load latest_posts %}

Step #2: Invoke the custom template tag code by using {% %} template tag syntax

Invoke the custom tag in the template code by using the custom tag’s name and any necessary arguments. For example, if you have a custom simple tag called “latest_blog_posts” that takes a count argument to limit the number of posts returned, you would use it in your template code like this: {% latest_blog_posts "John" %}.

For our Django blog application, we do not need to provide any additional argument to the custom tag. Here’s how to invoke the get_latest_posts tag:

{% get_latest_posts %}

The template code above should return all the latest 10 posts in each template that you invoke it.

Using custom template tags in your Django templates is as easy as that. It takes a similar style used to load built-in template tags such as {% for %}, {% if %}, {% with %}, {% block %}, etc.

If you get any error such as ‘custom_tags’ is not a registered tag library. must be one of:, be sure to check this article I have written on troubleshooting problems associated with creating custom template tags.

How to create custom template tags with multiple arguments in Django

Creating custom template tags with multiple arguments in Django involves defining a function that implements the logic for your custom tag and adding the necessary arguments to the function.

Thus, when invoking the custom template tag in your Django template file, you must provide extra multiple arguments.

Here are the detailed steps on how to create custom template tags with multiple arguments:

1. Import the django.template library and the register object from django.template.library.
2. Define your custom template tag function that implements the logic you want and the additional arguments that will be added as parameters when invoking the tag.
3. Decorate the function using the appropriate decorator. You can use either @register.simple_tag or @register.inclusion_tag decorator.
4. Load the custom tag library by adding the following line of code to the top of your template file: {% load my_tags %}.
5. Use your custom tag in the template code while passing the multiple arguments needed by your custom template tag

For demonstration, let’s create a custom template tag that greets a user by their name and time of the day. Follow these steps:

The example will use the name of the custom template tags module as greetings.py

1. Import the necessary libraries and objects in your custom template tags module

from django import template

register = template.Library()

2. Define your custom tag function while providing as many arguments as you want for your logic to work

def greet_user(username, time_of_the_day): # here's where to provide the arguments needed by your custom template tag
    
    # define your logic here
    return f"Hi, {username}! Good {time_of_the_day}."

3. Register your custom template tag by decorating it with the appropriate decorator

In this example, the custom tag function should be decorated with @register.simple_tag.

@register.simple_tag
def greet_user(username, time_of_the_day): # here's where to provide the arguments needed by your custom template tag
    
    # define your logic here
    return f"Hi, {username}! Good {time_of_the_day}."

4. Load your custom library in your template file

{% load greetings %}

5. Use your custom tag in the template file while providing the necessary arguments

In this example, the custom tag can be used in the template code by passing two arguments: a username and a time of the day.

{% greet_user "Steve" "morning" %}

In this example, the result should display, Hi Steve! Good Morning.

That’s how you create custom template tags with additional multiple arguments.

What is the difference between template files and template tags?

Template files are the HTML files that define the structure and content of your web pages while template tags are custom code snippets that can be inserted into template files for additional functionality.

Here is a table showing the differences between template files and template tags:

Template files	Template tags
Represent the structure and content of a webpage.	Provides additional dynamic functionality within the Django template.
Create as a .html file. They are typically written in HTML.	Created inside a Python module, .py file. They are written in Python.
Uses standard template language	Use standard Python programming language
Allow a limited amount of dynamic behavior.	Offer a wider range of dynamic behavior and conditionals.
Used to display content.	Used to modify, process, and control content.

Conclusion

In conclusion, the use of custom template tags in Django can greatly improve the functionality and efficiency of your templates. Understanding how to create and use custom template tags is a valuable skill for both beginner and experienced Django developers.

Through this article, we have discussed the different types of custom template tags, such as simple_tag and inclusion_tag, and the steps involved in setting up the environment, creating custom template tags, registering the tag, and using the custom template tags in templates.

Whether you’re looking to simplify your code, add custom functionality, or improve the overall user experience of your Django templates, this is the right how-to guide you need to achieve that.