## 5.3.3 Zope Page Template Tutorial

The Zope Page Template (ZPT) language is actually just a set of XML attributes that can be applied to markup of an DTD. These attributes tell the ZPT interpreter how to process the element. There are seven different attributes that you can use to direct the processing of an XML or HTML file (in order of evaluation): define, condition, repeat, content, replace, attributes, and omit-tag. These attributes are described in section . For a more complete description, see the official ZPT documentation at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ZPT.stx.

### Template Attribute Language Expression Syntax (TALES)

The Template Attribute Language Expression Syntax (TALES) is used by the attribute language described in the next section. The TALES syntax is used to evaluate expressions based on objects in the template namespace. The results of these expressions can be used to define variables, produce output, or be used as booleans. There are also several operators used to modify the behavior or interpretation of an expression. The expressions and their modifiers are described below.

#### path: operator

A “path” is the most basic form on an expression in ZPT. The basic form is shown below.

    [path:]string [ | TALES expression ]

The path: operator is actually optional on all paths. Leaving it off makes no difference. The “string” in the above syntax is a ’/’ delimited string of names. Each name refers to a property of the previous name in the string. Properties can include attributes, methods, or keys in a dictionary. These properties can in turn have properties of their own. Some examples of paths are shown below.

    # Access the parentNode attribute of chapter, then get its title
    chapter/parentNode/title

    # Get the key named 'foo' from the dictionary bar
    bar/foo

    # Call the title method on the string in the variable booktitle
    booktitle/title

It is possible to specify multiple paths separated by a pipe (|). These paths are evaluated from left to right. The first one to return a non-None value is used.

    # Look for the title on the current chapter node as well as its parents
    chapter/title | chapter/parentNode/title | chapter/parentNode/parentNode/title

    # Look for the value of the option otherwise get its default value
    myoptions/encoding | myoptions/defaultencoding

There are a few keywords that can be used in place of a path in a TALES expression as well.

Name&Purpose
nothing&same as None in Python
default&keeps whatever the existing value of the element or attribute is
options&dictionary of values passed in to the template when instatiated
repeat&the repeat variable (see )
attrs&dictonary of the original attributes of the element
CONTEXTS&dictionary containing all of the above

#### exists: operator

This operator returns true if the path exists. If the path does not exist, the operator returns false. The syntax is as follows.

    exists:path

The “path” in the code above is a path as described in section . This operator is commonly combined with the not: operator.

#### nocall: operator

By default, if a property that is retrieved is callable, it will be called automatically. Using the nocall: operator, prevents this execution from happening. The syntax is shown below.

    nocall:path

#### not: operator

The not: operator simply negates the boolean result of the path. If the path is a boolean true, the not: operator will return false, and vice versa. The syntax is shown below.

    not:path

#### string: operator

The string: operator allows you to combine literal strings and paths into one string. Paths are inserted into the literal string using a syntax much like that of Python Templates: $path or ${path}. The general syntax is:

    string:text

Here are some examples of using the string: operator.

    string:Next - ${section/links/next}
    string:($pagenumber)
    string:[${figure/number}] ${figure/caption}

#### python: operator

The python: operator allows you to evaluate a Python expression. The syntax is as follows.

    python:python-code

The “python-code” in the expression above can include any of the Python built-in functions and operators as well as four new functions that correspond to the TALES operators: path, string, exists, and nocall. Each of these functions takes a string containing the path to be evaluated (e.g. path(’foo/bar’), exists(’chapter/title’), etc.).

When using Python operators, you must escape any characters that would not be legal in an XML/HTML document (i.e. <>&). For example, to write an expression to test if a number was less than or greater than two numbers, you would need to do something like the following example.

    # See if the figure number is less than 2 or greater than 4
    python: path('figure/number') &lt; 2 or path('figure/number') &gt; 4

#### stripped: operator

The stripped: operator only exists in the SimpleTAL distribution provided by plasTeX. It evaluates the given path and removes any markup from that path. Essentially, it is a way to get a plain text representation of the path. The syntax is as follows.

    stripped:path

### Template Attribute Language (TAL) Attributes

#### tal:define

The `tal:define` attribute allows you to define a variable for use later in the template. Variables can be specifies as local (only for use in the scope of the current element) or global (for use anywhere in the template). The syntax of the define attribute is shown below.

    tal:define="[ local | global ] name expression [; define-expression ]"

The define attributes sets the value of “name” to “expression.” By default, the scope of the variable is local, but can be specified as global by including the “global” keyword before the name of the variable. As shown in the grammar above, you can specify multiple variables in one `tal:define` attribute by separating the define expressions by semi-colons.

Examples of using the `tal:define` attribute are shown belaw.

    <p tal:define="global title document/title;
                   next self/links/next;
                   previous self/links/previous;
                   length python:len(self);
                   up string:Up - ${self/links/up}">
    ...
    </p>

#### tal:condition

The `tal:condition` attribute allows you to conditionally include an element. The syntax is shown below.

    tal:condition="expression"

