<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Defs
— Mako 0.3.6 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.3.6',
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>
<script type="text/javascript" src="_static/init.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Mako 0.3.6 Documentation" href="index.html" />
<link rel="next" title="The Mako Runtime Environment" href="runtime.html" />
<link rel="prev" title="Syntax" href="syntax.html" />
</head>
<body>
<h1>Mako 0.3.6 Documentation</h1>
<div id="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 class="versionheader">
Version: <span class="versionnum">0.3.6</span> Last Updated: 11/13/2010 16:04:30
</div>
<div class="clearboth"></div>
<div class="topnav">
<div id="pagecontrol">
<a href="genindex.html">Index</a>
<div class="sourcelink">(<a href="_sources/defs.txt">view source)</div>
</div>
<div class="navbanner">
<a class="totoc" href="index.html">Table of Contents</a>
»
Defs
<div class="prevnext">
Previous:
<a href="syntax.html" title="previous chapter">Syntax</a>
Next:
<a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>
</div>
<h2>
Defs
</h2>
</div>
<ul>
<li><a class="reference internal" href="#">Defs</a><ul>
<li><a class="reference internal" href="#calling-defs-from-other-files">Calling defs from Other Files</a></li>
<li><a class="reference internal" href="#calling-defs-programmatically">Calling defs programmatically</a></li>
<li><a class="reference internal" href="#defs-within-defs">Defs within Defs</a></li>
<li><a class="reference internal" href="#calling-a-def-with-embedded-content-and-or-other-defs">Calling a def with embedded content and/or other defs</a></li>
</ul>
</li>
</ul>
<div class="clearboth"></div>
</div>
<div class="document">
<div class="body">
<div class="section" id="defs">
<span id="defs-toplevel"></span><h1>Defs<a class="headerlink" href="#defs" title="Permalink to this headline">¶</a></h1>
<p><tt class="docutils literal"><span class="pre"><%def></span></tt> is the single tag used to demarcate any block of text
and/or code. It exists within generated Python as a callable
function:</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">"hello()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> hello world</span>
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>They are normally called as expressions:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="x">the def: </span><span class="cp">${</span><span class="n">hello</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>If the <tt class="docutils literal"><span class="pre"><%def></span></tt> is not nested inside of another <tt class="docutils literal"><span class="pre"><%def></span></tt>,
its known as a <strong>top level def</strong> and can be accessed anywhere in
the template, including above where it was defined.</p>
<p>All defs, top level or not, have access to the current
contextual namespace in exactly the same way their containing
template does. Suppose the template below is executed with the
variables <tt class="docutils literal"><span class="pre">username</span></tt> and <tt class="docutils literal"><span class="pre">accountdata</span></tt> inside the context:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="x">Hello there </span><span class="cp">${</span><span class="n">username</span><span class="cp">}</span><span class="x">, how are ya. Lets see what your account says:</span>
<span class="cp">${</span><span class="n">account</span><span class="p">()</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">"account()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> Account for </span><span class="cp">${</span><span class="n">username</span><span class="cp">}</span><span class="x">:<br/></span>
<span class="cp">%</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">accountdata</span><span class="p">:</span><span class="x"></span>
<span class="x"> Value: </span><span class="cp">${</span><span class="n">row</span><span class="cp">}</span><span class="x"><br/></span>
<span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">username</span></tt> and <tt class="docutils literal"><span class="pre">accountdata</span></tt> variables are present
within the main template body as well as the body of the
<tt class="docutils literal"><span class="pre">account()</span></tt> def.</p>
<p>Since defs are just Python functions, you can define and pass
arguments to them as well:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="n">account</span><span class="p">(</span><span class="n">accountname</span><span class="o">=</span><span class="s">'john'</span><span class="p">)</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">"account(accountname, type='regular')"</span><span class="cp">></span><span class="x"></span>
<span class="x"> account name: </span><span class="cp">${</span><span class="n">accountname</span><span class="cp">}</span><span class="x">, type </span><span class="cp">${</span><span class="nb">type</span><span class="cp">}</span><span class="x"></span>
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>When you declare an argument signature for your def, they are
required to follow normal Python conventions (i.e., all
arguments are required except keyword arguments with a default
value). This is in contrast to using context-level variables,
which evaluate to <tt class="docutils literal"><span class="pre">UNDEFINED</span></tt> if you reference a name that
does not exist.</p>
<div class="section" id="calling-defs-from-other-files">
<h2>Calling defs from Other Files<a class="headerlink" href="#calling-defs-from-other-files" title="Permalink to this headline">¶</a></h2>
<p>Top level <tt class="docutils literal"><span class="pre"><%defs></span></tt> are <strong>exported</strong> by your template’s
module, and can be called from the outside; including from other
templates, as well as normal Python code. Calling a <tt class="docutils literal"><span class="pre"><%def></span></tt>
from another template is something like using an <tt class="docutils literal"><span class="pre"><%include></span></tt>
- except you are calling a specific function within the
template, not the whole template.</p>
<p>The remote <tt class="docutils literal"><span class="pre"><%def></span></tt> call is also a little bit like calling
functions from other modules in Python. There is an “import”
step to pull the names from another template into your own
template; then the function or functions are available.</p>
<p>To import another template, use the <tt class="docutils literal"><span class="pre"><%namespace></span></tt> tag:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%</span><span class="nb">namespace</span> <span class="na">name=</span><span class="s">"mystuff"</span> <span class="na">file=</span><span class="s">"mystuff.html"</span><span class="cp">/></span><span class="x"></span>
</pre></div>
</div>
<p>The above tag adds a local variable “mystuff” to the current
scope.</p>
<p>Then, just call the defs off of <tt class="docutils literal"><span class="pre">mystuff</span></tt>:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp">${</span><span class="n">mystuff</span><span class="o">.</span><span class="n">somedef</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span><span class="n">y</span><span class="o">=</span><span class="mi">7</span><span class="p">)</span><span class="cp">}</span><span class="x"></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre"><%namespace></span></tt> tag also supports some of the other
semantics of Python’s <tt class="docutils literal"><span class="pre">import</span></tt> statement, including pulling
names into the local variable space, or using <tt class="docutils literal"><span class="pre">*</span></tt> to represent
all names, using the <tt class="docutils literal"><span class="pre">import</span></tt> attribute:</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">"mystuff.html"</span> <span class="na">import=</span><span class="s">"foo, bar"</span><span class="cp">/></span><span class="x"></span>
</pre></div>
</div>
<p>This is just a quick intro to the concept of a <strong>namespace</strong>,
which is a central Mako concept that has its own chapter in
these docs. For more detail and examples, see
<a class="reference internal" href="namespaces.html"><em>Namespaces</em></a>.</p>
</div>
<div class="section" id="calling-defs-programmatically">
<h2>Calling defs programmatically<a class="headerlink" href="#calling-defs-programmatically" title="Permalink to this headline">¶</a></h2>
<p>You can call def’s programmatically from any <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> object
using the <a class="reference internal" href="usage.html#mako.template.Template.get_def" title="mako.template.Template.get_def"><tt class="xref py py-meth docutils literal"><span class="pre">get_def()</span></tt></a> method, which returns a <a class="reference internal" href="usage.html#mako.template.DefTemplate" title="mako.template.DefTemplate"><tt class="xref py py-class docutils literal"><span class="pre">DefTemplate</span></tt></a>
object. This is a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> subclass which the parent
<a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><tt class="xref py py-class docutils literal"><span class="pre">Template</span></tt></a> creates, and is usable like any other template:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mako.template</span> <span class="kn">import</span> <span class="n">Template</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s">"""</span>
<span class="s"> <</span><span class="si">%d</span><span class="s">ef name="hi(name)"></span>
<span class="s"> hi ${name}!</span>
<span class="s"> </</span><span class="si">%d</span><span class="s">ef></span>
<span class="s"> <</span><span class="si">%d</span><span class="s">ef name="bye(name)"></span>
<span class="s"> bye ${name}!</span>
<span class="s"> </</span><span class="si">%d</span><span class="s">ef></span>
<span class="s">"""</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">get_def</span><span class="p">(</span><span class="s">"hi"</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"ed"</span><span class="p">)</span>
<span class="k">print</span> <span class="n">template</span><span class="o">.</span><span class="n">get_def</span><span class="p">(</span><span class="s">"bye"</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"ed"</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="defs-within-defs">
<h2>Defs within Defs<a class="headerlink" href="#defs-within-defs" title="Permalink to this headline">¶</a></h2>
<p>The def model follows regular Python rules for closures.
Declaring <tt class="docutils literal"><span class="pre"><%def></span></tt> inside another <tt class="docutils literal"><span class="pre"><%def></span></tt> declares it
within the parent’s <strong>enclosing scope</strong>:</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">"mydef()"</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">"subdef()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> a sub def</span>
<span class="x"> </span><span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
<span class="x"> im the def, and the subcomponent is </span><span class="cp">${</span><span class="n">subdef</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>Just like Python, names that exist outside the inner <tt class="docutils literal"><span class="pre"><%def></span></tt>
exist inside it as well:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%</span>
<span class="n">x</span> <span class="o">=</span> <span class="mi">12</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">"outer()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> </span><span class="cp"><%</span>
<span class="n">y</span> <span class="o">=</span> <span class="mi">15</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">"inner()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> inner, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x">, y is </span><span class="cp">${</span><span class="n">y</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </span><span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
<span class="x"> outer, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x">, y is </span><span class="cp">${</span><span class="n">y</span><span class="cp">}</span><span class="x"></span>
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>Assigning to a name inside of a def declares that name as local
to the scope of that def (again, like Python itself). This means
the following code will raise an error:</p>
<div class="highlight-mako"><div class="highlight"><pre><span class="cp"><%</span>
<span class="n">x</span> <span class="o">=</span> <span class="mi">10</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">"somedef()"</span><span class="cp">></span>
<span class="cp">## error !</span><span class="x"></span>
<span class="x"> somedef, x is </span><span class="cp">${</span><span class="n">x</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </span><span class="cp"><%</span>
<span class="n">x</span> <span class="o">=</span> <span class="mi">27</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>
</pre></div>
</div>
<p>...because the assignment to <tt class="docutils literal"><span class="pre">x</span></tt> declares x as local to the
scope of <tt class="docutils literal"><span class="pre">somedef</span></tt>, rendering the “outer” version unreachable
in the expression that tries to render it.</p>
</div>
<div class="section" id="calling-a-def-with-embedded-content-and-or-other-defs">
<span id="defs-with-content"></span><h2>Calling a def with embedded content and/or other defs<a class="headerlink" href="#calling-a-def-with-embedded-content-and-or-other-defs" title="Permalink to this headline">¶</a></h2>
<p>A flip-side to def within def is a def call with content. This
is where you call a def, and at the same time declare a block of
content (or multiple blocks) that can be used by the def being
called. The main point of such a call is to create custom,
nestable tags, just like any other template language’s
custom-tag creation system - where the external tag controls the
execution of the nested tags and can communicate state to them.
Only with Mako, you don’t have to use any external Python
modules, you can define arbitrarily nestable tags right in your
templates.</p>
<p>To achieve this, the target def is invoked using the form
<tt class="docutils literal"><span class="pre"><%namepacename:defname></span></tt> instead of the normal <tt class="docutils literal"><span class="pre">${}</span></tt>
syntax. This syntax, introduced in Mako 0.2.3, is functionally
equivalent another tag known as <tt class="docutils literal"><span class="pre">call</span></tt>, which takes the form
<tt class="docutils literal"><span class="pre"><%call</span> <span class="pre">expr='namespacename.defname(args)'></span></tt>. While <tt class="docutils literal"><span class="pre">%call</span></tt>
is available in all versions of Mako, the newer style is
probably more familiar looking. The <tt class="docutils literal"><span class="pre">namespace</span></tt> portion of the
call is the name of the <strong>namespace</strong> in which the def is
defined - in the most simple cases, this can be <tt class="docutils literal"><span class="pre">local</span></tt> or
<tt class="docutils literal"><span class="pre">self</span></tt> to reference the current template’s namespace (the
difference between <tt class="docutils literal"><span class="pre">local</span></tt> and <tt class="docutils literal"><span class="pre">self</span></tt> is one of inheritance
- see <a class="reference internal" href="namespaces.html#namespaces-builtin"><em>Built-in Namespaces</em></a> for details).</p>
<p>When the target def is invoked, a variable <tt class="docutils literal"><span class="pre">caller</span></tt> is placed
in its context which contains another namespace containing the
body and other defs defined by the caller. The body itself is
referenced by the method <tt class="docutils literal"><span class="pre">body()</span></tt>. Below, we build a <tt class="docutils literal"><span class="pre">%def</span></tt>
that operates upon <tt class="docutils literal"><span class="pre">caller.body()</span></tt> to invoke the body of the
custom tag:</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">"buildtable()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> <table></span>
<span class="x"> <tr><td></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </td></tr></span>
<span class="x"> </table></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">self:buildtable</span><span class="cp">></span><span class="x"></span>
<span class="x"> I am the table body.</span>
<span class="cp"></%</span><span class="nb">self:buildtable</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>This produces the output (whitespace formatted):</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><table></span>
<span class="nt"><tr><td></span>
I am the table body.
<span class="nt"></td></tr></span>
<span class="nt"></table></span>
</pre></div>
</div>
<p>Using the older <tt class="docutils literal"><span class="pre">%call</span></tt> syntax looks like:</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">"buildtable()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> <table></span>
<span class="x"> <tr><td></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </td></tr></span>
<span class="x"> </table></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">call</span> <span class="na">expr=</span><span class="s">"buildtable()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> I am the table body.</span>
<span class="cp"></%</span><span class="nb">call</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">body()</span></tt> can be executed multiple times or not at all.
This means you can use def-call-with-content to build iterators,
conditionals, etc:</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">"lister(count)"</span><span class="cp">></span>
<span class="cp">%</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">count</span><span class="p">):</span><span class="x"></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span>
<span class="cp">%</span><span class="k"> endfor</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="nb">self:lister</span> <span class="na">count=</span><span class="s">"${3}"</span><span class="cp">></span><span class="x"></span>
<span class="x"> hi</span>
<span class="cp"></%</span><span class="nb">self:lister</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>Produces:</p>
<div class="highlight-html"><div class="highlight"><pre>hi
hi
hi
</pre></div>
</div>
<p>Notice above we pass <tt class="docutils literal"><span class="pre">3</span></tt> as a Python expression, so that it
remains as an integer.</p>
<p>A custom “conditional” tag:</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">"conditional(expression)"</span><span class="cp">></span>
<span class="cp">%</span> <span class="k">if</span> <span class="n">expression</span><span class="p">:</span><span class="x"></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span>
<span class="cp">%</span><span class="k"> endif</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="nb">self:conditional</span> <span class="na">expression=</span><span class="s">"${4==4}"</span><span class="cp">></span><span class="x"></span>
<span class="x"> im the result</span>
<span class="cp"></%</span><span class="nb">self:conditional</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>Produces:</p>
<div class="highlight-html"><div class="highlight"><pre>im the result
</pre></div>
</div>
<p>But that’s not all. The <tt class="docutils literal"><span class="pre">body()</span></tt> function also can handle
arguments, which will augment the local namespace of the body
callable. The caller must define the arguments which it expects
to receive from its target def using the <tt class="docutils literal"><span class="pre">args</span></tt> attribute,
which is a comma-separated list of argument names. Below, our
<tt class="docutils literal"><span class="pre"><%def></span></tt> calls the <tt class="docutils literal"><span class="pre">body()</span></tt> of its caller, passing in an
element of data from its argument:</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">"layoutdata(somedata)"</span><span class="cp">></span><span class="x"></span>
<span class="x"> <table></span>
<span class="cp">%</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">somedata</span><span class="p">:</span><span class="x"></span>
<span class="x"> <tr></span>
<span class="cp">%</span> <span class="k">for</span> <span class="n">col</span> <span class="ow">in</span> <span class="n">item</span><span class="p">:</span><span class="x"></span>
<span class="x"> <td></span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">(</span><span class="n">col</span><span class="o">=</span><span class="n">col</span><span class="p">)</span><span class="cp">}</span><span class="x"></td></span>
<span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
<span class="x"> </tr></span>
<span class="cp">%</span><span class="k"> endfor</span><span class="x"></span>
<span class="x"> </table></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">self:layoutdata</span> <span class="na">somedata=</span><span class="s">"${[[1,2,3],[4,5,6],[7,8,9]]}"</span> <span class="na">args=</span><span class="s">"col"</span><span class="cp">></span><span class="x">\</span>
<span class="x">Body data: </span><span class="cp">${</span><span class="n">col</span><span class="cp">}</span><span class="x">\</span>
<span class="cp"></%</span><span class="nb">self:layoutdata</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>Produces:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><table></span>
<span class="nt"><tr></span>
<span class="nt"><td></span>Body data: 1<span class="nt"></td></span>
<span class="nt"><td></span>Body data: 2<span class="nt"></td></span>
<span class="nt"><td></span>Body data: 3<span class="nt"></td></span>
<span class="nt"></tr></span>
<span class="nt"><tr></span>
<span class="nt"><td></span>Body data: 4<span class="nt"></td></span>
<span class="nt"><td></span>Body data: 5<span class="nt"></td></span>
<span class="nt"><td></span>Body data: 6<span class="nt"></td></span>
<span class="nt"></tr></span>
<span class="nt"><tr></span>
<span class="nt"><td></span>Body data: 7<span class="nt"></td></span>
<span class="nt"><td></span>Body data: 8<span class="nt"></td></span>
<span class="nt"><td></span>Body data: 9<span class="nt"></td></span>
<span class="nt"></tr></span>
<span class="nt"></table></span>
</pre></div>
</div>
<p>You don’t have to stick to calling just the <tt class="docutils literal"><span class="pre">body()</span></tt> function.
The caller can define any number of callables, allowing the
<tt class="docutils literal"><span class="pre"><%call></span></tt> tag to produce whole layouts:</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">"layout()"</span><span class="cp">></span>
<span class="cp">## a layout def</span><span class="x"></span>
<span class="x"> <div class="mainlayout"></span>
<span class="x"> <div class="header"></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">header</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </div></span>
<span class="x"> <div class="sidebar"></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">sidebar</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </div></span>
<span class="x"> <div class="content"></span>
<span class="x"> </span><span class="cp">${</span><span class="n">caller</span><span class="o">.</span><span class="n">body</span><span class="p">()</span><span class="cp">}</span><span class="x"></span>
<span class="x"> </div></span>
<span class="x"> </div></span>
<span class="cp"></%</span><span class="nb">def</span><span class="cp">></span>
<span class="cp">## calls the layout def</span><span class="x"></span>
<span class="cp"><%</span><span class="nb">self:layout</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">"header()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> I am the header</span>
<span class="x"> </span><span class="cp"></%</span><span class="nb">def</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">"sidebar()"</span><span class="cp">></span><span class="x"></span>
<span class="x"> <ul></span>
<span class="x"> <li>sidebar 1</li></span>
<span class="x"> <li>sidebar 2</li></span>
<span class="x"> </ul></span>
<span class="x"> </span><span class="cp"></%</span><span class="nb">def</span><span class="cp">></span><span class="x"></span>
<span class="x"> this is the body</span>
<span class="cp"></%</span><span class="nb">self:layout</span><span class="cp">></span><span class="x"></span>
</pre></div>
</div>
<p>The above layout would produce:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">class=</span><span class="s">"mainlayout"</span><span class="nt">></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"header"</span><span class="nt">></span>
I am the header
<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"sidebar"</span><span class="nt">></span>
<span class="nt"><ul></span>
<span class="nt"><li></span>sidebar 1<span class="nt"></li></span>
<span class="nt"><li></span>sidebar 2<span class="nt"></li></span>
<span class="nt"></ul></span>
<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">class=</span><span class="s">"content"</span><span class="nt">></span>
this is the body
<span class="nt"></div></span>
<span class="nt"></div></span>
</pre></div>
</div>
<p>The number of things you can do with <tt class="docutils literal"><span class="pre"><%call></span></tt> and/or the
<tt class="docutils literal"><span class="pre"><%namespacename:defname></span></tt> calling syntax is enormous. You can
create form widget libraries, such as an enclosing <tt class="docutils literal"><span class="pre"><FORM></span></tt>
tag and nested HTML input elements, or portable wrapping schemes
using <tt class="docutils literal"><span class="pre"><div></span></tt> or other elements. You can create tags that
interpret rows of data, such as from a database, providing the
individual columns of each row to a <tt class="docutils literal"><span class="pre">body()</span></tt> callable which
lays out the row any way it wants. Basically anything you’d do
with a “custom tag” or tag library in some other system, Mako
provides via <tt class="docutils literal"><span class="pre"><%def></span></tt> tags and plain Python callables which are
invoked via <tt class="docutils literal"><span class="pre"><%namespacename:defname></span></tt> or <tt class="docutils literal"><span class="pre"><%call></span></tt>.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav">
<div class="prevnext">
Previous:
<a href="syntax.html" title="previous chapter">Syntax</a>
Next:
<a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>
</div>
<div class="doc_copyright">
© Copyright the Mako authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
174107171d05f96998bd4cf15e0088c4
>
files
>
105
