← Back to branch summary

~ubuntu-branches/ubuntu/utopic/mako/utopic-proposed

« back to all changes in this revision

Viewing changes to doc/inheritance.html

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski
  • Date: 2014-06-10 20:38:26 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20140610203826-5gtppywd9v3gf14a
Tags: 1.0.0-1
* New upstream release
* Add python-changelog and python-sphinx-paramlinks to Build-Depends
  (needed while rebuilding documentation)
* Enable Python 3.X tests during build (add necessary packages to
  Build-Depends)
* Update links to upstream changelog (now points to changelog.rst)
* Add lintian override for source-is-missing doc/searchindex.js
  (this file is generated by sphinx-build, all sources are in the tarball)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/inheritance.html
6
6
    
7
7
                Inheritance
8
8
             —
9
 
    Mako 0.9.1 Documentation
 
9
    Mako 1.0.0 Documentation
10
10
</title>
11
11
 
12
12
<!-- begin iterate through sphinx environment css_files -->
13
13
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
14
14
    <link rel="stylesheet" href="_static/docs.css" type="text/css" />
15
15
    <link rel="stylesheet" href="_static/site.css" type="text/css" />
 
16
    <link rel="stylesheet" href="_static/changelog.css" type="text/css" />
 
17
    <link rel="stylesheet" href="_static/sphinx_paramlinks.css" type="text/css" />
16
18
<!-- end iterate through sphinx environment css_files -->
17
19
 
18
20
 
22
24
    <script type="text/javascript">
23
25
      var DOCUMENTATION_OPTIONS = {
24
26
          URL_ROOT:    './',
25
 
          VERSION:     '0.9.1',
 
27
          VERSION:     '1.0.0',
26
28
          COLLAPSE_MODINDEX: false,
27
29
          FILE_SUFFIX: '.html'
28
30
      };
32
34
        <script type="text/javascript" src="_static/doctools.js"></script>
33
35
    <link rel="index" title="Index" href="genindex.html" />
34
36
    <link rel="search" title="Search" href="search.html" />
35
 
    <link rel="top" title="Mako 0.9.1 Documentation" href="index.html" />
 
37
    <link rel="top" title="Mako 1.0.0 Documentation" href="index.html" />
36
38
        <link rel="next" title="Filtering and Buffering" href="filtering.html" />
37
39
        <link rel="prev" title="Namespaces" href="namespaces.html" />
38
40
 
71
73
 
72
74
 
73
75
<div id="docs-header">
74
 
    <h1>Mako 0.9.1 Documentation</h1>
 
76
    <h1>Mako 1.0.0 Documentation</h1>
75
77
 
76
78
    <div id="docs-search">
77
79
    Search:
83
85
    </div>
84
86
 
85
87
    <div id="docs-version-header">
86
 
        Release: <span class="version-num">0.9.1</span>
 
88
        Release: <span class="version-num">1.0.0</span>
87
89
 
88
90
    </div>
89
91
 
108
110
    </div>
109
111
 
110
112
    <div id="docs-navigation-banner">
111
 
        <a href="index.html">Mako 0.9.1 Documentation</a>
 
113
        <a href="index.html">Mako 1.0.0 Documentation</a>
112
114
        » 
113
115
                Inheritance
114
116
            
133
135
<li><a class="reference internal" href="#but-what-about-defs">But what about Defs?</a></li>
134
136
<li><a class="reference internal" href="#using-the-next-namespace-to-produce-content-wrapping">Using the <tt class="docutils literal"><span class="pre">next</span></tt> Namespace to Produce Content Wrapping</a></li>
135
137
<li><a class="reference internal" href="#using-the-parent-namespace-to-augment-defs">Using the <tt class="docutils literal"><span class="pre">parent</span></tt> Namespace to Augment Defs</a></li>
 
138
<li><a class="reference internal" href="#using-include-with-template-inheritance">Using <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt> with Template Inheritance</a></li>
136
139
<li><a class="reference internal" href="#inheritable-attributes">Inheritable Attributes</a></li>
137
140
</ul>
138
141
</li>
613
616
</div>
614
617
<p>and you&#8217;re now a template inheritance ninja!</p>
615
618
</div>
 
619
<div class="section" id="using-include-with-template-inheritance">
 
620
<h2>Using <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt> with Template Inheritance<a class="headerlink" href="#using-include-with-template-inheritance" title="Permalink to this headline">¶</a></h2>
 
621
<p>A common source of confusion is the behavior of the <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt> tag,
 
622
often in conjunction with its interaction within template inheritance.
 
623
Key to understanding the <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt> tag is that it is a <em>dynamic</em>, e.g.
 
624
runtime, include, and not a static include.   The <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt> is only processed
 
625
as the template renders, and not at inheritance setup time.   When encountered,
 
626
the referenced template is run fully as an entirely separate template with no
 
627
linkage to any current inheritance structure.</p>
 
628
<p>If the tag were on the other hand a <em>static</em> include, this would allow source
 
629
within the included template to interact within the same inheritance context
 
630
as the calling template, but currently Mako has no static include facility.</p>
 
631
<p>In practice, this means that <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt> elements defined in an <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt>
 
632
file will not interact with corresponding <tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt> elements in the calling
 
633
template.</p>
 
634
<p>A common mistake is along these lines:</p>
 
635
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## partials.mako</span><span class="x"></span>
 
