Language Reference: Code Style

${…} operator

The ${...} notation is short-hand for text insertion. The Python-expression inside the braces is evaluated and the result included in the output (all inserted text is escaped by default):

<div id="section-${index + 1}">

To escape this behavior, prefix the notation with a backslash character: \${...}.

Note that if an object implements the __html__ method, the result of this method will be inserted as-is (without XML escaping).

Code blocks

The <?python ... ?> notation allows you to embed Python code in templates:

  <?python numbers = map(str, range(1, 10)) ?>
  Please input a number from the range ${", ".join(numbers)}.

The scope of name assignments is up to the nearest macro definition, or the template, if macros are not used.

Note that code blocks can span multiple line and start on the next line of where the processing instruction begins:

  foo = [1, 2, 3]

You can use this to debug templates:

  <?python import pdb; pdb.set_trace() ?>

Markup comments

You can apply the “!” and “?” modifiers to change how comments are processed:


<!--! This comment will be dropped from output -->


<!--? This comment will be included verbatim -->

That is, evaluation of ${...} expressions is disabled if the comment opens with the “?” character.

Language extensions

Chameleon extends the page template language with a new expression types and language features. Some take inspiration from Genshi.

New expression types

The structure expression wraps an expression result as structure:

<div>${structure: body.text}</div>

The import expression imports module globals:

<div tal:define="compile import: re.compile">

The load expression loads templates relative to the current template:

<div tal:define="compile load:">

Tuple unpacking

The tal:define and tal:repeat statements support tuple unpacking:

tal:define="(a, b, c) [1, 2, 3]"

Extended iterable unpacking using the asterisk character is not currently supported (even for versions of Python that support it natively).

Dictionary lookup as fallback after attribute error

If attribute lookup (using the obj.<name> syntax) raises an AttributeError exception, a secondary lookup is attempted using dictionary lookup — obj['<name>'].

Behind the scenes, this is done by rewriting all attribute-lookups to a custom lookup call:

def lookup_attr(obj, key):
        return getattr(obj, key)
    except AttributeError as exc:
            get = obj.__getitem__
        except AttributeError:
            raise exc
            return get(key)
        except KeyError:
            raise exc

Inline string substitution

In element attributes and in the text or tail of an element, string expression interpolation is available using the ${...} syntax:

<span class="content-${item_type}">
   ${title or item_id}

Code blocks

Using <?python ... ?> notation, you can embed Python statements in your templates:

  <?python numbers = map(str, range(1, 10)) ?>
  Please input a number from the range ${", ".join(numbers)}.

Literal content

While the tal:content and tal:repeat attributes both support the structure keyword which inserts the content as a literal (without XML-escape), an object may also provide an__html__ method to the same effect.

The result of the method will be inserted as structure.

This is particularly useful for content which is substituted using the expression operator: "${...}" since the structure keyword is not allowed here.

Switch statement

Two new attributes have been added: tal:switch and tal:case. A case attribute works like a condition and only allows content if the value matches that of the nearest parent switch value.

Incompatibilities and differences

There are a number of incompatibilities and differences between the Chameleon language implementation and the Zope reference implementation (ZPT):

Default expression

The default expression type is Python.

Template arguments

Arguments passed by keyword to the render- or call method are inserted directly into the template execution namespace. This is different from ZPT where these are only available through the options dictionary.


<div tal:content="options/title" />


<div tal:content="title" />

Special symbols

The CONTEXTS symbol is not available.

The package works as a compatibility layer. The template classes in this package provide a implementation which is fully compatible with ZPT.

Leave a Comment

Your email address will not be published.