Zope.org - METAL for Beginners

www.zope.org

old.zope.org
- /Products
- /Members

Log in

Forgot your password?

METAL for Beginners

Created by . Last modified on 2003/08/05.

A beginners guide to METAL

This is part of an effort to 'give something back' into the pot of the ZPT (Zope Page Templates) system. I'm certainly not an expert in ZPT, so I'm likely to have got a few things wrong - please let me know and I'll try to get them fixed

This is not an introduction to ZPT - there's plenty of other resources to help you there.

What is METAL?

It's a macro language built into the ZPT system. I'll let Evan Simpson (leading light in the ZPT community) describe what a macro is used for

Macros are a way to share chunks of presentation, and have the shared stuff appear inline in the template. You don't use them for plugging in data values; That's what tal:replace and tal:content are for. - Evan Simpson

Getting Started with Macros

Firstly, create a page template document, call it 'mymacro'. The standard document looks like this;

<html>
  <head>
    <title tal:content="template/title">The title</title>
  </head>
  <body>
    
    <h2><span tal:replace="here/title_or_id">content title or id</span>
        <span tal:condition="template/title"
              tal:replace="template/title">optional template id</span></h2>

    This is Page Template <em tal:content="template/id">template id</em>.
  </body>
</html>

Ok, now change the html tag so it looks like this

<html xmlns:tal="http://xml.zope.org/namespaces/tal"
      xmlns:metal="http://xml.zope.org/namespaces/metal"
      metal:define-macro="master">

I dunno about you, but seeing all that XML namespace stuff made me a little worried initially (having been on a few XML lists where namespaces stoked up some dreadful religious wars didn't help...). The good news is you don't need them, so you can change the html tag to this;

<html
      metal:define-macro="master">

Much nicer.

Ok, we'll start using macros now, we'll add a navigation bar and a nice tabular outline - change the page template 'mymacro' so it looks like this

<html metal:define-macro="master">
  <head>
    <title tal:content="template/title">The title</title>
  </head>
  <body>
<table border="1">
<tr><td>I am a navigation bar - put links in here</td></tr>
<tr><td>    
    <h2><span tal:replace="here/title_or_id">content title or id</span>
        <span tal:condition="template/title"
              tal:replace="template/title">optional template id</span></h2>
   <div metal:define-slot="main">
     If you supply a tag with a 'fill-slot="main"' attribute
     when using this macro, that tag will replace this text.
This is the main block. It contains everything.
     </div>

</td>
</tr>
</table>
  </body>
</html>

Use the 'test' tab to see what it looks like.

To use this macro effectively, you'll need to call it from another page template, so create one called 'use_mymacro' and enter the following;

<html metal:use-macro="here/mymacro/macros/master">
  <head>
    <title tal:content="template/title">The title</title>
  </head>
  <body>
 <p>I know nothing</p>
  </body>
</html>

BIG TIP:Don't select the 'Expand Macros when Editing' check box. It expands out all the macro content and you lose your clean document. I may have misunderstood how 'Expand Macros...' works though.

If you 'test' the 'use_mymacro' page template you've just created, you'll get a big surprise, the 'I know nothing' text isn't displayed.

However, the page itself gives you a huge clue as to what to do next If you supply a tag with a 'fill-slot="main"' attribute when using this macro, that tag will replace this text. This is the main block. It contains everything. . Ok, change the 'use_mymacro' page template so it looks like this;

<html metal:use-macro="here/mymacro/macros/master">
  <head>
    <title tal:content="template/title">The title</title>
  </head>
  <body>
 <p metal:fill-slot="main">I know nothing</p>
  </body>
</html>

Ok, now 'test' this page template - success!. You could use standard tal:replace and tal:content structures in the <p> tag and that content will be used instead of the static content I've put in.

A word about using slots. Evan Simpson says this about using slots on the ZPT list;

You only need to use slots if you want to be able to override parts of a macro in templates that use it. To do this, give a tag in the macro definition a slot name with metal:define-slot. When you use this macro, the slot contents will be used normally along with the rest of the macro, unless you add a metal:fill-slot statement with the slot's name. A metal:fill-slot statement tag completely replaces the slot tag from the macro definition, including the tag name and any attributes.

What I use Macros for

I use macros to 'manage away' the interface elements of my site. I should also be able to render completely different layouts by changing the metal:use-macro="here/mymacro/macros/master" attribute in the html tag, eg for visually impaired people. By changing the 'mymacro' part of the attribute, totally different output can be generated.

Links and Other Resources

You can get to a lot of resources from the ZPT site, but here's ones I use all the time

I'll add to this HowTo when I get more METAL-Zen.