TALES Reference¶
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.
Implementation Note
In this documentation, you will occasionally see boxes like this one. They contain extra information specific to one or more implementations of Page Templates.
Note
When this document refers to the “page template
implementation,”, “ZPT implementation” or the
“implementation”, it means the software that parses and
renders page templates to produce output. This could be a
framework like Zope, or it could a separate library like
zope.pagetemplate
. For more information, see
Page Template Implementations.
Introduction¶
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
path:a/b/c
nothing
path: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.
Implementation Note
If you do not specify a prefix, Zope and zope.pagetemplate
assumes that the expression is a path expression. Other
implementations may choose a different default.
TALES Expression Types¶
These are the TALES expression types defined in the standard:
- path expressions
- locate a value by its path.
- exists expressions
- test whether a path is valid.
- nocall expressions
- locate an object by its path.
- not expressions
- negate an expression
- string expressions
- format a string
- python expressions
- execute a Python expression
Built-in Names¶
These are the names always available to TALES expressions:
nothing: | special value used by to represent a non-value (e.g. void, None, Nil, NULL). |
---|---|
default: | special value used to specify that existing text should not be replaced. See the documentation for individual TAL statements for details on how they interpret default. |
options: | the keyword arguments passed to the template. These are generally available when a template is called from Methods and Scripts, rather than from the web. |
repeat: | the repeat variables; see the tal:repeat documentation. |
attrs: | a dictionary containing the initial values of the attributes of the current statement tag. |
CONTEXTS: | the list of standard names (this list). This can be used to access a built-in variable that has been hidden by a local or global variable with the same name. |
Zope Implementation Note
The following names are optional names supported by Zope, but are not required by the TALES standard.
root: | the system’s top-most object: the Zope root folder. |
---|---|
context: | the object to which the template is being applied. |
container: | The folder in which the template is located. |
template: | the template itself. |
request: | the publishing request object. |
user: | the authenticated user object. |
modules: | a collection through which Python modules and packages can be accessed. Only modules which are approved by the Zope security policy can be accessed. |
zope.pagetemplate
provides template
and modules
by
default. z3c.pt
tries to provide those in addition to
request
and context
. For both system, other values may be
provided by the calling framework.
TALES Exists expressions¶
Description¶
Exists expressions test for the existence of paths. An exists expression returns true when the path expressions following it expression returns a value. It is false when the path expression cannot locate an object.
Examples¶
Testing for the existence of a form variable:
<p tal:condition="not:exists:request/form/number">
Please enter a number between 0 and 5
</p>
Note that in this case you can’t use the expression, not:request/form/number, since that expression will be true if the number variable exists and is zero.
TALES Nocall expressions¶
Description¶
Nocall expressions avoid rendering the results 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, Script, 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. For example, if you want to put a DTML Document into a variable so that you can refer to its properties, you can’t use a normal path expression because it will render the Document into a string.
Examples¶
Using nocall to get the properties of a document:
<span tal:define="doc nocall:context/aDoc"
tal:content="string:${doc/getId}: ${doc/title}">
Id: Title
</span>
Using nocall expressions on a functions:
<p tal:define="join nocall:modules/string/join">
This example defines a variable:: join which is bound to the string.join function.
TALES Not expressions¶
Description¶
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:
- the number 0 is false
- positive and negative numbers are true
- an empty string or other sequence is false
- a non-empty string or other sequence is true
- a non-value (e.g.
nothing
, void, None, Nil, NULL, etc) is false - all other values are implementation-dependent.
If no expression string is supplied, an error should be generated.
Implementation Note
Python implementations use the bool
type to check for truth.
Typically this means all objects not specifically listed above as false are true, but individual object classes can customize that.
Examples¶
Testing a sequence:
<p tal:condition="not:context/objectIds">
There are no contained objects.
</p>
TALES 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
context/some-file 2009_02.html.tar.gz/foo
root/to/branch | default
request/name | string:Anonymous Coward
context/?tname/macros/?mname
When a path expression is evaluated, the implementation 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 sub-object named by the path segment.
Implementation Note
In Zope, zope.pagetemplate
and z3c.pt
, sub-objects
are located according to standard traversal rules (via
getattr, getitem, or traversal hooks). Note that traversal hooks
are used last and only if fetching an attribute failed.
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 expressible 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 TALES overview for a list of built-in variables. Variable names are looked up first in locals, then in globals, 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 global or local variable declaration. You can always access the built-in names explicitly by prefixing them with CONTEXTS. (e.g. CONTEXTS/root, CONTEXTS/nothing, etc).
Examples¶
Inserting a cookie variable or a property:
<span tal:replace="request/cookies/pref | context/pref">
preference
</span>
Inserting the user name:
<p tal:content="user/getUserName">
User name
</p>
TALES Python expressions¶
Description¶
Python expressions evaluate Python code in a security-restricted environment. Python expressions offer the same facilities as those available in Python-based Scripts and DTML variable expressions.
Security Restrictions¶
Zope Implementation Note
This entire section applies to the Zope framework.
zope.pagetemplate
also provides optional security
restrictions.
Python expressions are subject to the same security restrictions as Python-based scripts. These restrictions include:
- access limits
- Python expressions are subject to Zope permission and role security restrictions. In addition, expressions cannot access objects whose names begin with underscore.
- write limits
- Python expressions cannot change attributes of Zope objects.
Despite these limits malicious Python expressions can cause problems.
Built-in Functions¶
These standard Python built-ins are available:
- None
- abs
- apply
- callable
- chr
- cmp
- complex
- delattr
- divmod
- filter
- float
- getattr
- hash
- hex
- int
- isinstance
- issubclass
- list
- len
- long
- map
- max
- min
- oct
- ord
- repr
- round
- setattr
- str
- tuple
Zope Implementation Note
Python expressions have the same built-ins as Python-based Scripts with a few additions.
The range
and pow
functions are available and work the same way they do in
standard Python; however, they are limited to keep them from generating very
large numbers and sequences. This limitation helps to avoid accidental long
execution times.
These functions are available in Python expressions, but not in Python-based scripts:
- path(string)
- Evaluate a TALES path expression.
- string(string)
- Evaluate a TALES string expression.
- exists(string)
- Evaluates a TALES exists expression.
- nocall(string)
- Evaluates a TALES nocall expression.
Python Modules¶
A number of Python modules are available by default. You can make more modules
available. You can access modules either via path expressions (for example
modules/string/join
) or in Python with the modules
mapping object (for
example modules["string"].join
). Here are the default modules:
- string
- The standard
Python string module
Note: most of the functions in the module are also available as methods on string objects. - random
- The standard
Python random module
. - math
- The standard
Python math module
.
Zope Implementation Note
Zope makes these additional modules available.
- sequence
- A module with a powerful sorting function.
- Products.PythonScripts.standard
- Various HTML formatting functions available in DTML.
- ZTUtils
- Batch processing facilities similar to those offered by
dtml-in
. - AccessControl
- Security and access checking facilities. See AccessControl for more
- information.
Implementation Note
Some implementations simply make the entire contents of
sys.modules
available, importing new modules on demand. This
includes zope.pagetemplate
and Zope. z3c.pt
does not
import on demand, but does provide access to all currently imported
modules.
Examples¶
Using a module usage (pick a random choice from a list):
<span tal:replace="python:modules['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>
TALES 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. 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:total: ${request/form/total}">
total: 12
</p>
Including a dollar sign:
<p tal:content="string:cost: $$$cost">
cost: $42.00
</p>