Calling Defs from Other Files¶

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:

<%namespace name="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:

<%namespace file="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.

Calling Defs Programmatically¶

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:

from mako.template import Template

template = Template("""
    <%def name="hi(name)">
        hi ${name}!
    </%def>

    <%def name="bye(name)">
        bye ${name}!
    </%def>
""")

print(template.get_def("hi").render(name="ed"))
print(template.get_def("bye").render(name="ed"))

Defs within Defs¶

The def model follows regular Python rules for closures. Declaring <%def> inside another <%def> declares it within the parent’s enclosing scope:

<%def name="mydef()">
    <%def name="subdef()">
        a sub def
    </%def>

    i'm the def, and the subcomponent is ${subdef()}
</%def>

Just like Python, names that exist outside the inner <%def> exist inside it as well:

<%
    x = 12
%>
<%def name="outer()">
    <%
        y = 15
    %>
    <%def name="inner()">
        inner, x is ${x}, y is ${y}
    </%def>

    outer, x is ${x}, y is ${y}
</%def>

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:

<%
    x = 10
%>
<%def name="somedef()">
    ## error !
    somedef, x is ${x}
    <%
        x = 27
    %>
</%def>

…because the assignment to x declares x as local to the scope of somedef, rendering the “outer” version unreachable in the expression that tries to render it.

Calling a Def with Embedded Content and/or Other Defs¶

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 <%call expr='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:

<%def name="buildtable()">
    <table>
        <tr><td>
            ${caller.body()}
        </td></tr>
    </table>
</%def>

<%self:buildtable>
    I am the table body.
</%self:buildtable>

This produces the output (whitespace formatted):

<table>
    <tr><td>
        I am the table body.
    </td></tr>
</table>

Using the older %call syntax looks like:

<%def name="buildtable()">
    <table>
        <tr><td>
            ${caller.body()}
        </td></tr>
    </table>
</%def>

<%call expr="buildtable()">
    I am the table body.
</%call>

The body() can be executed multiple times or not at all. This means you can use def-call-with-content to build iterators, conditionals, etc:

<%def name="lister(count)">
    % for x in range(count):
        ${caller.body()}
    % endfor
</%def>

<%self:lister count="${3}">
    hi
</%self:lister>

Produces:

hi
hi
hi

Notice above we pass 3 as a Python expression, so that it remains as an integer.

A custom “conditional” tag:

<%def name="conditional(expression)">
    % if expression:
        ${caller.body()}
    % endif
</%def>

<%self:conditional expression="${4==4}">
    i'm the result
</%self:conditional>

Produces:

i'm the result

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:

<%def name="layoutdata(somedata)">
    <table>
    % for item in somedata:
        <tr>
        % for col in item:
            <td>${caller.body(col=col)}</td>
        % endfor
        </tr>
    % endfor
    </table>
</%def>

<%self:layoutdata somedata="${[[1,2,3],[4,5,6],[7,8,9]]}" args="col">\
Body data: ${col}\
</%self:layoutdata>

Produces:

<table>
    <tr>
        <td>Body data: 1</td>
        <td>Body data: 2</td>
        <td>Body data: 3</td>
    </tr>
    <tr>
        <td>Body data: 4</td>
        <td>Body data: 5</td>
        <td>Body data: 6</td>
    </tr>
    <tr>
        <td>Body data: 7</td>
        <td>Body data: 8</td>
        <td>Body data: 9</td>
    </tr>
</table>

You don’t have to stick to calling just the body() function. The caller can define any number of callables, allowing the <%call> tag to produce whole layouts:

<%def name="layout()">
    ## a layout def
    <div class="mainlayout">
        <div class="header">
            ${caller.header()}
        </div>

        <div class="sidebar">
            ${caller.sidebar()}
        </div>

        <div class="content">
            ${caller.body()}
        </div>
    </div>
</%def>

## calls the layout def
<%self:layout>
    <%def name="header()">
        I am the header
    </%def>
    <%def name="sidebar()">
        <ul>
            <li>sidebar 1</li>
            <li>sidebar 2</li>
        </ul>
    </%def>

        this is the body
</%self:layout>

The above layout would produce:

<div class="mainlayout">
    <div class="header">
    I am the header
    </div>

    <div class="sidebar">
    <ul>
        <li>sidebar 1</li>
        <li>sidebar 2</li>
    </ul>
    </div>

    <div class="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>.

Using Named Blocks¶

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:

<html>
<%block name="header">
    <head>
        <title>
            <%block name="title">Title</%block>
        </title>
    </head>
</%block>
<body>
    ${next.body()}
</body>
</html>

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:

<div name="page">
    <%block name="pagecontrol">
        <a href="">previous page</a> |
        <a href="">next page</a>
    </%block>

    <table>
        ## some content
    </table>

    ${pagecontrol()}
</div>

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.

Using Page Arguments in Named Blocks¶

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:

<%page args="post"/>

<a name="${post.title}" />

<span class="post_prose">
    <%block name="post_prose" args="post">
        ${post.content}
    </%block>
</span>

Where above, if the template is called via a directive like <%include file="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:

<%block name="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.