====================
Template Inheritance
====================

The most powerful part of Jinja is template inheritance. Template inheritance
allows you to build a base "skeleton" template that contains all the common
elements of your site and defines **blocks** or **markers** that child
templates can override.

Sounds complicated but is very basic. It's easiest to understand it by starting
with an example.

Base Template
=============

This template, which we'll call ``base.html``, defines a simple HTML skeleton
document that you might use for a simple two-column page. It's the job of
"child" templates to fill the empty blocks with content::

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <link rel="stylesheet" href="style.css" />
      <title>{% marker "title" %} ~ My Webpage</title>
      {% marker "htmlhead" %}
    </head>
    <body>
      <div id="content">
        {% marker "content" %}
      </div>

      <div id="footer">
        {% block "footer" %}
        &copy; Copyright 2006 by <a href="http://mydomain.tld">myself</a>.
        {% endblock %}
      </div>
    </body>

In this example, the ``{% block %}`` and ``{% marker %}`` tags define four
blocks that child templates 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. The ``marker`` tag is the same as an empty ``block`` tag.

Child Template
==============

A child template might look like this::

    {% extends "base" %}
    {% marker "title" set "Index" %}

    {% block "htmlhead" %}
      <style type="text/css">
        .important {
          color: #336699;
        }
      </style>
    {% endblock %}
    
    {% block "content" %}
        <h1>Index</h1>
        <p>
          Welcome on my awsome homepage.
        </p>
    {% endblock %}

The ``{% extends %}`` tag is the key here. It tells the template engine that
this template "extends" another template. When the template system evaluates
this template, first it locates the parent.

The filename of the template depends on the template loader. For example the
``FileSystemReader`` allows you to access other templates by giving the
filename without the file extension. You can access subdirectory with an slash::

    {% extends "layout/default" %}

But this behavior can depend on the application using Jinja.

Note that since the child template didn't define the ``footer`` block, the
value from the parent template is used instead. Content within a ``{% block %}``
tag, or the optional default value of a marker tag
``{% marker "name" set "value" %}`` in a parent template is always used
as a fallback.

.. admonition:: Note

    You can't define multiple ``{% block %}`` tags with the same name in the
    same template. This limitation exists because a block tag works in "both"
    directions. That is, a block tag doesn't just provide a hole to fill - it
    also defines the content that fills the hole in the *parent*. If there were
    two similarly-named ``{% block %}`` tags in a template, that template's
    parent wouldn't know which one of the blocks' content to use.

    If you want to use a block only in one direction but use it twice you can
    use the ``{% capture %}`` tag. More information in the `utils`_ section.

.. _utils: utils.txt
