Illustration by Brendan Davis

ZPTs for Beginners

One of the attractive aspects of Zope is that it allows for the inclusion of dynamic content in Webpages. Using the powerful Zope-specific language DTML (Document Template Markup Language) the Zope programmer can create DTML Documents and DTML Methods that allow Webpages to be individualized for the user. One drawback of DTML, however, is that it complicates communication between Zope programmers and Webpage designers using presentation tools such as Macromedia's Dreamweaver? or Adobe GoLive? because the DTML tags are not recognized by these programs. Zope Corporation's new language TAL (Template Attribute Language), which is used in Zope Page Templates, avoids this pitfall, as its attributes are used within standard HTML tags.

For some time now, the Zope community has been debating Zope Corporation's decision to change the Zope content programming standard from the Document Template Markup Language (DTML) to Zope Page Templates (ZPTs) or, more precisely, to the Template Attribute Language (TAL). There are many pros and cons with both languages, but your choice will ultimately depend on personal preference and the tools you use to program. At least for the foreseeable future the Zope programmer will still be able to work with DTML if he so chooses, a language that many have become accustomed to over the years.

Like DTML, TAL is designed to create dynamic content within an HTML Webpage. The difference is that TAL "hides" within HTML tags and can therefore be used with presentation tools such as Adobe GoLive?, while DTML tends to hinder the use of these tools.

Moreover, with ZPTs it is possible to create pages that include sample data as placeholders. This allows one to give customers a clear idea of what their pages will look like, using sample ("default") data.

There are three terms that are essential for working with Page Templates:

1. Template Attribute Language (TAL)
2. TAL Expression Syntax (TALES)
3. Macro Expansion for TAL (METAL)

TAL and TALES go together: TAL defines the attributes you can use within any HTML tag and TALES defines certain groups of values that the attributes may be assigned.

In the example above, tal:content is the TAL attribute and template/title is an expression defined by TALES. When the <title> tag is rendered the content of the TALES expression template/title replaces the following sample data The title (it is not necessary to have text at this site: "The title" only serves a mnemonic function). I will explain the different TAL attributes and TALES expression in the next two sections of this article.

METAL is an expansion of TAL. It allows you to create templates/macros for your Webpages. Here is an example of how a macro is defined using METAL:

Let us take a look now at the default souce code for a Zope Page Template:

Click Here for the code example

This code does not contain any macros but it does contain several TAL attributes and TALES expressions. Lines 3 and 9 contain the content attribute, lines 6 and 8 contain the replace attribute and line 7 contains the condition attribute. The TALES expressions used in this code are template/title (lines 3, 7 and 8), here/title_or_id (line 6) and template/id (line 9).

When this code is rendered, the TALES expressions are evaluated and, depending on the TAL attributes, replace different things in the HTML tags they've been included in, e.g. sample data, HTML attributes or the whole HTML tag.

This will now be explained in detail, for each of the TAL attributes.

There are seven TAL attributes. They can be used within any HTML tag.

With the define attribute you can define variables. There are two types of variables: global ones, which are valid throughout the entire page, and local ones, which are only valid within the HTML tag they have been defined in.

1. <span tal:define="name string:William Petersen"></span>
2. <span tal:define="global name string:William Petersen"></span>

The first example defines the variable name only locally, while the second example defines it globally.

With the content attribute you define what is to be included between the beginning and end HTML tags that the content attribute is used in.

<h1 tal:content="string:Hello ${name}!">a welcoming headline</h1>

When the example above is rendered, the Website user will see, for example, Hello John! provided that the value of the variable name is 'John'.

The replace attribute is similar to the content attribute but instead of putting the attribute's value between the beginning and end HTML tags, the value replaces the tags and anything in between them. This finds its application when one wants to use a TAL attribute, which can only be achieved over an HTML tag, but the HTML tag itself is not to be rendered.

<span tal:replace="string:This text replaces the sample text 
as well as the span tags">sample text</span>

After rendering the source code will not contain the HTML tag <span>. It will have been replaced by the text defined by the replace attribute.

NOTE: You can only use either replace or content in an HTML tag, not both.

The attributes attribute is used to generate dynamically any HTML tag attribute. In the following example, the src attribute of the HTML tag <img> is generated using the variable image_var:

<img tal:attributes="src string:images/${image_var}.jpg">

When the above example is rendered, the source code will be: <img src="images/my_image.jpg">provided that the value of the variable image_var is 'my_image'.

The repeat attribute is used to create loops. The following example produces a table with five rows, with each row designated by a successive number, starting with 0:

<table>
  <tr tal:repeat="nr python:range(5)">
    <td tal:content="nr">show numbers 0 to 4</td>
  </tr>
</table>

The HTML tag -- in ths case <tr>?</tr> -- and everything in between is repeated as many times as is defined in the tal:repeat attribute. As with a FOR-loop, you need to define an iterator, which in this example is nr.

The condition attribute is used in lieu of an IF-construct. If a condition is true, the HTML tag and any TAL attributes defined within it are rendered. If the condition is false, the HTML tag is omitted.

<table>
<span tal:repeat="nr python:range(5)">
  <tr bgcolor="yellow" tal:condition="repeat/nr/odd">
    <td>odd</td>
  </tr>
  <tr bgcolor="white" tal:condition="repeat/nr/even">
    <td>even</td>
  </tr>
</span>
</table>

The example above produces a table with alternating yellow and white rows.

The on-error attribute is very useful if you think the rendered value of a TAL attribute might produce an error under certain circumstances. You can use the on-error attribute to define, for example, an error message to be displayed in case of an error: <span tal:content="python:5/0" tal:on-error="string:Error!"></span> or, by using the value nothing, to detemine that the attribute not be rendered: <span tal:content="python:5/0" tal:on-error="nothing"></span>

