The Template Attribute Language Expression Syntax (TALES) standard describes expressions that supply TAL and METAL with data. TALES is one possible expression syntax for these languages, but they are not bound to this definition. Similarly, TALES could be used in a context having nothing to do with TAL or METAL.
Note
The TALES expression components used by the reference implementation are incompatible with z3c.pt and will not work. This z3c.pt package provides its own implementations.
TALES expressions are described below with any delimiter or quote markup from higher language layers removed. Here is the basic definition of TALES syntax:
Expression ::= [type_prefix ':'] String
type_prefix ::= Name
Here are some simple examples:
a.b.c
a/b/c
nothing
python: 1 + 2
string:Hello, ${user/getUserName}
The optional type prefix determines the semantics and syntax of the expression string that follows it. A given implementation of TALES can define any number of expression types, with whatever syntax you like. It also determines which expression type is indicated by omitting the prefix.
These are the TALES expression types supported by z3c.pt:
Note
if you do not specify a prefix within an expression context, z3c.pt` assumes that the expression is a path expression.
In addition to template, macros, default and repeat, the following names are always available to TALES expressions in z3c.pt:
The following names are available in TALES expressions when evaluated inside page templates:
Finally, view page templates provide the following names:
Nocall expressions avoid calling the __call__ method of the last element of a path expression.
An ordinary path expression tries to render the object that it fetches. This means that if the object is a function, method, or some other kind of executable thing, then expression will evaluate to the result of calling the object. This is usually what you want, but not always.
Using nocall to prevent calling the __call__ of the last element of a path expression:
<span tal:define="doc nocall:context/acallabledocument"
tal:content="string:${doc/getId}: ${doc/title}">
Id: Title</span>
A not expression evaluates the expression string (recursively) as a full expression, and returns the boolean negation of its value. If the expression supplied does not evaluate to a boolean value, not will issue a warning and coerce the expression’s value into a boolean type based on the following rules:
If no expression string is supplied, an error should be generated.
z3c.pt considers all objects not specifically listed above as false to be true.
Path expression syntax:
PathExpr ::= Path [ '|' Expression ]
Path ::= variable [ '/' PathSegment ]*
variable ::= Name
PathSegment ::= ( '?' variable ) | PathChar+
PathChar ::= AlphaNumeric | ' ' | '_' | '-' | '.' | ',' | '~'
A path expression consists of a path optionally followed by a vertical bar (|) and alternate expression. A path consists of one or more non-empty strings separated by slashes. The first string must be a variable name (a built-in variable or a user defined variable), and the remaining strings, the path segments, may contain letters, digits, spaces, and the punctuation characters underscore, dash, period, comma, and tilde.
A limited amount of indirection is possible by using a variable name prefixed with ? as a path segment. The variable must contain a string, which replaces that segment before the path is traversed.
For example:
request/cookies/oatmeal
nothing
here/some-file 2001_02.html.tar.gz/foo
root/to/branch | default
request/name | string:Anonymous Coward
here/?tname/macros/?mname
When a path expression is evaluated, z3c.pt attempts to traverse the path, from left to right, until it succeeds or runs out of paths segments. To traverse a path, it first fetches the object stored in the variable. For each path segment, it traverses from the current object to the subobject named by the path segment. Subobjects are located according to standard traversal rules.
Note
The Zope 3 traversal API is used to traverse to subobjects. The five.pt package provides a Zope 2-compatible path expression.
Once a path has been successfully traversed, the resulting object is the value of the expression. If it is a callable object, such as a method or template, it is called.
If a traversal step fails, and no alternate expression has been specified, an error results. Otherwise, the alternate expression is evaluated.
The alternate expression can be any TALES expression. For example, request/name | string:Anonymous Coward is a valid path expression. This is useful chiefly for providing default values, such as strings and numbers, which are not expressable as path expressions. Since the alternate expression can be a path expression, it is possible to “chain” path expressions, as in first | second | third | nothing.
If no path is given the result is nothing.
Since every path must start with a variable name, you need a set of starting variables that you can use to find other objects and values. See the Built-in Names for a list of built-in variables. Variable names are looked up first in locals, then in the built-in list, so the built-in variables act just like built-ins in Python; They are always available, but they can be shadowed by a local variable declaration.
Inserting a cookie variable or a property:
<span tal:replace="request/cookies/pref | here/pref">
preference
</span>
Inserting the user name:
<p tal:content="user/getUserName">
User name
</p>
Python expressions evaluate Python code in a restricted environment (no access to variables starting with an underscore). Python expressions offer the same facilities as those available in Python-based Scripts and DTML variable expressions.
Using a module usage (pick a random choice from a list):
<span tal:replace="python:random.choice([
'one', 'two', 'three', 'four', 'five'])">
A random number between one and five
</span>
String processing (capitalize the user name):
<p tal:content="python:user.getUserName().capitalize()">
User Name
</p>
Basic math (convert an image size to megabytes):
<p tal:content="python:image.getSize() / 1048576.0">
12.2323
</p>
String formatting (format a float to two decimal places):
<p tal:content="python:'%0.2f' % size">
13.56
</p>
String expression syntax:
string_expression ::= ( plain_string | [ varsub ] )*
varsub ::= ( '$' Path ) | ( '${' Path '}' )
plain_string ::= ( '$$' | non_dollar )*
non_dollar ::= any character except '$'
String expressions interpret the expression string as text. If no expression string is supplied the resulting string is empty. The string can contain variable substitutions of the form $name or ${path}, where name is a variable name, and path is a path expression. The escaped string value of the path expression is inserted into the string.
Note
To prevent a $ from being interpreted this way, it must be escaped as $$.
Basic string formatting:
<span tal:replace="string:$this and $that">
Spam and Eggs
</span>
Using paths:
<p tal:content="string:${request/form/total}">
total: 12
</p>
Including a dollar sign:
<p tal:content="string:$$$cost">
cost: $42.00
</p>