Chameleon

Chameleon is an HTML/XML template engine for Python.

It’s designed to generate the document output of a web application, typically HTML markup or XML.

The language used is page templates, originally a Zope invention [1], but available here as a standalone library that you can use in any script or application running Python 2.7 and up, including 3.4+ and pypy). It comes with a set of new features, too.

The template engine compiles templates into Python byte-code and is optimized for speed. For a complex template language, the performance is very good.

Found a bug? Please report issues to the issue tracker.

Need help? Post to the Pylons discussion list or join the #pyramid channel on Freenode IRC.

Getting the code

You can download the package from the Python package index or install the latest release using setuptools or the newer distribute (required for Python 3.x):

$ easy_install Chameleon

There are no required library dependencies on Python 2.7 and up [2].

The project is hosted in a GitHub repository. Code contributions are welcome. The easiest way is to use the pull request interface.

Introduction

The page templates language is used within your document structure as special element attributes and text markup. Using a set of simple language constructs, you control the document flow, element repetition, text replacement and translation.

Note

If you’ve used page templates in a Zope environment previously, note that Chameleon uses Python as the default expression language (instead of path expressions).

The basic language (known as the template attribute language or TAL) is simple enough to grasp from an example:

<html>
  <body>
    <h1>Hello, ${'world'}!</h1>
    <table>
      <tr tal:repeat="row 'apple', 'banana', 'pineapple'">
        <td tal:repeat="col 'juice', 'muffin', 'pie'">
           ${row.capitalize()} ${col}
        </td>
      </tr>
    </table>
  </body>
</html>

The ${...} notation is short-hand for text insertion [3]. The Python-expression inside the braces is evaluated and the result included in the output. By default, the string is escaped before insertion. To avoid this, use the structure: prefix:

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

Note that if the expression result is an object that implements an __html__() method [4], this method will be called and the result treated as “structure”. An example of such an object is the Markup class that’s included as a utility:

from chameleon.utils import Markup
username = Markup("<tt>%s</tt>" % username)

The macro language (known as the macro expansion language or METAL) provides a means of filling in portions of a generic template.

On the left, the macro template; on the right, a template that loads and uses the macro, filling in the “content” slot:

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

    <div id="content">
      <metal:content define-slot="content" />
    </div>
  </body>
</html>

In the example, the expression type load is used to retrieve a template from the file system using a path relative to the calling template.

The METAL system works with TAL such that you can for instance fill in a slot that appears in a tal:repeat loop, or refer to variables defined using tal:define.

The third language subset is the translation system (known as the internationalization language or I18N):

<html i18n:domain="example">

  ...

  <div i18n:translate="">
     You have <span i18n:name="amount">${round(amount, 2)}</span> dollars in your account.
  </div>

  ...

</html>

Each translation message is marked up using i18n:translate and values can be mapped using i18n:name. Attributes are marked for translation using i18n:attributes. The template engine generates gettext translation strings from the markup:

"You have ${amount} dollars in your account."

If you use a web framework such as Pyramid, the translation system is set up automatically and will negotiate on a target language based on the HTTP request or other parameter. If not, then you need to configure this manually.

Next steps

This was just an introduction. There are a number of other basic statements that you need to know in order to use the language. This is all covered in the language reference.

If you’re already familiar with the page template language, you can skip ahead to the getting started section to learn how to use the template engine in your code.

To learn about integration with your favorite web framework see the section on framework integration.

License

This software is made available under a BSD-like license.

Indices and Tables

Notes

[1]The template language specifications and API for the Page Templates engine are based on Zope Page Templates (see in particular zope.pagetemplate). However, the Chameleon compiler and Page Templates engine is an entirely new codebase, packaged as a standalone distribution. It does not require a Zope software environment.
[2]The translation system in Chameleon is pluggable and based on gettext. There is built-in support for the zope.i18n package. If this package is installed, it will be used by default. The translationstring package offers some of the same helper and utility classes, without the Zope application interface.
[3]This syntax was taken from Genshi.
[4]See the WebHelpers library which provide a simple wrapper around this method.