Django, as a web framework, uses templates as a way of producing static HTML from the output of a Django view. In practice, Django’s templates are simply HTML files, with some special syntax and a set of tools which lets Django render the HTML page on-the-fly for the visiting user. Templates are highly customizable, but are meant to be simple, with most of the “heavy” logic going into the view. Let’s dive deeper and learn some standard ways of dealing with common problems.
By default, Django comes with a ton of built-in template tags and filters that help us perform repeatable template tasks throughout our apps.
Tags: Tags provide arbitrary logic in the rendering process. Django leaves this definition fairly vague, but tags are able to output content, grab content from the database (more on this later), or perform control operations like if statements or for loops.
Examples of tags:
firstof tag will output the first provided variable which evaluates to
True. This is a good replacement for a large
if/elif/elif/elif/elif block that’s just evaluating on truthiness within your Django templates.
for tag in Django will loop over each item in a list, making that item (product, in this case) available in the template context before the tag is closed with
endfor. This is a widely used pattern when working with lists of Django model instances which have been returned from the view.
Filters: Filters transform the values of variables and arguments. Filters would be used in tasks like rendering a string in uppercase or formatting a date string into a user’s region.
Examples of filters:
The date filter will format a date (
value, in the example) given a string with some format characters. The example would output the string:
Mon 01 Apr 2019.
The slugify filter will convert the spaces of a string into hyphens and convert the string to lowercase, among other things. The output of this example
Django, by default, will make some assumptions about the structure of our project when it’s looking for templates. Knowing this, we can set up our project with a template directory and application template directories.
Imagine a project, cloud, with the following structure:
cloud/ accounts/ urls.py models.py views.py templates/ accounts/ login.html register.html blog/ urls.py views.py models.py templates/ blog/ create.html post.html list.html config/ settings/ base.py local.py urls.py manage.py templates/ includes/ messages.html modal.html base.html logged_in.html
An important aspect of Django’s templating system is template inheritance. Django applications are meant to be reusable, and we can apply the same methodology to our templates by inheriting common HTML from other templates.
A typical pattern is to have a common base template for common aspects of your application, logged-in pages, logged-out pages, or in places where significant changes are made to the underlying HTML. From our example above,
base.html would contain most of the core structure that would make up each page, with blocks defined for app or page-specific customizations.
base.html may contain:
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,
initial-scale=1, shrink-to-fit=no"> <link rel="stylesheet" type="text/css" media="all"
href="" /> <link rel="stylesheet" type="text/css" media="all"
We use Django’s
The inside of a JS console once the page has loaded:
>> window._sharedData.DEBUG false
>> window._sharedData.USERS_AUTOCOMPLETE_ENDPOINT '/api/users/autocomplete/'
Properly handling querysets within your templates can be a performance bottleneck for Django depending on the complexities of your model definitions.
Django’s templating system is tightly coupled with Django’s object-relational mapping layer which returns us data from the database. Without proper consideration of this coupling you may, inadvertently, cause the number of queries run on each page load to jump to unmaintainable amounts. In some cases, this can cause the database to become too sluggish to operate certain pages on your site, or worse, crash and need to be restarted.
Thankfully, Django provides mechanisms and patterns which we can use to make sure our templates are running as fast as possible and we’re not killing the database server.
Consider this common Django pattern:
class UserListView(ListView): template_name = 'accounts/list.html' model = User paginate_by = 25 context_object_name = 'users' queryset = User.objects.all()
... <table> <thead> <tr> <th>Username</th> <th>Email</th> <th>Profile photo URL</th> <th>Joined</th> </tr> </thead> <tbody> </tbody> </table> ...
Can you spot the problem? It may not be obvious at first, but look at this line:
When Django is processing and rendering our template (line by line), it will need to do an additional query to grab information from the profile object as it’s a related field. In our example view, we’re paginating by 25 users, so this one line in the template could account for an additional 25 queries (on each page request as the profile object, as with all related objects and models in Django) which aren’t included in the original query for the 25 users. You can imagine how this could become a very slow page if we were including fields from other related objects in our table, or if we were paginating by 100 users instead of 25.
To resolve this, we’ll change one line in our view,
accounts/views.py, to select related objects when we’re running our original query for users:
class UserListView(ListView): template_name = 'accounts/list.html' model = User paginate_by = 25 context_object_name = 'users' queryset = User.objects.select_related( 'profile')
By replacing our
User.objects.select_related(‘profile’), we’re telling Django to include related profile instances when it’s performing its query for our users. This will include the
Profile model on each
User instance, preventing Django from needing to run an extra query each time we ask for information from the profile within the template.
select_related functionality does not work with many-to-many model relationships, or with many-to-one relationships. For this, we’d want to use Django’s
prefetch_related does its magic in Python, as opposed to SQL select statements, by joining related objects into instances which can be accessed in templates as we’ve done above. It doesn’t perform things in a single query like
select_related is able to, but it’s much more efficient than running a query each time you request a related attribute.
A prefetch for related projects and organizations and one-to-many relationships off of the
User model would look like this:
class UserListView(ListView): template_name = 'accounts/list.html' model = User paginate_by = 25 context_object_name = 'users' queryset = User.objects.prefecth_related( 'profile', 'organizations')
You can use tools like django-debug-toolbar to investigate templates and views in your Django application which may benefit from using
prefetch_related. Once installed, django-debug-toolbar is able to show which queries are run when a view is executed and a template is loaded. This is incredibly useful for debugging slow pages, a template you’ve written may be running hundreds of queries.
While not technically a Django templating system-specific best practice, using namespaces with your Django URLs makes developing inside templates much simpler.
I find example 2 (below) to be much easier to quickly understand than example 1.
<a href="">2021 Archive</a></li>
<a href="">2021 Archive</a></li>
URL namespaces allow us to have unique URL names, even if another application uses the same URL name (
edit, for example.) Without using URL namespaces, a Django project couldn’t have two URLs named
create. With namespacing, we’re able to name and reference our URLs simply, without needing long complex names for each URL in our application.
A URL named
blog-article-create, would become
users: profile:create since
create is no longer reserved by a single application in our project. Setting this up is fairly straightforward.
urls.py file for example 1 (above) would look something like this:
from django.urls import path
from . import views
urlpatterns = [ #... path('articles//', views.year_archive, name='news-year-archive'), #... ]
If we introduce namespacing, we’ll end up with a project setup like this:
from django.urls import path
from . import views
archive_patterns = [
path('/', views.year_archive, name='year'),
urlpatterns = [
path('', include(archive_patterns, namespace='archive')),
from django.urls import include, path
urlpatterns = [
path('articles/', include('blog.urls', namespace='blog')),
This allows us to traverse from the blog namespace of URLs, into the archive namespace where we can designate URLs which will behave just inside the articles/ path, inside the blog application. Rendering the URL using the url template tag is also just as easy and intuitive (seen in example 2 above.)
Django templates aren’t difficult to work with, but as we’ve seen above, there are a number of ways we can make working in Django templates even easier:
Posted by Zac Clancy
Zac Clancy is a senior software engineer and technical advisor with broad experience ranging from technology startups to forward deployment into the immediate aftermath of international disasters. Zac led small US-based technology teams while in Haiti following the 2010 earthquake, helping to automate certain aspects of the emergency medical supply chain with software. Since Haiti, Zac has led initiatives, advised decision-makers, and implemented solutions during international disasters, or other critical incidents in some of the world’s most challenging locations.LinkedIn Twitter Website