A template is simply a text file. All Django templates by convention have
".html" extensions, but they can actually generate any text-based format (HTML,
XML, CSV, etc.).
To actually be useful, a template will contain **variables**, which get replaced
with values from the database when the template is evaluated, and **tags**,
which control the logic of the template.
Below is a minimal template that I'll be using to illustrate the parts of a template throughout this introduction::
{% extends base_generic %}
{% 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 %}
What's a variable?
==================
Variables look like this: ``{{ variable }}``. When the template engine
encounters a variable, it evaluates that variable and replaces the variable with
the result. Many variables will be structures with named attributes; you can
"drill down" into these structures with dots (``.``), so in the above example ``
{{ section.title }}`` will be replaces with the ``title`` attribute of the
``section`` object.
If you use a variable that doesn't exist, it will be silently ignored; the
variable will be replaced by nothingness.
See `Using the built-in reference`_, below, for help on finding what variables
are available in a given template.
Variables may be modified before being displayed by **filters**.
What's a filter?
================
Filters look like this: ``{{ name|lower }}``. This display the value of the
``{{ name }}`` variable after being filtered through the ``lower`` filter which,
as you might have guessed, lowercases the text passed through it.
We use the pipe character to apply filters to emphasize the analogy with filters
on a water pipe: text enters one side, has some operation performed on it, and
"flows" out the other side. Stretching the analogy to the breaking point,
filters may be "chained"; the output of one filter applied to the next: ``{{
text|escape|linebreaks }}`` is a common idiom for escaping text contents and
then converting line breaks to ``<p>`` tags.
Certain filters take arguments; a filter argument looks like this: ``{{
bio|truncatewords:"30" }}``. This will display the first 30 words of the
``bio`` variable. Filter arguments always are in double quotes.
The `Built-in filter reference`_ below describes all the built-in filters.
What's a tag?
=============
Tags look like this: ``{% tag %}``. Tags are much more complex than variables:
some create text in the output; some control flow by performing loops, or logic;
some load external information into the template to be used by later variables.
Some tags are "block" tags with matching beginning and ending tags (i.e. ``{% tag %} ... tag contents ... {% endtag %}``. The `Built-in tag reference`_ below describes all the built-in tags.
Template Inheritance
====================
The most powerful -- and thus the most complex -- part of Django's template
engine is template inheritance. In a nutshell, template inheritance allows you
to build a base "skeleton" template that contains all the common elements of
your site and defines **blocks** that child templates can override.
It's easiest to understand template inheritance by starting with an example::
<html>
<head>
<link rel="stylesheet" href="style.css" />
<title>{% block title %}My Amazing Site{% endblock %}</title>
</head>
<body>
<div id="sidebar">
{% block sidebar %}
<ul>
<li><a href="/">Home</a></li>
<li><a href="/blog/">Blog</a></li>
</ul>
{% endblock %}
</div>
<div id="content">
{% block content %}{% endblock %}
</div>
</body>
This template, which we'll call ``base.html`` defines a simple HTML skeleton
document that you might use for a simple two-column page. Since this template
won't actually be used directly, I've used the ``{% block %}`` tag to define the
three blocks that child templates will fill in. All that the ``block`` tag does
is to signal to the template engine that a child template may override those
portions of the template.
To use this template, I might define a child template as follows::
{% extends "base" %}
{% block title %}My Amazing Blog{% endblock %}
{% block content %}
{% for entry in blog_entries %}
<h2>{{ entry.title }}</h2>
<p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}
The ``{% extends %}`` tag is the key here; it tells the template engine that
this template "extends" another template. When this template is evaluated, the
first step the template engine will perform is to locate the parent template --
in this case, "base" (note the dropping of the ".html" extension). At that
point, the template engine will notice the three blocks in ``base.html``, and
replace those blocks with the contents of the child template. Depending on the
value of ``blog_entries``, the output might look like::
<html>
<head>
<link rel="stylesheet" href="style.css" />
<title>My Amazing Blog</title>
</head>
<body>
<div id="sidebar">
<ul>
<li><a href="/">Home</a></li>
<li><a href="/blog/">Blog</a></li>
</ul>
</div>
<div id="content">
<h2>Entry one</h2>
<p>This is my first entry.</p>
<h2>Entry two</h2>
<p>This is my second entry.</p>
</div>
</body>
Note that since the child template did not define the ``sidebar`` block, the
value from the parent template is used instead.
Template inheritance does not have to be only single-level; multi-level
inheritance is possible, and indeed, quite useful.
Here are some tips for working with inheritance:
* More ``{% block %}`` tags in your base templates are better. Remember,
child templates do not have to define all parent blocks, so you can
fill in reasonable defaults in a number of blocks, then only define
the ones you need later on.
* If you find yourself reproducing the same content in a number of
documents, it probably means you should move that content to a
new ``{% block %}`` in a parent template.
* We often prefer to use three-level inheritance: a single base template
for the entire site, a set of mid-level templates for each section of
the site, and then the individual templates for each page. This
maximizes code reuse, and makes adding items to places like the
section-wide navigation possible.
* 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.
Using the built-in reference
============================
Since Django can be used to develop any sort of site, the tags, filters, and
variables available will be different depending on the application. To make it
