| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596 |
- <html xmlns="http://www.w3.org/1999/xhtml">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
- <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
- <head>
- <title>
-
- Syntax
- —
- Mako 0.8.1 Documentation
- </title>
- <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
- <link rel="stylesheet" href="_static/docs.css" type="text/css" />
- <script type="text/javascript">
- var DOCUMENTATION_OPTIONS = {
- URL_ROOT: '#',
- VERSION: '0.8.1',
- COLLAPSE_MODINDEX: false,
- FILE_SUFFIX: '.html'
- };
- </script>
- <script type="text/javascript" src="_static/jquery.js"></script>
- <script type="text/javascript" src="_static/underscore.js"></script>
- <script type="text/javascript" src="_static/doctools.js"></script>
- <link rel="index" title="Index" href="genindex.html" />
- <link rel="search" title="Search" href="search.html" />
- <link rel="top" title="Mako 0.8.1 Documentation" href="index.html" />
- <link rel="next" title="Defs and Blocks" href="defs.html" />
- <link rel="prev" title="Usage" href="usage.html" />
- <link rel="stylesheet" href="_static/site.css"></link>
- </head>
- <body>
- <div id="wrap">
- <div class="rightbar">
- <div class="slogan">
- Hyperfast and lightweight templating for the Python platform.
- </div>
- </div>
- <a href="http://www.makotemplates.org/"><img src="_static/makoLogo.png" /></a>
- <hr/>
-
- <div id="docs-container">
- <div id="docs-header">
- <h1>Mako 0.8.1 Documentation</h1>
- <div id="docs-search">
- Search:
- <form class="search" action="search.html" method="get">
- <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
- </form>
- </div>
- <div id="docs-version-header">
- Release: <span class="version-num">0.8.1</span>
- </div>
- </div>
- <div id="docs-top-navigation">
- <div id="docs-top-page-control" class="docs-navigation-links">
- <ul>
- <li>Prev:
- <a href="usage.html" title="previous chapter">Usage</a>
- </li>
- <li>Next:
- <a href="defs.html" title="next chapter">Defs and Blocks</a>
- </li>
- <li>
- <a href="index.html">Table of Contents</a> |
- <a href="genindex.html">Index</a>
- | <a href="_sources/syntax.txt">view source
- </li>
- </ul>
- </div>
- <div id="docs-navigation-banner">
- <a href="index.html">Mako 0.8.1 Documentation</a>
- »
- Syntax
-
- <h2>
-
- Syntax
-
- </h2>
- </div>
- </div>
- <div id="docs-body-container">
- <div id="docs-sidebar">
- <h3><a href="index.html">Table of Contents</a></h3>
- <ul>
- <li><a class="reference internal" href="#">Syntax</a><ul>
- <li><a class="reference internal" href="#expression-substitution">Expression Substitution</a></li>
- <li><a class="reference internal" href="#expression-escaping">Expression Escaping</a></li>
- <li><a class="reference internal" href="#control-structures">Control Structures</a><ul>
- <li><a class="reference internal" href="#the-loop-context">The Loop Context</a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#comments">Comments</a></li>
- <li><a class="reference internal" href="#newline-filters">Newline Filters</a></li>
- <li><a class="reference internal" href="#python-blocks">Python Blocks</a></li>
- <li><a class="reference internal" href="#module-level-blocks">Module-level Blocks</a></li>
- <li><a class="reference internal" href="#tags">Tags</a><ul>
- <li><a class="reference internal" href="#page"><tt class="docutils literal"><span class="pre"><%page></span></tt></a></li>
- <li><a class="reference internal" href="#include"><tt class="docutils literal"><span class="pre"><%include></span></tt></a></li>
- <li><a class="reference internal" href="#def"><tt class="docutils literal"><span class="pre"><%def></span></tt></a></li>
- <li><a class="reference internal" href="#block"><tt class="docutils literal"><span class="pre"><%block></span></tt></a></li>
- <li><a class="reference internal" href="#namespace"><tt class="docutils literal"><span class="pre"><%namespace></span></tt></a></li>
- <li><a class="reference internal" href="#inherit"><tt class="docutils literal"><span class="pre"><%inherit></span></tt></a></li>
- <li><a class="reference internal" href="#nsname-defname"><tt class="docutils literal"><span class="pre"><%</span></tt>nsname<tt class="docutils literal"><span class="pre">:</span></tt>defname<tt class="docutils literal"><span class="pre">></span></tt></a></li>
- <li><a class="reference internal" href="#call"><tt class="docutils literal"><span class="pre"><%call></span></tt></a></li>
- <li><a class="reference internal" href="#doc"><tt class="docutils literal"><span class="pre"><%doc></span></tt></a></li>
- <li><a class="reference internal" href="#text"><tt class="docutils literal"><span class="pre"><%text></span></tt></a></li>
- </ul>
- </li>
- <li><a class="reference internal" href="#returning-early-from-a-template">Returning Early from a Template</a></li>
- </ul>
- </li>
- </ul>
- <h4>Previous Topic</h4>
- <p>
- <a href="usage.html" title="previous chapter">Usage</a>
- </p>
- <h4>Next Topic</h4>
- <p>
- <a href="defs.html" title="next chapter">Defs and Blocks</a>
- </p>
- <h4>Quick Search</h4>
- <p>
- <form class="search" action="search.html" method="get">
- <input type="text" name="q" size="18" /> <input type="submit" value="Search" />
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
- </form>
- </p>
- </div>
- <div id="docs-body" class="withsidebar" >
-
- <div class="section" id="syntax">
- <span id="syntax-toplevel"></span><h1>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h1>
- <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.</p>
- <div class="section" id="expression-substitution">
- <h2>Expression Substitution<a class="headerlink" href="#expression-substitution" title="Permalink to this headline">¶</a></h2>
- <p>The simplest expression is just a variable substitution. The
- syntax for this is the <tt class="docutils literal"><span class="pre">${}</span></tt> construct, which is inspired by
- Perl, Genshi, JSP EL, and others:</p>
- <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>
- </pre></div>
- </div>
- <p>Above, the string representation of <tt class="docutils literal"><span class="pre">x</span></tt> is applied to the
- template’s output stream. If you’re wondering where <tt class="docutils literal"><span class="pre">x</span></tt> comes
- from, it’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
- template’s rendering function. If <tt class="docutils literal"><span class="pre">x</span></tt> was not supplied to the
- template and was not otherwise assigned locally, it evaluates to
- a special value <tt class="docutils literal"><span class="pre">UNDEFINED</span></tt>. More on that later.</p>
- <p>The contents within the <tt class="docutils literal"><span class="pre">${}</span></tt> tag are evaluated by Python
- directly, so full expressions are OK:</p>
- <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>
- </pre></div>
- </div>
- <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.</p>
- </div>
- <div class="section" id="expression-escaping">
- <h2>Expression Escaping<a class="headerlink" href="#expression-escaping" title="Permalink to this headline">¶</a></h2>
- <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
- substitution using the <tt class="docutils literal"><span class="pre">|</span></tt> operator:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- </pre></div>
- </div>
- <p>The above expression applies URL escaping to the expression, and
- 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
- 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>
- represents XML escaping, and <tt class="docutils literal"><span class="pre">trim</span></tt> applies a trim function.</p>
- <p>Read more about built-in filtering functions, including how to
- make your own filter functions, in <a class="reference internal" href="filtering.html"><em>Filtering and Buffering</em></a>.</p>
- </div>
- <div class="section" id="control-structures">
- <h2>Control Structures<a class="headerlink" href="#control-structures" title="Permalink to this headline">¶</a></h2>
- <p>A control structure refers to all those things that control the
- flow of a program – 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
- <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,
- control structures are written using the <tt class="docutils literal"><span class="pre">%</span></tt> marker followed
- by a regular Python control expression, and are “closed” by
- using another <tt class="docutils literal"><span class="pre">%</span></tt> marker with the tag “<tt class="docutils literal"><span class="pre">end<name></span></tt>”, where
- “<tt class="docutils literal"><span class="pre"><name></span></tt>” is the keyword of the expression:</p>
- <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>
- <span class="x"> this is some output</span>
- <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
- </pre></div>
- </div>
- <p>The <tt class="docutils literal"><span class="pre">%</span></tt> can appear anywhere on the line as long as no text
- precedes it; indentation is not significant. The full range of
- Python “colon” expressions are allowed here, including
- <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
- Mako has a built-in tag for defs which is more full-featured.</p>
- <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">'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><span class="x"></span>
- <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><span class="x"></span>
- <span class="x"> its two or three</span>
- <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><span class="x"></span>
- <span class="x"> four/five</span>
- <span class="cp">%</span> <span class="k">else</span><span class="p">:</span><span class="x"></span>
- <span class="x"> one</span>
- <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
- <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
- </pre></div>
- </div>
- <p>The <tt class="docutils literal"><span class="pre">%</span></tt> sign can also be “escaped”, if you actually want to
- emit a percent sign as the first non whitespace character on a
- line, by escaping it as in <tt class="docutils literal"><span class="pre">%%</span></tt>:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="x">%% some text</span>
- <span class="x"> %% some more text</span>
- </pre></div>
- </div>
- <div class="section" id="the-loop-context">
- <h3>The Loop Context<a class="headerlink" href="#the-loop-context" title="Permalink to this headline">¶</a></h3>
- <p>The <strong>loop context</strong> provides additional information about a loop
- while inside of a <tt class="docutils literal"><span class="pre">%</span> <span class="pre">for</span></tt> structure:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="x"><ul></span>
- <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="x"></span>
- <span class="x"> <li>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"></li></span>
- <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
- <span class="x"></ul></span>
- </pre></div>
- </div>
- <p>See <a class="reference internal" href="runtime.html#loop-context"><em>The Loop Context</em></a> for more information on this feature.</p>
- <p class="versionadded">
- <span class="versionmodified">New in version 0.7.</span></p>
- </div>
- </div>
- <div class="section" id="comments">
- <h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2>
- <p>Comments come in two varieties. The single line comment uses
- <tt class="docutils literal"><span class="pre">##</span></tt> as the first non-space characters on a line:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp">## this is a comment.</span><span class="x"></span>
- <span class="x">...text ...</span>
- </pre></div>
- </div>
- <p>A multiline version exists using <tt class="docutils literal"><span class="pre"><%doc></span> <span class="pre">...text...</span> <span class="pre"></%doc></span></tt>:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%doc></span>
- <span class="cp"> these are comments</span>
- <span class="cp"> more comments</span>
- <span class="cp"></%doc></span><span class="x"></span>
- </pre></div>
- </div>
- </div>
- <div class="section" id="newline-filters">
- <h2>Newline Filters<a class="headerlink" href="#newline-filters" title="Permalink to this headline">¶</a></h2>
- <p>The backslash (“<tt class="docutils literal"><span class="pre">\</span></tt>”) character, placed at the end of any
- line, will consume the newline character before continuing to
- the next line:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="x">here is a line that goes onto </span><span class="o">\</span>
- <span class="x">another line.</span>
- </pre></div>
- </div>
- <p>The above text evaluates to:</p>
- <div class="highlight-text"><div class="highlight"><pre>here is a line that goes onto another line.
- </pre></div>
- </div>
- </div>
- <div class="section" id="python-blocks">
- <h2>Python Blocks<a class="headerlink" href="#python-blocks" title="Permalink to this headline">¶</a></h2>
- <p>Any arbitrary block of python can be dropped in using the <tt class="docutils literal"><span class="pre"><%</span>
- <span class="pre">%></span></tt> tags:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="x">this is a template</span>
- <span class="cp"><%</span>
- <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>
- <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>
- <span class="cp">%></span>
- <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>
- <span class="x"> element: </span><span class="cp">${</span><span class="n">elem</span><span class="cp">}</span>
- <span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
- </pre></div>
- </div>
- <p>Within <tt class="docutils literal"><span class="pre"><%</span> <span class="pre">%></span></tt>, 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.</p>
- </div>
- <div class="section" id="module-level-blocks">
- <h2>Module-level Blocks<a class="headerlink" href="#module-level-blocks" title="Permalink to this headline">¶</a></h2>
- <p>A variant on <tt class="docutils literal"><span class="pre"><%</span> <span class="pre">%></span></tt> is the module-level code block, denoted
- by <tt class="docutils literal"><span class="pre"><%!</span> <span class="pre">%></span></tt>. 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 <tt class="docutils literal"><span class="pre"><%!</span> <span class="pre">%></span></tt>
- tags to declare your template’s imports, as well as any
- pure-Python functions you might want to declare:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%!</span>
- <span class="kn">import</span> <span class="nn">mylib</span>
- <span class="kn">import</span> <span class="nn">re</span>
- <span class="k">def</span> <span class="nf">filter</span><span class="p">(</span><span class="n">text</span><span class="p">):</span>
- <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>
- <span class="cp">%></span><span class="x"></span>
- </pre></div>
- </div>
- <p>Any number of <tt class="docutils literal"><span class="pre"><%!</span> <span class="pre">%></span></tt> blocks can be declared anywhere in a
- template; they will be rendered in the resulting module
- in a single contiguous block above all render callables,
- in the order in which they appear in the source template.</p>
- </div>
- <div class="section" id="tags">
- <h2>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h2>
- <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 <tt class="docutils literal"><span class="pre">%</span></tt>
- character. The tag is closed either by a contained slash
- character, or an explicit closing tag:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- <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><span class="x"></span>
- <span class="x"> this is a def</span>
- <span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
- </pre></div>
- </div>
- <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 <tt class="docutils literal"><span class="pre">${}</span></tt>) inside the attribute text:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- </pre></div>
- </div>
- <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 it’s not
- valid.</p>
- <p>Heres a quick summary of all the tags:</p>
- <div class="section" id="page">
- <h3><tt class="docutils literal"><span class="pre"><%page></span></tt><a class="headerlink" href="#page" title="Permalink to this headline">¶</a></h3>
- <p>This tag defines general characteristics of the template,
- including caching arguments, and optional lists of arguments
- which the template expects when invoked.</p>
- <div class="highlight-mako"><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><span class="x"></span>
- </pre></div>
- </div>
- <p>Or a page tag that defines caching characteristics:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- </pre></div>
- </div>
- <p>Currently, only one <tt class="docutils literal"><span class="pre"><%page></span></tt> 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 <tt class="docutils literal"><span class="pre"><%page></span></tt> tag
- defined in your template, else you may not get the results you
- want. The details of what <tt class="docutils literal"><span class="pre"><%page></span></tt> is used for are described
- 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>
- </div>
- <div class="section" id="include">
- <h3><tt class="docutils literal"><span class="pre"><%include></span></tt><a class="headerlink" href="#include" title="Permalink to this headline">¶</a></h3>
- <p>A tag that is familiar from other template languages, <tt class="docutils literal"><span class="pre">%include</span></tt>
- is a regular joe that just accepts a file argument and calls in
- the rendered result of that file:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- <span class="x"> hello world</span>
- <span class="cp"><%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">"footer.html"</span><span class="cp">/></span><span class="x"></span>
- </pre></div>
- </div>
- <p>Include also accepts arguments which are available as <tt class="docutils literal"><span class="pre"><%page></span></tt> arguments in the receiving template:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%</span><span class="nb">include</span> <span class="na">file=</span><span class="s">"toolbar.html"</span> <span class="na">args=</span><span class="s">"current_section='members', username='ed'"</span><span class="cp">/></span><span class="x"></span>
- </pre></div>
- </div>
- </div>
- <div class="section" id="def">
- <h3><tt class="docutils literal"><span class="pre"><%def></span></tt><a class="headerlink" href="#def" title="Permalink to this headline">¶</a></h3>
- <p>The <tt class="docutils literal"><span class="pre">%def</span></tt> 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:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- <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>
- <span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
- <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>
- </pre></div>
- </div>
- <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
- the Mako compiler provides many extra services with <tt class="docutils literal"><span class="pre">%def</span></tt> that
- you wouldn’t normally have, such as the ability to export defs
- as template “methods”, automatic propagation of the current
- <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
- 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 <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>
- </div>
- <div class="section" id="block">
- <h3><tt class="docutils literal"><span class="pre"><%block></span></tt><a class="headerlink" href="#block" title="Permalink to this headline">¶</a></h3>
- <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>,
- except executes itself immediately in its base-most scope,
- and can also be anonymous (i.e. with no name):</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%</span><span class="nb">block</span> <span class="na">filter=</span><span class="s">"h"</span><span class="cp">></span><span class="x"></span>
- <span class="x"> some <html> stuff.</span>
- <span class="cp"></%</span><span class="nb">block</span><span class="cp">></span><span class="x"></span>
- </pre></div>
- </div>
- <p>Inspired by Jinja2 blocks, named blocks offer a syntactically pleasing way
- to do inheritance:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="x"><html></span>
- <span class="x"> <body></span>
- <span class="x"> </span><span class="cp"><%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">"header"</span><span class="cp">></span><span class="x"></span>
- <span class="x"> <h2></span><span class="cp"><%</span><span class="nb">block</span> <span class="na">name=</span><span class="s">"title"</span><span class="cp">/></span><span class="x"></h2></span>
- <span class="x"> </span><span class="cp"></%</span><span class="nb">block</span><span class="cp">></span><span class="x"></span>
- <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>
- <span class="x"> </body></span>
- <span class="x"></html></span>
- </pre></div>
- </div>
- <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>
- <p class="versionadded">
- <span class="versionmodified">New in version 0.4.1.</span></p>
- </div>
- <div class="section" id="namespace">
- <h3><tt class="docutils literal"><span class="pre"><%namespace></span></tt><a class="headerlink" href="#namespace" title="Permalink to this headline">¶</a></h3>
- <p><tt class="docutils literal"><span class="pre">%namespace</span></tt> is Mako’s equivalent of Python’s <tt class="docutils literal"><span class="pre">import</span></tt>
- 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.</p>
- <div class="highlight-mako"><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><span class="x"></span>
- </pre></div>
- </div>
- <p>The underlying object generated by <tt class="docutils literal"><span class="pre">%namespace</span></tt>, an instance of
- <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
- 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 class="reference internal" href="namespaces.html"><em>Namespaces</em></a>.</p>
- </div>
- <div class="section" id="inherit">
- <h3><tt class="docutils literal"><span class="pre"><%inherit></span></tt><a class="headerlink" href="#inherit" title="Permalink to this headline">¶</a></h3>
- <p>Inherit allows templates to arrange themselves in <strong>inheritance
- chains</strong>. This is a concept familiar in many other template
- languages.</p>
- <div class="highlight-mako"><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><span class="x"></span>
- </pre></div>
- </div>
- <p>When using the <tt class="docutils literal"><span class="pre">%inherit</span></tt> 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 flexibility in this area, including dynamic
- inheritance, content wrapping, and polymorphic method calls.
- Check it out in <a class="reference internal" href="inheritance.html"><em>Inheritance</em></a>.</p>
- </div>
- <div class="section" id="nsname-defname">
- <h3><tt class="docutils literal"><span class="pre"><%</span></tt>nsname<tt class="docutils literal"><span class="pre">:</span></tt>defname<tt class="docutils literal"><span class="pre">></span></tt><a class="headerlink" href="#nsname-defname" title="Permalink to this headline">¶</a></h3>
- <p>Any user-defined “tag” can be created against
- a namespace by using a tag with a name of the form
- <tt class="docutils literal"><span class="pre"><%<namespacename>:<defname>></span></tt>. The closed and open formats of such a
- tag are equivalent to an inline expression and the <tt class="docutils literal"><span class="pre"><%call></span></tt>
- tag, respectively.</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%</span><span class="nb">mynamespace:somedef</span> <span class="na">param=</span><span class="s">"some value"</span><span class="cp">></span><span class="x"></span>
- <span class="x"> this is the body</span>
- <span class="cp"></%</span><span class="nb">mynamespace:somedef</span><span class="cp">></span><span class="x"></span>
- </pre></div>
- </div>
- <p>To create custom tags which accept a body, see
- <a class="reference internal" href="defs.html#defs-with-content"><em>Calling a Def with Embedded Content and/or Other Defs</em></a>.</p>
- <p class="versionadded">
- <span class="versionmodified">New in version 0.2.3.</span></p>
- </div>
- <div class="section" id="call">
- <h3><tt class="docutils literal"><span class="pre"><%call></span></tt><a class="headerlink" href="#call" title="Permalink to this headline">¶</a></h3>
- <p>The call tag is the “classic” form of a user-defined tag, and is
- roughly equivalent to the <tt class="docutils literal"><span class="pre"><%namespacename:defname></span></tt> syntax
- 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>
- </div>
- <div class="section" id="doc">
- <h3><tt class="docutils literal"><span class="pre"><%doc></span></tt><a class="headerlink" href="#doc" title="Permalink to this headline">¶</a></h3>
- <p>The <tt class="docutils literal"><span class="pre">%doc</span></tt> tag handles multiline comments:</p>
- <div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%doc></span>
- <span class="cp"> these are comments</span>
- <span class="cp"> more comments</span>
- <span class="cp"></%doc></span><span class="x"></span>
- </pre></div>
- </div>
- <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>
- </div>
- <div class="section" id="text">
- <h3><tt class="docutils literal"><span class="pre"><%text></span></tt><a class="headerlink" href="#text" title="Permalink to this headline">¶</a></h3>
- <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:</p>
- <div class="highlight-mako"><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><span class="x"></span>
- <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>
- <span class="x"> </span><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><span class="x"></span>
- <span class="cp"></%</span><span class="nb">text</span><span class="cp">></span><span class="x"></span>
- </pre></div>
- </div>
- </div>
- </div>
- <div class="section" id="returning-early-from-a-template">
- <h2>Returning Early from a Template<a class="headerlink" href="#returning-early-from-a-template" title="Permalink to this headline">¶</a></h2>
- <p>Sometimes you want to stop processing a template or <tt class="docutils literal"><span class="pre"><%def></span></tt>
- method in the middle and just use the text you’ve accumulated so
- far. You can use a <tt class="docutils literal"><span class="pre">return</span></tt> statement inside a Python
- block to do that.</p>
- <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>
- <span class="x"> No records found.</span>
- <span class="x"> </span><span class="cp"><%</span> <span class="k">return</span> <span class="cp">%></span>
- <span class="cp">%</span><span class="k"> endif</span><span class="x"></span>
- </pre></div>
- </div>
- <p>Or perhaps:</p>
- <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="k">return</span>
- <span class="cp">%></span><span class="x"></span>
- </pre></div>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div id="docs-bottom-navigation" class="docs-navigation-links">
- Previous:
- <a href="usage.html" title="previous chapter">Usage</a>
- Next:
- <a href="defs.html" title="next chapter">Defs and Blocks</a>
- <div id="docs-copyright">
- © Copyright the Mako authors and contributors.
- Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3
- with Mako templates.
- </div>
- </div>
- </div>
- <div class="clearfix">
- <hr/>
- <div class="copyright">Website content copyright © by Michael Bayer.
- All rights reserved. Mako and its documentation are licensed
- under the MIT license. mike(&)zzzcomputing.com</div>
- </div>
- </div>
- </body>
- </html>
|