Illustration by Brendan Davis

Debugging ZPTs

Many Web designers use presentation tools such as Dreamweaver either exclusively or as an aid in designing Webpages. They then give their Webpages to Zope developers who, up to now, have coded the required dynamic content in DTML. This created problems when the Web designers wanted to work on their pages again in Dreamweaver, which doesn't recognize the DTML tags. Zope Page Templates (ZPTs) and the Template Attribute Language (TAL) solve this problem, among offering other advantages. In this article we give an introduction to the debugging of ZPTs.

Zope Page Templates (ZPTs) will play an integral part in Zope's future. Using ZPTs enables Web designers and application developers to work better together. With ZPTs, the Web designer can create the layout of a Webpage using a presentation tool such as Adobe GoLive™ or Dreamweaver™ and then give it to application developers who use the Template Attribute Language (TAL), the TAL Expression Syntax (TALES) and the Macro Expansion for TAL (METAL) to program dynamic content. Since TAL and METAL are used as attributes within existing HTML tags and do not use extra tags, as DTML does, the pages are not messed up when they are opened in a presentation tool and the presentation tools do not mess up the source code. Moreover, you can easily include sample data as a placeholder in your code for dynamically created content when using Zope Page Templates.

This article, however, is not about the pros and cons of Zope Page Templates but about how to debug your templates with or without using a presentation tool to edit them. Although it is much easier to edit ZPTs in a presentation tool instead of using the Zope Management Interface (ZMI), for debugging you will often also need to open the page templates in the ZMI.

The most most annoying error message I encountered while working with ZPTs was the following:

Well, thank you very much for the detailed explanation. The problem here was that I was using Adobe GoLive™ to edit the pages and (at first) never opened them in the Zope Management Interface. This changed pretty quickly because most of the time you cannot debug your Zope Page Templates just using the presentation tool since it doesn't give you any error messages at all. The ZMI usually gives you enough data to get rid of the problem. But I’m getting ahead of myself. Let’s start with the error messages that you can produce.

There are two types of error messages you will encounter when working with Zope Page Templates. They depend on the kind of error you produce.

1. Errors that result in an error message right after the ZPT is saved (this can only be seen in the ZMI, not while working in the presentation tool).
2. Errors that only result in an error message when the Page Template is rendered.

Errors of the first type are the easier ones to solve because Zope tells you exactly where the problem is. The second error type is due to an error in your programming - i.e., a logical error - which is always more difficult to debug.

As I said before, if your ZPT contains an error of the first type, Zope tells you what and where the problem is right after you save the page template in the ZMI (see Fig. 1). Sometimes the line given as the one with the error in it may not be correct for the origin of the error because the actual error has occurred earlier but not been caught at that point.

As mentioned above, when you use a presentation tool to edit a Page Template, you won’t get any error messages, since the program does not check the code for errors.

Fig. 1 - First Type of ZPT Error Message

There is also another indication that a ZPT contains errors. There will be an exclamation mark between the ZPT's id and its icon in the folder listing (see Fig 2).

Fig. 2 - Exclamation Mark Indicating a Page Template with an Error

This first type of error comprises two kinds: macro expansion errors and compilation errors.

Macro expansion errors occur when you name a macro or slot incorrectly and the 'Expand macros when editing' checkbox is activated, i.e. whenever there is a problem with METAL. The template will try to call the macro or slot but cannot due to a spelling mistake, for example, or an undefined macro or slot.

Example of an error message:

In this example, I tried to access the macro "mainstructure" using the following code:

The error resulted because the macro "mainstructure" does not exist in the main template 'my_macros'. In such a case, just check your spelling and the path to your macros.

Note: You should be careful with activating the 'Expand macros when editing' checkbox. If you accidentally misname a slot in your new page template and then save it, everything inside this misnamed slot will go lost because the slot that was defined in the macro cannot be filled.

Compilation errors occur whenever there is a problem with TAL or TALES. This happens if you spell an attribute such as tal:repeat or tal:content wrong or if the expression you use within the attribute value has errors.

The following error messages were caused a) by misspelling the TAL attribute tal:content; and b) by using a Python expression without saying that the attribute value is supposed to be a Python expression:

• Compilation failed
  TAL.TALDefs.TALError: bad TAL attribute: 'cntent', at line 6, column 9
• Compilation failed
  TAL.TALDefs.TALError: Invalid variable name "str('a')+str('b')" in expression 'str('a')+str('b')', at line 12, column 1

As you can see, the error messages are quite descriptive, and the errors are easily rectified.

The second type of error that causes error messages is the result of faulty programming or simple mistakes - for example, if you misspelled the name of a variable or tried to call it from the wrong namespace. Figure 3 shows the usual error message you will see in these cases.

Fig. 3 - Second Type of ZPT Error Message

There are different namespaces used in ZPTs, such as 'template', 'user', 'request', 'here'. In earlier versions of the Page Templates, the error message would tell you that the variable 'id2' was not found, for example, in the namespace 'template'. This would have been caused by a simple spelling mistake: the variable name should have been 'id'.

But it seems that this slightly more descriptive error message (which is of no practical use in debugging) was abandoned in favor of the usual Zope error message seen in Figure 3.

Sometimes, programming errors do not cause error messages. These are, of course, the most difficult errors to debug - for example, if elements on your page are not displayed the way you want them to be. This could still be simply a spelling mistake - although, in general, debugging errors of this type is a minor art of its own.

Listing 1 shows a sample code for a loop with a condition. This code is supposed to display a series of table rows on the page - the number depending on the variable 'num_fields' - but only if the variable 'num_fields' exists in the 'request' namespace. This sample code however, will not display anything since I intentionally misspelled the variable name in the condition (Line 1), leaving out the underscore character.

This sample code won’t cause an error message; the table rows will simply not appear on the page.

Listing 1 - Sample Code for a Loop With a Condition (Contains an Error)

1. <tr tal:condition="python:request.get('numfields') is not None"
2. tal:repeat="tab_field python:range(int(request['num_fields']))"
3. ….
4. </tr>

In a case like this, you need to find out where exactly the error is in your code - when this is not as obvious as in this above example. There are several strategies you can try to solve the problem.

For example, you can print out several variables or the 'request' before and/or after the part of the code that you believe is faulty to compare them to what values they should contain.

If you get faulty values for one or more variables that are computed within a loop (tal:repeat), you could use the tal:on-error attribute (see Listing 2). This way you can print out a variable’s value when the value causes an error. Normally, you would not be able to print out any variables at all since you would receive an error message whenever you called the page. The tal:on-error attribute makes it nonetheless possible to view the page, but now with the erroneous variable values.

Listing 2 - Sample Code for the TAL:ON-ERROR Attribute

1. <tr tal:repeat="tab_field python:range(int(request['num_fields']))">
2. <td tal:content=”python:tab_field[0]” tal:on-error=”tab_field”>
3. ...
4. </td>
5. </tr>

It might also be useful to comment out part of your code. In contrast to DTML where you need to use the dtml-comment tags so that any dtml-commands within these tags are not computed - and thus cannot produce errors -- in ZPTs it is sufficient to use the >!-- and --< tags used in HTML for comments.

I hope this article has given you an idea of how to debug your Zope Page Template source code, based on the two types of error message and on some examples for the errors behind them. This will be of help with your further work with ZPTs.