Django's template language is quite simple. However, you can save a lot of time by following some elegant template design patterns. Let's take a look at some of them.
Problem: Templates have lots of repeated content in several pages.
Solution: Use template inheritance wherever possible and include snippets elsewhere.
Users expect pages of a website to follow a consistent structure. Certain interface elements, such as navigation menu, headers, and footers are seen in most web applications. However, it is cumbersome to repeat them in every template.
Most templating languages have an include mechanism. The contents of another file, possibly a template, can be included at the position where it is invoked. This can get tedious in a large project.
The sequence of the snippets to be included in every template would be mostly the same. The ordering is important and hard to check for mistakes. Ideally, we should be able to create a 'base' structure. New pages ought to extend this base to specify only the changes or make extensions to the base content.
Django templates have a powerful extension mechanism. Similar to classes in programming, a template can be extended through inheritance. However, for that to work, the base itself must be structured into blocks as follows:
The base.html template is, by convention, the base structure for the entire site. This template will usually be well-formed HTML (that is, with a preamble and matching closing tags) that has several placeholders marked with the {% block tags %} tag. For example, a minimal base.html file looks like the following:
<html>
<body>
<h1>{% block heading %}Untitled{% endblock %}</h1>
{% block content %}
{% endblock %}
</body>
</html>There are two blocks here, heading and content, that can be overridden. You can extend the base to create specific pages that can override these blocks. For example, here is an about page:
{% extends "base.html" %}
{% block content %}
<p> This is a simple About page </p>
{% endblock %}
{% block heading %}About{% endblock %}Notice that we do not have to repeat the structure. We can also mention the blocks in any order. The rendered result will have the right blocks in the right places as defined in base.html.
If the inheriting template does not override a block, then its parent's contents are used. In the preceding example, if the
about template does not have a heading, then it will have the default heading of 'Untitled'.
The inheriting template can be further inherited forming an inheritance chain. This pattern can be used to create a common derived base for pages with a certain layout, for example, single-column layout. A common base template can also be created for a section of the site, for example, blog pages.
Usually, all inheritance chains can be traced back to a common root, base.html; hence, the pattern's name—Template inheritance tree. Of course, this need not be strictly followed. The error pages 404.html and 500.html are usually not inherited and stripped bare of most tags to prevent further errors.
Problem: The navigation bar is a common component in most pages. However, the active link needs to reflect the current page the user is on.
Solution: Conditionally, change the active link markup by setting context variables or based on the request path.
The naïve way to implement the active link in a navigation bar is to manually set it in every page. However, this is neither DRY nor foolproof.
There are several solutions to determine the active link. Excluding JavaScript-based approaches, they can be mainly grouped into template-only and custom tag-based solutions.
By mentioning an active_link variable while including the snippet of the navigation template, this solution is both simple and easy to implement.
In every template, you will need to include the following line (or inherit it):
{% include "_navbar.html" with active_link='link2' %}The _navbar.html file contains the navigation menu with a set of checks for the active link variable:
{# _navbar.html #}
<ul class="nav nav-pills">
<li{% if active_link == "link1" %} class="active"{% endif %}><a href="{% url 'link1' %}">Link 1</a></li>
<li{% if active_link == "link2" %} class="active"{% endif %}><a href="{% url 'link2' %}">Link 2</a></li>
<li{% if active_link == "link3" %} class="active"{% endif %}><a href="{% url 'link3' %}">Link 3</a></li>
</ul>Django templates offer a versatile set of built-in tags. It is quite easy to create your own custom tag. Since custom tags live inside an app, create a templatetags directory inside an app. This directory must be a package, so it should have an (empty) __init__.py file.
Next, write your custom template in an appropriately named Python file. For example, for this active link pattern, we can create a file called nav.py with the following contents:
# app/templatetags/nav.py
from django.core.urlresolvers import resolve
from django.template import Library
register = Library()
@register.simple_tag
def active_nav(request, url):
url_name = resolve(request.path).url_name
if url_name == url:
return "active"
return ""This file defines a custom tag named active_nav. It retrieves the URL's path component from the request argument (say, /about/—see Chapter 4, Views and URLs, for a detailed explanation of the URL path). Then, the resolve() function is used to lookup the URL pattern's name (as defined in urls.py) from the path. Finally, it returns the string "active" only when the pattern's name matches the expected pattern name.
The syntax for calling this custom tag in a template is {% active_nav request 'pattern_name' %}. Notice that the request needs to be passed in every page this tag is used.
Including a variable in several views can get cumbersome. Instead, we add a built-in context processor to TEMPLATE_CONTEXT_PROCESSORS in settings.py so that the request will be present in a
request variable across the site, as follows:
# settings.py
from django.conf import global_settings
TEMPLATE_CONTEXT_PROCESSORS =
global_settings.TEMPLATE_CONTEXT_PROCESSORS + (
'django.core.context_processors.request',
)Now, all that remains is to use this custom tag in your template to set the active attribute:
{# base.html #}
{% load nav %}
<ul class="nav nav-pills">
<li class={% active_nav request 'active1' %}><a href="{% url 'active1' %}">Active 1</a></li>
<li class={% active_nav request 'active2' %}><a href="{% url 'active2' %}">Active 2</a></li>
<li class={% active_nav request 'active3' %}><a href="{% url 'active3' %}">Active 3</a></li>
</ul>