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 :ref:`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 :ref:`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 :ref:`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:: $ pip install Chameleon .. _no-dependencies: There are no required library dependencies on Python 3.11 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: .. code-block:: genshi

Hello, ${'world'}!

${row.capitalize()} ${col}

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: .. code-block:: genshi

${structure: ...}

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("%s" % 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: .. code-block:: genshi

${structure: document.body}

Example — ${document.title}

${document.title}

In the example, the expression type :ref:`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): .. code-block:: genshi ...

You have ${round(amount, 2)} dollars in your account.

... 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 :ref:`language reference `. If you're already familiar with the page template language, you can skip ahead to the :ref:`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 :ref:`framework integration `. License ------- This software is made available under a BSD-like license. Contents ======== .. toctree:: :maxdepth: 2 library.rst reference.rst integration.rst configuration.rst Indices and Tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` 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.