The `tal:condition` attribute is very simple. If the expression evaluates to true, the element and its children will be evaluated and included in the output. If the expression evaluates to false, the element and its children will not be evaluated or included in the output. Valid expressions for the `tal:condition` attribute are the same as those for the expressions in the `tal:define` attribute.

    <p tal:condition="python:len(self)">
        <b tal:condition="self/caption">Caption for paragraph</b>
        ...
    </p>

#### tal:repeat

The `tal:repeat` attribute allows you to repeat an element multiple times; the syntax is shown below.

    tal:repeat="name expression"

When the `tal:repeat` attribute is used on an element, the result of“expression” is iterated over, and a new element is generated for each item in the iteration. The value of the current item is set to “name” much like in the `tal:define` attribute.

Within the scope of the repeated element, another variable is available: repeat. This variable contains several properties related to the loop.

Name&Purpose
index&number of the current iteration starting from zero
number&number of the current iteration starting from one
even&is true if the iteration number is even
odd&is true if the iteration number is odd
start&is true if this is the first iteration
end&is true if this is the last iteration; This is never true if the repeat expression returns an iterator
length&the length of the sequence being iterated over; This is set to sys.maxint for iterators.
letter&lower case letter corresponding to the current iteration number starting with ’a’
Letter&upper case letter corresponding to the current iteration number starting with ’A’
roman&lower case Roman numeral corresponding to the current iteration number starting with ’i’
Roman&upper case Roman numeral corresponding to the current iteration number starting with ’I’

To access the properties listed above, you must use the property of the repeat variable that corresponds to the repeat variable name. For example, if your repeat variable name is “item”, you would access the above variables using the expressions repeat/item/index, repeat/item/number, repeat/item/even, etc.

A simple example of the `tal:repeat` attribute is shown below.

    <ol>
    <li tal:repeat="option options" tal:content="option/name">option name</li>
    </ol>

One commonly used feature of rendering tables is alternating row colors. This is a little bit tricky with ZPT since the `tal:condition` attribute is evaluated before the `tal:repeat` directive. You can get around this by using the `metal:` namespace. This is the namespace used by ZPT’s macro language1 You can create another element around the element you want to be conditional. This wrapper element is simply there to do the iterating, but is not included in the output. The example below shows how to do alternating row colors in an HTML table.

    <table>
    <metal:block tal:repeat="employee employees">
    <!-- even rows -->
    <tr tal:condition="repeat/employee/even" style="background-color: white">
        <td tal:content="employee/name"></td>
        <td tal:content="employee/title"></td>
    </tr>
    <!-- odd rows -->
    <tr tal:condition="repeat/employee/odd" style="background-color: gray">
        <td tal:content="employee/name"></td>
        <td tal:content="employee/title"></td>
    </tr>
    </metal:block>
    </table>

#### tal:content

The `tal:content` attribute evaluates an expression and replaces the content of the element with the result of the expression. The syntax is shown below.

    tal:content="[ text | structure ] expression"

The text and structure options in the `tal:content` attribute indicate whether or not the content returned by the expression should be escaped (i.e. "&<> replaced by &quot;, &amp;, &lt;, and &gt;, respectively). When the text option is used, these special characters are escaped; this is the default behavior. When the structure option is specified, the result of the expression is assumed to be valid markup and is not escaped.

In SimpleTAL, the default behavior is the same as using the text option. However, in plasTeX, 99.9% of the time the content returned by the expression is valid markup, so the default was changed to structure in the SimpleTAL package distributed with plasTeX.

#### tal:replace

The `tal:replace` attribute is much like the `tal:content` attribute. They both evaluate an expression and include the content of that expression in the output, and they both have a text and structure option to indicate escaping of special characters. The difference is that when the `tal:replace` attribute is used, the element with the `tal:replace` attribute on it is not included in the output. Only the content of the evaluated expression is returned. The syntax of the `tal:replace` attribute is shown below.

    tal:replace="[ text | structure ] expression"

#### tal:attributes

The `tal:attributes` attribute allows you to programatically create attributes on the element. The syntax is shown below.

    tal:attributes="name expression [; attribute-expression ]"

The syntax of the `tal:attributes` attribute is very similar to that of the `tal:define` attribute. However, in the case of the `tal:attributes` attribute, the name is the name of the attribute to be created on the element and the expression is evaluated to get the value of the attribute. If an error occurs or None is returned by the expression, then the attribute is removed from the element.

Just as in the case of the `tal:define` attribute, you can specify multiple attributes separated by semi-colons (;). If a semi-colon character is needed in the expression, then it must be represented by a double semi-colon (;;).

An example of using the `tal:attributes` is shown below.

    <a tal:attributes="href self/links/next/url;
                       title self/links/next/title">link text</a>

#### tal:omit-tag

The `tal:omit-tag` attribute allows you to conditionally omit an element. The syntax is shown below.

    tal:omit-tag="expression"

If the value of “expression” evaluates to true (or is empty), the element is omitted; however, the content of the element is still sent to the output. If the expression evaluates to false, the element is included in the output.

Footnotes

1. The macro language isn’t discussed here. See the official ZPT documentation for more information.