HAYDN ELLEN

Django’s template tags provide an elegant way to add custom functionality to templates without cluttering views or embedding logic directly into the HTML. This lets you build dynamic, reusable elements across your site. As a Django developer, you quickly find that while the built-in tags are helpful, sometimes you need more tailored behavior. I recently developed a custom tag for my blog to display a random featured post. Here’s how I went about creating it and the deeper role custom template tags play in Django.

A custom template tag is essentially a reusable snippet of Python that adds functionality to your templates. These tags let you perform actions or dynamically pull in data, like related articles or frequently asked questions, in a clean, modular way. The Django template system is great for managing complex sites, but for anything outside its default tags, you’ll want to add your own.

For the blog I am building (and it is not just any blog, it is a Haydn Ellen blog!), I wanted to show a “Featured Post” in the sidebar, displaying a different post each time a user visits a page. This approach keeps the page visually fresh and encourages readers to discover new content. I’ll walk through the process of building a custom template tag to do this.

The first step is to organize your custom tags by creating a directory in your Django app, specifically named templatetags. Inside this directory, you’ll need an init.py file to indicate that it’s a package. In my case, I created a file called featured_content.py where the custom tag function lives.

Defining the tag itself involves importing Django’s template module, as well as the models and any other libraries you need. Here’s what the initial setup looked like for my featured content tag:

from django import template
from myapp.models import Post
import random

register = template.Library()

Here, I’m importing Django’s template module to register the tag and bringing in the Post model and random library to select a random post. The register = template.Library() line is what initializes the tag library, where I’ll add my custom tags and filters.

To create the tag that retrieves a random featured post, I defined a function and decorated it with @register.simple_tag. This decorator makes the function available as a simple tag in templates. Here’s the function I created for the tag:

@register.simple_tag
def get_random_global_featured_post():
    featured_posts = Post.objects.filter(is_featured=True)
    return random.choice(featured_posts) if featured_posts else None

This function does several things at once. By using Post.objects.filter(is_featured=True), it retrieves only posts marked as “featured” in the database. Next, random.choice(featured_posts) picks a random post from the queryset of featured posts, ensuring that a different post is displayed each time. If no posts are marked as featured, it returns None as a fallback, which prevents errors when rendering.

After defining the tag function, the next step is to make it available in templates by loading it. At the top of any template where you want to use the tag, add {% load featured_content %}. This line tells Django to look in featured_content.py for custom tags.

Once the tag is loaded, calling it in a template and assigning the result to a variable is straightforward:

{% get_random_global_featured_post as global_featured_post %}

This line assigns the output of get_random_global_featured_post to a template variable named global_featured_post. This step effectively brings in the featured post data into the template context, allowing it to be rendered dynamically. Each page load now retrieves a different post for the featured section, making the sidebar or header content feel fresh.

Finally, displaying the featured post within the template becomes simple with this setup. You can check if global_featured_post is defined, and if so, render the title, image, and any other details. Here’s a snippet showing how I displayed the featured post: 

With this code, the featured post displays only if a random post was successfully retrieved. The truncatewords filter keeps the excerpt concise, and the image, title, and link allow readers to click through to the full post.

Here’s one I built, it’s the output of the code in this tutorial (styled with Tailwind CSS):

Creating this custom template tag allowed me to keep logic out of the views and templates, ensuring the site remains organized and the templates remain clean. The best part is that this featured_content tag is fully reusable across different templates, which saves time and keeps my project organized.

Beyond this specific example, the process of creating custom template tags in Django has opened up many possibilities for my site’s content management. Whether you need to dynamically display related posts, show popular tags, or manage other reusable content, custom template tags in Django let you add modular, clean functionality. By keeping logic out of the view and template layers, template tags help ensure a project that’s easy to maintain and extend.

If you find yourself implementing the same snippet of logic repeatedly across templates, try creating a custom tag. You’ll save time and build a codebase that’s easy to work with, now and in the future.