D.2 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 language ¹ 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 ", &, <, and >, 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 plasT_eX, 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 plasT_eX.

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.