Previous Topic

Next Topic

Quick Search

<%def> and <%block> 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 def. They differ in their scope and calling semantics.
Whereas <%def> provides a construct that is very much like a named Python
def, the <%block> is more layout oriented.

The <%def> tag requires a name attribute, where the name references
a Python function signature:

<%defname="hello()"> hello world</%def>

To invoke the <%def>, it is normally called as an expression:

the def: ${hello()}

If the <%def> is not nested inside of another <%def>,
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 username and accountdata inside the context:

Hello there ${username}, how are ya. Lets see what your account says:${account()}<%defname="account()"> Account for ${username}:<br/>%forrowinaccountdata: Value: ${row}<br/>% endfor</%def>

The username and accountdata variables are present
within the main template body as well as the body of the
account() def.

Since defs are just Python functions, you can define and pass
arguments to them as well:

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 UNDEFINED if you reference a name that
does not exist.

Top level <%def>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 <%def>
from another template is something like using an <%include>
– except you are calling a specific function within the
template, not the whole template.

The remote <%def> 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 <%namespace> tag:

<%namespacename="mystuff"file="mystuff.html"/>

The above tag adds a local variable mystuff to the current
scope.

Then, just call the defs off of mystuff:

${mystuff.somedef(x=5,y=7)}

The <%namespace> tag also supports some of the other
semantics of Python’s import statement, including pulling
names into the local variable space, or using * to represent
all names, using the import attribute:

<%namespacefile="mystuff.html"import="foo, bar"/>

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
Namespaces.

You can call defs programmatically from any Template object
using the get_def() method, which returns a DefTemplate
object. This is a Template subclass which the parent
Template creates, and is usable like any other template:

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
<%namespacename:defname> instead of the normal ${}
syntax. This syntax, introduced in Mako 0.2.3, is functionally
equivalent to another tag known as %call, which takes the form
<%callexpr='namespacename.defname(args)'>. While %call
is available in all versions of Mako, the newer style is
probably more familiar looking. The namespace portion of the
call is the name of the namespace in which the def is
defined – in the most simple cases, this can be local or
self to reference the current template’s namespace (the
difference between local and self is one of inheritance
– see Built-in Namespaces for details).

When the target def is invoked, a variable caller 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 body(). Below, we build a %def
that operates upon caller.body() to invoke the body of the
custom tag:

But that’s not all. The body() 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 args attribute,
which is a comma-separated list of argument names. Below, our
<%def> calls the body() of its caller, passing in an
element of data from its argument:

<divclass="mainlayout"><divclass="header">
I am the header
</div><divclass="sidebar"><ul><li>sidebar 1</li><li>sidebar 2</li></ul></div><divclass="content">
this is the body
</div></div>

The number of things you can do with <%call> and/or the
<%namespacename:defname> calling syntax is enormous. You can
create form widget libraries, such as an enclosing <FORM>
tag and nested HTML input elements, or portable wrapping schemes
using <div> 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 body() 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 <%def> tags and plain Python callables which are
invoked via <%namespacename:defname> or <%call>.

The <%block> tag introduces some new twists on the
<%def> tag which make it more closely tailored towards layout.

New in version 0.4.1.

An example of a block:

<html> <body><%block> this is a block.</%block> </body></html>

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:

<html><body>
this is a block.
</body></html>

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:

<html> <body><%blockcached="True"cache_timeout="60"> This content will be cached for 60 seconds.</%block> </body></html>

Blocks also work in iterations, conditionals, just like defs:

%ifsome_condition:<%block>condition is met</%block>% endif

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:

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 <%def> tag, the name given to a block is
global for the entire template regardless of how deeply it’s nested:

The above example has two named blocks “header” and “title”, both of which can be referred to
by an inheriting template. A detailed walkthrough of this usage can be found at Inheritance.

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:

The content referenced by pagecontrol above will be rendered both above and below the <table> tags.

To keep things sane, named blocks have restrictions that defs do not:

The <%block> declaration cannot have any argument signature.

The name of a <%block> 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.

A named <%block> cannot be defined within a <%def>, or inside the body of a “call”, i.e.
<%call> or <%namespacename:defname> tag. Anonymous blocks can, however.

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 <%page> tag aren’t automatically available.
Using arguments with the <%page> tag is described in the section
The body() Method, and refers to scenarios such as when the
body() method of a template is called from an inherited template passing
arguments, or the template is invoked from an <%include> tag
with arguments. To allow a named block to share the same arguments
passed to the page, the args attribute can be used:

Where above, if the template is called via a directive like
<%includefile="post.mako"args="post=post"/>, the post
variable is available both in the main body as well as the
post_prose block.

Similarly, the **pageargs variable is present, in named blocks only,
for those arguments not explicit in the <%page> tag:

<%blockname="post_prose">${pageargs['post'].content}</%block>

The args 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.