defs.html 56 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737
  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. Defs and Blocks
  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="The Mako Runtime Environment" href="runtime.html" />
  32. <link rel="prev" title="Syntax" href="syntax.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="syntax.html" title="previous chapter">Syntax</a>
  63. </li>
  64. <li>Next:
  65. <a href="runtime.html" title="next chapter">The Mako Runtime Environment</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/defs.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. Defs and Blocks
  78. <h2>
  79. Defs and Blocks
  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="#">Defs and Blocks</a><ul>
  88. <li><a class="reference internal" href="#using-defs">Using Defs</a><ul>
  89. <li><a class="reference internal" href="#calling-defs-from-other-files">Calling Defs from Other Files</a></li>
  90. <li><a class="reference internal" href="#calling-defs-programmatically">Calling Defs Programmatically</a></li>
  91. <li><a class="reference internal" href="#defs-within-defs">Defs within Defs</a></li>
  92. <li><a class="reference internal" href="#calling-a-def-with-embedded-content-and-or-other-defs">Calling a Def with Embedded Content and/or Other Defs</a></li>
  93. </ul>
  94. </li>
  95. <li><a class="reference internal" href="#using-blocks">Using Blocks</a><ul>
  96. <li><a class="reference internal" href="#using-named-blocks">Using Named Blocks</a></li>
  97. <li><a class="reference internal" href="#using-page-arguments-in-named-blocks">Using Page Arguments in Named Blocks</a></li>
  98. </ul>
  99. </li>
  100. </ul>
  101. </li>
  102. </ul>
  103. <h4>Previous Topic</h4>
  104. <p>
  105. <a href="syntax.html" title="previous chapter">Syntax</a>
  106. </p>
  107. <h4>Next Topic</h4>
  108. <p>
  109. <a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>
  110. </p>
  111. <h4>Quick Search</h4>
  112. <p>
  113. <form class="search" action="search.html" method="get">
  114. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  115. <input type="hidden" name="check_keywords" value="yes" />
  116. <input type="hidden" name="area" value="default" />
  117. </form>
  118. </p>
  119. </div>
  120. <div id="docs-body" class="withsidebar" >
  121. <div class="section" id="defs-and-blocks">
  122. <span id="defs-toplevel"></span><h1>Defs and Blocks<a class="headerlink" href="#defs-and-blocks" title="Permalink to this headline">¶</a></h1>
  123. <p><code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> and <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> are two tags that both demarcate any block of text
  124. and/or code. They both exist within generated Python as a callable function,
  125. i.e., a Python <code class="docutils literal"><span class="pre">def</span></code>. They differ in their scope and calling semantics.
  126. Whereas <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> provides a construct that is very much like a named Python
  127. <code class="docutils literal"><span class="pre">def</span></code>, the <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> is more layout oriented.</p>
  128. <div class="section" id="using-defs">
  129. <h2>Using Defs<a class="headerlink" href="#using-defs" title="Permalink to this headline">¶</a></h2>
  130. <p>The <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> tag requires a <code class="docutils literal"><span class="pre">name</span></code> attribute, where the <code class="docutils literal"><span class="pre">name</span></code> references
  131. a Python function signature:</p>
  132. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;hello()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  133. <span class="x"> hello world</span>
  134. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  135. </pre></div>
  136. </div>
  137. <p>To invoke the <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>, it is normally called as an expression:</p>
  138. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">the def: </span><span class="cp">${</span><span class="n">hello</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  139. </pre></div>
  140. </div>
  141. <p>If the <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> is not nested inside of another <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>,
  142. it&#8217;s known as a <strong>top level def</strong> and can be accessed anywhere in
  143. the template, including above where it was defined.</p>
  144. <p>All defs, top level or not, have access to the current
  145. contextual namespace in exactly the same way their containing
  146. template does. Suppose the template below is executed with the
  147. variables <code class="docutils literal"><span class="pre">username</span></code> and <code class="docutils literal"><span class="pre">accountdata</span></code> inside the context:</p>
  148. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">Hello there </span><span class="cp">${</span><span class="n">username</span><span class="cp">}</span><span class="x">, how are ya. Lets see what your account says:</span>
  149. <span class="cp">${</span><span class="n">account</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  150. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;account()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  151. <span class="x"> Account for </span><span class="cp">${</span><span class="n">username</span><span class="cp">}</span><span class="x">:&lt;br/&gt;</span>
  152. <span class="cp">%</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">accountdata</span><span class="p">:</span><span class="x"></span>
  153. <span class="x"> Value: </span><span class="cp">${</span><span class="n">row</span><span class="cp">}</span><span class="x">&lt;br/&gt;</span>
  154. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  155. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  156. </pre></div>
  157. </div>
  158. <p>The <code class="docutils literal"><span class="pre">username</span></code> and <code class="docutils literal"><span class="pre">accountdata</span></code> variables are present
  159. within the main template body as well as the body of the
  160. <code class="docutils literal"><span class="pre">account()</span></code> def.</p>
  161. <p>Since defs are just Python functions, you can define and pass
  162. arguments to them as well:</p>
  163. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="n">account</span><span class="p">(</span><span class="n">accountname</span><span class="o">=</span><span class="s1">&#39;john&#39;</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  164. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;account(accountname, type=&#39;regular&#39;)&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  165. <span class="x"> account name: </span><span class="cp">${</span><span class="n">accountname</span><span class="cp">}</span><span class="x">, type: </span><span class="cp">${</span><span class="nb">type</span><span class="cp">}</span><span class="x"></span>
  166. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  167. </pre></div>
  168. </div>
  169. <p>When you declare an argument signature for your def, they are
  170. required to follow normal Python conventions (i.e., all
  171. arguments are required except keyword arguments with a default
  172. value). This is in contrast to using context-level variables,
  173. which evaluate to <code class="docutils literal"><span class="pre">UNDEFINED</span></code> if you reference a name that
  174. does not exist.</p>
  175. <div class="section" id="calling-defs-from-other-files">
  176. <h3>Calling Defs from Other Files<a class="headerlink" href="#calling-defs-from-other-files" title="Permalink to this headline">¶</a></h3>
  177. <p>Top level <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>s are <strong>exported</strong> by your template&#8217;s
  178. module, and can be called from the outside; including from other
  179. templates, as well as normal Python code. Calling a <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>
  180. from another template is something like using an <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code>
  181. &#8211; except you are calling a specific function within the
  182. template, not the whole template.</p>
  183. <p>The remote <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> call is also a little bit like calling
  184. functions from other modules in Python. There is an &#8220;import&#8221;
  185. step to pull the names from another template into your own
  186. template; then the function or functions are available.</p>
  187. <p>To import another template, use the <code class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></code> tag:</p>
  188. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">&quot;mystuff&quot;</span> <span class="na">file=</span><span class="s">&quot;mystuff.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  189. </pre></div>
  190. </div>
  191. <p>The above tag adds a local variable <code class="docutils literal"><span class="pre">mystuff</span></code> to the current
  192. scope.</p>
  193. <p>Then, just call the defs off of <code class="docutils literal"><span class="pre">mystuff</span></code>:</p>
  194. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">${</span><span class="n">mystuff</span><span class="o">.</span><span class="n">somedef</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span><span class="n">y</span><span class="o">=</span><span class="mi">7</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  195. </pre></div>
  196. </div>
  197. <p>The <code class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></code> tag also supports some of the other
  198. semantics of Python&#8217;s <code class="docutils literal"><span class="pre">import</span></code> statement, including pulling
  199. names into the local variable space, or using <code class="docutils literal"><span class="pre">*</span></code> to represent
  200. all names, using the <code class="docutils literal"><span class="pre">import</span></code> attribute:</p>
  201. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">file=</span><span class="s">&quot;mystuff.html&quot;</span> <span class="na">import=</span><span class="s">&quot;foo, bar&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  202. </pre></div>
  203. </div>
  204. <p>This is just a quick intro to the concept of a <strong>namespace</strong>,
  205. which is a central Mako concept that has its own chapter in
  206. these docs. For more detail and examples, see
  207. <a class="reference internal" href="namespaces.html"><span class="std std-ref">Namespaces</span></a>.</p>
  208. </div>
  209. <div class="section" id="calling-defs-programmatically">
  210. <h3>Calling Defs Programmatically<a class="headerlink" href="#calling-defs-programmatically" title="Permalink to this headline">¶</a></h3>
  211. <p>You can call defs programmatically from any <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object
  212. using the <a class="reference internal" href="usage.html#mako.template.Template.get_def" title="mako.template.Template.get_def"><code class="xref py py-meth docutils literal"><span class="pre">get_def()</span></code></a> method, which returns a <a class="reference internal" href="usage.html#mako.template.DefTemplate" title="mako.template.DefTemplate"><code class="xref py py-class docutils literal"><span class="pre">DefTemplate</span></code></a>
  213. object. This is a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> subclass which the parent
  214. <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> creates, and is usable like any other template:</p>
  215. <div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
  216. <span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;&quot;&quot;</span>
  217. <span class="s2"> &lt;</span><span class="si">%d</span><span class="s2">ef name=&quot;hi(name)&quot;&gt;</span>
  218. <span class="s2"> hi ${name}!</span>
  219. <span class="s2"> &lt;/</span><span class="si">%d</span><span class="s2">ef&gt;</span>
  220. <span class="s2"> &lt;</span><span class="si">%d</span><span class="s2">ef name=&quot;bye(name)&quot;&gt;</span>
  221. <span class="s2"> bye ${name}!</span>
  222. <span class="s2"> &lt;/</span><span class="si">%d</span><span class="s2">ef&gt;</span>
  223. <span class="s2">&quot;&quot;&quot;</span><span class="p">)</span>
  224. <span class="k">print</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">get_def</span><span class="p">(</span><span class="s2">&quot;hi&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;ed&quot;</span><span class="p">))</span>
  225. <span class="k">print</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">get_def</span><span class="p">(</span><span class="s2">&quot;bye&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;ed&quot;</span><span class="p">))</span>
  226. </pre></div>
  227. </div>
  228. </div>
  229. <div class="section" id="defs-within-defs">
  230. <h3>Defs within Defs<a class="headerlink" href="#defs-within-defs" title="Permalink to this headline">¶</a></h3>
  231. <p>The def model follows regular Python rules for closures.
  232. Declaring <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> inside another <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> declares it
  233. within the parent&#8217;s <strong>enclosing scope</strong>:</p>
  234. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;mydef()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  235. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;subdef()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  236. <span class="x"> a sub def</span>
  237. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  238. <span class="x"> i&#39;m the def, and the subcomponent is </span><span class="cp">${</span><span class="n">subdef</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  239. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  240. </pre></div>
  241. </div>
  242. <p>Just like Python, names that exist outside the inner <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>
  243. exist inside it as well:</p>
  244. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span>
  245. <span class="n">x</span> <span class="o">=</span> <span class="mi">12</span>
  246. <span class="cp">%&gt;</span><span class="x"></span>
  247. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;outer()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  248. <span class="x"> </span><span class="cp">&lt;%</span>
  249. <span class="n">y</span> <span class="o">=</span> <span class="mi">15</span>
  250. <span class="cp">%&gt;</span><span class="x"></span>
  251. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;inner()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  252. <span class="x"> inner, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x">, y is </span><span class="cp">${</span><span class="n">y</span><span class="cp">}</span><span class="x"></span>
  253. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  254. <span class="x"> outer, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x">, y is </span><span class="cp">${</span><span class="n">y</span><span class="cp">}</span><span class="x"></span>
  255. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  256. </pre></div>
  257. </div>
  258. <p>Assigning to a name inside of a def declares that name as local
  259. to the scope of that def (again, like Python itself). This means
  260. the following code will raise an error:</p>
  261. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span>
  262. <span class="n">x</span> <span class="o">=</span> <span class="mi">10</span>
  263. <span class="cp">%&gt;</span><span class="x"></span>
  264. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;somedef()&quot;</span><span class="cp">&gt;</span>
  265. <span class="cp">## error !</span><span class="x"></span>
  266. <span class="x"> somedef, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x"></span>
  267. <span class="x"> </span><span class="cp">&lt;%</span>
  268. <span class="n">x</span> <span class="o">=</span> <span class="mi">27</span>
  269. <span class="cp">%&gt;</span><span class="x"></span>
  270. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  271. </pre></div>
  272. </div>
  273. <p>...because the assignment to <code class="docutils literal"><span class="pre">x</span></code> declares <code class="docutils literal"><span class="pre">x</span></code> as local to the
  274. scope of <code class="docutils literal"><span class="pre">somedef</span></code>, rendering the &#8220;outer&#8221; version unreachable
  275. in the expression that tries to render it.</p>
  276. </div>
  277. <div class="section" id="calling-a-def-with-embedded-content-and-or-other-defs">
  278. <span id="defs-with-content"></span><h3>Calling a Def with Embedded Content and/or Other Defs<a class="headerlink" href="#calling-a-def-with-embedded-content-and-or-other-defs" title="Permalink to this headline">¶</a></h3>
  279. <p>A flip-side to def within def is a def call with content. This
  280. is where you call a def, and at the same time declare a block of
  281. content (or multiple blocks) that can be used by the def being
  282. called. The main point of such a call is to create custom,
  283. nestable tags, just like any other template language&#8217;s
  284. custom-tag creation system &#8211; where the external tag controls the
  285. execution of the nested tags and can communicate state to them.
  286. Only with Mako, you don&#8217;t have to use any external Python
  287. modules, you can define arbitrarily nestable tags right in your
  288. templates.</p>
  289. <p>To achieve this, the target def is invoked using the form
  290. <code class="docutils literal"><span class="pre">&lt;%namespacename:defname&gt;</span></code> instead of the normal <code class="docutils literal"><span class="pre">${}</span></code>
  291. syntax. This syntax, introduced in Mako 0.2.3, is functionally
  292. equivalent to another tag known as <code class="docutils literal"><span class="pre">%call</span></code>, which takes the form
  293. <code class="docutils literal"><span class="pre">&lt;%call</span> <span class="pre">expr='namespacename.defname(args)'&gt;</span></code>. While <code class="docutils literal"><span class="pre">%call</span></code>
  294. is available in all versions of Mako, the newer style is
  295. probably more familiar looking. The <code class="docutils literal"><span class="pre">namespace</span></code> portion of the
  296. call is the name of the <strong>namespace</strong> in which the def is
  297. defined &#8211; in the most simple cases, this can be <code class="docutils literal"><span class="pre">local</span></code> or
  298. <code class="docutils literal"><span class="pre">self</span></code> to reference the current template&#8217;s namespace (the
  299. difference between <code class="docutils literal"><span class="pre">local</span></code> and <code class="docutils literal"><span class="pre">self</span></code> is one of inheritance
  300. &#8211; see <a class="reference internal" href="namespaces.html#namespaces-builtin"><span class="std std-ref">Built-in Namespaces</span></a> for details).</p>
  301. <p>When the target def is invoked, a variable <code class="docutils literal"><span class="pre">caller</span></code> is placed
  302. in its context which contains another namespace containing the
  303. body and other defs defined by the caller. The body itself is
  304. referenced by the method <code class="docutils literal"><span class="pre">body()</span></code>. Below, we build a <code class="docutils literal"><span class="pre">%def</span></code>
  305. that operates upon <code class="docutils literal"><span class="pre">caller.body()</span></code> to invoke the body of the
  306. custom tag:</p>
  307. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;buildtable()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  308. <span class="x"> &lt;table&gt;</span>
  309. <span class="x"> &lt;tr&gt;&lt;td&gt;</span>
  310. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  311. <span class="x"> &lt;/td&gt;&lt;/tr&gt;</span>
  312. <span class="x"> &lt;/table&gt;</span>
  313. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  314. <span class="cp">&lt;%</span><span class="nb">self:buildtable</span><span class="cp">&gt;</span><span class="x"></span>
  315. <span class="x"> I am the table body.</span>
  316. <span class="cp">&lt;/%</span><span class="nb">self:buildtable</span><span class="cp">&gt;</span><span class="x"></span>
  317. </pre></div>
  318. </div>
  319. <p>This produces the output (whitespace formatted):</p>
  320. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">table</span><span class="p">&gt;</span>
  321. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;&lt;</span><span class="nt">td</span><span class="p">&gt;</span>
  322. I am the table body.
  323. <span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  324. <span class="p">&lt;/</span><span class="nt">table</span><span class="p">&gt;</span>
  325. </pre></div>
  326. </div>
  327. <p>Using the older <code class="docutils literal"><span class="pre">%call</span></code> syntax looks like:</p>
  328. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;buildtable()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  329. <span class="x"> &lt;table&gt;</span>
  330. <span class="x"> &lt;tr&gt;&lt;td&gt;</span>
  331. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  332. <span class="x"> &lt;/td&gt;&lt;/tr&gt;</span>
  333. <span class="x"> &lt;/table&gt;</span>
  334. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  335. <span class="cp">&lt;%</span><span class="nb">call</span> <span class="na">expr=</span><span class="s">&quot;buildtable()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  336. <span class="x"> I am the table body.</span>
  337. <span class="cp">&lt;/%</span><span class="nb">call</span><span class="cp">&gt;</span><span class="x"></span>
  338. </pre></div>
  339. </div>
  340. <p>The <code class="docutils literal"><span class="pre">body()</span></code> can be executed multiple times or not at all.
  341. This means you can use def-call-with-content to build iterators,
  342. conditionals, etc:</p>
  343. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;lister(count)&quot;</span><span class="cp">&gt;</span>
  344. <span class="cp">%</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">count</span><span class="p">):</span><span class="x"></span>
  345. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span>
  346. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  347. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  348. <span class="cp">&lt;%</span><span class="nb">self:lister</span> <span class="na">count=</span><span class="s">&quot;${3}&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  349. <span class="x"> hi</span>
  350. <span class="cp">&lt;/%</span><span class="nb">self:lister</span><span class="cp">&gt;</span><span class="x"></span>
  351. </pre></div>
  352. </div>
  353. <p>Produces:</p>
  354. <div class="highlight-html"><div class="highlight"><pre><span></span>hi
  355. hi
  356. hi
  357. </pre></div>
  358. </div>
  359. <p>Notice above we pass <code class="docutils literal"><span class="pre">3</span></code> as a Python expression, so that it
  360. remains as an integer.</p>
  361. <p>A custom &#8220;conditional&#8221; tag:</p>
  362. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;conditional(expression)&quot;</span><span class="cp">&gt;</span>
  363. <span class="cp">%</span> <span class="k">if</span> <span class="n">expression</span><span class="p">:</span><span class="x"></span>
  364. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span>
  365. <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
  366. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  367. <span class="cp">&lt;%</span><span class="nb">self:conditional</span> <span class="na">expression=</span><span class="s">&quot;${4==4}&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  368. <span class="x"> i&#39;m the result</span>
  369. <span class="cp">&lt;/%</span><span class="nb">self:conditional</span><span class="cp">&gt;</span><span class="x"></span>
  370. </pre></div>
  371. </div>
  372. <p>Produces:</p>
  373. <div class="highlight-html"><div class="highlight"><pre><span></span>i&#39;m the result
  374. </pre></div>
  375. </div>
  376. <p>But that&#8217;s not all. The <code class="docutils literal"><span class="pre">body()</span></code> function also can handle
  377. arguments, which will augment the local namespace of the body
  378. callable. The caller must define the arguments which it expects
  379. to receive from its target def using the <code class="docutils literal"><span class="pre">args</span></code> attribute,
  380. which is a comma-separated list of argument names. Below, our
  381. <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> calls the <code class="docutils literal"><span class="pre">body()</span></code> of its caller, passing in an
  382. element of data from its argument:</p>
  383. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;layoutdata(somedata)&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  384. <span class="x"> &lt;table&gt;</span>
  385. <span class="cp">%</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">somedata</span><span class="p">:</span><span class="x"></span>
  386. <span class="x"> &lt;tr&gt;</span>
  387. <span class="cp">%</span> <span class="k">for</span> <span class="n">col</span> <span class="ow">in</span> <span class="n">item</span><span class="p">:</span><span class="x"></span>
  388. <span class="x"> &lt;td&gt;</span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">(</span><span class="n">col</span><span class="o">=</span><span class="n">col</span><span class="p">)</span><span class="cp">}</span><span class="x">&lt;/td&gt;</span>
  389. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  390. <span class="x"> &lt;/tr&gt;</span>
  391. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  392. <span class="x"> &lt;/table&gt;</span>
  393. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  394. <span class="cp">&lt;%</span><span class="nb">self:layoutdata</span> <span class="na">somedata=</span><span class="s">&quot;${[[1,2,3],[4,5,6],[7,8,9]]}&quot;</span> <span class="na">args=</span><span class="s">&quot;col&quot;</span><span class="cp">&gt;</span><span class="x">\</span>
  395. <span class="x">Body data: </span><span class="cp">${</span><span class="n">col</span><span class="cp">}</span><span class="x">\</span>
  396. <span class="cp">&lt;/%</span><span class="nb">self:layoutdata</span><span class="cp">&gt;</span><span class="x"></span>
  397. </pre></div>
  398. </div>
  399. <p>Produces:</p>
  400. <div class="highlight-html"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">table</span><span class="p">&gt;</span>
  401. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;</span>
  402. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 1<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  403. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 2<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  404. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 3<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  405. <span class="p">&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  406. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;</span>
  407. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 4<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  408. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 5<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  409. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 6<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  410. <span class="p">&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  411. <span class="p">&lt;</span><span class="nt">tr</span><span class="p">&gt;</span>
  412. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 7<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  413. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 8<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  414. <span class="p">&lt;</span><span class="nt">td</span><span class="p">&gt;</span>Body data: 9<span class="p">&lt;/</span><span class="nt">td</span><span class="p">&gt;</span>
  415. <span class="p">&lt;/</span><span class="nt">tr</span><span class="p">&gt;</span>
  416. <span class="p">&lt;/</span><span class="nt">table</span><span class="p">&gt;</span>
  417. </pre></div>
  418. </div>
  419. <p>You don&#8217;t have to stick to calling just the <code class="docutils literal"><span class="pre">body()</span></code> function.
  420. The caller can define any number of callables, allowing the
  421. <code class="docutils literal"><span class="pre">&lt;%call&gt;</span></code> tag to produce whole layouts:</p>
  422. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;layout()&quot;</span><span class="cp">&gt;</span>
  423. <span class="cp">## a layout def</span><span class="x"></span>
  424. <span class="x"> &lt;div class=&quot;mainlayout&quot;&gt;</span>
  425. <span class="x"> &lt;div class=&quot;header&quot;&gt;</span>
  426. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  427. <span class="x"> &lt;/div&gt;</span>
  428. <span class="x"> &lt;div class=&quot;sidebar&quot;&gt;</span>
  429. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">sidebar</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  430. <span class="x"> &lt;/div&gt;</span>
  431. <span class="x"> &lt;div class=&quot;content&quot;&gt;</span>
  432. <span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  433. <span class="x"> &lt;/div&gt;</span>
  434. <span class="x"> &lt;/div&gt;</span>
  435. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span>
  436. <span class="cp">## calls the layout def</span><span class="x"></span>
  437. <span class="cp">&lt;%</span><span class="nb">self:layout</span><span class="cp">&gt;</span><span class="x"></span>
  438. <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>
  439. <span class="x"> I am the header</span>
  440. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  441. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;sidebar()&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  442. <span class="x"> &lt;ul&gt;</span>
  443. <span class="x"> &lt;li&gt;sidebar 1&lt;/li&gt;</span>
  444. <span class="x"> &lt;li&gt;sidebar 2&lt;/li&gt;</span>
  445. <span class="x"> &lt;/ul&gt;</span>
  446. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  447. <span class="x"> this is the body</span>
  448. <span class="cp">&lt;/%</span><span class="nb">self:layout</span><span class="cp">&gt;</span><span class="x"></span>
  449. </pre></div>
  450. </div>
  451. <p>The above layout would produce:</p>
  452. <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;mainlayout&quot;</span><span class="p">&gt;</span>
  453. <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>
  454. I am the header
  455. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  456. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;sidebar&quot;</span><span class="p">&gt;</span>
  457. <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
  458. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>sidebar 1<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  459. <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span>sidebar 2<span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
  460. <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
  461. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  462. <span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;content&quot;</span><span class="p">&gt;</span>
  463. this is the body
  464. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  465. <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
  466. </pre></div>
  467. </div>
  468. <p>The number of things you can do with <code class="docutils literal"><span class="pre">&lt;%call&gt;</span></code> and/or the
  469. <code class="docutils literal"><span class="pre">&lt;%namespacename:defname&gt;</span></code> calling syntax is enormous. You can
  470. create form widget libraries, such as an enclosing <code class="docutils literal"><span class="pre">&lt;FORM&gt;</span></code>
  471. tag and nested HTML input elements, or portable wrapping schemes
  472. using <code class="docutils literal"><span class="pre">&lt;div&gt;</span></code> or other elements. You can create tags that
  473. interpret rows of data, such as from a database, providing the
  474. individual columns of each row to a <code class="docutils literal"><span class="pre">body()</span></code> callable which
  475. lays out the row any way it wants. Basically anything you&#8217;d do
  476. with a &#8220;custom tag&#8221; or tag library in some other system, Mako
  477. provides via <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> tags and plain Python callables which are
  478. invoked via <code class="docutils literal"><span class="pre">&lt;%namespacename:defname&gt;</span></code> or <code class="docutils literal"><span class="pre">&lt;%call&gt;</span></code>.</p>
  479. </div>
  480. </div>
  481. <div class="section" id="using-blocks">
  482. <span id="blocks"></span><h2>Using Blocks<a class="headerlink" href="#using-blocks" title="Permalink to this headline">¶</a></h2>
  483. <p>The <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> tag introduces some new twists on the
  484. <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> tag which make it more closely tailored towards layout.</p>
  485. <div class="versionadded">
  486. <p><span class="versionmodified">New in version 0.4.1.</span></p>
  487. </div>
  488. <p>An example of a block:</p>
  489. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;html&gt;</span>
  490. <span class="x"> &lt;body&gt;</span>
  491. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  492. <span class="x"> this is a block.</span>
  493. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  494. <span class="x"> &lt;/body&gt;</span>
  495. <span class="x">&lt;/html&gt;</span>
  496. </pre></div>
  497. </div>
  498. <p>In the above example, we define a simple block. The block renders its content in the place
  499. that it&#8217;s defined. Since the block is called for us, it doesn&#8217;t need a name and the above
  500. is referred to as an <strong>anonymous block</strong>. So the output of the above template will be:</p>
  501. <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>
  502. <span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
  503. this is a block.
  504. <span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
  505. <span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
  506. </pre></div>
  507. </div>
  508. <p>So in fact the above block has absolutely no effect. Its usefulness comes when we start
  509. using modifiers. Such as, we can apply a filter to our block:</p>
  510. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;html&gt;</span>
  511. <span class="x"> &lt;body&gt;</span>
  512. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">filter=</span><span class="s">&quot;h&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  513. <span class="x"> &lt;html&gt;this is some escaped html.&lt;/html&gt;</span>
  514. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  515. <span class="x"> &lt;/body&gt;</span>
  516. <span class="x">&lt;/html&gt;</span>
  517. </pre></div>
  518. </div>
  519. <p>or perhaps a caching directive:</p>
  520. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;html&gt;</span>
  521. <span class="x"> &lt;body&gt;</span>
  522. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_timeout=</span><span class="s">&quot;60&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  523. <span class="x"> This content will be cached for 60 seconds.</span>
  524. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  525. <span class="x"> &lt;/body&gt;</span>
  526. <span class="x">&lt;/html&gt;</span>
  527. </pre></div>
  528. </div>
  529. <p>Blocks also work in iterations, conditionals, just like defs:</p>
  530. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">%</span> <span class="k">if</span> <span class="n">some_condition</span><span class="p">:</span><span class="x"></span>
  531. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x">condition is met</span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
  532. <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
  533. </pre></div>
  534. </div>
  535. <p>While the block renders at the point it is defined in the template,
  536. the underlying function is present in the generated Python code only
  537. once, so there&#8217;s no issue with placing a block inside of a loop or
  538. similar. Anonymous blocks are defined as closures in the local
  539. rendering body, so have access to local variable scope:</p>
  540. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">%</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">):</span><span class="x"></span>
  541. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x">i is </span><span class="cp">${</span><span class="n">i</span><span class="cp">}&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span>
  542. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  543. </pre></div>
  544. </div>
  545. <div class="section" id="using-named-blocks">
  546. <h3>Using Named Blocks<a class="headerlink" href="#using-named-blocks" title="Permalink to this headline">¶</a></h3>
  547. <p>Possibly the more important area where blocks are useful is when we
  548. do actually give them names. Named blocks are tailored to behave
  549. somewhat closely to Jinja2&#8217;s block tag, in that they define an area
  550. of a layout which can be overridden by an inheriting template. In
  551. sharp contrast to the <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code> tag, the name given to a block is
  552. global for the entire template regardless of how deeply it&#8217;s nested:</p>
  553. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;html&gt;</span>
  554. <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>
  555. <span class="x"> &lt;head&gt;</span>
  556. <span class="x"> &lt;title&gt;</span>
  557. <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">Title</span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  558. <span class="x"> &lt;/title&gt;</span>
  559. <span class="x"> &lt;/head&gt;</span>
  560. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  561. <span class="x">&lt;body&gt;</span>
  562. <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>
  563. <span class="x">&lt;/body&gt;</span>
  564. <span class="x">&lt;/html&gt;</span>
  565. </pre></div>
  566. </div>
  567. <p>The above example has two named blocks &#8220;<code class="docutils literal"><span class="pre">header</span></code>&#8221; and &#8220;<code class="docutils literal"><span class="pre">title</span></code>&#8221;, both of which can be referred to
  568. by an inheriting template. A detailed walkthrough of this usage can be found at <a class="reference internal" href="inheritance.html"><span class="std std-ref">Inheritance</span></a>.</p>
  569. <p>Note above that named blocks don&#8217;t have any argument declaration the way defs do. They still implement themselves
  570. as Python functions, however, so they can be invoked additional times beyond their initial definition:</p>
  571. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="x">&lt;div name=&quot;page&quot;&gt;</span>
  572. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;pagecontrol&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  573. <span class="x"> &lt;a href=&quot;&quot;&gt;previous page&lt;/a&gt; |</span>
  574. <span class="x"> &lt;a href=&quot;&quot;&gt;next page&lt;/a&gt;</span>
  575. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  576. <span class="x"> &lt;table&gt;</span>
  577. <span class="x"> ## some content</span>
  578. <span class="x"> &lt;/table&gt;</span>
  579. <span class="x"> </span><span class="cp">${</span><span class="n">pagecontrol</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
  580. <span class="x">&lt;/div&gt;</span>
  581. </pre></div>
  582. </div>
  583. <p>The content referenced by <code class="docutils literal"><span class="pre">pagecontrol</span></code> above will be rendered both above and below the <code class="docutils literal"><span class="pre">&lt;table&gt;</span></code> tags.</p>
  584. <p>To keep things sane, named blocks have restrictions that defs do not:</p>
  585. <ul class="simple">
  586. <li>The <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> declaration cannot have any argument signature.</li>
  587. <li>The name of a <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> can only be defined once in a template &#8211; an error is raised if two blocks of the same
  588. name occur anywhere in a single template, regardless of nesting. A similar error is raised if a top level def
  589. shares the same name as that of a block.</li>
  590. <li>A named <code class="docutils literal"><span class="pre">&lt;%block&gt;</span></code> cannot be defined within a <code class="docutils literal"><span class="pre">&lt;%def&gt;</span></code>, or inside the body of a &#8220;call&#8221;, i.e.
  591. <code class="docutils literal"><span class="pre">&lt;%call&gt;</span></code> or <code class="docutils literal"><span class="pre">&lt;%namespacename:defname&gt;</span></code> tag. Anonymous blocks can, however.</li>
  592. </ul>
  593. </div>
  594. <div class="section" id="using-page-arguments-in-named-blocks">
  595. <h3>Using Page Arguments in Named Blocks<a class="headerlink" href="#using-page-arguments-in-named-blocks" title="Permalink to this headline">¶</a></h3>
  596. <p>A named block is very much like a top level def. It has a similar
  597. restriction to these types of defs in that arguments passed to the
  598. template via the <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag aren&#8217;t automatically available.
  599. Using arguments with the <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag is described in the section
  600. <a class="reference internal" href="namespaces.html#namespaces-body"><span class="std std-ref">The body() Method</span></a>, and refers to scenarios such as when the
  601. <code class="docutils literal"><span class="pre">body()</span></code> method of a template is called from an inherited template passing
  602. arguments, or the template is invoked from an <code class="docutils literal"><span class="pre">&lt;%include&gt;</span></code> tag
  603. with arguments. To allow a named block to share the same arguments
  604. passed to the page, the <code class="docutils literal"><span class="pre">args</span></code> attribute can be used:</p>
  605. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">args=</span><span class="s">&quot;post&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  606. <span class="x">&lt;a name=&quot;</span><span class="cp">${</span><span class="n">post</span><span class="o">.</span><span class="n">title</span><span class="cp">}</span><span class="x">&quot; /&gt;</span>
  607. <span class="x">&lt;span class=&quot;post_prose&quot;&gt;</span>
  608. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;post_prose&quot;</span> <span class="na">args=</span><span class="s">&quot;post&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  609. <span class="x"> </span><span class="cp">${</span><span class="n">post</span><span class="o">.</span><span class="n">content</span><span class="cp">}</span><span class="x"></span>
  610. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  611. <span class="x">&lt;/span&gt;</span>
  612. </pre></div>
  613. </div>
  614. <p>Where above, if the template is called via a directive like
  615. <code class="docutils literal"><span class="pre">&lt;%include</span> <span class="pre">file=&quot;post.mako&quot;</span> <span class="pre">args=&quot;post=post&quot;</span> <span class="pre">/&gt;</span></code>, the <code class="docutils literal"><span class="pre">post</span></code>
  616. variable is available both in the main body as well as the
  617. <code class="docutils literal"><span class="pre">post_prose</span></code> block.</p>
  618. <p>Similarly, the <code class="docutils literal"><span class="pre">**pageargs</span></code> variable is present, in named blocks only,
  619. for those arguments not explicit in the <code class="docutils literal"><span class="pre">&lt;%page&gt;</span></code> tag:</p>
  620. <div class="highlight-mako"><div class="highlight"><pre><span></span><span class="cp">&lt;%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">&quot;post_prose&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  621. <span class="x"> </span><span class="cp">${</span><span class="n">pageargs</span><span class="p">[</span><span class="s1">&#39;post&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">content</span><span class="cp">}</span><span class="x"></span>
  622. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  623. </pre></div>
  624. </div>
  625. <p>The <code class="docutils literal"><span class="pre">args</span></code> attribute is only allowed with named blocks. With
  626. anonymous blocks, the Python function is always rendered in the same
  627. scope as the call itself, so anything available directly outside the
  628. anonymous block is available inside as well.</p>
  629. </div>
  630. </div>
  631. </div>
  632. </div>
  633. </div>
  634. <div id="docs-bottom-navigation" class="docs-navigation-links">
  635. Previous:
  636. <a href="syntax.html" title="previous chapter">Syntax</a>
  637. Next:
  638. <a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>
  639. <div id="docs-copyright">
  640. &copy; Copyright the Mako authors and contributors.
  641. Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.5.3
  642. with Mako templates.
  643. </div>
  644. </div>
  645. </div>
  646. <div class="clearfix">
  647. <hr/>
  648. <div class="copyright">Website content copyright &copy; by Michael Bayer.
  649. All rights reserved. Mako and its documentation are licensed
  650. under the MIT license. mike(&)zzzcomputing.com</div>
  651. </div>
  652. </div>
  653. </body>
  654. </html>