^^&&^^

Edit File: defs.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
 <title>
 
 
 Defs and Blocks
 &mdash;
 Mako 1.1.0 Documentation

</title>

<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 <link rel="stylesheet" href="_static/changelog.css" type="text/css" />
 <link rel="stylesheet" href="_static/sphinx_paramlinks.css" type="text/css" />
 <link rel="stylesheet" href="_static/docs.css" type="text/css" />

</head>
 <body>

<div id="docs-header">
 <h1>Mako 1.1.0 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: 1.1.0

</div>

<div id="docs-top-navigation">
 <div id="docs-top-page-control" class="docs-navigation-links">
 <ul>
 <li>Prev:
 <a href="syntax.html" title="previous chapter">Syntax</a>
 </li>
 <li>Next:
 <a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>
 </li>

<li>
 <a href="index.html">Table of Contents</a> |
 <a href="genindex.html">Index</a>
 </li>
 </ul>
 </div>

<div id="docs-navigation-banner">
 <a href="index.html">Mako 1.1.0 Documentation</a>
 » 
 Defs and Blocks

<h2>
 
 Defs and Blocks
 
 </h2>
 </div>

</div>

<h3><a href="index.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">Defs and Blocks</a><ul>
<li><a class="reference internal" href="#using-defs">Using 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>
<li><a class="reference internal" href="#using-blocks">Using Blocks</a><ul>
<li><a class="reference internal" href="#using-named-blocks">Using Named Blocks</a></li>
<li><a class="reference internal" href="#using-page-arguments-in-named-blocks">Using Page Arguments in Named Blocks</a></li>
</ul>
</li>
</ul>
</li>
</ul>

<h4>Previous Topic</h4>
 
 <a href="syntax.html" title="previous chapter">Syntax</a>
 
 <h4>Next Topic</h4>
 
 <a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>

<h4>Quick Search</h4>
 
 <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-body" class="withsidebar" >
 
<div class="section" id="defs-and-blocks">
<h1>Defs and Blocks<a class="headerlink" href="#defs-and-blocks" title="Permalink to this headline">¶</a></h1>
<code class="docutils literal notranslate">&lt;%def&gt;</code> and <code class="docutils literal notranslate">&lt;%block&gt;</code> are two tags that both demarcate any block of text
and/or code. They both exist within generated Python as a callable function,
i.e., a Python <code class="docutils literal notranslate">def</code>. They differ in their scope and calling semantics.
Whereas <code class="docutils literal notranslate">&lt;%def&gt;</code> provides a construct that is very much like a named Python
<code class="docutils literal notranslate">def</code>, the <code class="docutils literal notranslate">&lt;%block&gt;</code> is more layout oriented.
<div class="section" id="using-defs">
<h2>Using Defs<a class="headerlink" href="#using-defs" title="Permalink to this headline">¶</a></h2>
The <code class="docutils literal notranslate">&lt;%def&gt;</code> tag requires a <code class="docutils literal notranslate">name</code> attribute, where the <code class="docutils literal notranslate">name</code> references
a Python function signature:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;hello()&quot;&gt;
 hello world
&lt;/%def&gt;</pre></div>
</div>
To invoke the <code class="docutils literal notranslate">&lt;%def&gt;</code>, it is normally called as an expression:
<div class="highlight-mako notranslate"><div class="highlight"><pre>the def: ${hello()}</pre></div>
</div>
If the <code class="docutils literal notranslate">&lt;%def&gt;</code> is not nested inside of another <code class="docutils literal notranslate">&lt;%def&gt;</code>,
it’s known as a top level def and can be accessed anywhere in
the template, including above where it was defined.
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 <code class="docutils literal notranslate">username</code> and <code class="docutils literal notranslate">accountdata</code> inside the context:
<div class="highlight-mako notranslate"><div class="highlight"><pre>Hello there ${username}, how are ya. Lets see what your account says:

${account()}

&lt;%def name=&quot;account()&quot;&gt;
 Account for ${username}:&lt;br/&gt;

% for row in accountdata:
 Value: ${row}&lt;br/&gt;
 % endfor
