inheritance.html 60 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778
  1. <html xmlns="http://www.w3.org/1999/xhtml">
  2. <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  3. <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
  4. <head>
  5. <title>
  6. Inheritance
  7. &mdash;
  8. Mako 1.0.7 Documentation
  9. </title>
  10. <!-- begin iterate through sphinx environment css_files -->
  11. <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  12. <link rel="stylesheet" href="_static/docs.css" type="text/css" />
  13. <link rel="stylesheet" href="_static/site.css" type="text/css" />
  14. <link rel="stylesheet" href="_static/changelog.css" type="text/css" />
  15. <link rel="stylesheet" href="_static/sphinx_paramlinks.css" type="text/css" />
  16. <!-- end iterate through sphinx environment css_files -->
  17. <script type="text/javascript">
  18. var DOCUMENTATION_OPTIONS = {
  19. URL_ROOT: './',
  20. VERSION: '1.0.7',
  21. COLLAPSE_MODINDEX: false,
  22. FILE_SUFFIX: '.html'
  23. };
  24. </script>
  25. <script type="text/javascript" src="_static/jquery.js"></script>
  26. <script type="text/javascript" src="_static/underscore.js"></script>
  27. <script type="text/javascript" src="_static/doctools.js"></script>
  28. <link rel="index" title="Index" href="genindex.html" />
  29. <link rel="search" title="Search" href="search.html" />
  30. <link rel="top" title="Mako 1.0.7 Documentation" href="index.html" />
  31. <link rel="next" title="Filtering and Buffering" href="filtering.html" />
  32. <link rel="prev" title="Namespaces" href="namespaces.html" />
  33. </head>
  34. <body>
  35. <div id="wrap">
  36. <div class="rightbar">
  37. <div class="slogan">
  38. Hyperfast and lightweight templating for the Python platform.
  39. </div>
  40. </div>
  41. <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
  42. <hr/>
  43. <div id="docs-container">
  44. <div id="docs-header">
  45. <h1>Mako 1.0.7 Documentation</h1>
  46. <div id="docs-search">
  47. Search:
  48. <form class="search" action="search.html" method="get">
  49. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  50. <input type="hidden" name="check_keywords" value="yes" />
  51. <input type="hidden" name="area" value="default" />
  52. </form>
  53. </div>
  54. <div id="docs-version-header">
  55. Release: <span class="version-num">1.0.7</span>
  56. </div>
  57. </div>
  58. <div id="docs-top-navigation">
  59. <div id="docs-top-page-control" class="docs-navigation-links">
  60. <ul>
  61. <li>Prev:
  62. <a href="namespaces.html" title="previous chapter">Namespaces</a>
  63. </li>
  64. <li>Next:
  65. <a href="filtering.html" title="next chapter">Filtering and Buffering</a>
  66. </li>
  67. <li>
  68. <a href="index.html">Table of Contents</a> |
  69. <a href="genindex.html">Index</a>
  70. | <a href="_sources/inheritance.rst.txt">view source
  71. </li>
  72. </ul>
  73. </div>
  74. <div id="docs-navigation-banner">
  75. <a href="index.html">Mako 1.0.7 Documentation</a>
  76. »
  77. Inheritance
  78. <h2>
  79. Inheritance
  80. </h2>
  81. </div>
  82. </div>
  83. <div id="docs-body-container">
  84. <div id="docs-sidebar">
  85. <h3><a href="index.html">Table of Contents</a></h3>
  86. <ul>
  87. <li><a class="reference internal" href="#">Inheritance</a><ul>
  88. <li><a class="reference internal" href="#nesting-blocks">Nesting Blocks</a></li>
  89. <li><a class="reference internal" href="#rendering-a-named-block-multiple-times">Rendering a Named Block Multiple Times</a></li>
  90. <li><a class="reference internal" href="#but-what-about-defs">But what about Defs?</a></li>
  91. <li><a class="reference internal" href="#using-the-next-namespace-to-produce-content-wrapping">Using the <code class="docutils literal"><span class="pre">next</span></code> Namespace to Produce Content Wrapping</a></li>
  92. <li><a class="reference internal" href="#using-the-parent-namespace-to-augment-defs">Using the <code class="docutils literal"><span class="pre">parent</span></code> Namespace to Augment Defs</a></li>
  93. <li><a class="reference internal" href="#using-include-with-template-inheritance">Using <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> with Template Inheritance</a></li>
  94. <li><a class="reference internal" href="#inheritable-attributes">Inheritable Attributes</a></li>
  95. </ul>
  96. </li>
  97. </ul>
  98. <h4>Previous Topic</h4>
  99. <p>
  100. <a href="namespaces.html" title="previous chapter">Namespaces</a>
  101. </p>
  102. <h4>Next Topic</h4>
  103. <p>
  104. <a href="filtering.html" title="next chapter">Filtering and Buffering</a>
  105. </p>
  106. <h4>Quick Search</h4>
  107. <p>
  108. <form class="search" action="search.html" method="get">
  109. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  110. <input type="hidden" name="check_keywords" value="yes" />
  111. <input type="hidden" name="area" value="default" />
  112. </form>
  113. </p>
  114. </div>
  115. <div id="docs-body" class="withsidebar" >
  116. <div class="section" id="inheritance">
  117. <span id="inheritance-toplevel"></span><h1>Inheritance<a class="headerlink" href="#inheritance" title="Permalink to this headline">¶</a></h1>
  118. <div class="admonition note">
  119. <p class="first admonition-title">Note</p>
  120. <p class="last">Most of the inheritance examples here take advantage of a feature that&#8217;s
  121. new in Mako as of version 0.4.1 called the &#8220;block&#8221;. This tag is very similar to
  122. the &#8220;def&#8221; tag but is more streamlined for usage with inheritance. Note that
  123. all of the examples here which use blocks can also use defs instead. Contrasting
  124. usages will be illustrated.</p>
  125. </div>
  126. <p>Using template inheritance, two or more templates can organize
  127. themselves into an <strong>inheritance chain</strong>, where content and
  128. functions from all involved templates can be intermixed. The
  129. general paradigm of template inheritance is this: if a template
  130. <code class="docutils literal"><span class="pre">A</span></code> inherits from template <code class="docutils literal"><span class="pre">B</span></code>, then template <code class="docutils literal"><span class="pre">A</span></code> agrees
  131. to send the executional control to template <code class="docutils literal"><span class="pre">B</span></code> at runtime
  132. (<code class="docutils literal"><span class="pre">A</span></code> is called the <strong>inheriting</strong> template). Template <code class="docutils literal"><span class="pre">B</span></code>,
  133. the <strong>inherited</strong> template, then makes decisions as to what
  134. resources from <code class="docutils literal"><span class="pre">A</span></code> shall be executed.</p>
  135. <p>In practice, it looks like this. Here&#8217;s a hypothetical inheriting
  136. template, <code class="docutils literal"><span class="pre">index.html</span></code>:</p>
  137. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## index.html</span><span class="x"></span>
  138. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  139. <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>
  140. <span class="x"> this is some header content</span>
  141. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  142. <span class="x">this is the body content.</span>
  143. </pre></div>
  144. </div>
  145. <p>And <code class="docutils literal"><span class="pre">base.html</span></code>, the inherited template:</p>
  146. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## base.html</span><span class="x"></span>
  147. <span class="x">&lt;html&gt;</span>
  148. <span class="x"> &lt;body&gt;</span>
  149. <span class="x"> &lt;div class=&quot;header&quot;&gt;</span>
  150. <span class="x"> </span><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>
  151. <span class="x"> &lt;/div&gt;</span>
  152. <span class="x"> </span><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>
  153. <span class="x"> &lt;div class=&quot;footer&quot;&gt;</span>
  154. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;footer&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  155. <span class="x"> this is the footer</span>
  156. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  157. <span class="x"> &lt;/div&gt;</span>
  158. <span class="x"> &lt;/body&gt;</span>
  159. <span class="x">&lt;/html&gt;</span>
  160. </pre></div>
  161. </div>
  162. <p>Here is a breakdown of the execution:</p>
  163. <ol class="arabic">
  164. <li><p class="first">When <code class="docutils literal"><span class="pre">index.html</span></code> is rendered, control immediately passes to
  165. <code class="docutils literal"><span class="pre">base.html</span></code>.</p>
  166. </li>
  167. <li><p class="first"><code class="docutils literal"><span class="pre">base.html</span></code> then renders the top part of an HTML document,
  168. then invokes the <code class="docutils literal"><span class="pre">&lt;%block</span> <span class="pre">name=&quot;header&quot;&gt;</span></code> block. It invokes the
  169. underlying <code class="docutils literal"><span class="pre">header()</span></code> function off of a built-in namespace
  170. called <code class="docutils literal"><span class="pre">self</span></code> (this namespace was first introduced in the
  171. <a class="reference internal" href="namespaces.html"><span class="doc">Namespaces chapter</span></a> in <a class="reference internal" href="namespaces.html#namespace-self"><span class="std std-ref">self</span></a>). Since
  172. <code class="docutils literal"><span class="pre">index.html</span></code> is the topmost template and also defines a block
  173. called <code class="docutils literal"><span class="pre">header</span></code>, it&#8217;s this <code class="docutils literal"><span class="pre">header</span></code> block that ultimately gets
  174. executed &#8211; instead of the one that&#8217;s present in <code class="docutils literal"><span class="pre">base.html</span></code>.</p>
  175. </li>
  176. <li><p class="first">Control comes back to <code class="docutils literal"><span class="pre">base.html</span></code>. Some more HTML is
  177. rendered.</p>
  178. </li>
  179. <li><p class="first"><code class="docutils literal"><span class="pre">base.html</span></code> executes <code class="docutils literal"><span class="pre">self.body()</span></code>. The <code class="docutils literal"><span class="pre">body()</span></code>
  180. function on all template-based namespaces refers to the main
  181. body of the template, therefore the main body of
  182. <code class="docutils literal"><span class="pre">index.html</span></code> is rendered.</p>
  183. </li>
  184. <li><p class="first">When <code class="docutils literal"><span class="pre">&lt;%block</span> <span class="pre">name=&quot;header&quot;&gt;</span></code> is encountered in <code class="docutils literal"><span class="pre">index.html</span></code>
  185. during the <code class="docutils literal"><span class="pre">self.body()</span></code> call, a conditional is checked &#8211; does the
  186. current inherited template, i.e. <code class="docutils literal"><span class="pre">base.html</span></code>, also define this block? If yes,
  187. the <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> is <strong>not</strong> executed here &#8211; the inheritance
  188. mechanism knows that the parent template is responsible for rendering
  189. this block (and in fact it already has). In other words a block
  190. only renders in its <em>basemost scope</em>.</p>
  191. </li>
  192. <li><p class="first">Control comes back to <code class="docutils literal"><span class="pre">base.html</span></code>. More HTML is rendered,
  193. then the <code class="docutils literal"><span class="pre">&lt;%block</span> <span class="pre">name=&quot;footer&quot;&gt;</span></code> expression is invoked.</p>
  194. </li>
  195. <li><p class="first">The <code class="docutils literal"><span class="pre">footer</span></code> block is only defined in <code class="docutils literal"><span class="pre">base.html</span></code>, so being
  196. the topmost definition of <code class="docutils literal"><span class="pre">footer</span></code>, it&#8217;s the one that
  197. executes. If <code class="docutils literal"><span class="pre">index.html</span></code> also specified <code class="docutils literal"><span class="pre">footer</span></code>, then
  198. its version would <strong>override</strong> that of the base.</p>
  199. </li>
  200. <li><p class="first"><code class="docutils literal"><span class="pre">base.html</span></code> finishes up rendering its HTML and the template
  201. is complete, producing:</p>
  202. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">html</span><span class="p">&gt;</span>
  203. <span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
  204. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;header&quot;</span><span class="p">&gt;</span>
  205. this is some header content
  206. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  207. this is the body content.
  208. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;footer&quot;</span><span class="p">&gt;</span>
  209. this is the footer
  210. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  211. <span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
  212. <span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
  213. </pre></div>
  214. </div>
  215. </li>
  216. </ol>
  217. <p>...and that is template inheritance in a nutshell. The main idea
  218. is that the methods that you call upon <code class="docutils literal"><span class="pre">self</span></code> always
  219. correspond to the topmost definition of that method. Very much
  220. the way <code class="docutils literal"><span class="pre">self</span></code> works in a Python class, even though Mako is
  221. not actually using Python class inheritance to implement this
  222. functionality. (Mako doesn&#8217;t take the &#8220;inheritance&#8221; metaphor too
  223. seriously; while useful to setup some commonly recognized
  224. semantics, a textual template is not very much like an
  225. object-oriented class construct in practice).</p>
  226. <div class="section" id="nesting-blocks">
  227. <h2>Nesting Blocks<a class="headerlink" href="#nesting-blocks" title="Permalink to this headline">¶</a></h2>
  228. <p>The named blocks defined in an inherited template can also be nested within
  229. other blocks. The name given to each block is globally accessible via any inheriting
  230. template. We can add a new block <code class="docutils literal"><span class="pre">title</span></code> to our <code class="docutils literal"><span class="pre">header</span></code> block:</p>
  231. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## base.html</span><span class="x"></span>
  232. <span class="x">&lt;html&gt;</span>
  233. <span class="x"> &lt;body&gt;</span>
  234. <span class="x"> &lt;div class=&quot;header&quot;&gt;</span>
  235. <span class="x"> </span><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>
  236. <span class="x"> &lt;h2&gt;</span>
  237. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;title&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  238. <span class="x"> &lt;/h2&gt;</span>
  239. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  240. <span class="x"> &lt;/div&gt;</span>
  241. <span class="x"> </span><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>
  242. <span class="x"> &lt;div class=&quot;footer&quot;&gt;</span>
  243. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;footer&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  244. <span class="x"> this is the footer</span>
  245. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  246. <span class="x"> &lt;/div&gt;</span>
  247. <span class="x"> &lt;/body&gt;</span>
  248. <span class="x">&lt;/html&gt;</span>
  249. </pre></div>
  250. </div>
  251. <p>The inheriting template can name either or both of <code class="docutils literal"><span class="pre">header</span></code> and <code class="docutils literal"><span class="pre">title</span></code>, separately
  252. or nested themselves:</p>
  253. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## index.html</span><span class="x"></span>
  254. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  255. <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>
  256. <span class="x"> this is some header content</span>
  257. <span class="x"> </span><span class="cp">${</span><span class="n">parent</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  258. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  259. <span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;title&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  260. <span class="x"> this is the title</span>
  261. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  262. <span class="x">this is the body content.</span>
  263. </pre></div>
  264. </div>
  265. <p>Note when we overrode <code class="docutils literal"><span class="pre">header</span></code>, we added an extra call <code class="docutils literal"><span class="pre">${parent.header()}</span></code> in order to invoke
  266. the parent&#8217;s <code class="docutils literal"><span class="pre">header</span></code> block in addition to our own. That&#8217;s described in more detail below,
  267. in <a class="reference internal" href="#parent-namespace"><span class="std std-ref">Using the parent Namespace to Augment Defs</span></a>.</p>
  268. </div>
  269. <div class="section" id="rendering-a-named-block-multiple-times">
  270. <h2>Rendering a Named Block Multiple Times<a class="headerlink" href="#rendering-a-named-block-multiple-times" title="Permalink to this headline">¶</a></h2>
  271. <p>Recall from the section <a class="reference internal" href="defs.html#blocks"><span class="std std-ref">Using Blocks</span></a> that a named block is just like a <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>,
  272. with some different usage rules. We can call one of our named sections distinctly, for example
  273. a section that is used more than once, such as the title of a page:</p>
  274. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;html&gt;</span>
  275. <span class="x"> &lt;head&gt;</span>
  276. <span class="x"> &lt;title&gt;</span><span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">()</span><span class="cp">}</span><span class="x">&lt;/title&gt;</span>
  277. <span class="x"> &lt;/head&gt;</span>
  278. <span class="x"> &lt;body&gt;</span>
  279. <span class="x"> </span><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>
  280. <span class="x"> &lt;h2&gt;</span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;title&quot;</span><span class="cp">/&gt;</span><span class="x">&lt;/h2&gt;</span>
  281. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  282. <span class="x"> </span><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>
  283. <span class="x"> &lt;/body&gt;</span>
  284. <span class="x">&lt;/html&gt;</span>
  285. </pre></div>
  286. </div>
  287. <p>Where above an inheriting template can define <code class="docutils literal"><span class="pre">&lt;%block</span> <span class="pre">name=&quot;title&quot;&gt;</span></code> just once, and it will be
  288. used in the base template both in the <code class="docutils literal"><span class="pre">&lt;title&gt;</span></code> section as well as the <code class="docutils literal"><span class="pre">&lt;h2&gt;</span></code>.</p>
  289. </div>
  290. <div class="section" id="but-what-about-defs">
  291. <h2>But what about Defs?<a class="headerlink" href="#but-what-about-defs" title="Permalink to this headline">¶</a></h2>
  292. <p>The previous example used the <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> tag to produce areas of content
  293. to be overridden. Before Mako 0.4.1, there wasn&#8217;t any such tag &#8211; instead
  294. there was only the <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> tag. As it turns out, named blocks and defs are
  295. largely interchangeable. The def simply doesn&#8217;t call itself automatically,
  296. and has more open-ended naming and scoping rules that are more flexible and similar
  297. to Python itself, but less suited towards layout. The first example from
  298. this chapter using defs would look like:</p>
  299. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## index.html</span><span class="x"></span>
  300. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  301. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;header()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  302. <span class="x"> this is some header content</span>
  303. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  304. <span class="x">this is the body content.</span>
  305. </pre></div>
  306. </div>
  307. <p>And <code class="docutils literal"><span class="pre">base.html</span></code>, the inherited template:</p>
  308. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## base.html</span><span class="x"></span>
  309. <span class="x">&lt;html&gt;</span>
  310. <span class="x"> &lt;body&gt;</span>
  311. <span class="x"> &lt;div class=&quot;header&quot;&gt;</span>
  312. <span class="x"> </span><span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  313. <span class="x"> &lt;/div&gt;</span>
  314. <span class="x"> </span><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>
  315. <span class="x"> &lt;div class=&quot;footer&quot;&gt;</span>
  316. <span class="x"> </span><span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">footer</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  317. <span class="x"> &lt;/div&gt;</span>
  318. <span class="x"> &lt;/body&gt;</span>
  319. <span class="x">&lt;/html&gt;</span>
  320. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;header()&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  321. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;footer()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  322. <span class="x"> this is the footer</span>
  323. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  324. </pre></div>
  325. </div>
  326. <p>Above, we illustrate that defs differ from blocks in that their definition
  327. and invocation are defined in two separate places, instead of at once. You can <em>almost</em> do exactly what a
  328. block does if you put the two together:</p>
  329. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;div class=&quot;header&quot;&gt;</span>
  330. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;header()&quot;</span><span class="cp">&gt;&lt;/%</span><span class="nb">def</span><span class="cp">&gt;${</span><span class="bp">self</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  331. <span class="x">&lt;/div&gt;</span>
  332. </pre></div>
  333. </div>
  334. <p>The <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> is obviously more streamlined than the <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> for this kind
  335. of usage. In addition,
  336. the above &#8220;inline&#8221; approach with <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> does not work with nesting:</p>
  337. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;head&gt;</span>
  338. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;header()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  339. <span class="x"> &lt;title&gt;</span>
  340. <span class="x"> ## this won&#39;t work !</span>
  341. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;title()&quot;</span><span class="cp">&gt;</span><span class="x">default title</span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;${</span><span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  342. <span class="x"> &lt;/title&gt;</span>
  343. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;${</span><span class="bp">self</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  344. <span class="x">&lt;/head&gt;</span>
  345. </pre></div>
  346. </div>
  347. <p>Where above, the <code class="docutils literal"><span class="pre">title()</span></code> def, because it&#8217;s a def within a def, is not part of the
  348. template&#8217;s exported namespace and will not be part of <code class="docutils literal"><span class="pre">self</span></code>. If the inherited template
  349. did define its own <code class="docutils literal"><span class="pre">title</span></code> def at the top level, it would be called, but the &#8220;default title&#8221;
  350. above is not present at all on <code class="docutils literal"><span class="pre">self</span></code> no matter what. For this to work as expected
  351. you&#8217;d instead need to say:</p>
  352. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;head&gt;</span>
  353. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;header()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  354. <span class="x"> &lt;title&gt;</span>
  355. <span class="x"> </span><span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">title</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  356. <span class="x"> &lt;/title&gt;</span>
  357. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;${</span><span class="bp">self</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  358. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;title()&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  359. <span class="x">&lt;/head&gt;</span>
  360. </pre></div>
  361. </div>
  362. <p>That is, <code class="docutils literal"><span class="pre">title</span></code> is defined outside of any other defs so that it is in the <code class="docutils literal"><span class="pre">self</span></code> namespace.
  363. It works, but the definition needs to be potentially far away from the point of render.</p>
  364. <p>A named block is always placed in the <code class="docutils literal"><span class="pre">self</span></code> namespace, regardless of nesting,
  365. so this restriction is lifted:</p>
  366. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## base.html</span><span class="x"></span>
  367. <span class="x">&lt;head&gt;</span>
  368. <span class="x"> </span><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>
  369. <span class="x"> &lt;title&gt;</span>
  370. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;title&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  371. <span class="x"> &lt;/title&gt;</span>
  372. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  373. <span class="x">&lt;/head&gt;</span>
  374. </pre></div>
  375. </div>
  376. <p>The above template defines <code class="docutils literal"><span class="pre">title</span></code> inside of <code class="docutils literal"><span class="pre">header</span></code>, and an inheriting template can define
  377. one or both in <strong>any</strong> configuration, nested inside each other or not, in order for them to be used:</p>
  378. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## index.html</span><span class="x"></span>
  379. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  380. <span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;title&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  381. <span class="x"> the title</span>
  382. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  383. <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>
  384. <span class="x"> the header</span>
  385. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  386. </pre></div>
  387. </div>
  388. <p>So while the <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> tag lifts the restriction of nested blocks not being available externally,
  389. in order to achieve this it <em>adds</em> the restriction that all block names in a single template need
  390. to be globally unique within the template, and additionally that a <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> can&#8217;t be defined
  391. inside of a <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>. It&#8217;s a more restricted tag suited towards a more specific use case than <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>.</p>
  392. </div>
  393. <div class="section" id="using-the-next-namespace-to-produce-content-wrapping">
  394. <h2>Using the <code class="docutils literal"><span class="pre">next</span></code> Namespace to Produce Content Wrapping<a class="headerlink" href="#using-the-next-namespace-to-produce-content-wrapping" title="Permalink to this headline">¶</a></h2>
  395. <p>Sometimes you have an inheritance chain that spans more than two
  396. templates. Or maybe you don&#8217;t, but you&#8217;d like to build your
  397. system such that extra inherited templates can be inserted in
  398. the middle of a chain where they would be smoothly integrated.
  399. If each template wants to define its layout just within its main
  400. body, you can&#8217;t just call <code class="docutils literal"><span class="pre">self.body()</span></code> to get at the
  401. inheriting template&#8217;s body, since that is only the topmost body.
  402. To get at the body of the <em>next</em> template, you call upon the
  403. namespace <code class="docutils literal"><span class="pre">next</span></code>, which is the namespace of the template
  404. <strong>immediately following</strong> the current template.</p>
  405. <p>Lets change the line in <code class="docutils literal"><span class="pre">base.html</span></code> which calls upon
  406. <code class="docutils literal"><span class="pre">self.body()</span></code> to instead call upon <code class="docutils literal"><span class="pre">next.body()</span></code>:</p>
  407. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## base.html</span><span class="x"></span>
  408. <span class="x">&lt;html&gt;</span>
  409. <span class="x"> &lt;body&gt;</span>
  410. <span class="x"> &lt;div class=&quot;header&quot;&gt;</span>
  411. <span class="x"> </span><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>
  412. <span class="x"> &lt;/div&gt;</span>
  413. <span class="x"> </span><span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  414. <span class="x"> &lt;div class=&quot;footer&quot;&gt;</span>
  415. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;footer&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  416. <span class="x"> this is the footer</span>
  417. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  418. <span class="x"> &lt;/div&gt;</span>
  419. <span class="x"> &lt;/body&gt;</span>
  420. <span class="x">&lt;/html&gt;</span>
  421. </pre></div>
  422. </div>
  423. <p>Lets also add an intermediate template called <code class="docutils literal"><span class="pre">layout.html</span></code>,
  424. which inherits from <code class="docutils literal"><span class="pre">base.html</span></code>:</p>
  425. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## layout.html</span><span class="x"></span>
  426. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;base.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  427. <span class="x">&lt;ul&gt;</span>
  428. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;toolbar&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  429. <span class="x"> &lt;li&gt;selection 1&lt;/li&gt;</span>
  430. <span class="x"> &lt;li&gt;selection 2&lt;/li&gt;</span>
  431. <span class="x"> &lt;li&gt;selection 3&lt;/li&gt;</span>
  432. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  433. <span class="x">&lt;/ul&gt;</span>
  434. <span class="x">&lt;div class=&quot;mainlayout&quot;&gt;</span>
  435. <span class="x"> </span><span class="cp">${</span><span class="nb">next</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  436. <span class="x">&lt;/div&gt;</span>
  437. </pre></div>
  438. </div>
  439. <p>And finally change <code class="docutils literal"><span class="pre">index.html</span></code> to inherit from
  440. <code class="docutils literal"><span class="pre">layout.html</span></code> instead:</p>
  441. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## index.html</span><span class="x"></span>
  442. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;layout.html&quot;</span><span class="cp">/&gt;</span>
  443. <span class="cp">## .. rest of template</span><span class="x"></span>
  444. </pre></div>
  445. </div>
  446. <p>In this setup, each call to <code class="docutils literal"><span class="pre">next.body()</span></code> will render the body
  447. of the next template in the inheritance chain (which can be
  448. written as <code class="docutils literal"><span class="pre">base.html</span> <span class="pre">-&gt;</span> <span class="pre">layout.html</span> <span class="pre">-&gt;</span> <span class="pre">index.html</span></code>). Control
  449. is still first passed to the bottommost template <code class="docutils literal"><span class="pre">base.html</span></code>,
  450. and <code class="docutils literal"><span class="pre">self</span></code> still references the topmost definition of any
  451. particular def.</p>
  452. <p>The output we get would be:</p>
  453. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">html</span><span class="p">&gt;</span>
  454. <span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
  455. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;header&quot;</span><span class="p">&gt;</span>
  456. this is some header content
  457. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  458. <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
  459. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 1<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  460. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 2<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  461. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 3<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  462. <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
  463. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;mainlayout&quot;</span><span class="p">&gt;</span>
  464. this is the body content.
  465. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  466. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;footer&quot;</span><span class="p">&gt;</span>
  467. this is the footer
  468. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  469. <span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
  470. <span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
  471. </pre></div>
  472. </div>
  473. <p>So above, we have the <code class="docutils literal"><span class="pre">&lt;html&gt;</span></code>, <code class="docutils literal"><span class="pre">&lt;body&gt;</span></code> and
  474. <code class="docutils literal"><span class="pre">header</span></code>/<code class="docutils literal"><span class="pre">footer</span></code> layout of <code class="docutils literal"><span class="pre">base.html</span></code>, we have the
  475. <code class="docutils literal"><span class="pre">&lt;ul&gt;</span></code> and <code class="docutils literal"><span class="pre">mainlayout</span></code> section of <code class="docutils literal"><span class="pre">layout.html</span></code>, and the
  476. main body of <code class="docutils literal"><span class="pre">index.html</span></code> as well as its overridden <code class="docutils literal"><span class="pre">header</span></code>
  477. def. The <code class="docutils literal"><span class="pre">layout.html</span></code> template is inserted into the middle of
  478. the chain without <code class="docutils literal"><span class="pre">base.html</span></code> having to change anything.
  479. Without the <code class="docutils literal"><span class="pre">next</span></code> namespace, only the main body of
  480. <code class="docutils literal"><span class="pre">index.html</span></code> could be used; there would be no way to call
  481. <code class="docutils literal"><span class="pre">layout.html</span></code>&#8216;s body content.</p>
  482. </div>
  483. <div class="section" id="using-the-parent-namespace-to-augment-defs">
  484. <span id="parent-namespace"></span><h2>Using the <code class="docutils literal"><span class="pre">parent</span></code> Namespace to Augment Defs<a class="headerlink" href="#using-the-parent-namespace-to-augment-defs" title="Permalink to this headline">¶</a></h2>
  485. <p>Lets now look at the other inheritance-specific namespace, the
  486. opposite of <code class="docutils literal"><span class="pre">next</span></code> called <code class="docutils literal"><span class="pre">parent</span></code>. <code class="docutils literal"><span class="pre">parent</span></code> is the
  487. namespace of the template <strong>immediately preceding</strong> the current
  488. template. What&#8217;s useful about this namespace is that
  489. defs or blocks can call upon their overridden versions.
  490. This is not as hard as it sounds and
  491. is very much like using the <code class="docutils literal"><span class="pre">super</span></code> keyword in Python. Lets
  492. modify <code class="docutils literal"><span class="pre">index.html</span></code> to augment the list of selections provided
  493. by the <code class="docutils literal"><span class="pre">toolbar</span></code> function in <code class="docutils literal"><span class="pre">layout.html</span></code>:</p>
  494. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## index.html</span><span class="x"></span>
  495. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;layout.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  496. <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>
  497. <span class="x"> this is some header content</span>
  498. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  499. <span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;toolbar&quot;</span><span class="cp">&gt;</span>
  500. <span class="cp">## call the parent&#39;s toolbar first</span><span class="x"></span>
  501. <span class="x"> </span><span class="cp">${</span><span class="n">parent</span><span class="o">.</span><span class="n">toolbar</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  502. <span class="x"> &lt;li&gt;selection 4&lt;/li&gt;</span>
  503. <span class="x"> &lt;li&gt;selection 5&lt;/li&gt;</span>
  504. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  505. <span class="x">this is the body content.</span>
  506. </pre></div>
  507. </div>
  508. <p>Above, we implemented a <code class="docutils literal"><span class="pre">toolbar()</span></code> function, which is meant
  509. to override the definition of <code class="docutils literal"><span class="pre">toolbar</span></code> within the inherited
  510. template <code class="docutils literal"><span class="pre">layout.html</span></code>. However, since we want the content
  511. from that of <code class="docutils literal"><span class="pre">layout.html</span></code> as well, we call it via the
  512. <code class="docutils literal"><span class="pre">parent</span></code> namespace whenever we want it&#8217;s content, in this case
  513. before we add our own selections. So the output for the whole
  514. thing is now:</p>
  515. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">html</span><span class="p">&gt;</span>
  516. <span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
  517. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;header&quot;</span><span class="p">&gt;</span>
  518. this is some header content
  519. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  520. <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
  521. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 1<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  522. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 2<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  523. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 3<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  524. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 4<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  525. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>selection 5<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  526. <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
  527. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;mainlayout&quot;</span><span class="p">&gt;</span>
  528. this is the body content.
  529. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  530. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;footer&quot;</span><span class="p">&gt;</span>
  531. this is the footer
  532. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  533. <span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
  534. <span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
  535. </pre></div>
  536. </div>
  537. <p>and you&#8217;re now a template inheritance ninja!</p>
  538. </div>
  539. <div class="section" id="using-include-with-template-inheritance">
  540. <h2>Using <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> with Template Inheritance<a class="headerlink" href="#using-include-with-template-inheritance" title="Permalink to this headline">¶</a></h2>
  541. <p>A common source of confusion is the behavior of the <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> tag,
  542. often in conjunction with its interaction within template inheritance.
  543. Key to understanding the <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> tag is that it is a <em>dynamic</em>, e.g.
  544. runtime, include, and not a static include. The <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> is only processed
  545. as the template renders, and not at inheritance setup time. When encountered,
  546. the referenced template is run fully as an entirely separate template with no
  547. linkage to any current inheritance structure.</p>
  548. <p>If the tag were on the other hand a <em>static</em> include, this would allow source
  549. within the included template to interact within the same inheritance context
  550. as the calling template, but currently Mako has no static include facility.</p>
  551. <p>In practice, this means that <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> elements defined in an <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code>
  552. file will not interact with corresponding <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> elements in the calling
  553. template.</p>
  554. <p>A common mistake is along these lines:</p>
  555. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## partials.mako</span><span class="x"></span>
  556. <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>
  557. <span class="x"> Global Header</span>
  558. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
  559. <span class="cp">## parent.mako</span><span class="x"></span>
  560. <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>
  561. <span class="cp">## child.mako</span><span class="x"></span>
  562. <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>
  563. <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>
  564. <span class="x"> Custom Header</span>
  565. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  566. </pre></div>
  567. </div>
  568. <p>Above, one might expect that the <code class="docutils literal"><span class="pre">&quot;header&quot;</span></code> block declared in <code class="docutils literal"><span class="pre">child.mako</span></code>
  569. might be invoked, as a result of it overriding the same block present in
  570. <code class="docutils literal"><span class="pre">parent.mako</span></code> via the include for <code class="docutils literal"><span class="pre">partials.mako</span></code>. But this is not the case.
  571. Instead, <code class="docutils literal"><span class="pre">parent.mako</span></code> will invoke <code class="docutils literal"><span class="pre">partials.mako</span></code>, which then invokes
  572. <code class="docutils literal"><span class="pre">&quot;header&quot;</span></code> in <code class="docutils literal"><span class="pre">partials.mako</span></code>, and then is finished rendering. Nothing
  573. from <code class="docutils literal"><span class="pre">child.mako</span></code> will render; there is no interaction between the <code class="docutils literal"><span class="pre">&quot;header&quot;</span></code>
  574. block in <code class="docutils literal"><span class="pre">child.mako</span></code> and the <code class="docutils literal"><span class="pre">&quot;header&quot;</span></code> block in <code class="docutils literal"><span class="pre">partials.mako</span></code>.</p>
  575. <p>Instead, <code class="docutils literal"><span class="pre">parent.mako</span></code> must explicitly state the inheritance structure.
  576. In order to call upon specific elements of <code class="docutils literal"><span class="pre">partials.mako</span></code>, we will call upon
  577. it as a namespace:</p>
  578. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## partials.mako</span><span class="x"></span>
  579. <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>
  580. <span class="x"> Global Header</span>
  581. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
  582. <span class="cp">## parent.mako</span><span class="x"></span>
  583. <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>
  584. <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>
  585. <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>
  586. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
  587. <span class="cp">## child.mako</span><span class="x"></span>
  588. <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>
  589. <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>
  590. <span class="x"> Custom Header</span>
  591. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  592. </pre></div>
  593. </div>
  594. <p>Where above, <code class="docutils literal"><span class="pre">parent.mako</span></code> states the inheritance structure that <code class="docutils literal"><span class="pre">child.mako</span></code>
  595. is to participate within. <code class="docutils literal"><span class="pre">partials.mako</span></code> only defines defs/blocks that can be
  596. used on a per-name basis.</p>
  597. <p>Another scenario is below, which results in both <code class="docutils literal"><span class="pre">&quot;SectionA&quot;</span></code> blocks being rendered for the <code class="docutils literal"><span class="pre">child.mako</span></code> document:</p>
  598. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## base.mako</span><span class="x"></span>
  599. <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>
  600. <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>
  601. <span class="x"> base.mako</span>
  602. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
  603. <span class="cp">## parent.mako</span><span class="x"></span>
  604. <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>
  605. <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>
  606. <span class="cp">## child.mako</span><span class="x"></span>
  607. <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>
  608. <span class="x"> child.mako</span>
  609. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  610. </pre></div>
  611. </div>
  612. <p>The resolution is similar; instead of using <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code>, we call upon the blocks
  613. of <code class="docutils literal"><span class="pre">child.mako</span></code> using a namespace:</p>
  614. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">## parent.mako</span><span class="x"></span>
  615. <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>
  616. <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>
  617. <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>
  618. <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>
  619. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  620. </pre></div>
  621. </div>
  622. </div>
  623. <div class="section" id="inheritable-attributes">
  624. <span id="inheritance-attr"></span><h2>Inheritable Attributes<a class="headerlink" href="#inheritable-attributes" title="Permalink to this headline">¶</a></h2>
  625. <p>The <a class="reference internal" href="namespaces.html#mako.runtime.Namespace.attr" title="mako.runtime.Namespace.attr"><code class="xref py py-attr docutils literal"><span class="pre">attr</span></code></a> accessor of the <a class="reference internal" href="namespaces.html#mako.runtime.Namespace" title="mako.runtime.Namespace"><code class="xref py py-class docutils literal"><span class="pre">Namespace</span></code></a> object
  626. allows access to module level variables declared in a template. By accessing
  627. <code class="docutils literal"><span class="pre">self.attr</span></code>, you can access regular attributes from the
  628. inheritance chain as declared in <code class="docutils literal"><span class="pre">&lt;%!</span> <span class="pre">%&gt;</span></code> sections. Such as:</p>
  629. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%!</span>
  630. <span class="n">class_</span> <span class="o">=</span> <span class="s2">&quot;grey&quot;</span>
  631. <span class="cp">%&gt;</span><span class="x"></span>
  632. <span class="x">&lt;div class=&quot;</span><span class="cp">${</span><span class="bp">self</span><span class="o">.</span><span class="n">attr</span><span class="o">.</span><span class="n">class_</span><span class="cp">}</span><span class="x">&quot;&gt;</span>
  633. <span class="x"> </span><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>
  634. <span class="x">&lt;/div&gt;</span>
  635. </pre></div>
  636. </div>
  637. <p>If an inheriting template overrides <code class="docutils literal"><span class="pre">class_</span></code> to be
  638. <code class="docutils literal"><span class="pre">&quot;white&quot;</span></code>, as in:</p>
  639. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%!</span>
  640. <span class="n">class_</span> <span class="o">=</span> <span class="s2">&quot;white&quot;</span>
  641. <span class="cp">%&gt;</span><span class="x"></span>
  642. <span class="cp">&lt;%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">&quot;parent.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  643. <span class="x">This is the body</span>
  644. </pre></div>
  645. </div>
  646. <p>you&#8217;ll get output like:</p>
  647. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;white&quot;</span><span class="p">&gt;</span>
  648. This is the body
  649. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  650. </pre></div>
  651. </div>
  652. <div class="admonition seealso">
  653. <p class="first admonition-title">See also</p>
  654. <p class="last"><a class="reference internal" href="namespaces.html#namespace-attr-for-includes"><span class="std std-ref">Version One - Use Namespace.attr</span></a> - a more sophisticated example using
  655. <a class="reference internal" href="namespaces.html#mako.runtime.Namespace.attr" title="mako.runtime.Namespace.attr"><code class="xref py py-attr docutils literal"><span class="pre">Namespace.attr</span></code></a>.</p>
  656. </div>
  657. </div>
  658. </div>
  659. </div>
  660. </div>
  661. <div id="docs-bottom-navigation" class="docs-navigation-links">
  662. Previous:
  663. <a href="namespaces.html" title="previous chapter">Namespaces</a>
  664. Next:
  665. <a href="filtering.html" title="next chapter">Filtering and Buffering</a>
  666. <div id="docs-copyright">
  667. &copy; Copyright the Mako authors and contributors.
  668. Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.5.3
  669. with Mako templates.
  670. </div>
  671. </div>
  672. </div>
  673. <div class="clearfix">
  674. <hr/>
  675. <div class="copyright">Website content copyright &copy; by Michael Bayer.
  676. All rights reserved. Mako and its documentation are licensed
  677. under the MIT license. mike(&)zzzcomputing.com</div>
  678. </div>
  679. </div>
  680. </body>
  681. </html>