636
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;header&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
637
<span class="x">    Global Header</span>
 
638
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
 
639
 
 
640
<span class="cp">## parent.mako</span><span class="x"></span>
 
641
<span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;partials.mako&quot;</span><span class="cp">&gt;</span>
 
642
 
 
643
<span class="cp">## child.mako</span><span class="x"></span>
 
644
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;parent.mako&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
645
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;header&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
646
<span class="x">    Custom Header</span>
 
647
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
 
648
</pre></div>
 
649
</div>
 
650
<p>Above, one might expect that the <tt class="docutils literal"><span class="pre">&quot;header&quot;</span></tt> block declared in <tt class="docutils literal"><span class="pre">child.mako</span></tt>
 
651
might be invoked, as a result of it overriding the same block present in
 
652
<tt class="docutils literal"><span class="pre">parent.mako</span></tt> via the include for <tt class="docutils literal"><span class="pre">partials.mako</span></tt>.  But this is not the case.
 
653
Instead, <tt class="docutils literal"><span class="pre">parent.mako</span></tt> will invoke <tt class="docutils literal"><span class="pre">partials.mako</span></tt>, which then invokes
 
654
<tt class="docutils literal"><span class="pre">&quot;header&quot;</span></tt> in <tt class="docutils literal"><span class="pre">partials.mako</span></tt>, and then is finished rendering.  Nothing
 
655
from <tt class="docutils literal"><span class="pre">child.mako</span></tt> will render; there is no interaction between the <tt class="docutils literal"><span class="pre">&quot;header&quot;</span></tt>
 
656
block in <tt class="docutils literal"><span class="pre">child.mako</span></tt> and the <tt class="docutils literal"><span class="pre">&quot;header&quot;</span></tt> block in <tt class="docutils literal"><span class="pre">partials.mako</span></tt>.</p>
 
657
<p>Instead, <tt class="docutils literal"><span class="pre">parent.mako</span></tt> must explicitly state the inheritance structure.
 
658
In order to call upon specific elements of <tt class="docutils literal"><span class="pre">partials.mako</span></tt>, we will call upon
 
659
it as a namespace:</p>
 
660
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## partials.mako</span><span class="x"></span>
 
661
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;header&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
662
<span class="x">    Global Header</span>
 
663
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
 
664
 
 
665
<span class="cp">## parent.mako</span><span class="x"></span>
 
666
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;partials&quot;</span> <span class="na">file=</span><span class="s">&quot;partials.mako&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
 
667
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;header&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
668
<span class="x">    </span><span class="cp">${</span><span class="n">partials</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
 
669
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
 
670
 
 
671
<span class="cp">## child.mako</span><span class="x"></span>
 
672
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;parent.mako&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
673
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;header&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
674
<span class="x">    Custom Header</span>
 
675
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
 
676
</pre></div>
 
677
</div>
 
678
<p>Where above, <tt class="docutils literal"><span class="pre">parent.mako</span></tt> states the inheritance structure that <tt class="docutils literal"><span class="pre">child.mako</span></tt>
 
679
is to participate within.  <tt class="docutils literal"><span class="pre">partials.mako</span></tt> only defines defs/blocks that can be
 
680
used on a per-name basis.</p>
 
681
<p>Another scenario is below, which results in both <tt class="docutils literal"><span class="pre">&quot;SectionA&quot;</span></tt> blocks being rendered for the <tt class="docutils literal"><span class="pre">child.mako</span></tt> document:</p>
 
682
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## base.mako</span><span class="x"></span>
 
683
<span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
 
684
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;SectionA&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
685
<span class="x">    base.mako</span>
 
686
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
 
687
 
 
688
<span class="cp">## parent.mako</span><span class="x"></span>
 
689
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.mako&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
690
<span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;child.mako&quot;</span><span class="cp">&gt;</span>
 
691
 
 
692
<span class="cp">## child.mako</span><span class="x"></span>
 
693
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;SectionA&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
694
<span class="x">    child.mako</span>
 
695
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
 
696
</pre></div>
 
697
</div>
 
698
<p>The resolution is similar; instead of using <tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt>, we call upon the blocks
 
699
of <tt class="docutils literal"><span class="pre">child.mako</span></tt> using a namespace:</p>
 
700
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">## parent.mako</span><span class="x"></span>
 
701
<span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.mako&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
702
<span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;child&quot;</span> <span class="na">file=</span><span class="s">&quot;child.mako&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
703
 
 
704
<span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;SectionA&quot;</span><span class="cp">&gt;</span><span class="x"></span>
 
705
<span class="x">    </span><span class="cp">${</span><span class="n">child</span><span class="o">.</span><span class="n">SectionA</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
 
706
<span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
 
707
</pre></div>
 
708
</div>
 
709
</div>
616
710
<div class="section" id="inheritable-attributes">
617
711
<span id="inheritance-attr"></span><h2>Inheritable Attributes<a class="headerlink" href="#inheritable-attributes" title="Permalink to this headline">¶</a></h2>
618
712
<p>The <a class="reference internal" href="namespaces.html#mako.runtime.Namespace.attr" title="mako.runtime.Namespace.attr"><tt class="xref py py-attr docutils literal"><span class="pre">attr</span></tt></a> accessor of the <a class="reference internal" href="namespaces.html#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">Namespace</span></tt></a> object