There are several namespaces and variables in TAL, which help organize the predefined variables that you can use in your page templates. Each namespace contains several variables which can only be called within their respective namespace.

You can use nothing in a tal:replace, tal:content or tal:on-error. Used with tal:content and tal:on-error, it erases the TAL attribute it is used with. Used with tal:replace, it removes the entire HTML tag.

As I said at the beginning of this article, you can enter sample data into your ZPT to demonstrate Webpages:

If you want the sample data to appear on the page instead of the values defined in the TAL attributes, use "default" as follows:

The TALES expression default can be used with tal:replace, tal:content and tal:attributes.

The options namespace contains any keyword argument that was passed to the template - for example, if the page template is called from an external method or a method in a Python product. If you have a method that ends by calling a ZPT (here: "index.html"):

then the variable list will be accessible via the options namespace:

This namespace contains all the attributes used in the current HTML tag. It is a dictionary where the keys are the attributes and the values are the key values of the attributes.

For the example above, the attrs dictionary looks like this:

This variable contains the root of your Zope application. From here you can get to any object in Zope by giving the whole path to that object. For example: root/TestFolder/index.html would give you the object index.html located in the folder TestFolder in the Zope root folder.

You can assign an object as a new root as follows:

would define TestFolder as the new root so that later in your code your paths will be shorter and clearer.

The variable here refers to the object which calls the template. Most of the time, this is the same object as the container (see below). But if you use acquisition, here and container may be different objects.

The container variable refers to the object in which the page template using this variable is located. This is usually a Folder object. You can use the container variable to call Zope objects that are located on a path relative to the location of your page template.

The template variable refers to the page template object. If you have a ZPT called index_html, you can get its id using the following code:

The modules variable gives you access to various modules that can be used within Zope Page Templates. You can use it, for example, to shorten your expressions: to use the Python method replace(), you would need to import it as follows:

But if you know you will be needing the string module more than once in your page template, you can proceed as follows:

repeat:

I used this variable in the loop-example above when describing the TAL attribute repeat. In the loop you need to define an iterator -- in the example it was nr. If you call the iterator via the repeat variable like this:

you get the iterator object. This object comes with a number of useful methods - for example, the methods odd and even, which return 0 (FALSE) or 1 (TRUE) depending on whether the index of the iterator is odd or even. Other methods are:

To use these methods on an iterator, call them as follows:

With the request namespace you gain access to variables that have been submitted by forms, as well as to environmental variables such as URL or BASE, and to the RESPONSE object. You can also set your own variables in the request:

This variable refers to the user object of the currently logged-in user. You can get the user's name, roles and other information via this variable:

In the examples used throughout this article, there were various ways to express attribute values. Often you can simply use the TALES expressions, such as template/id.

Sometimes, however, you need to use Python expressions. This is done by writing python: in front of your Python expression:

As you can see, variables in Python expressions are called by just giving their names. Python expressions can be used within any TAL attribute.

If you just need a string within a TAL attribute, such as the 'Hello John' string used in an earlier example, use string: in the same way python: is used.

Here, variables are called between ${ and }. Strings can also be used with any TAL attributes.

With macros you can give all the pages of your Website the same basic look without having to repeatedly code the same HTML. The advantage is that when you decide to change the look of your Website, you will only need to change the macro(s) instead of having to go through all your pages and changing them accordingly.

Figure 1 - Macros are defined in Page Template objects.

Macros are defined in Page Template objects. You can have as many macros in one page template as you want, but if you have a lot of macros from the perspective of organization it is better to put each macro in its own page template.

The METAL attributes that declare macros and slots are:

metal:define-macro
metal:define-slot

Note that slots can only be defined within a macro.

To use a macro or a slot in a page template, you employ the following attributes:

metal:use-macro
metal:fill-slot

The source code of Listing 2 shows how macros and slots are defined in context:

<html metal:define-macro="main">
  <head>
    <title tal:content="template/title">The title</title>
  </head>
  <body>
     <span metal:define-slot="bodyslot">
     This is the slot "bodyslot".</span>
   </body>
</html>

The values of the METAL attributes are the names of a macro or slot, by means of which a macro or a slot is called in a page template (see Listing 3).

<html metal:use-macro="here/standard_template.pt/macros/main">
  <span metal:fill-slot="bodyslot">
     This is the text unique to this Webpage which is entered 
     into the slot bodyslot defined in the macro main.
  </span>
</html>

To use a macro, you need to state where to find it. First comes the path to the page template which contains the macro (in the above example: here/standard_template.pt). Then comes the word macros, to access the macros defined in the page template, followed by the name of the macro as defined in the metal:define-macro attribute.

To call the slot one only needs its name as defined in the metal:define-slot attribute.

I hope this article has given you an introduction to Zope Page Templates and an overview of what is possible with them. If you are having trouble using ZPTs, the ZopeMag article 'Debugging ZPTs' might be of use to you. If you are a bit more comfortable with ZPTs, you might find another ZopeMag article of interest in which ZPTs are used to create a database user interface.

Article: Creating a Database User Interface with Zope Page Templates:
http://www.zopemag.com/Issue001/Section_Tutorials/tutorial_DatabaseZPT_01.html

Article: Debugging ZPTs:
http://www.zopemag.com/Issue002/Section_Articles/article_DbugZPTs_01.html

The Front Page of the Old ZPT Wiki:
http://www.zope.org//Wikis/DevSite/Projects/ZPT/FrontPage

ZPTs Chapter in the Zope Book:
http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx