Chameleon Template Engine

The Template Attribute Language (TAL) is used to create dynamic XML-like content by allowing elements to be replaced, repeated, or omitted.

Execution Order

When an element contains multiple TAL statements, they are executed in a specific order regardless of their written order in the tag:

1. tal:define (Variables are set first for use in subsequent statements)
2. tal:switch (Switch conditions)
3. tal:condition (Conditional inclusion)
4. tal:repeat (Repetition)
5. tal:case (Switch cases)
6. tal:content or tal:replace (Content substitution)
7. tal:omit-tag (Implied with tal:replace)
8. tal:attributes (Attribute manipulation)

Statement Reference

Note: tal:content and tal:replace cannot be used on the same element.

The Macro Expansion Language (METAL) allows you to create generic templates with slots that can be filled in by other templates.

Key components:

• metal:main: Defines a macro template.
• use-macro: Used by a calling template to load a macro (e.g., use-macro="load: main.pt").
• metal:fill-slot: Used in the calling template to provide content for a specific slot.
• metal:content: Used in the macro template to define where the incoming content should be placed (e.g., define-slot="content").

Note: The load: expression type retrieves a template from the file system relative to the calling template.

<!-- Macro Template -->
<html xmlns="http://www.w3.org/1999/xhtml">
  <metal:main use-macro="load: main.pt">
    <head>
      <title>Example &mdash; ${document.title}</title>
    </head>
    <body>
      <h1>${document.title}</h1>
      <div id="content">
        <metal:content define-slot="content" />
      </div>
    </body>
  </metal:main>
</html>

<!-- Calling Template -->
<metal:main use-macro="load: main.pt">
  <head>
    <p metal:fill-slot="content">${structure: document.body}</p>
  </head>
</metal:main>

You can extend Chameleon's language by writing custom expression compilers. You can register these globally by modifying PageTemplate.expression_types or locally by subclassing a template class and overriding its expression_types attribute.

Custom compilers are typically implemented as closures that return a function accepting (target, engine) and returning a list of AST nodes.

import ast
from chameleon import PageTemplate, PageTemplateFile
from chameleon.tales import PythonExpr

# 1. Define the compiler as a closure
def uppercase_expression(string):
    def compiler(target, engine):
        uppercased = string.upper()
        value = ast.Constant(uppercased)
        return [ast.Assign(targets=[target], value=value)]
    return compiler

# 2. Option A: Register globally
PageTemplate.expression_types['upper'] = uppercase_expression

# 3. Option B: Register via subclassing (preferred for isolation)
class MyPageTemplateFile(PageTemplateFile):
    expression_types = {
        'python': PythonExpr,
        'upper': uppercase_expression
    }

# Usage in template: <div tal:content="upper: hello, world" />

Chameleon provides several expression types and features to extend standard template languages:

New Expression Types

• structure: <expr>: Wraps the result as structure (inserts raw HTML without escaping).
• import: <module>: Imports module globals.
• load: <template>: Loads templates relative to the current template.

Language Features

• Tuple Unpacking: tal:define and tal:repeat support tuple unpacking (e.g., tal:define="(a, b, c) [1, 2, 3]"). Note that asterisk-based iterable unpacking is not supported.
• Fallback Dictionary Lookup: If attribute lookup (obj.name) raises an AttributeError, Chameleon automatically attempts a dictionary lookup (obj['name']).
• Switch Statements: Use tal:switch on a parent element and tal:case on children to implement conditional logic.
• Inline String Substitution: Use ${...} inside element attributes or text/tail content.

<!-- Structure expression -->
<div>${structure: body.text}</div>

<!-- Import expression -->
<div tal:define="compile import: re.compile">...</div>

<!-- Load expression -->
<div tal:define="compile load: main.pt">...</div>

<!-- Tuple unpacking -->
<div tal:define="(a, b, c) [1, 2, 3]"></div>

<!-- Switch statement -->
<div tal:switch="status">
  <div tal:case="'active'">Active</div>
  <div tal:case="'inactive'">Inactive</div>
</div>

Chameleon uses XML namespaces to distinguish template instructions from standard HTML/XML attributes. While you can declare them explicitly at the top of your template, Chameleon provides sane defaults for common prefixes.

Explicit Declaration

You can declare namespaces manually using xmlns:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:tal="http://xml.zope.org/namespaces/tal"
      xmlns:metal="http://xml.zope.org/namespaces/metal"
      xmlns:i18n="http://xml.zope.org/namespaces/i18n">
</html>

Default Prefixes

Chameleon automatically sets up default prefixes for:

• tal
• metal
• i18n

This allows you to use them immediately without boilerplate declaration.

Data Attributes

If the enable_data_attributes option is enabled, you can also use the data- prefix for template commands (e.g., data-tal-content="...").

<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <p tal:content="text"> ... </p>
  </body>
</html>