从其他文件调用 defs

顶层的 <%defs> 被编译到模板对应的模块中，并且可以被从外部调用；包括从其他模板，或是普通的 Python 代码来调用。从其他模板中调用 <%def> 有点像使用 <%include> —— 差别在于，你是在调用模板中的一个函数，而不是整个模板。

远程的 <%def> 调用也有点类似于 Python 中调用另一个模块中的函数的情形。需要有一个“导入”的步骤，以便从其他模板中萃取出名称，添加到你自己的模板中；然后这些名称的函数才可以被调用。

要导入另一个模板，使用 <%namespace> 标签：:

<%namespace name="mystuff" file="mystuff.html"/>

上面的标签添加了一个局部变量 "mystuff" 到当前范围中。

然后，只要调用 mystuff 中的函数即可：:

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

<%namespace> 标签还支持类似 Python import 语句的一些其他的语义，包括将名称提取到局部变量空间中，或使用 * 来代表所有名称，使用 import 属性：:

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

这里只是对名称空间的概念做了一个简单的介绍，名称空间是 Mako 的一个核心概念，在文档中有独立的章节介绍。更多的细节和例子，见 [:/Namespaces: Namespaces]。

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>

    im the def, and the subcomopnent 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 <%call> tag instead of the normal ${} syntax. The target def then gets a variable caller placed in its context which contains a namespace containing the body and other defs defined within the <%call> tag. The body itself is referenced by the method body():

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

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

This produces the output (whitespace formatted):

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

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(1,count):
        ${caller.body()}
    % endfor
</%def>

<%call expr="lister(3)">
    hi
</%call>

Produces:

hi
hi
hi

A custom "conditional" tag:

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

<%call expr="conditional(4==4)">
    im the result
</%call>

Produces:

im the result

But that's not all. The body() function also can handle arguments, which will augment the local namespace of the body callable:

<%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>

<%call expr="layoutdata([[1,2,3],[4,5,6],[7,8,9]])" args="col">
    Body data: ${col}
</%call>

Produces (whitespace formatted):

<table>
    <tr>
        <td>Body data: 1</td><td>Body data: 2</td><td>Body data: 3</td>
        <td>Body data: 4</td><td>Body data: 5</td><td>Body data: 6</td>
        <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
<%call expr="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
</%call>

The above layout would produce (whitespace formatted):

<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> 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>``s or even plain Python callables which are called via ``<%call>.

[[-- HuangYi [2007-06-15 05:37:02]]]