3
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
4
<title>Mako Documentation - Syntax</title>
6
<link rel="stylesheet" href="docs.css"></link>
7
<link rel="stylesheet" href="highlight.css"></link>
25
<div id="topanchor"><a name="top"> </a></div>
27
<div id="pagecontrol"><a href="index.html">Multiple Pages</a> | <a href="documentation.html">One Page</a></div>
29
<h1>Mako Documentation</h1>
31
<div class="versionheader">Version: 0.1.9 Last Updated: 09/25/07 16:19:18</div>
46
<div class="prevnext">
47
Previous: <a href="usage.html">Basic Usage</a>
50
Next: <a href="defs.html">Defs</a>
52
<h3><a href="index.html">Table of Contents</a></h3>
57
<a href="#syntax">Syntax</a>
61
<li><A style="" href="syntax.html#syntax_expression">Expression Substiution</a></li>
65
<li><A style="" href="syntax.html#syntax_expression_expression">Expression Escaping</a></li>
73
<li><A style="" href="syntax.html#syntax_control">Control Structures</a></li>
79
<li><A style="" href="syntax.html#syntax_comments">Comments</a></li>
85
<li><A style="" href="syntax.html#syntax_newline">Newline Filters</a></li>
91
<li><A style="" href="syntax.html#syntax_python">Python Blocks</a></li>
95
<li><A style="" href="syntax.html#syntax_python_module-level">Module-level Blocks</a></li>
103
<li><A style="" href="syntax.html#syntax_tags">Tags</a></li>
107
<li><A style="" href="syntax.html#syntax_tags_page"><%page></a></li>
113
<li><A style="" href="syntax.html#syntax_tags_include"><%include></a></li>
119
<li><A style="" href="syntax.html#syntax_tags_def"><%def></a></li>
125
<li><A style="" href="syntax.html#syntax_tags_namespace"><%namespace></a></li>
131
<li><A style="" href="syntax.html#syntax_tags_inherit"><%inherit></a></li>
137
<li><A style="" href="syntax.html#syntax_tags_call"><%call></a></li>
143
<li><A style="" href="syntax.html#syntax_tags_doc"><%doc></a></li>
149
<li><A style="" href="syntax.html#syntax_tags_text"><%text></a></li>
172
<A name="syntax"></a>
174
<div class="section">
181
<p>A Mako template is parsed from a text stream containing any kind of content, XML, HTML, email text, etc. The template can further contain Mako-specific directives which represent variable and/or expression substitutions, control structures (i.e. conditionals and loops), server-side comments, full blocks of Python code, as well as various tags that offer additional functionality. All of these constructs compile into real Python code. This means that you can leverage the full power of Python in almost every aspect of a Mako template.
186
<A name="syntax_expression"></a>
188
<div class="subsection">
191
<h3>Expression Substiution</h3>
195
<p>The simplest expression is just a variable substitution. The syntax for this is the <code>${}</code> construct, which is inspired by Perl, Genshi, JSP EL, and others:
202
<div class="highlight" ><pre>this is x: <span class="cp">${</span><span class="n">x</span><span class="cp">}</span>
206
<p>Above, the string representation of <code>x</code> is applied to the template's output stream. If you're wondering where <code>x</code> comes from, its usually from the <code>Context</code> supplied to the template's rendering function. If <code>x</code> was not supplied to the template and was not otherwise assigned locally, it evaluates to a special value <code>UNDEFINED</code>. More on that later.
208
<p>The contents within the <code>${}</code> tag are evaluated by Python directly, so full expressions are OK:
215
<div class="highlight" ><pre>pythagorean theorem: <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>
219
<p>The results of the expression are evaluated into a string result in all cases before being rendered to the output stream, such as the above example where the expression produces a numeric result.
224
<A name="syntax_expression_expression"></a>
226
<div class="subsection">
229
<h3>Expression Escaping</h3>
233
<p>Mako includes a number of built-in escaping mechanisms, including HTML, URI and XML escaping, as well as a "trim" function. These escapes can be added to an expression substituion using the <code>|</code> operator:
240
<div class="highlight" ><pre><span class="cp">${</span><span class="s">"this is some text"</span> <span class="o">|</span> <span class="n">u</span><span class="cp">}</span>
244
<p>The above expression applies URL escaping to the expression, and produces <code>this+is+some+text</code>. The <code>u</code> name indicates URL escaping, whereas <code>h</code> represents HTML escaping, <code>x</code> represents XML escaping, and <code>trim</code> applies a trim function.
246
<p>Read more about built in filtering functions, including how to make your own filter functions, in <a href="filtering.html">Filtering and Buffering</a>.
256
<a href="#top">back to section top</a>
262
<A name="syntax_control"></a>
264
<div class="subsection">
267
<h3>Control Structures</h3>
271
<p>A control structure refers to all those things that control the flow of a program - conditionals (i.e. if/else), loops (like while and for), as well as things like <code>try/except</code>. In Mako, control structures are written using the <code>%</code> marker followed by a regular Python control expression, and are "closed" by using another <code>%</code> marker with the tag "<code>end<name></code>", where "<code><name></code>" is the keyword of the expression:
278
<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>
280
<span class="cp">%</span><span class="k"> endif</span>
284
<p>The <code>%</code> can appear anywhere on the line as long as no text precedes it; indentation is not signficant. The full range of Python "colon" expressions are allowed here, including <code>if/elif/else</code>, <code>while</code>, <code>for</code>, and even <code>def</code>, although Mako has a built-in tag for defs which is more full-featured.
291
<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">'one'</span><span class="p">,</span> <span class="s">'two'</span><span class="p">,</span> <span class="s">'three'</span><span class="p">,</span> <span class="s">'four'</span><span class="p">,</span> <span class="s">'five'</span><span class="p">]:</span>
292
<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">'t'</span><span class="p">:</span>
294
<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">'f'</span><span class="p">:</span>
296
<span class="cp">%</span> <span class="k">else</span><span class="p">:</span>
298
<span class="cp">%</span><span class="k">endif</span>
299
<span class="cp">%</span><span class="k"> endfor</span>
306
<a href="#top">back to section top</a>
312
<A name="syntax_comments"></a>
314
<div class="subsection">
321
<p>Comments come in two varieties. The single line comment uses <code>##</code> as the first non-space characters on a line:
328
<div class="highlight" ><pre><span class="cp">## this is a comment.</span>
333
<p>A multiline version exists using <code><%doc> ...text... </%doc></code>:
340
<div class="highlight" ><pre><span class="cp"><%doc></span>
341
<span class="cp"> these are comments</span>
342
<span class="cp"> more comments</span>
343
<span class="cp"></%doc></span>
347
<p>Note that this is <strong>new behavior as of Mako 0.1.3</strong>. The syntax prior to this version was the single pound sign (<code>#</code>), which was agreed by the Mako userbase that it conflicted with CSS elements too often and also did not address multiline comments easily.
352
<a href="#top">back to section top</a>
358
<A name="syntax_newline"></a>
360
<div class="subsection">
363
<h3>Newline Filters</h3>
367
<p>The backslash ("<code>\</code>") character, placed at the end of any line, will consume the newline character before continuing to the next line:
374
<div class="highlight" ><pre>here is a line that goes onto <span class="o">\</span>
375
<span class="o"></span>another line.
379
<p>The above text evaluates to:
386
<div class="highlight" ><pre>here is a line that goes onto another line.
393
<a href="#top">back to section top</a>
399
<A name="syntax_python"></a>
401
<div class="subsection">
404
<h3>Python Blocks</h3>
408
<p>Any arbitrary block of python can be dropped in using the <code><% %></code> tags:
415
<div class="highlight" ><pre>this is a template
416
<span class="cp"><%</span>
417
<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">'foo'</span><span class="p">)</span>
418
<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>
419
<span class="cp">%></span>
420
<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>
421
element: <span class="cp">${</span><span class="n">y</span><span class="cp">}</span>
422
<span class="cp">%</span><span class="k"> endfor</span>
426
<p>Within <code><% %></code>, you're writing a regular block of Python code. While the code can appear with an arbitrary level of preceding whitespace, it has to be consistently formatted with itself. Mako's compiler will adjust the block of Python to be consistent with the surrounding generated Python code.
431
<A name="syntax_python_module-level"></a>
433
<div class="subsection">
436
<h3>Module-level Blocks</h3>
440
<p>A variant on <code><% %></code> is the module-level code block, denoted by <code><%! %></code>. Code within these tags is executed at the module level of the template, and not within the rendering function of the template. Therefore, this code does not have access to the template's context and is only executed when the template is loaded into memory (which can be only once per application, or more, depending on the runtime environment). Use the <code><%! %></code> tags to declare your template's imports, as well as any pure-Python functions you might want to declare:
447
<div class="highlight" ><pre><span class="cp"><%!</span>
448
<span class="k">import</span> <span class="nn">mylib</span>
449
<span class="k">import</span> <span class="nn">re</span>
451
<span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="n">text</span><span class="p">):</span>
452
<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'^@'</span><span class="p">,</span> <span class="s">''</span><span class="p">,</span> <span class="n">text</span><span class="p">)</span>
453
<span class="cp">%></span>
457
<p>Any number of <code><%! %></code> blocks can be declared anywhere in a template; they will be rendered in the resulting module in the order that they appear.
467
<a href="#top">back to section top</a>
473
<A name="syntax_tags"></a>
475
<div class="subsection">
482
<p>The rest of what Mako offers takes place in the form of tags. All tags use the same syntax, which is similar to an XML tag except that the first character of the tag name is a <code>%</code> character. The tag is closed either by a contained slash character, or an explicit closing tag:
489
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">"foo.txt"</span><span class="cp">/></span>
491
<span class="cp"><%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">"foo"</span> <span class="na">buffered=</span><span class="s">"True"</span><span class="cp">></span>
493
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span>
497
<p>All tags have a set of attributes which are defined for each tag. Some of these attributes are required. Also, many attributes support <strong>evaluation</strong>, meaning you can embed an expression (using <code>${}</code>) inside the attribute text:
504
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">"/foo/bar/${myfile}.txt"</span><span class="cp">/></span>
508
<p>Whether or not an attribute accepts runtime evaluation depends on the type of tag and how that tag is compiled into the template. The best way to find out if you can stick an expression in is to try it ! The lexer will tell you if its not valid.
510
<p>Heres a quick summary of all the tags:
515
<A name="syntax_tags_page"></a>
517
<div class="subsection">
524
<p>This tag defines general characteristics of the template, including caching arguments, and optional lists of arguments which the template expects when invoked.
531
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">page</span> <span class="na">args=</span><span class="s">"x, y, z='default'"</span><span class="cp">/></span>
535
<p>Or a page tag that defines caching characteristics:
542
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">page</span> <span class="na">cached=</span><span class="s">"True"</span> <span class="na">cache_type=</span><span class="s">"memory"</span><span class="cp">/></span>
546
<p>Currently, only one <code><%page></code> tag gets used per template, the rest get ignored. While this will be improved in a future release, for now make sure you have only one <code><%page></code> tag defined in your template, else you may not get the results you want. The details of what <code><%page></code> is used for are described further in <a href="namespaces.html#namespaces_body">The "body()" method</a> as well as <a href="caching.html">Caching</a>.
551
<a href="#top">back to section top</a>
557
<A name="syntax_tags_include"></a>
559
<div class="subsection">
566
<p>A tag that is familiar from other template languages, %include is a regular joe that just accepts a file argument and calls in the rendered result of that file:
573
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">"header.html"</span><span class="cp">/></span>
577
<span class="cp"><%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">"footer.html"</span><span class="cp">/></span>
584
<a href="#top">back to section top</a>
590
<A name="syntax_tags_def"></a>
592
<div class="subsection">
599
<p>The <code>%def</code> tag defines a Python function which contains a set of content, that can be called at some other point in the template. The basic idea is simple:
606
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">"myfunc(x)"</span><span class="cp">></span>
607
this is myfunc, x is <span class="cp">${</span><span class="n">x</span><span class="cp">}</span>
608
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span>
610
<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>
614
<p>The %def tag is a lot more powerful than a plain Python def, as the Mako compiler provides many extra services with %def that you wouldn't normally have, such as the ability to export defs as template "methods", automatic propigation of the current <code>Context</code>, buffering/filtering/caching flags, and def calls with content, which enable packages of defs to be sent as arguments to other def calls (not as hard as it sounds). Get the full deal on what %def can do in <a href="defs.html">Defs</a>.
619
<a href="#top">back to section top</a>
625
<A name="syntax_tags_namespace"></a>
627
<div class="subsection">
630
<h3><%namespace></h3>
634
<p>%namespace is Mako's equivalent of Python's <code>import</code> statement. It allows access to all the rendering functions and metadata of other template files, plain Python modules, as well as locally defined "packages" of functions.
641
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">namespace</span> <span class="na">file=</span><span class="s">"functions.html"</span> <span class="na">import=</span><span class="s">"*"</span><span class="cp">/></span>
645
<p>The underlying object generated by %namespace, an instance of <code>mako.runtime.Namespace</code>, is a central construct used in templates to reference template-specific information such as the current URI, inheritance structures, and other things that are not as hard as they sound right here. Namespaces are described in <a href="namespaces.html">Namespaces</a>.
650
<a href="#top">back to section top</a>
656
<A name="syntax_tags_inherit"></a>
658
<div class="subsection">
665
<p>Inherit allows templates to arrange themselves in <strong>inheritance chains</strong>. This is a concept familiar in many other template languages.
672
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">inherit</span> <span class="na">file=</span><span class="s">"base.html"</span><span class="cp">/></span>
676
<p>When using the %inherit tag, control is passed to the topmost inherited template first, which then decides how to handle calling areas of content from its inheriting templates. Mako offers a lot of flexbility in this area, including dynamic inheritance, content wrapping, and polymorphic method calls. Check it out in <a href="inheritance.html">Inheritance</a>.
681
<a href="#top">back to section top</a>
687
<A name="syntax_tags_call"></a>
689
<div class="subsection">
696
<p>The call tag is used to call <code><%defs></code> with additional embedded content. This tag is described in <a href="defs.html#defs_defswithcontent">Calling a def with embedded content and/or other defs</a>.
701
<a href="#top">back to section top</a>
707
<A name="syntax_tags_doc"></a>
709
<div class="subsection">
716
<p>The doc tag handles multiline comments:
723
<div class="highlight" ><pre><span class="cp"><%doc></span>
724
<span class="cp"> these are comments</span>
725
<span class="cp"> more comments</span>
726
<span class="cp"></%doc></span>
730
<p>Also the <code>##</code> symbol as the first non-space characters on a line can be used for single line comments.
735
<a href="#top">back to section top</a>
741
<A name="syntax_tags_text"></a>
743
<div class="subsection">
750
<p>This tag suspends the Mako lexer's normal parsing of Mako template directives, and returns its entire body contents as plain text. It is used pretty much to write documentation about Mako:
757
<div class="highlight" ><pre><span class="cp"><%</span><span class="nb">text</span> <span class="na">filter=</span><span class="s">"h"</span><span class="cp">></span>
758
heres some fake mako <span class="cp">${</span><span class="n">syntax</span><span class="cp">}</span>
759
<span class="cp"><%</span><span class="nb">def</span> <span class="na">name=</span><span class="s">"x()"</span><span class="cp">>${</span><span class="n">x</span><span class="cp">}</%</span><span class="nb">def</span><span class="cp">></span>
760
<span class="cp"></%</span><span class="nb">text</span><span class="cp">></span>
778
<a href="#top">back to section top</a>
785
<div class="toolbar">
786
<div class="prevnext">
787
Previous: <a href="usage.html">Basic Usage</a>
790
Next: <a href="defs.html">Defs</a>
792
<h3><a href="index.html">Table of Contents</a></h3>
added
removed
src/Mako-0.1.9/doc/syntax.html
