syntax.html 39 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596
  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. Syntax
  7. &mdash;
  8. Mako 0.8.1 Documentation
  9. </title>
  10. <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  11. <link rel="stylesheet" href="_static/docs.css" type="text/css" />
  12. <script type="text/javascript">
  13. var DOCUMENTATION_OPTIONS = {
  14. URL_ROOT: '#',
  15. VERSION: '0.8.1',
  16. COLLAPSE_MODINDEX: false,
  17. FILE_SUFFIX: '.html'
  18. };
  19. </script>
  20. <script type="text/javascript" src="_static/jquery.js"></script>
  21. <script type="text/javascript" src="_static/underscore.js"></script>
  22. <script type="text/javascript" src="_static/doctools.js"></script>
  23. <link rel="index" title="Index" href="genindex.html" />
  24. <link rel="search" title="Search" href="search.html" />
  25. <link rel="top" title="Mako 0.8.1 Documentation" href="index.html" />
  26. <link rel="next" title="Defs and Blocks" href="defs.html" />
  27. <link rel="prev" title="Usage" href="usage.html" />
  28. <link rel="stylesheet" href="_static/site.css"></link>
  29. </head>
  30. <body>
  31. <div id="wrap">
  32. <div class="rightbar">
  33. <div class="slogan">
  34. Hyperfast and lightweight templating for the Python platform.
  35. </div>
  36. </div>
  37. <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
  38. <hr/>
  39. <div id="docs-container">
  40. <div id="docs-header">
  41. <h1>Mako 0.8.1 Documentation</h1>
  42. <div id="docs-search">
  43. Search:
  44. <form class="search" action="search.html" method="get">
  45. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  46. <input type="hidden" name="check_keywords" value="yes" />
  47. <input type="hidden" name="area" value="default" />
  48. </form>
  49. </div>
  50. <div id="docs-version-header">
  51. Release: <span class="version-num">0.8.1</span>
  52. </div>
  53. </div>
  54. <div id="docs-top-navigation">
  55. <div id="docs-top-page-control" class="docs-navigation-links">
  56. <ul>
  57. <li>Prev:
  58. <a href="usage.html" title="previous chapter">Usage</a>
  59. </li>
  60. <li>Next:
  61. <a href="defs.html" title="next chapter">Defs and Blocks</a>
  62. </li>
  63. <li>
  64. <a href="index.html">Table of Contents</a> |
  65. <a href="genindex.html">Index</a>
  66. | <a href="_sources/syntax.txt">view source
  67. </li>
  68. </ul>
  69. </div>
  70. <div id="docs-navigation-banner">
  71. <a href="index.html">Mako 0.8.1 Documentation</a>
  72. »
  73. Syntax
  74. <h2>
  75. Syntax
  76. </h2>
  77. </div>
  78. </div>
  79. <div id="docs-body-container">
  80. <div id="docs-sidebar">
  81. <h3><a href="index.html">Table of Contents</a></h3>
  82. <ul>
  83. <li><a class="reference internal" href="#">Syntax</a><ul>
  84. <li><a class="reference internal" href="#expression-substitution">Expression Substitution</a></li>
  85. <li><a class="reference internal" href="#expression-escaping">Expression Escaping</a></li>
  86. <li><a class="reference internal" href="#control-structures">Control Structures</a><ul>
  87. <li><a class="reference internal" href="#the-loop-context">The Loop Context</a></li>
  88. </ul>
  89. </li>
  90. <li><a class="reference internal" href="#comments">Comments</a></li>
  91. <li><a class="reference internal" href="#newline-filters">Newline Filters</a></li>
  92. <li><a class="reference internal" href="#python-blocks">Python Blocks</a></li>
  93. <li><a class="reference internal" href="#module-level-blocks">Module-level Blocks</a></li>
  94. <li><a class="reference internal" href="#tags">Tags</a><ul>
  95. <li><a class="reference internal" href="#page"><tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt></a></li>
  96. <li><a class="reference internal" href="#include"><tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt></a></li>
  97. <li><a class="reference internal" href="#def"><tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt></a></li>
  98. <li><a class="reference internal" href="#block"><tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt></a></li>
  99. <li><a class="reference internal" href="#namespace"><tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt></a></li>
  100. <li><a class="reference internal" href="#inherit"><tt class="docutils literal"><span class="pre">&lt;%inherit&gt;</span></tt></a></li>
  101. <li><a class="reference internal" href="#nsname-defname"><tt class="docutils literal"><span class="pre">&lt;%</span></tt>nsname<tt class="docutils literal"><span class="pre">:</span></tt>defname<tt class="docutils literal"><span class="pre">&gt;</span></tt></a></li>
  102. <li><a class="reference internal" href="#call"><tt class="docutils literal"><span class="pre">&lt;%call&gt;</span></tt></a></li>
  103. <li><a class="reference internal" href="#doc"><tt class="docutils literal"><span class="pre">&lt;%doc&gt;</span></tt></a></li>
  104. <li><a class="reference internal" href="#text"><tt class="docutils literal"><span class="pre">&lt;%text&gt;</span></tt></a></li>
  105. </ul>
  106. </li>
  107. <li><a class="reference internal" href="#returning-early-from-a-template">Returning Early from a Template</a></li>
  108. </ul>
  109. </li>
  110. </ul>
  111. <h4>Previous Topic</h4>
  112. <p>
  113. <a href="usage.html" title="previous chapter">Usage</a>
  114. </p>
  115. <h4>Next Topic</h4>
  116. <p>
  117. <a href="defs.html" title="next chapter">Defs and Blocks</a>
  118. </p>
  119. <h4>Quick Search</h4>
  120. <p>
  121. <form class="search" action="search.html" method="get">
  122. <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
  123. <input type="hidden" name="check_keywords" value="yes" />
  124. <input type="hidden" name="area" value="default" />
  125. </form>
  126. </p>
  127. </div>
  128. <div id="docs-body" class="withsidebar" >
  129. <div class="section" id="syntax">
  130. <span id="syntax-toplevel"></span><h1>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h1>
  131. <p>A Mako template is parsed from a text stream containing any kind
  132. of content, XML, HTML, email text, etc. The template can further
  133. contain Mako-specific directives which represent variable and/or
  134. expression substitutions, control structures (i.e. conditionals
  135. and loops), server-side comments, full blocks of Python code, as
  136. well as various tags that offer additional functionality. All of
  137. these constructs compile into real Python code. This means that
  138. you can leverage the full power of Python in almost every aspect
  139. of a Mako template.</p>
  140. <div class="section" id="expression-substitution">
  141. <h2>Expression Substitution<a class="headerlink" href="#expression-substitution" title="Permalink to this headline">¶</a></h2>
  142. <p>The simplest expression is just a variable substitution. The
  143. syntax for this is the <tt class="docutils literal"><span class="pre">${}</span></tt> construct, which is inspired by
  144. Perl, Genshi, JSP EL, and others:</p>
  145. <div class="highlight-mako"><div class="highlight"><pre><span class="x">this is x: </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x"></span>
  146. </pre></div>
  147. </div>
  148. <p>Above, the string representation of <tt class="docutils literal"><span class="pre">x</span></tt> is applied to the
  149. template&#8217;s output stream. If you&#8217;re wondering where <tt class="docutils literal"><span class="pre">x</span></tt> comes
  150. from, it&#8217;s usually from the <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a> supplied to the
  151. template&#8217;s rendering function. If <tt class="docutils literal"><span class="pre">x</span></tt> was not supplied to the
  152. template and was not otherwise assigned locally, it evaluates to
  153. a special value <tt class="docutils literal"><span class="pre">UNDEFINED</span></tt>. More on that later.</p>
  154. <p>The contents within the <tt class="docutils literal"><span class="pre">${}</span></tt> tag are evaluated by Python
  155. directly, so full expressions are OK:</p>
  156. <div class="highlight-mako"><div class="highlight"><pre><span class="x">pythagorean theorem: </span><span class="cp">${</span><span class="nb">pow</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="o">+</span> <span class="nb">pow</span><span class="p">(</span><span class="n">y</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  157. </pre></div>
  158. </div>
  159. <p>The results of the expression are evaluated into a string result
  160. in all cases before being rendered to the output stream, such as
  161. the above example where the expression produces a numeric
  162. result.</p>
  163. </div>
  164. <div class="section" id="expression-escaping">
  165. <h2>Expression Escaping<a class="headerlink" href="#expression-escaping" title="Permalink to this headline">¶</a></h2>
  166. <p>Mako includes a number of built-in escaping mechanisms,
  167. including HTML, URI and XML escaping, as well as a &#8220;trim&#8221;
  168. function. These escapes can be added to an expression
  169. substitution using the <tt class="docutils literal"><span class="pre">|</span></tt> operator:</p>
  170. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="s">&quot;this is some text&quot;</span> <span class="o">|</span> <span class="n">u</span><span class="cp">}</span><span class="x"></span>
  171. </pre></div>
  172. </div>
  173. <p>The above expression applies URL escaping to the expression, and
  174. produces <tt class="docutils literal"><span class="pre">this+is+some+text</span></tt>. The <tt class="docutils literal"><span class="pre">u</span></tt> name indicates URL
  175. escaping, whereas <tt class="docutils literal"><span class="pre">h</span></tt> represents HTML escaping, <tt class="docutils literal"><span class="pre">x</span></tt>
  176. represents XML escaping, and <tt class="docutils literal"><span class="pre">trim</span></tt> applies a trim function.</p>
  177. <p>Read more about built-in filtering functions, including how to
  178. make your own filter functions, in <a class="reference internal" href="filtering.html"><em>Filtering and Buffering</em></a>.</p>
  179. </div>
  180. <div class="section" id="control-structures">
  181. <h2>Control Structures<a class="headerlink" href="#control-structures" title="Permalink to this headline">¶</a></h2>
  182. <p>A control structure refers to all those things that control the
  183. flow of a program &#8211; conditionals (i.e. <tt class="docutils literal"><span class="pre">if</span></tt>/<tt class="docutils literal"><span class="pre">else</span></tt>), loops (like
  184. <tt class="docutils literal"><span class="pre">while</span></tt> and <tt class="docutils literal"><span class="pre">for</span></tt>), as well as things like <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">except</span></tt>. In Mako,
  185. control structures are written using the <tt class="docutils literal"><span class="pre">%</span></tt> marker followed
  186. by a regular Python control expression, and are &#8220;closed&#8221; by
  187. using another <tt class="docutils literal"><span class="pre">%</span></tt> marker with the tag &#8220;<tt class="docutils literal"><span class="pre">end&lt;name&gt;</span></tt>&#8221;, where
  188. &#8220;<tt class="docutils literal"><span class="pre">&lt;name&gt;</span></tt>&#8221; is the keyword of the expression:</p>
  189. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">%</span> <span class="k">if</span> <span class="n">x</span><span class="o">==</span><span class="mi">5</span><span class="p">:</span><span class="x"></span>
  190. <span class="x"> this is some output</span>
  191. <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
  192. </pre></div>
  193. </div>
  194. <p>The <tt class="docutils literal"><span class="pre">%</span></tt> can appear anywhere on the line as long as no text
  195. precedes it; indentation is not significant. The full range of
  196. Python &#8220;colon&#8221; expressions are allowed here, including
  197. <tt class="docutils literal"><span class="pre">if</span></tt>/<tt class="docutils literal"><span class="pre">elif</span></tt>/<tt class="docutils literal"><span class="pre">else</span></tt>, <tt class="docutils literal"><span class="pre">while</span></tt>, <tt class="docutils literal"><span class="pre">for</span></tt>, and even <tt class="docutils literal"><span class="pre">def</span></tt>, although
  198. Mako has a built-in tag for defs which is more full-featured.</p>
  199. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">%</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="p">[</span><span class="s">&#39;one&#39;</span><span class="p">,</span> <span class="s">&#39;two&#39;</span><span class="p">,</span> <span class="s">&#39;three&#39;</span><span class="p">,</span> <span class="s">&#39;four&#39;</span><span class="p">,</span> <span class="s">&#39;five&#39;</span><span class="p">]:</span><span class="x"></span>
  200. <span class="cp">%</span> <span class="k">if</span> <span class="n">a</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="s">&#39;t&#39;</span><span class="p">:</span><span class="x"></span>
  201. <span class="x"> its two or three</span>
  202. <span class="cp">%</span> <span class="k">elif</span> <span class="n">a</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="s">&#39;f&#39;</span><span class="p">:</span><span class="x"></span>
  203. <span class="x"> four/five</span>
  204. <span class="cp">%</span> <span class="k">else</span><span class="p">:</span><span class="x"></span>
  205. <span class="x"> one</span>
  206. <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
  207. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  208. </pre></div>
  209. </div>
  210. <p>The <tt class="docutils literal"><span class="pre">%</span></tt> sign can also be &#8220;escaped&#8221;, if you actually want to
  211. emit a percent sign as the first non whitespace character on a
  212. line, by escaping it as in <tt class="docutils literal"><span class="pre">%%</span></tt>:</p>
  213. <div class="highlight-mako"><div class="highlight"><pre><span class="x">%% some text</span>
  214. <span class="x"> %% some more text</span>
  215. </pre></div>
  216. </div>
  217. <div class="section" id="the-loop-context">
  218. <h3>The Loop Context<a class="headerlink" href="#the-loop-context" title="Permalink to this headline">¶</a></h3>
  219. <p>The <strong>loop context</strong> provides additional information about a loop
  220. while inside of a <tt class="docutils literal"><span class="pre">%</span> <span class="pre">for</span></tt> structure:</p>
  221. <div class="highlight-mako"><div class="highlight"><pre><span class="x">&lt;ul&gt;</span>
  222. <span class="cp">%</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="p">(</span><span class="s">&quot;one&quot;</span><span class="p">,</span> <span class="s">&quot;two&quot;</span><span class="p">,</span> <span class="s">&quot;three&quot;</span><span class="p">):</span><span class="x"></span>
  223. <span class="x"> &lt;li&gt;Item </span><span class="cp">${</span><span class="n">loop</span><span class="o">.</span><span class="n">index</span><span class="cp">}</span><span class="x">: </span><span class="cp">${</span><span class="n">a</span><span class="cp">}</span><span class="x">&lt;/li&gt;</span>
  224. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  225. <span class="x">&lt;/ul&gt;</span>
  226. </pre></div>
  227. </div>
  228. <p>See <a class="reference internal" href="runtime.html#loop-context"><em>The Loop Context</em></a> for more information on this feature.</p>
  229. <p class="versionadded">
  230. <span class="versionmodified">New in version 0.7.</span></p>
  231. </div>
  232. </div>
  233. <div class="section" id="comments">
  234. <h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2>
  235. <p>Comments come in two varieties. The single line comment uses
  236. <tt class="docutils literal"><span class="pre">##</span></tt> as the first non-space characters on a line:</p>
  237. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">## this is a comment.</span><span class="x"></span>
  238. <span class="x">...text ...</span>
  239. </pre></div>
  240. </div>
  241. <p>A multiline version exists using <tt class="docutils literal"><span class="pre">&lt;%doc&gt;</span> <span class="pre">...text...</span> <span class="pre">&lt;/%doc&gt;</span></tt>:</p>
  242. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%doc&gt;</span>
  243. <span class="cp"> these are comments</span>
  244. <span class="cp"> more comments</span>
  245. <span class="cp">&lt;/%doc&gt;</span><span class="x"></span>
  246. </pre></div>
  247. </div>
  248. </div>
  249. <div class="section" id="newline-filters">
  250. <h2>Newline Filters<a class="headerlink" href="#newline-filters" title="Permalink to this headline">¶</a></h2>
  251. <p>The backslash (&#8220;<tt class="docutils literal"><span class="pre">\</span></tt>&#8221;) character, placed at the end of any
  252. line, will consume the newline character before continuing to
  253. the next line:</p>
  254. <div class="highlight-mako"><div class="highlight"><pre><span class="x">here is a line that goes onto </span><span class="o">\</span>
  255. <span class="x">another line.</span>
  256. </pre></div>
  257. </div>
  258. <p>The above text evaluates to:</p>
  259. <div class="highlight-text"><div class="highlight"><pre>here is a line that goes onto another line.
  260. </pre></div>
  261. </div>
  262. </div>
  263. <div class="section" id="python-blocks">
  264. <h2>Python Blocks<a class="headerlink" href="#python-blocks" title="Permalink to this headline">¶</a></h2>
  265. <p>Any arbitrary block of python can be dropped in using the <tt class="docutils literal"><span class="pre">&lt;%</span>
  266. <span class="pre">%&gt;</span></tt> tags:</p>
  267. <div class="highlight-mako"><div class="highlight"><pre><span class="x">this is a template</span>
  268. <span class="cp">&lt;%</span>
  269. <span class="n">x</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">get_resource</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">)</span>
  270. <span class="n">y</span> <span class="o">=</span> <span class="p">[</span><span class="n">z</span><span class="o">.</span><span class="n">element</span> <span class="k">for</span> <span class="n">z</span> <span class="ow">in</span> <span class="n">x</span> <span class="k">if</span> <span class="n">x</span><span class="o">.</span><span class="n">frobnizzle</span><span class="o">==</span><span class="mi">5</span><span class="p">]</span>
  271. <span class="cp">%&gt;</span>
  272. <span class="cp">%</span> <span class="k">for</span> <span class="n">elem</span> <span class="ow">in</span> <span class="n">y</span><span class="p">:</span><span class="x"></span>
  273. <span class="x"> element: </span><span class="cp">${</span><span class="n">elem</span><span class="cp">}</span>
  274. <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
  275. </pre></div>
  276. </div>
  277. <p>Within <tt class="docutils literal"><span class="pre">&lt;%</span> <span class="pre">%&gt;</span></tt>, you&#8217;re writing a regular block of Python code.
  278. While the code can appear with an arbitrary level of preceding
  279. whitespace, it has to be consistently formatted with itself.
  280. Mako&#8217;s compiler will adjust the block of Python to be consistent
  281. with the surrounding generated Python code.</p>
  282. </div>
  283. <div class="section" id="module-level-blocks">
  284. <h2>Module-level Blocks<a class="headerlink" href="#module-level-blocks" title="Permalink to this headline">¶</a></h2>
  285. <p>A variant on <tt class="docutils literal"><span class="pre">&lt;%</span> <span class="pre">%&gt;</span></tt> is the module-level code block, denoted
  286. by <tt class="docutils literal"><span class="pre">&lt;%!</span> <span class="pre">%&gt;</span></tt>. Code within these tags is executed at the module
  287. level of the template, and not within the rendering function of
  288. the template. Therefore, this code does not have access to the
  289. template&#8217;s context and is only executed when the template is
  290. loaded into memory (which can be only once per application, or
  291. more, depending on the runtime environment). Use the <tt class="docutils literal"><span class="pre">&lt;%!</span> <span class="pre">%&gt;</span></tt>
  292. tags to declare your template&#8217;s imports, as well as any
  293. pure-Python functions you might want to declare:</p>
  294. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%!</span>
  295. <span class="kn">import</span> <span class="nn">mylib</span>
  296. <span class="kn">import</span> <span class="nn">re</span>
  297. <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="n">text</span><span class="p">):</span>
  298. <span class="k">return</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">r&#39;^@&#39;</span><span class="p">,</span> <span class="s">&#39;&#39;</span><span class="p">,</span> <span class="n">text</span><span class="p">)</span>
  299. <span class="cp">%&gt;</span><span class="x"></span>
  300. </pre></div>
  301. </div>
  302. <p>Any number of <tt class="docutils literal"><span class="pre">&lt;%!</span> <span class="pre">%&gt;</span></tt> blocks can be declared anywhere in a
  303. template; they will be rendered in the resulting module
  304. in a single contiguous block above all render callables,
  305. in the order in which they appear in the source template.</p>
  306. </div>
  307. <div class="section" id="tags">
  308. <h2>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h2>
  309. <p>The rest of what Mako offers takes place in the form of tags.
  310. All tags use the same syntax, which is similar to an XML tag
  311. except that the first character of the tag name is a <tt class="docutils literal"><span class="pre">%</span></tt>
  312. character. The tag is closed either by a contained slash
  313. character, or an explicit closing tag:</p>
  314. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;foo.txt&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  315. <span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;foo&quot;</span> <span class="na">buffered=</span><span class="s">&quot;True&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  316. <span class="x"> this is a def</span>
  317. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  318. </pre></div>
  319. </div>
  320. <p>All tags have a set of attributes which are defined for each
  321. tag. Some of these attributes are required. Also, many
  322. attributes support <strong>evaluation</strong>, meaning you can embed an
  323. expression (using <tt class="docutils literal"><span class="pre">${}</span></tt>) inside the attribute text:</p>
  324. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;/foo/bar/${myfile}.txt&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  325. </pre></div>
  326. </div>
  327. <p>Whether or not an attribute accepts runtime evaluation depends
  328. on the type of tag and how that tag is compiled into the
  329. template. The best way to find out if you can stick an
  330. expression in is to try it! The lexer will tell you if it&#8217;s not
  331. valid.</p>
  332. <p>Heres a quick summary of all the tags:</p>
  333. <div class="section" id="page">
  334. <h3><tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt><a class="headerlink" href="#page" title="Permalink to this headline">¶</a></h3>
  335. <p>This tag defines general characteristics of the template,
  336. including caching arguments, and optional lists of arguments
  337. which the template expects when invoked.</p>
  338. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">args=</span><span class="s">&quot;x, y, z=&#39;default&#39;&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  339. </pre></div>
  340. </div>
  341. <p>Or a page tag that defines caching characteristics:</p>
  342. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">page</span> <span class="na">cached=</span><span class="s">&quot;True&quot;</span> <span class="na">cache_type=</span><span class="s">&quot;memory&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  343. </pre></div>
  344. </div>
  345. <p>Currently, only one <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> tag gets used per template, the
  346. rest get ignored. While this will be improved in a future
  347. release, for now make sure you have only one <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> tag
  348. defined in your template, else you may not get the results you
  349. want. The details of what <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> is used for are described
  350. further in <a class="reference internal" href="namespaces.html#namespaces-body"><em>The body() Method</em></a> as well as <a class="reference internal" href="caching.html"><em>Caching</em></a>.</p>
  351. </div>
  352. <div class="section" id="include">
  353. <h3><tt class="docutils literal"><span class="pre">&lt;%include&gt;</span></tt><a class="headerlink" href="#include" title="Permalink to this headline">¶</a></h3>
  354. <p>A tag that is familiar from other template languages, <tt class="docutils literal"><span class="pre">%include</span></tt>
  355. is a regular joe that just accepts a file argument and calls in
  356. the rendered result of that file:</p>
  357. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;header.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  358. <span class="x"> hello world</span>
  359. <span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;footer.html&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  360. </pre></div>
  361. </div>
  362. <p>Include also accepts arguments which are available as <tt class="docutils literal"><span class="pre">&lt;%page&gt;</span></tt> arguments in the receiving template:</p>
  363. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">&quot;toolbar.html&quot;</span> <span class="na">args=</span><span class="s">&quot;current_section=&#39;members&#39;, username=&#39;ed&#39;&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  364. </pre></div>
  365. </div>
  366. </div>
  367. <div class="section" id="def">
  368. <h3><tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt><a class="headerlink" href="#def" title="Permalink to this headline">¶</a></h3>
  369. <p>The <tt class="docutils literal"><span class="pre">%def</span></tt> tag defines a Python function which contains a set
  370. of content, that can be called at some other point in the
  371. template. The basic idea is simple:</p>
  372. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;myfunc(x)&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  373. <span class="x"> this is myfunc, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x"></span>
  374. <span class="cp">&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  375. <span class="cp">${</span><span class="n">myfunc</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
  376. </pre></div>
  377. </div>
  378. <p>The <tt class="docutils literal"><span class="pre">%def</span></tt> tag is a lot more powerful than a plain Python <tt class="docutils literal"><span class="pre">def</span></tt>, as
  379. the Mako compiler provides many extra services with <tt class="docutils literal"><span class="pre">%def</span></tt> that
  380. you wouldn&#8217;t normally have, such as the ability to export defs
  381. as template &#8220;methods&#8221;, automatic propagation of the current
  382. <a class="reference internal" href="runtime.html#mako.runtime.Context" title="mako.runtime.Context"><tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt></a>, buffering/filtering/caching flags, and def calls
  383. with content, which enable packages of defs to be sent as
  384. arguments to other def calls (not as hard as it sounds). Get the
  385. full deal on what <tt class="docutils literal"><span class="pre">%def</span></tt> can do in <a class="reference internal" href="defs.html"><em>Defs and Blocks</em></a>.</p>
  386. </div>
  387. <div class="section" id="block">
  388. <h3><tt class="docutils literal"><span class="pre">&lt;%block&gt;</span></tt><a class="headerlink" href="#block" title="Permalink to this headline">¶</a></h3>
  389. <p><tt class="docutils literal"><span class="pre">%block</span></tt> is a tag that is close to a <tt class="docutils literal"><span class="pre">%def</span></tt>,
  390. except executes itself immediately in its base-most scope,
  391. and can also be anonymous (i.e. with no name):</p>
  392. <div class="highlight-mako"><div class="highlight"><pre><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>
  393. <span class="x"> some &lt;html&gt; stuff.</span>
  394. <span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  395. </pre></div>
  396. </div>
  397. <p>Inspired by Jinja2 blocks, named blocks offer a syntactically pleasing way
  398. to do inheritance:</p>
  399. <div class="highlight-mako"><div class="highlight"><pre><span class="x">&lt;html&gt;</span>
  400. <span class="x"> &lt;body&gt;</span>
  401. <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>
  402. <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>
  403. <span class="x"> </span><span class="cp">&lt;/%</span><span class="nb">block</span><span class="cp">&gt;</span><span class="x"></span>
  404. <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>
  405. <span class="x"> &lt;/body&gt;</span>
  406. <span class="x">&lt;/html&gt;</span>
  407. </pre></div>
  408. </div>
  409. <p>Blocks are introduced in <a class="reference internal" href="defs.html#blocks"><em>Using Blocks</em></a> and further described in <a class="reference internal" href="inheritance.html"><em>Inheritance</em></a>.</p>
  410. <p class="versionadded">
  411. <span class="versionmodified">New in version 0.4.1.</span></p>
  412. </div>
  413. <div class="section" id="namespace">
  414. <h3><tt class="docutils literal"><span class="pre">&lt;%namespace&gt;</span></tt><a class="headerlink" href="#namespace" title="Permalink to this headline">¶</a></h3>
  415. <p><tt class="docutils literal"><span class="pre">%namespace</span></tt> is Mako&#8217;s equivalent of Python&#8217;s <tt class="docutils literal"><span class="pre">import</span></tt>
  416. statement. It allows access to all the rendering functions and
  417. metadata of other template files, plain Python modules, as well
  418. as locally defined &#8220;packages&#8221; of functions.</p>
  419. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">namespace</span> <span class="na">file=</span><span class="s">&quot;functions.html&quot;</span> <span class="na">import=</span><span class="s">&quot;*&quot;</span><span class="cp">/&gt;</span><span class="x"></span>
  420. </pre></div>
  421. </div>
  422. <p>The underlying object generated by <tt class="docutils literal"><span class="pre">%namespace</span></tt>, an instance of
  423. <a class="reference internal" href="namespaces.html#mako.runtime.Namespace" title="mako.runtime.Namespace"><tt class="xref py py-class docutils literal"><span class="pre">mako.runtime.Namespace</span></tt></a>, is a central construct used in
  424. templates to reference template-specific information such as the
  425. current URI, inheritance structures, and other things that are
  426. not as hard as they sound right here. Namespaces are described
  427. in <a class="reference internal" href="namespaces.html"><em>Namespaces</em></a>.</p>
  428. </div>
  429. <div class="section" id="inherit">
  430. <h3><tt class="docutils literal"><span class="pre">&lt;%inherit&gt;</span></tt><a class="headerlink" href="#inherit" title="Permalink to this headline">¶</a></h3>
  431. <p>Inherit allows templates to arrange themselves in <strong>inheritance
  432. chains</strong>. This is a concept familiar in many other template
  433. languages.</p>
  434. <div class="highlight-mako"><div class="highlight"><pre><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>
  435. </pre></div>
  436. </div>
  437. <p>When using the <tt class="docutils literal"><span class="pre">%inherit</span></tt> tag, control is passed to the topmost
  438. inherited template first, which then decides how to handle
  439. calling areas of content from its inheriting templates. Mako
  440. offers a lot of flexibility in this area, including dynamic
  441. inheritance, content wrapping, and polymorphic method calls.
  442. Check it out in <a class="reference internal" href="inheritance.html"><em>Inheritance</em></a>.</p>
  443. </div>
  444. <div class="section" id="nsname-defname">
  445. <h3><tt class="docutils literal"><span class="pre">&lt;%</span></tt>nsname<tt class="docutils literal"><span class="pre">:</span></tt>defname<tt class="docutils literal"><span class="pre">&gt;</span></tt><a class="headerlink" href="#nsname-defname" title="Permalink to this headline">¶</a></h3>
  446. <p>Any user-defined &#8220;tag&#8221; can be created against
  447. a namespace by using a tag with a name of the form
  448. <tt class="docutils literal"><span class="pre">&lt;%&lt;namespacename&gt;:&lt;defname&gt;&gt;</span></tt>. The closed and open formats of such a
  449. tag are equivalent to an inline expression and the <tt class="docutils literal"><span class="pre">&lt;%call&gt;</span></tt>
  450. tag, respectively.</p>
  451. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">mynamespace:somedef</span> <span class="na">param=</span><span class="s">&quot;some value&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  452. <span class="x"> this is the body</span>
  453. <span class="cp">&lt;/%</span><span class="nb">mynamespace:somedef</span><span class="cp">&gt;</span><span class="x"></span>
  454. </pre></div>
  455. </div>
  456. <p>To create custom tags which accept a body, see
  457. <a class="reference internal" href="defs.html#defs-with-content"><em>Calling a Def with Embedded Content and/or Other Defs</em></a>.</p>
  458. <p class="versionadded">
  459. <span class="versionmodified">New in version 0.2.3.</span></p>
  460. </div>
  461. <div class="section" id="call">
  462. <h3><tt class="docutils literal"><span class="pre">&lt;%call&gt;</span></tt><a class="headerlink" href="#call" title="Permalink to this headline">¶</a></h3>
  463. <p>The call tag is the &#8220;classic&#8221; form of a user-defined tag, and is
  464. roughly equivalent to the <tt class="docutils literal"><span class="pre">&lt;%namespacename:defname&gt;</span></tt> syntax
  465. described above. This tag is also described in <a class="reference internal" href="defs.html#defs-with-content"><em>Calling a Def with Embedded Content and/or Other Defs</em></a>.</p>
  466. </div>
  467. <div class="section" id="doc">
  468. <h3><tt class="docutils literal"><span class="pre">&lt;%doc&gt;</span></tt><a class="headerlink" href="#doc" title="Permalink to this headline">¶</a></h3>
  469. <p>The <tt class="docutils literal"><span class="pre">%doc</span></tt> tag handles multiline comments:</p>
  470. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%doc&gt;</span>
  471. <span class="cp"> these are comments</span>
  472. <span class="cp"> more comments</span>
  473. <span class="cp">&lt;/%doc&gt;</span><span class="x"></span>
  474. </pre></div>
  475. </div>
  476. <p>Also the <tt class="docutils literal"><span class="pre">##</span></tt> symbol as the first non-space characters on a line can be used for single line comments.</p>
  477. </div>
  478. <div class="section" id="text">
  479. <h3><tt class="docutils literal"><span class="pre">&lt;%text&gt;</span></tt><a class="headerlink" href="#text" title="Permalink to this headline">¶</a></h3>
  480. <p>This tag suspends the Mako lexer&#8217;s normal parsing of Mako
  481. template directives, and returns its entire body contents as
  482. plain text. It is used pretty much to write documentation about
  483. Mako:</p>
  484. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span><span class="nb">text</span> <span class="na">filter=</span><span class="s">&quot;h&quot;</span><span class="cp">&gt;</span><span class="x"></span>
  485. <span class="x"> heres some fake mako </span><span class="cp">${</span><span class="n">syntax</span><span class="cp">}</span><span class="x"></span>
  486. <span class="x"> </span><span class="cp">&lt;%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">&quot;x()&quot;</span><span class="cp">&gt;${</span><span class="n">x</span><span class="cp">}&lt;/%</span><span class="nb">def</span><span class="cp">&gt;</span><span class="x"></span>
  487. <span class="cp">&lt;/%</span><span class="nb">text</span><span class="cp">&gt;</span><span class="x"></span>
  488. </pre></div>
  489. </div>
  490. </div>
  491. </div>
  492. <div class="section" id="returning-early-from-a-template">
  493. <h2>Returning Early from a Template<a class="headerlink" href="#returning-early-from-a-template" title="Permalink to this headline">¶</a></h2>
  494. <p>Sometimes you want to stop processing a template or <tt class="docutils literal"><span class="pre">&lt;%def&gt;</span></tt>
  495. method in the middle and just use the text you&#8217;ve accumulated so
  496. far. You can use a <tt class="docutils literal"><span class="pre">return</span></tt> statement inside a Python
  497. block to do that.</p>
  498. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">%</span> <span class="k">if</span> <span class="ow">not</span> <span class="nb">len</span><span class="p">(</span><span class="n">records</span><span class="p">):</span><span class="x"></span>
  499. <span class="x"> No records found.</span>
  500. <span class="x"> </span><span class="cp">&lt;%</span> <span class="k">return</span> <span class="cp">%&gt;</span>
  501. <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
  502. </pre></div>
  503. </div>
  504. <p>Or perhaps:</p>
  505. <div class="highlight-mako"><div class="highlight"><pre><span class="cp">&lt;%</span>
  506. <span class="k">if</span> <span class="ow">not</span> <span class="nb">len</span><span class="p">(</span><span class="n">records</span><span class="p">):</span>
  507. <span class="k">return</span>
  508. <span class="cp">%&gt;</span><span class="x"></span>
  509. </pre></div>
  510. </div>
  511. </div>
  512. </div>
  513. </div>
  514. </div>
  515. <div id="docs-bottom-navigation" class="docs-navigation-links">
  516. Previous:
  517. <a href="usage.html" title="previous chapter">Usage</a>
  518. Next:
  519. <a href="defs.html" title="next chapter">Defs and Blocks</a>
  520. <div id="docs-copyright">
  521. &copy; Copyright the Mako authors and contributors.
  522. Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3
  523. with Mako templates.
  524. </div>
  525. </div>
  526. </div>
  527. <div class="clearfix">
  528. <hr/>
  529. <div class="copyright">Website content copyright &copy; by Michael Bayer.
  530. All rights reserved. Mako and its documentation are licensed
  531. under the MIT license. mike(&)zzzcomputing.com</div>
  532. </div>
  533. </div>
  534. </body>
  535. </html>