File: inheritance.html

package info (click to toggle)
jinja 1.2-2
links: PTS, VCS
area: main
in suites: lenny
size: 1,408 kB
ctags: 1,171
sloc: python: 6,438; ansic: 397; makefile: 74
file content (256 lines) | stat: -rw-r--r-- 17,389 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <title>Template Inheritance &mdash; Jinja Documentation</title>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">
  <link rel="stylesheet" href="style.css" type="text/css">
  <style type="text/css">
    .syntax  { background: #ffffff; }
.syntax .c { color: #888888 } /* Comment */
.syntax .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.syntax .k { color: #008800; font-weight: bold } /* Keyword */
.syntax .cm { color: #888888 } /* Comment.Multiline */
.syntax .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.syntax .c1 { color: #888888 } /* Comment.Single */
.syntax .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.syntax .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.syntax .ge { font-style: italic } /* Generic.Emph */
.syntax .gr { color: #aa0000 } /* Generic.Error */
.syntax .gh { color: #303030 } /* Generic.Heading */
.syntax .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.syntax .go { color: #888888 } /* Generic.Output */
.syntax .gp { color: #555555 } /* Generic.Prompt */
.syntax .gs { font-weight: bold } /* Generic.Strong */
.syntax .gu { color: #606060 } /* Generic.Subheading */
.syntax .gt { color: #aa0000 } /* Generic.Traceback */
.syntax .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.syntax .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.syntax .kp { color: #008800 } /* Keyword.Pseudo */
.syntax .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.syntax .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.syntax .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.syntax .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.syntax .na { color: #336699 } /* Name.Attribute */
.syntax .nb { color: #003388 } /* Name.Builtin */
.syntax .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.syntax .no { color: #003366; font-weight: bold } /* Name.Constant */
.syntax .nd { color: #555555 } /* Name.Decorator */
.syntax .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.syntax .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.syntax .nl { color: #336699; font-style: italic } /* Name.Label */
.syntax .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.syntax .py { color: #336699; font-weight: bold } /* Name.Property */
.syntax .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.syntax .nv { color: #336699 } /* Name.Variable */
.syntax .ow { color: #008800 } /* Operator.Word */
.syntax .w { color: #bbbbbb } /* Text.Whitespace */
.syntax .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.syntax .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.syntax .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.syntax .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.syntax .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.syntax .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.syntax .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.syntax .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.syntax .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.syntax .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.syntax .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.syntax .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.syntax .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.syntax .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.syntax .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.syntax .bp { color: #003388 } /* Name.Builtin.Pseudo */
.syntax .vc { color: #336699 } /* Name.Variable.Class */
.syntax .vg { color: #dd7700 } /* Name.Variable.Global */
.syntax .vi { color: #3333bb } /* Name.Variable.Instance */
.syntax .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
  </style>
</head>
<body>
  <div id="content">
    
      <h1 class="heading"><span>Jinja</span></h1>
      <h2 class="subheading">Template Inheritance</h2>
    
    
    <div id="toc">
      <h2>Navigation</h2>
      <ul>
        <li><a href="index.html">back to index</a></li>
      </ul>
      
        <h2>Contents</h2>
        <ul class="contents">
        
          <li><a href="#base-template">Base Template</a></li>
        
          <li><a href="#child-template">Child Template</a></li>
        
          <li><a href="#how-inheritance-works-internally">How Inheritance Works Internally</a></li>
        
          <li><a href="#super-blocks">Super Blocks</a></li>
        
          <li><a href="#block-shortcuts">Block Shortcuts</a></li>
        
        </ul>
      
    </div>
    
    <div id="contentwrapper">
      <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> 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>
<div class="syntax"><pre><span class="cp">&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.0 Strict//EN&quot;</span>
<span class="cp"> &quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd&quot;&gt;</span>
<span class="nt">&lt;html</span> <span class="na">xmlns=</span><span class="s">&quot;http://www.w3.org/1999/xhtml&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;head&gt;</span>
  <span class="nt">&lt;link</span> <span class="na">rel=</span><span class="s">&quot;stylesheet&quot;</span> <span class="na">href=</span><span class="s">&quot;style.css&quot;</span> <span class="nt">/&gt;</span>
  <span class="nt">&lt;title&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span> - My Webpage<span class="nt">&lt;/title&gt;</span>
  <span class="cp">{%</span> <span class="k">block</span> <span class="nv">html_head</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="nt">&lt;/head&gt;</span>
<span class="nt">&lt;body&gt;</span>
  <span class="nt">&lt;div</span> <span class="na">id=</span><span class="s">&quot;content&quot;</span><span class="nt">&gt;</span>
    <span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
  <span class="nt">&lt;/div&gt;</span>

  <span class="nt">&lt;div</span> <span class="na">id=</span><span class="s">&quot;footer&quot;</span><span class="nt">&gt;</span>
    <span class="cp">{%</span> <span class="k">block</span> <span class="nv">footer</span> <span class="cp">%}</span>
    <span class="ni">&amp;copy;</span> Copyright 2006 by <span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">&quot;http://mydomain.tld&quot;</span><span class="nt">&gt;</span>myself<span class="nt">&lt;/a&gt;</span>.
    <span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
  <span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;/body&gt;</span>
</pre></div>
<p>In this example, the <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></tt> tags define four blocks that child templates
can fill in. All the <cite>block</cite> tag does is to tell the template engine that a
child template may override those portions of the template.</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>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base.html&quot;</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>Index<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">html_head</span> <span class="cp">%}</span>
  <span class="nt">&lt;style </span><span class="na">type=</span><span class="s">&quot;text/css&quot;</span><span class="nt">&gt;</span>
    <span class="nc">.important</span> <span class="p">{</span>
      <span class="k">color</span><span class="o">:</span> <span class="m">#336699</span><span class="p">;</span>
    <span class="p">}</span>
  <span class="nt">&lt;/style&gt;</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
    <span class="nt">&lt;h1&gt;</span>Index<span class="nt">&lt;/h1&gt;</span>
    <span class="nt">&lt;p</span> <span class="na">class=</span><span class="s">&quot;important&quot;</span><span class="nt">&gt;</span>
      Welcome on my awsome homepage.
    <span class="nt">&lt;/p&gt;</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
<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.  It must be always the first tag
in a template but whitespace or a comment is allowed before.  This was not
enforced with Jinja 1.0 and 1.1, it does however raise a syntax error with
1.2 or later.</p>
<p>The filename of the template depends on the template loader. For example the
<tt class="docutils literal"><span class="pre">FileSystemLoader</span></tt> allows you to access other templates by giving the
filename. You can access templates in subdirectories with an slash:</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;layout/default.html&quot;</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<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.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">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>
</div>
</div>
<div class="section">
<h2><a id="how-inheritance-works-internally" name="how-inheritance-works-internally">How Inheritance Works Internally</a></h2>
<p>Inheritance in Jinja is straightforward. If a template contains an
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></tt> tag it's considered being a child template, otherwise it's
a layout template. In a layout template you can place blocks basically
everywhere. In a child template blocks can only be located either at the
top level or inside another block.</p>
<p>Data outside of a block in a child template is executed before the layout
template is rendered, thus you can use it to propagate data to the whole
inheritance chain. Having a block in an invalid position you will receive
an syntax error. Here some examples:</p>
<p><strong>impossible</strong>:</p>
<blockquote>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s1">&#39;master.html&#39;</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">if</span> <span class="nv">some_condition</span> <span class="cp">%}</span><span class="x"></span>
<span class="x">  </span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">body</span> <span class="cp">%}</span><span class="x"></span>
<span class="x">    ...</span>
<span class="x">  </span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<p>This can't work because template inheritance works at translation /
compilation time not at template execution.</p>
</blockquote>
<p><strong>possible</strong>:</p>
<blockquote>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">extends</span> <span class="s1">&#39;master.html&#39;</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">body</span> <span class="cp">%}</span><span class="x"></span>
<span class="x">  </span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">some_condition</span> <span class="cp">%}</span><span class="x"></span>
<span class="x">    </span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">myblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="x">      ...</span>
<span class="x">    </span><span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
<span class="x">  </span><span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span><span class="x"></span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<p>This can work although it probably makes no sense in this specific case.
However the condition is handled at runtime because it's in a valid block
and defines a new block subtemplates can override.</p>
</blockquote>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">Unlike Python Jinja does not support multiple inheritance.  So you can
only have one extends tag with only one constant string argument.</p>
</div>
</div>
<div class="section">
<h2><a id="super-blocks" name="super-blocks">Super Blocks</a></h2>
<p>Starting with <cite>Jinja 1.1</cite> it's possible to render the contents of the parent
block. By calling it you get the results of the parent block back. If you want
to get the data of the parent you can give it an offset:</p>
<div class="syntax"><pre><span class="cp">{{</span> <span class="nv">super</span><span class="o">()</span> <span class="cp">}}</span><span class="x"></span>
<span class="x">    return the parent data</span>

<span class="cp">{{</span> <span class="nv">super</span><span class="o">(</span><span class="m">1</span><span class="o">)</span> <span class="cp">}}</span><span class="x"></span>
<span class="x">    the same as above</span>

<span class="cp">{{</span> <span class="nv">super</span><span class="o">(</span><span class="m">2</span><span class="o">)</span> <span class="cp">}}</span><span class="x"></span>
<span class="x">    return the data of the second parent block</span>
</pre></div>
</div>
<div class="section">
<h2><a id="block-shortcuts" name="block-shortcuts">Block Shortcuts</a></h2>
<p>With Jinja 1.1 onwards it's possible to have a shortcut syntax for blocks
with few content. The following constructs do the same:</p>
<div class="syntax"><pre><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{{</span> <span class="nv">page_title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="x"></span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="nv">page_title</span> <span class="cp">%}</span><span class="x"></span>
</pre></div>
<p>Note that as soon as you specify a second argument it's threated as
short block and Jinja won't look for an closing tag.</p>
</div>

    </div>
  </div>
</body>
<!-- generated on: 2007-11-17 18:18:06.064341
     file id: inheritance -->
</html>