metal:use-macro

This attribute calls a macro and includes its result in the current template.

<span
  tal:comment="main_menu template requires 'mdate' variable"
  tal:define="mdate page/last_modified"
  metal:use-macro="main_menu"
/>

You can refer to external macros defined in other templates by specifying the template source file.

<span metal:use-macro="site_macros.xhtml/main_menu"/>

It is interesting to note that you can also use the PHPTAL inline replacement feature inside the use-macro attribute value:

<span metal:use-macro="${design}/site_macros.xhtml/main_menu"/>

Macro can call itself. This way you can output arrays recursively:

<ul metal:define-macro="show-list">
    <li tal:repeat="item list">
        <tal:block tal:condition="php:is_array(item)" tal:define="list item" metal:use-macro="show-list" />
        <tal:block tal:condition="php:!is_array(item)" tal:content="item" />
    </li>
</ul>

Callbacks

Since you can use variables in macro names, you can create macros that call back other macros. This is useful in cases where slots are not enough.

<!-- this code uses "macroname" variable as name of macro to call back -->
<ul metal:define-macro="macro-with-callback">
    <li tal:repeat="item list">
        <tal:block metal:use-macro="${macroname}"/>
    </li>
</ul>

<!-- define callback -->
<div metal:define-macro="my-callback">
    this will be called every time
</div>

<!-- use it with the first macro -->
<div tal:define="macroname 'my-callback'" metal:use-macro="macro-with-callback"/>