Django Template Inheritance

1. The Scenario

In a project, elements such as the header and footer are often reused. To avoid rewriting these elements on every page, and so that a change does not require editing each page individually, the common parts need to be extracted — that is Django template inheritance.

2. Django’s Reusable Template Tags

Django’s built-in reusable template tags are mainly block, extends, and include.

First let us look at an example:

Define a project-wide common template base.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    {% block title %}
    <title>My Project</title>
    {% endblock %}
  </head>
  <body>
    <h1>My base</h1>
    {% block content %}{% endblock %} {% block footer %}
    <p>I am footer</p>
    {% endblock%}
  </body>
</html>

Using the common base.html template, define the home page index.html

1
2
3
4
5
{% extends "base.html" %} {% block title%}
<title>Home Page of My Project</title>
{% endblock %} {% block content %}
<p>Home page content</p>
{% endblock %}

2.1 block

Definition:

block defines a template block. The block in a child template overrides the block of the same name in the parent template. If you want the child template to add to the parent’s content rather than override it, you can use block.super.

Usage:

1
{% block index %} 子模板会替换父模板block index中的内容 {% endblock %}

1
{% block index %} {{ block.super }} 子模板新增的内容 {% endblock %}

2.2 extends

Definition:

extends means inheritance. Typically a project writes one base.html and a number of widget.html files. Most pages in the project inherit from base.html.

Usage:

The argument to extends is usually a string, and can also be a variable. Note that when using extends, extends must be the very first tag, otherwise it will not take effect.

1
{% extends 'base.html' %}

Definition:

include adds another template directly into the current template in the manner of a plugin.

Usage:

It may take a path, a relative path, or a variable name.

1
{% include 'tools.html' %}

2.3 Other Template Tags

autoescape controls the automatic escaping of the template.

1
{% autoescape off %} Hello {{ name }} {% endautoescape %}

load loads a tag library.

1
2
{% load staticfiles %}
<img src="{% static "images/hi.jpg" %}" />

You can also write custom tags. For example, after adding ‘django.contrib.humanize’ to INSTALLED_APPS, you can use load humanize in a template. Note that a loaded tag is not inherited by child templates.

3. Mako

Mako is a high-performance Python template library whose syntax borrows heavily from other template libraries such as Django and Jinja2. At the same time, Mako does not depend on any other Web framework and can be used directly for HTML generation. On first compilation, Mako compiles the HTML template into a Python file, greatly improving the speed of rendering and generating pages.

Mako

<%include>

Takes a filename as its argument and includes a file.

<%def>

Defines a Python function:

1
2
3
4
5
<%def name="myfunc(x)">
    this is myfunc, x is ${x}
</%def>

${myfunc(7)}

<%inherit>

Used for template inheritance.

1
<%inherit file="base.html"/>

<%call>

Used to call a Python function defined by <%def>.

parent

The namespace of the parent template in the inheritance chain. parent.head() references the parent template’s content from within the index.html child template.

The namespace of the next template in the inheritance chain. The position of next.body() determines where the child page’s content that is not inside a block is rendered. You can also use self.body(), but self.body() only renders content that is not inside a block in the final page, not content that is not inside a block in intermediate pages of the inheritance chain.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<!DOCTYPE html>
<html>
  <head>
    {% block title %}{% endblock %}
  </head>
  <body>
    {% block content %}{% endblock %}
  </body>
  <%block name="js"> {% endblock %} ${next.body()}
</html>

4. References

http://docs.makotemplates.org/en/latest/inheritance.html