File: inheritance.html

package info (click to toggle)
jinja 0.9-2
links: PTS
area: main
in suites: etch, etch-m68k
size: 412 kB
ctags: 485
sloc: python: 2,551; makefile: 40
file content (223 lines) | stat: -rw-r--r-- 8,477 bytes
<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Template Inheritance | Jinja Documentation</title>
    <style text="text/css">
        body {
            font-family: 'Arial', sans-serif;
            margin: 1em;
            padding: 0;
        }

        #navigation {
            float: right;
            margin: -1em -1em 1em 1em;
            padding: 1em 2em 0 2em;
            border: 1px solid #bbb;
            border-width: 0 0 1px 1px;
            background-color: #f8f8f8;
        }

        #page {
            width: 45em;
        }

        a {
            color: #d00;
        }

        a:hover {
            color: #d40;
        }

        h1 {
            font-size: 2em;
            color: #d00;
            margin: 0.5em 0 0.5em 0;
            padding: 0;
        }

        h2 {
            font-size: 1.7em;
            color: #bd2121;
            margin: 1em 0 0.5em 0;
        }

        h3 {
            font-size: 1.3em;
            color: #8a2424;
            margin: 0.5em 0 0 0;
        }

        p {
            margin: 0.5em 1em 0.5em 1em;
        }

        pre {
            margin: 1em 0 1em 2em;
            padding: 0.5em;
            border-top: 1px solid #ddd;
            border-bottom: 1px solid #ddd;
            background-color: #f2f2f2;
            overflow: auto;
        }
        
        li {
            line-height: 1.4em;
        }
        
        hr {
            margin: 1em;
            padding: 0;
            height: 1px!important;
            background-color: #ccc;
            border: none!important;
        }
        
        div.admonition {
            margin: 1em 0 1em 1.5em;
            padding: 0.5em 0.5em 0.5em 2em;
            background-color: #f6e3e3;
            border: 1px solid #d50000;
            border-left: none;
            border-right: none;
        }
        
        div.admonition p.admonition-title {
            font-size: 1.1em;
            color: #d40;
            font-weight: bold;
            margin: 0 0 0.5em -1em;
        }
        
        table {
            border-collapse: collapse;
            margin: 1em 2em 1em 1.5em;
        }
        
        table td, table th {
            text-align: left;
            border: 1px solid #eee;
            padding: 0.3em;
        }
        
        table th {
            background-color: #d00000;
            color: white;
            border: 1px solid #d00000;
            border-bottom: 1px solid #eee;
        }
    </style>
</head>
<body>
    <div id="navigation">
        <h3>Documentation</h3>
        <ul>
            
            <li><a href="index.html">back to index</a></li>
            
            <li><a href="http://wsgiarea.pocoo.org/repos/jinja/trunk/docs/source/inheritance.txt">view source online</a></li>
        </ul>
        
            <h3>Table of Contents</h3>
            <ul>
            
                <li><a href="#base-template">Base Template</a></li>
            
                <li><a href="#child-template">Child Template</a></li>
            
            </ul>
        
    </div>
    <h1>Template Inheritance</h1>
    <div id="page">
        <p>The most powerful part of Jinja is template inheritance. Template inheritance
allows you to build a base &quot;skeleton&quot; template that contains all the common
elements of your site and defines <strong>blocks</strong> or <strong>markers</strong> that child
templates can override.</p>
<p>Sounds complicated but is very basic. It's easiest to understand it by starting
with an example.</p>
<div class="section">
<h2><a id="base-template" name="base-template">Base Template</a></h2>
<p>This template, which we'll call <tt class="docutils literal"><span class="pre">base.html</span></tt>, defines a simple HTML skeleton
document that you might use for a simple two-column page. It's the job of
&quot;child&quot; templates to fill the empty blocks with content:</p>
<pre class="literal-block">
&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.0 Strict//EN&quot;
 &quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd&quot;&gt;
&lt;html xmlns=&quot;http://www.w3.org/1999/xhtml&quot;&gt;
&lt;head&gt;
  &lt;link rel=&quot;stylesheet&quot; href=&quot;style.css&quot; /&gt;
  &lt;title&gt;{% marker &quot;title&quot; %} ~ My Webpage&lt;/title&gt;
  {% marker &quot;htmlhead&quot; %}
&lt;/head&gt;
&lt;body&gt;
  &lt;div id=&quot;content&quot;&gt;
    {% marker &quot;content&quot; %}
  &lt;/div&gt;

  &lt;div id=&quot;footer&quot;&gt;
    {% block &quot;footer&quot; %}
    &amp;copy; Copyright 2006 by &lt;a href=&quot;http://mydomain.tld&quot;&gt;myself&lt;/a&gt;.
    {% endblock %}
  &lt;/div&gt;
&lt;/body&gt;
</pre>
<p>In this example, the <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></tt> and <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">marker</span> <span class="pre">%}</span></tt> tags define four
blocks that child templates can fill in. All the <tt class="docutils literal"><span class="pre">block</span></tt> tag does is to
tell the template engine that a child template may override those portions
of the template. The <tt class="docutils literal"><span class="pre">marker</span></tt> tag is the same as an empty <tt class="docutils literal"><span class="pre">block</span></tt> tag.</p>
</div>
<div class="section">
<h2><a id="child-template" name="child-template">Child Template</a></h2>
<p>A child template might look like this:</p>
<pre class="literal-block">
{% extends &quot;base&quot; %}
{% marker &quot;title&quot; set &quot;Index&quot; %}

{% block &quot;htmlhead&quot; %}
  &lt;style type=&quot;text/css&quot;&gt;
    .important {
      color: #336699;
    }
  &lt;/style&gt;
{% endblock %}

{% block &quot;content&quot; %}
    &lt;h1&gt;Index&lt;/h1&gt;
    &lt;p&gt;
      Welcome on my awsome homepage.
    &lt;/p&gt;
{% endblock %}
</pre>
<p>The <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></tt> tag is the key here. It tells the template engine that
this template &quot;extends&quot; another template. When the template system evaluates
this template, first it locates the parent.</p>
<p>The filename of the template depends on the template loader. For example the
<tt class="docutils literal"><span class="pre">FileSystemReader</span></tt> allows you to access other templates by giving the
filename without the file extension. You can access subdirectory with an slash:</p>
<pre class="literal-block">
{% extends &quot;layout/default&quot; %}
</pre>
<p>But this behavior can depend on the application using Jinja.</p>
<p>Note that since the child template didn't define the <tt class="docutils literal"><span class="pre">footer</span></tt> block, the
value from the parent template is used instead. Content within a <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></tt>
tag, or the optional default value of a marker tag
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">marker</span> <span class="pre">&quot;name&quot;</span> <span class="pre">set</span> <span class="pre">&quot;value&quot;</span> <span class="pre">%}</span></tt> in a parent template is always used
as a fallback.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>You can't define multiple <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></tt> tags with the same name in the
same template. This limitation exists because a block tag works in &quot;both&quot;
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 <em>parent</em>. If there were
two similarly-named <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></tt> tags in a template, that template's
parent wouldn't know which one of the blocks' content to use.</p>
<p class="last">If you want to use a block only in one direction but use it twice you can
use the <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">capture</span> <span class="pre">%}</span></tt> tag. More information in the <a class="reference" href="./utils.html">utils</a> section.</p>
</div>
</div>

    </div>
</body>
</html>