[ZPT] CVS: Products/PageTemplates/help - tal-attributes.stx:1.1 tal-condition.stx:1.1 tal-content.stx:1.1 tal-define.stx:1.1 tal-on-error.stx:1.1 tal-repeat.stx:1.1 tal-replace.stx:1.1 tal.stx:1.1
Amos Latteier
amos@zope.com
Thu, 20 Sep 2001 18:59:34 -0400
Update of /cvs-repository/Products/PageTemplates/help
In directory cvs.zope.org:/tmp/cvs-serv20219
Added Files:
tal-attributes.stx tal-condition.stx tal-content.stx
tal-define.stx tal-on-error.stx tal-repeat.stx tal-replace.stx
tal.stx
Log Message:
first cut at a TAL reference.
=== Added File Products/PageTemplates/help/tal-attributes.stx ===
attributes - Replace element attributes
Syntax
'tal:attributes' syntax::
argument ::= attribute_statement [';' attribute_statement]*
attribute_statement ::= attribute_name expression
attribute_name ::= [namespace ':'] Name
namespace ::= Name
*Note: If you want to include a semi-colon (;) in an 'expression',
it must be escaped by doubling it (;;).*
Description
The 'tal:attributes' statement replaces the value of an attribute
(or create an attribute) with a dynamic value. You can qualify an
attribute name with a namespace prefix, for example 'html:table', if
you are generating an XML document with multiple namespaces. The
value of each expression is converted to a string, if necessary.
If the expression associated with an attribute assignment evaluates
to *nothing*, then that attribute is deleted from the statement
element. If the expression evaluates to *default*, then that
attribute is left unchanged. Each attribute assignment is
independent, so attributes may be assigned in the same statement in
which some attributes are deleted and others are left alone.
If you use 'tal:attributes' on an element with an active
'tal:replace' command, the implementation may ignore the
'tal:attributes' statement. If it does not, the replacement must
use the 'structure' type, the structure returned by the expression
must yield at least one element, and the attributes will be replaced
on the first such element only. For example::
<span tal:replace="structure an_image" tal:attributes="border string:1">
May result in either::
<img src="foo.png">
or::
<img src="foo.png" border="1">
*Note: Zope will return the second result*
If you use 'tal:attributes' on an element with a 'tal:repeat'
statement, the replacement is made on each repetition of the
element, and the replacement expression is evaluated fresh for each
repetition.
Examples
Replacing a link::
<a href="/sample/link.html"
tal:attributes="href here/sub/absolute_url">
Replacing two attributes::
<textarea rows="80" cols="20"
tal:attributes="rows request/rows;cols request/cols">
=== Added File Products/PageTemplates/help/tal-condition.stx ===
condition - Conditionally insert or remove an element
Syntax
'tal:condition' syntax::
argument ::= expression
Description
The 'tal:condition' statement includes a particular part of a
template only under certain conditions, and omits it otherwise. If
its expression evaluates to a *true* value, then normal processing
of the element continues, otherwise the statement element is
immediately removed from the document. It is up to the interface
between TAL and the expression engine to determine the value of
*true* and *false*. For these purposes, the value *nothing* is
false, and *default* has the same effect as returning a true value.
*Note: Zope considers missing variables, None, zero, empty strings,
and empty sequences false; all other values are true.*
Examples
Test for variable before inserting it::
<p tal:condition="request/message"
tal:content="request/message">message goes here</p>
Test for alternate conditions::
<div tal:repeat="item python:range(10)">
<p tal:condition="repeat/item/even">Even</p>
<p tal:condition="repeat/item/odd">Odd</p>
</div>
=== Added File Products/PageTemplates/help/tal-content.stx ===
content - replace the content of an element
Syntax
'tal:content' syntax::
argument ::= (['text'] | 'structure') expression
Description
Rather than replacing an entire element, you can insert text or
structure in place of its children with the 'tal:content'
statement. The statement argument is exactly like that of
'tal:replace', and is interpreted in the same fashion. If the
expression evaluates to *nothing*, the statement element is left
childless. If the expression evaluates to *default*, then the
element's contents are unchanged.
*Note: The default replacement behavior is 'text'.*
Examples
Inserting the user name::
<p tal:content="user/name">Fred Farkas</p>
Inserting HTML/XML::
<p tal:content="structure here/getStory">marked <b>up</b>
content goes here.</p>
See Also
"'tal:replace'":tal-replace.stx
=== Added File Products/PageTemplates/help/tal-define.stx ===
define - Define variables
Syntax
'tal:define' syntax::
argument ::= define_scope [';' define_scope]*
define_scope ::= (['local'] | 'global') define_var
define_var ::= variable_name expression
variable_name ::= Name
*Note: If you want to include a semi-colon (;) in an 'expression',
it must be escaped by doubling it (;;).*
Description
The 'tal:define' statement defines variables. You can define two
different kinds of TAL variables: local and global. When you
define a local variable in a statement element, you can only use
that variable in that element and the elements it contains. If
you redefine a local variable in a contained element, the new
definition hides the outer element's definition within the inner
element. When you define a global variables, you can use it in
any element processed after the defining element. If you redefine
a global variable, you replace its definition for the rest of the
template.
*Note: local variables are the default*
If the expression associated with a variable evaluates to
*nothing*, then that variable has the value *nothing*, and may be
used as such in further expressions. Likewise, if the expression
evaluates to *default*, then the variable has the value *default*,
and may be used as such in further expressions.
Examples
Defining a global variable::
tal:define="global company_name string:Zope Corp, Inc."
Defining two varibles, where the second depends on the first::
tal:define="mytitle template/title; tlen python:len(mytitle)"
=== Added File Products/PageTemplates/help/tal-on-error.stx ===
on-error - Handle errors
Syntax
'tal:on-error' syntax::
argument ::= (['text'] | 'structure') expression
Description
The 'tal:on-error' statement provides error handling for your
template. When a TAL statement produces an error, the TAL
interpreter searches for a 'tal:on-error' statement on the same
element, then on the enclosing element, and so forth. The first
'tal:on-error' found is invoked. It is treated as a 'tal:content'
statement.
A local variable, 'error' is set. This variable has these
attributes:
'type' -- the exception type
'value' -- the exception instance
'traceback' -- the traceback object
The simplest sort of 'tal:on-error' statement has a literal error
string or *nothing* for an expression. A more complex handler may
call a script that examines the error and either emits error text
or raises an exception to propagate the error outwards.
Examples
Simple error message::
<b tal:on-error="string: Username is not defined!"
tal:content="here/getUsername">Ishmael</b>
Removing elements with errors::
<b tal:on-error="nothing"
tal:content="here/getUsername">Ishmael</b>
Calling an error-handling script::
<div tal:on-error="structure here/errorScript">
...
</div>
Here's what the error-handling script might look like::
## Script (Python) "errHandler"
##bind namespace=_
##
error=_['error']
if error.type==ZeroDivisionError:
return "<p>Can't divide by zero.</p>"
else
return """<p>An error ocurred.</p>
<p>Error type: %s</p>
<p>Error value: %s</p>""" % (error.type,
error.value)
See Also
"Python Tutorial: Errors and
Exceptions":http://www.python.org/doc/current/tut/node10.html
"Python Built-in
Exceptions":http://www.python.org/doc/current/lib/module-exceptions.html
=== Added File Products/PageTemplates/help/tal-repeat.stx ===
repeat - Repeat an element
Syntax
'tal:repeat' syntax::
argument ::= variable_name expression
variable_name ::= Name
Description
The 'tal:repeat' statement replicates a subtree of your document
once for each item in a sequence. The expression should evaluate
to a sequence. If the sequence is empty, then the statement
element is deleted, otherwise it is repeated for each value in the
sequence. If the expression is *default*, then the element is
left unchanged, and no new variables are defined.
The 'variable_name' is used to define a local variable and a
repeat variable. For each repetition, the local variable is set to
the current sequence element, and the repeat variable is set to an
iteration object.
Repeat Variables
You use repeat variables to access information about the current
repetition (such as the repeat index). The repeat variable has
the same name as the local variable, but is only accessible
through the builtin variable named 'repeat'.
The following information is available from the repeat variable:
o *index* - repetition number, starting from zero.
o *number* - repetition number, starting from one.
o *even* - true for even-indexed repetitions (0, 2, 4, ...).
o *odd* - true for odd-indexed repetitions (1, 3, 5, ...).
o *start* - true for the starting repetition (index 0).
o *end* - true for the ending, or final, repetition.
o *length* - length of the sequence, which will be the total number
of repetitions.
o *letter* - count reps with lower-case letters: "a" - "z", "aa" - "az",
"ba" - "bz", ..., "za" - "zz", "aaa" - "aaz", and so forth.
o *Letter* - upper-case version of *letter*.
You can access the contents of the repeat variable using path
expressions or Python expressions. In path expressions, you write
a three-part path consisting of the name 'repeat', the statement
variable's name, and the name of the information you want, for
example, 'repeat/item/start'. In Python expressions, you use
normal dictionary notation to get the repeat variable, then
attribute access to get the information, for example,
'python:repeat['item'].start'.
Examples
Iterating over a sequece of strings::
<p tal:repeat="txt python:'one', 'two', 'three'">
<span tal:replace="txt" />
</p>
Inserting a sequence of table rows, and using the repeat variable
to number the rows::
<table>
<tr tal:repeat="item here/cart">
<td tal:content="repeat/item/number">1</td>
<td tal:content="item/description">Widget</td>
<td tal:content="item/price">$1.50</td>
</tr>
</table>
Nested repeats::
<table border="1">
<tr tal:repeat="row python:range(10)">
<td tal:repeat="column python:range(10)">
<span tal:define="x repeat/row/number;
y repeat/column/number;
z python:x*y"
tal:replace="string:$x * $y = $z">1 * 1 = 1</span>
</td>
</tr>
</table>
=== Added File Products/PageTemplates/help/tal-replace.stx ===
replace - Replace an element
Syntax
'tal:replace' syntax::
argument ::= (['text'] | 'structure') expression
Description
The 'tal:replace' statement replaces an element with dynamic
content. It replaces the statement element with either text or a
structure (unescaped markup). The body of the statement is an
expression with an optional type prefix. The value of the
expression is converted into an escaped string if you prefix the
expression with 'text' or omit the prefix, and is inserted
unchanged if you prefix it with 'structure'. Escaping consists of
converting "&" to "&amp;", "<" to "&lt;", and
">" to "&gt;".
If the value is *nothing*, then the element is simply removed. If
the value is *default*, then the element is left unchanged.
Examples
The two ways to insert the title of a template::
<span tal:replace="template/title">Title</span>
<span tal:replace="text template/title">Title</span>
Inserting HTML/XML::
<div tal:replace="structure table" />
Inserting nothing::
<div tal:replace="nothing">This element is a comment.</div>
See Also
"'tal:content'":tal-content.stx
=== Added File Products/PageTemplates/help/tal.stx ===
TAL Overview
The *Template Attribute Language* is an attribute language used to
create dynamic templates. It allows elements of a document to be
replaced, repeated, or omitted.
The statements of TAL are XML attributes from the TAL namespace.
These attributes can be applied to an XML or HTML document in order
to make it act as a template.
A **TAL statement** has a name (the attribute name) and a body (the
attribute value). For example, an 'content' statement might look
like 'tal:content="string:Hello"'. The element on which a statement
is defined is its **statement element**. Most TAL statements
require expressions, but the syntax and semantics of these
expressions are not part of TAL. TALES is recommended for this
purpose.
The TAL namespace URI and recommended alias are currently defined
as::
xmlns:tal="http://xml.zope.org/namespaces/tal"
This is not a URL, but merely a unique identifier. Do not expect a
browser to resolve it successfully.
TAL Statements
Expressions used in statements may return values of any type,
although most statements will only accept strings, or will convert
values into a string representation. The expression language must
define a value named *nothing* (see [TALES]) that is not a string.
In particular, this value is useful for deleting elements or
attributes.
Order of Operations
When there is only one TAL statement per element, the order in
which they are executed is simple. Starting with the root
element, each element's statements are executed, then each of its
child elements is visited, in order, to do the same.
Any combination of statements may appear on the same elements,
except that the 'content' and 'replace' statements may not appear
together.
When an element has multiple statements, they are executed in this
order:
- 'define'
- 'condition'
- 'repeat'
- 'content' or 'replace'
- 'attributes'
- 'omit-tag'
Since the 'on-error' statement is only invoked when an error occurs,
it does not appear in the list.
The reasoning behind this ordering goes like this: You often want
to set up variables for use in other statements, so 'define' comes
first. The very next thing to do is decide whether this element
will be included at all, so 'condition' is next; since the
condition may depend on variables you just set, it comes after
'define'. It is valuable be able to replace various parts of an
element with different values on each iteration of a repeat, so
'repeat' is next. It makes no sense to replace attributes and
then throw them away, so 'attributes' is last. The remaining
statements clash, because they each replace or edit the statement
element.
See Also
"TALES Overview":tales.stx