Django Templates

A template is simply a text file. It can generate any text-based format (HTML, XML, CSV, etc.).

A template contains variables, which get replaced with values when the template is evaluated, and tags, which control the logic of the template.

Below is a minimal template that illustrates a few basics.

{% extends "base_generic.html" %}

{% block title %}{{ section.title }}{% endblock %}

{% block content %}
<h1>{{ section.title }}</h1>

{% for story in story_list %}
<h2>
  <a href="{{ story.get_absolute_url }}">
    {{ story.headline|upper }}
  </a>
</h2>
<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}
  • {% extends "base_generic.html" %} uses the literal value base_generic.html as the name of the parent template to extend.
  • for loops over each item in an array, making the item available in a context variable
  • upper converts a string into all uppercase.
  • truncatewords truncates a string after a certain number of words.

Template Inheritance

Let’s assume we create base.html which defines a simple HTML skeleton document that you might use for a basic html document. It’s the job of child template to fill the empty blocks with content.

In this example, the block tag defines three blocks that child template can fill in. All the block tag does is to tell the template engine that a child template may override those portions of the template.

A child template might look like this:

{% extends "base.html" %}

{% block title %}My Blog{% endblock %}

{% block content %}
{% for entry in blog_entries %}
    <h2>{{ entry.title }}</h2>
    <p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}

{{ block.super }}

So what is {{ block.super }}? And what is the purpose of it in Django Templates?

Let’s create a content block in example.html:

{% block content %}
    <p>Some example text.</p>
{% endblock %}

And then we can extend that block in a second.html template:

{% extends 'example.html' %}

{% block content %}
    <p>The previous example text is replaced by this text.</p>
{% endblock %}

In the second example above, only the latter sentence will be rendered: The previous example text is replaced by this text.

Some example text. is being overridden and replaced. You should use {{ block.super }} if you want both contents:

{% extends 'example.html' %}

{% block content %}
    {{ block.super }}
    <p>The previous example text is replaced by this text.</p>
{% endblock %}

It’s basically the same concept for super in any OOP; you call the constructor of the parent class to include whatever code is in there, instead of just overriding it.

From official Django Doc:

  • If you need to get the content of the block from the parent template, the {{ block.super }} variable will do the trick. This is useful if you want to add to the contents of a parent block instead of completely overriding it. Data inserted using {{ block.super }} will not be automatically escaped (see the next section), since it was already escaped, if necessary, in the parent template.