&lt;/%def&gt;</pre></div>
</div>
The <code class="docutils literal notranslate">username</code> and <code class="docutils literal notranslate">accountdata</code> variables are present
within the main template body as well as the body of the
<code class="docutils literal notranslate">account()</code> def.
Since defs are just Python functions, you can define and pass
arguments to them as well:
<div class="highlight-mako notranslate"><div class="highlight"><pre>${account(accountname=&#39;john&#39;)}

&lt;%def name=&quot;account(accountname, type=&#39;regular&#39;)&quot;&gt;
 account name: ${accountname}, type: ${type}
&lt;/%def&gt;</pre></div>
</div>
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 <code class="docutils literal notranslate">UNDEFINED</code> if you reference a name that
does not exist.
<div class="section" id="calling-defs-from-other-files">
<h3>Calling Defs from Other Files<a class="headerlink" href="#calling-defs-from-other-files" title="Permalink to this headline">¶</a></h3>
Top level <code class="docutils literal notranslate">&lt;%def&gt;</code>s are exported by your template’s
module, and can be called from the outside; including from other
templates, as well as normal Python code. Calling a <code class="docutils literal notranslate">&lt;%def&gt;</code>
from another template is something like using an <code class="docutils literal notranslate">&lt;%include&gt;</code>
– except you are calling a specific function within the
template, not the whole template.
The remote <code class="docutils literal notranslate">&lt;%def&gt;</code> 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.
To import another template, use the <code class="docutils literal notranslate">&lt;%namespace&gt;</code> tag:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%namespace name=&quot;mystuff&quot; file=&quot;mystuff.html&quot;/&gt;</pre></div>
</div>
The above tag adds a local variable <code class="docutils literal notranslate">mystuff</code> to the current
scope.
Then, just call the defs off of <code class="docutils literal notranslate">mystuff</code>:
<div class="highlight-mako notranslate"><div class="highlight"><pre>${mystuff.somedef(x=5,y=7)}</pre></div>
</div>
The <code class="docutils literal notranslate">&lt;%namespace&gt;</code> tag also supports some of the other
semantics of Python’s <code class="docutils literal notranslate">import</code> statement, including pulling
names into the local variable space, or using <code class="docutils literal notranslate">*</code> to represent
all names, using the <code class="docutils literal notranslate">import</code> attribute:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%namespace file=&quot;mystuff.html&quot; import=&quot;foo, bar&quot;/&gt;</pre></div>
</div>
This is just a quick intro to the concept of a namespace,
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">Namespaces</a>.
</div>
<div class="section" id="calling-defs-programmatically">
<h3>Calling Defs Programmatically<a class="headerlink" href="#calling-defs-programmatically" title="Permalink to this headline">¶</a></h3>
You can call defs programmatically from any <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal notranslate">Template</code></a> object
using the <a class="reference internal" href="usage.html#mako.template.Template.get_def" title="mako.template.Template.get_def"><code class="xref py py-meth docutils literal notranslate">get_def()</code></a> method, which returns a <a class="reference internal" href="usage.html#mako.template.DefTemplate" title="mako.template.DefTemplate"><code class="xref py py-class docutils literal notranslate">DefTemplate</code></a>
object. This is a <a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal notranslate">Template</code></a> subclass which the parent
<a class="reference internal" href="usage.html#mako.template.Template" title="mako.template.Template"><code class="xref py py-class docutils literal notranslate">Template</code></a> creates, and is usable like any other template:
<div class="highlight-python notranslate"><div class="highlight"><pre>from mako.template import Template

template = Template(&quot;&quot;&quot;
 &lt;%def name=&quot;hi(name)&quot;&gt;
 hi ${name}!
 &lt;/%def&gt;

&lt;%def name=&quot;bye(name)&quot;&gt;
 bye ${name}!
 &lt;/%def&gt;
&quot;&quot;&quot;)

print(template.get_def(&quot;hi&quot;).render(name=&quot;ed&quot;))
print(template.get_def(&quot;bye&quot;).render(name=&quot;ed&quot;))</pre></div>
</div>
</div>
<div class="section" id="defs-within-defs">
<h3>Defs within Defs<a class="headerlink" href="#defs-within-defs" title="Permalink to this headline">¶</a></h3>
The def model follows regular Python rules for closures.
Declaring <code class="docutils literal notranslate">&lt;%def&gt;</code> inside another <code class="docutils literal notranslate">&lt;%def&gt;</code> declares it
within the parent’s enclosing scope:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;mydef()&quot;&gt;
 &lt;%def name=&quot;subdef()&quot;&gt;
 a sub def
 &lt;/%def&gt;

i&#39;m the def, and the subcomponent is ${subdef()}
&lt;/%def&gt;</pre></div>
</div>
Just like Python, names that exist outside the inner <code class="docutils literal notranslate">&lt;%def&gt;</code>
exist inside it as well:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%
 x = 12
%&gt;
&lt;%def name=&quot;outer()&quot;&gt;
 &lt;%
 y = 15
 %&gt;
 &lt;%def name=&quot;inner()&quot;&gt;
 inner, x is ${x}, y is ${y}
 &lt;/%def&gt;

outer, x is ${x}, y is ${y}
&lt;/%def&gt;</pre></div>
</div>
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:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%
 x = 10
%&gt;
&lt;%def name=&quot;somedef()&quot;&gt;
 ## error !
 somedef, x is ${x}
 &lt;%
 x = 27
 %&gt;
&lt;/%def&gt;</pre></div>
</div>
…because the assignment to <code class="docutils literal notranslate">x</code> declares <code class="docutils literal notranslate">x</code> as local to the
scope of <code class="docutils literal notranslate">somedef</code>, rendering the “outer” version unreachable
in the expression that tries to render it.
</div>
<div class="section" id="calling-a-def-with-embedded-content-and-or-other-defs">
<h3>Calling a Def with Embedded Content and/or Other Defs<a class="headerlink" href="#calling-a-def-with-embedded-content-and-or-other-defs" title="Permalink to this headline">¶</a></h3>
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.
To achieve this, the target def is invoked using the form
<code class="docutils literal notranslate">&lt;%namespacename:defname&gt;</code> instead of the normal <code class="docutils literal notranslate">${}</code>
syntax. This syntax, introduced in Mako 0.2.3, is functionally
equivalent to another tag known as <code class="docutils literal notranslate">%call</code>, which takes the form
<code class="docutils literal notranslate">&lt;%call expr='namespacename.defname(args)'&gt;</code>. While <code class="docutils literal notranslate">%call</code>
is available in all versions of Mako, the newer style is
probably more familiar looking. The <code class="docutils literal notranslate">namespace</code> portion of the
call is the name of the namespace in which the def is
defined – in the most simple cases, this can be <code class="docutils literal notranslate">local</code> or
<code class="docutils literal notranslate">self</code> to reference the current template’s namespace (the
difference between <code class="docutils literal notranslate">local</code> and <code class="docutils literal notranslate">self</code> is one of inheritance
– see <a class="reference internal" href="namespaces.html#namespaces-builtin">Built-in Namespaces</a> for details).
When the target def is invoked, a variable <code class="docutils literal notranslate">caller</code> 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 <code class="docutils literal notranslate">body()</code>. Below, we build a <code class="docutils literal notranslate">%def</code>
that operates upon <code class="docutils literal notranslate">caller.body()</code> to invoke the body of the
custom tag:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;buildtable()&quot;&gt;
 &lt;table&gt;
 &lt;tr&gt;&lt;td&gt;
 ${caller.body()}
 &lt;/td&gt;&lt;/tr&gt;
 &lt;/table&gt;
&lt;/%def&gt;

&lt;%self:buildtable&gt;
 I am the table body.
&lt;/%self:buildtable&gt;</pre></div>
</div>
This produces the output (whitespace formatted):
<div class="highlight-html notranslate"><div class="highlight"><pre>&lt;table&gt;
 &lt;tr&gt;&lt;td&gt;
 I am the table body.
 &lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;</pre></div>
</div>
Using the older <code class="docutils literal notranslate">%call</code> syntax looks like:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;buildtable()&quot;&gt;
 &lt;table&gt;
 &lt;tr&gt;&lt;td&gt;
 ${caller.body()}
 &lt;/td&gt;&lt;/tr&gt;
 &lt;/table&gt;
&lt;/%def&gt;

&lt;%call expr=&quot;buildtable()&quot;&gt;
 I am the table body.
&lt;/%call&gt;</pre></div>
</div>
The <code class="docutils literal notranslate">body()</code> can be executed multiple times or not at all.
This means you can use def-call-with-content to build iterators,
conditionals, etc:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;lister(count)&quot;&gt;
 % for x in range(count):
 ${caller.body()}
 % endfor
&lt;/%def&gt;

&lt;%self:lister count=&quot;${3}&quot;&gt;
 hi
&lt;/%self:lister&gt;</pre></div>
</div>
Produces:
<div class="highlight-html notranslate"><div class="highlight"><pre>hi
hi
hi</pre></div>
</div>
Notice above we pass <code class="docutils literal notranslate">3</code> as a Python expression, so that it
remains as an integer.
A custom “conditional” tag:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;conditional(expression)&quot;&gt;
 % if expression:
 ${caller.body()}
 % endif
&lt;/%def&gt;

&lt;%self:conditional expression=&quot;${4==4}&quot;&gt;
 i&#39;m the result
&lt;/%self:conditional&gt;</pre></div>
</div>
Produces:
<div class="highlight-html notranslate"><div class="highlight"><pre>i&#39;m the result</pre></div>
</div>
But that’s not all. The <code class="docutils literal notranslate">body()</code> 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 <code class="docutils literal notranslate">args</code> attribute,
which is a comma-separated list of argument names. Below, our
<code class="docutils literal notranslate">&lt;%def&gt;</code> calls the <code class="docutils literal notranslate">body()</code> of its caller, passing in an
element of data from its argument:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;layoutdata(somedata)&quot;&gt;
 &lt;table&gt;
 % for item in somedata:
 &lt;tr&gt;
 % for col in item:
 &lt;td&gt;${caller.body(col=col)}&lt;/td&gt;
 % endfor
 &lt;/tr&gt;
 % endfor
 &lt;/table&gt;
&lt;/%def&gt;

&lt;%self:layoutdata somedata=&quot;${[[1,2,3],[4,5,6],[7,8,9]]}&quot; args=&quot;col&quot;&gt;\
Body data: ${col}\
&lt;/%self:layoutdata&gt;</pre></div>
</div>
Produces:
<div class="highlight-html notranslate"><div class="highlight"><pre>&lt;table&gt;
 &lt;tr&gt;
 &lt;td&gt;Body data: 1&lt;/td&gt;
 &lt;td&gt;Body data: 2&lt;/td&gt;
 &lt;td&gt;Body data: 3&lt;/td&gt;
 &lt;/tr&gt;
 &lt;tr&gt;
 &lt;td&gt;Body data: 4&lt;/td&gt;
 &lt;td&gt;Body data: 5&lt;/td&gt;
 &lt;td&gt;Body data: 6&lt;/td&gt;
 &lt;/tr&gt;
 &lt;tr&gt;
 &lt;td&gt;Body data: 7&lt;/td&gt;
 &lt;td&gt;Body data: 8&lt;/td&gt;
 &lt;td&gt;Body data: 9&lt;/td&gt;
 &lt;/tr&gt;
&lt;/table&gt;</pre></div>
</div>
You don’t have to stick to calling just the <code class="docutils literal notranslate">body()</code> function.
The caller can define any number of callables, allowing the
<code class="docutils literal notranslate">&lt;%call&gt;</code> tag to produce whole layouts:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%def name=&quot;layout()&quot;&gt;
 ## a layout def
 &lt;div class=&quot;mainlayout&quot;&gt;
 &lt;div class=&quot;header&quot;&gt;
 ${caller.header()}
 &lt;/div&gt;

&lt;div class=&quot;sidebar&quot;&gt;
 ${caller.sidebar()}
 &lt;/div&gt;

&lt;div class=&quot;content&quot;&gt;
 ${caller.body()}
 &lt;/div&gt;
 &lt;/div&gt;
&lt;/%def&gt;

## calls the layout def
&lt;%self:layout&gt;
 &lt;%def name=&quot;header()&quot;&gt;
 I am the header
 &lt;/%def&gt;
 &lt;%def name=&quot;sidebar()&quot;&gt;
 &lt;ul&gt;
 &lt;li&gt;sidebar 1&lt;/li&gt;
 &lt;li&gt;sidebar 2&lt;/li&gt;
 &lt;/ul&gt;
 &lt;/%def&gt;

this is the body
&lt;/%self:layout&gt;</pre></div>
</div>
The above layout would produce:
<div class="highlight-html notranslate"><div class="highlight"><pre>&lt;div class=&quot;mainlayout&quot;&gt;
 &lt;div class=&quot;header&quot;&gt;
 I am the header
 &lt;/div&gt;

&lt;div class=&quot;sidebar&quot;&gt;
 &lt;ul&gt;
 &lt;li&gt;sidebar 1&lt;/li&gt;
 &lt;li&gt;sidebar 2&lt;/li&gt;
 &lt;/ul&gt;
 &lt;/div&gt;

&lt;div class=&quot;content&quot;&gt;
 this is the body
 &lt;/div&gt;
&lt;/div&gt;</pre></div>
</div>
The number of things you can do with <code class="docutils literal notranslate">&lt;%call&gt;</code> and/or the
<code class="docutils literal notranslate">&lt;%namespacename:defname&gt;</code> calling syntax is enormous. You can
create form widget libraries, such as an enclosing <code class="docutils literal notranslate">&lt;FORM&gt;</code>
tag and nested HTML input elements, or portable wrapping schemes
using <code class="docutils literal notranslate">&lt;div&gt;</code> 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 <code class="docutils literal notranslate">body()</code> 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 <code class="docutils literal notranslate">&lt;%def&gt;</code> tags and plain Python callables which are
invoked via <code class="docutils literal notranslate">&lt;%namespacename:defname&gt;</code> or <code class="docutils literal notranslate">&lt;%call&gt;</code>.
</div>
</div>
<div class="section" id="using-blocks">
<h2>Using Blocks<a class="headerlink" href="#using-blocks" title="Permalink to this headline">¶</a></h2>
The <code class="docutils literal notranslate">&lt;%block&gt;</code> tag introduces some new twists on the
<code class="docutils literal notranslate">&lt;%def&gt;</code> tag which make it more closely tailored towards layout.
<div class="versionadded">
New in version 0.4.1.
</div>
An example of a block:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;html&gt;
 &lt;body&gt;
 &lt;%block&gt;
 this is a block.
 &lt;/%block&gt;
 &lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
In the above example, we define a simple block. The block renders its content in the place
that it’s defined. Since the block is called for us, it doesn’t need a name and the above
is referred to as an anonymous block. So the output of the above template will be:
<div class="highlight-html notranslate"><div class="highlight"><pre>&lt;html&gt;
 &lt;body&gt;
 this is a block.
 &lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
So in fact the above block has absolutely no effect. Its usefulness comes when we start
using modifiers. Such as, we can apply a filter to our block:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;html&gt;
 &lt;body&gt;
 &lt;%block filter=&quot;h&quot;&gt;
 &lt;html&gt;this is some escaped html.&lt;/html&gt;
 &lt;/%block&gt;
 &lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
or perhaps a caching directive:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;html&gt;
 &lt;body&gt;
 &lt;%block cached=&quot;True&quot; cache_timeout=&quot;60&quot;&gt;
 This content will be cached for 60 seconds.
 &lt;/%block&gt;
 &lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
Blocks also work in iterations, conditionals, just like defs:
<div class="highlight-mako notranslate"><div class="highlight"><pre>% if some_condition:
 &lt;%block&gt;condition is met&lt;/%block&gt;
% endif</pre></div>
</div>
While the block renders at the point it is defined in the template,
the underlying function is present in the generated Python code only
once, so there’s no issue with placing a block inside of a loop or
similar. Anonymous blocks are defined as closures in the local
rendering body, so have access to local variable scope:
<div class="highlight-mako notranslate"><div class="highlight"><pre>% for i in range(1, 4):
 &lt;%block&gt;i is ${i}&lt;/%block&gt;
% endfor</pre></div>
</div>
<div class="section" id="using-named-blocks">
<h3>Using Named Blocks<a class="headerlink" href="#using-named-blocks" title="Permalink to this headline">¶</a></h3>
Possibly the more important area where blocks are useful is when we
do actually give them names. Named blocks are tailored to behave
somewhat closely to Jinja2’s block tag, in that they define an area
of a layout which can be overridden by an inheriting template. In
sharp contrast to the <code class="docutils literal notranslate">&lt;%def&gt;</code> tag, the name given to a block is
global for the entire template regardless of how deeply it’s nested:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;html&gt;
&lt;%block name=&quot;header&quot;&gt;
 &lt;head&gt;
 &lt;title&gt;
 &lt;%block name=&quot;title&quot;&gt;Title&lt;/%block&gt;
 &lt;/title&gt;
 &lt;/head&gt;
&lt;/%block&gt;
&lt;body&gt;
 ${next.body()}
&lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
The above example has two named blocks “<code class="docutils literal notranslate">header</code>” and “<code class="docutils literal notranslate">title</code>”, both of which can be referred to
by an inheriting template. A detailed walkthrough of this usage can be found at <a class="reference internal" href="inheritance.html">Inheritance</a>.
Note above that named blocks don’t have any argument declaration the way defs do. They still implement themselves
as Python functions, however, so they can be invoked additional times beyond their initial definition:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;div name=&quot;page&quot;&gt;
 &lt;%block name=&quot;pagecontrol&quot;&gt;
 &lt;a href=&quot;&quot;&gt;previous page&lt;/a&gt; |
 &lt;a href=&quot;&quot;&gt;next page&lt;/a&gt;
 &lt;/%block&gt;

&lt;table&gt;
 ## some content
 &lt;/table&gt;

${pagecontrol()}
&lt;/div&gt;</pre></div>
</div>
The content referenced by <code class="docutils literal notranslate">pagecontrol</code> above will be rendered both above and below the <code class="docutils literal notranslate">&lt;table&gt;</code> tags.
To keep things sane, named blocks have restrictions that defs do not:
<ul class="simple">
<li>The <code class="docutils literal notranslate">&lt;%block&gt;</code> declaration cannot have any argument signature.</li>
<li>The name of a <code class="docutils literal notranslate">&lt;%block&gt;</code> can only be defined once in a template – an error is raised if two blocks of the same
name occur anywhere in a single template, regardless of nesting. A similar error is raised if a top level def
shares the same name as that of a block.</li>
<li>A named <code class="docutils literal notranslate">&lt;%block&gt;</code> cannot be defined within a <code class="docutils literal notranslate">&lt;%def&gt;</code>, or inside the body of a “call”, i.e.
<code class="docutils literal notranslate">&lt;%call&gt;</code> or <code class="docutils literal notranslate">&lt;%namespacename:defname&gt;</code> tag. Anonymous blocks can, however.</li>
</ul>
</div>
<div class="section" id="using-page-arguments-in-named-blocks">
<h3>Using Page Arguments in Named Blocks<a class="headerlink" href="#using-page-arguments-in-named-blocks" title="Permalink to this headline">¶</a></h3>
A named block is very much like a top level def. It has a similar
restriction to these types of defs in that arguments passed to the
template via the <code class="docutils literal notranslate">&lt;%page&gt;</code> tag aren’t automatically available.
Using arguments with the <code class="docutils literal notranslate">&lt;%page&gt;</code> tag is described in the section
<a class="reference internal" href="namespaces.html#namespaces-body">The body() Method</a>, and refers to scenarios such as when the
<code class="docutils literal notranslate">body()</code> method of a template is called from an inherited template passing
arguments, or the template is invoked from an <code class="docutils literal notranslate">&lt;%include&gt;</code> tag
with arguments. To allow a named block to share the same arguments
passed to the page, the <code class="docutils literal notranslate">args</code> attribute can be used:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%page args=&quot;post&quot;/&gt;

&lt;a name=&quot;${post.title}&quot; /&gt;

&lt;span class=&quot;post_prose&quot;&gt;
 &lt;%block name=&quot;post_prose&quot; args=&quot;post&quot;&gt;
 ${post.content}
 &lt;/%block&gt;
&lt;/span&gt;</pre></div>
</div>
Where above, if the template is called via a directive like
<code class="docutils literal notranslate">&lt;%include file=&quot;post.mako&quot; args=&quot;post=post&quot; /&gt;</code>, the <code class="docutils literal notranslate">post</code>
variable is available both in the main body as well as the
<code class="docutils literal notranslate">post_prose</code> block.
Similarly, the <code class="docutils literal notranslate">**pageargs</code> variable is present, in named blocks only,
for those arguments not explicit in the <code class="docutils literal notranslate">&lt;%page&gt;</code> tag:
<div class="highlight-mako notranslate"><div class="highlight"><pre>&lt;%block name=&quot;post_prose&quot;&gt;
 ${pageargs[&#39;post&#39;].content}
&lt;/%block&gt;</pre></div>
</div>
The <code class="docutils literal notranslate">args</code> attribute is only allowed with named blocks. With
anonymous blocks, the Python function is always rendered in the same
scope as the call itself, so anything available directly outside the
anonymous block is available inside as well.
</div>
</div>
</div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
 Previous:
 <a href="syntax.html" title="previous chapter">Syntax</a>
 Next:
 <a href="runtime.html" title="next chapter">The Mako Runtime Environment</a>

<div id="docs-copyright">
 &copy; Copyright the Mako authors and contributors.
 Documentation generated using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.1.2
 with Mako templates.
 </div>
</div>

</div>

<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/language_data.js"></script>

</body>
</html>