==================== 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:: {% marker "title" %} ~ My Webpage {% marker "htmlhead" %}

{% marker "content" %}

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" %} {% endblock %} {% block "content" %}

Index

Welcome on my awsome homepage.

{% 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