TALES Expressions

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:

  • python - execute a Python expression

  • path - locate a value by its “path” (via getattr and getitem)

  • nocall - locate an object by its path.

  • not - negate an expression

  • string - format a string

Note

if you do not specify a prefix within an expression context, z3c.pt` assumes that the expression is a path expression.

Built-in Names

In addition to template, macros, default and repeat, the following names are always available to TALES expressions in z3c.pt:

  • nothing - equal to the Python null-value None.

The following names are available in TALES expressions when evaluated inside page templates:

  • options - contains the keyword arguments passed to the render-method.

  • context - the template context

  • request - the current request

  • path - a method which will evaluate a path-expression, expressed as a string.

  • exists - a method which will evaluate an exists-expression, expressed as a string.

  • modules - provides access to previously imported system modules; using this variable is not recommended.

  • econtext - dynamic variable scope dictionary which keeps track of global variables brought into scope using macros; used internally by the engine, relying on this variable is not recommended (although some legacy applications do so).

Finally, view page templates provide the following names:

  • view - the view instance

nocall expressions

Syntax

nocall expression syntax:

nocall_expression ::= 'nocall:' path_expression

Description

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.

Examples

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>

not expressions

Syntax

not expression syntax:

not_expression ::= 'not:' expression

Description

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:

  1. the number 0 is false

  2. positive and negative numbers are true

  3. an empty string or other sequence is false

  4. a non-empty string or other sequence is true

  5. a non-value (e.g. None) is false

  6. all other values are implementation-dependent.

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.

Examples

Testing a sequence:

<p tal:condition="not:context/keys">
  There are no keys.
</p>

path expressions

Syntax

Path expression syntax:

PathExpr    ::= Path [ '|' Expression ]
Path        ::= variable [ '/' PathSegment ]*
variable    ::= Name
PathSegment ::= ( '?' variable ) | PathChar+
PathChar    ::= AlphaNumeric | ' ' | '_' | '-' | '.' | ',' | '~'

Description

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.

Examples

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

Syntax

Python expression syntax:

Any valid Python language expression

Description

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.

Examples

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 expressions

Syntax

String expression syntax:

string_expression ::= ( plain_string | [ varsub ] )*
varsub            ::= ( '$' Path ) | ( '${' Path '}' )
plain_string      ::= ( '$$' | non_dollar )*
non_dollar        ::= any character except '$'

Description

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 $$.

Examples

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>