Zope Page Templates
===================

The package provides a complete implementation of the Zope Page
Templates (ZPT) language.

Zope Page Templates (ZPT) is a system which can generate HTML and XML.
ZPT is formed by the *Template Attribute Language* (*TAL*), the
*Expression Syntax* (*TALES*), *Intertionalization* (*I18N*) and the
*Macro Expansion Template Attribute Language* (*METAL*).

Reference
---------

This reference is split into parts that correspond to each of the main
language features.

.. toctree::
   :maxdepth: 2

   tal
   tales
   metal
   i18n

Extensions
----------

The ZPT implementation is largely compatible with the reference
implementation. Below is an overview of notable differences:

Default expression

   The default expression is ``python:``. Path expressions are not
   supported in the base package. The package introduces the
   ``import:`` expression which imports global names.

Tuple unpacking

   The ``tal:define`` and ``tal:repeat`` clauses supports tuple
   unpacking::

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

   The star character is not supported.

Dot-notation for dictionary lookups

   If attribute lookup fails (i.e. the dot operator), dictionary
   lookup is tried. The engine replaces attribute lookups with a call
   to a function that has the following body::

      try:
          return context.key
      except AttributeError:
          try:
              return context[key]
          except KeyError:
              raise AttributeError(key)

Interpolation is supported

   The Genshi expression interpolation syntax is supported outside
   tags and inside static attributes::

      <span class="hello-${'world'}">
         Hello, ${'world'}!
      </span>

Literal insertion

   If objects for insertion provide an ``__html__`` method, it will be
   called and the result inserted literally, without escaping.


With Zope 2
-----------

The :mod:`five.pt` package brings the Chameleon template engine to
Zope 2 (see the project page for `five.pt
<http://pypi.python.org/pypi/five.pt>`_). It's a drop-in replacement,
providing bridges to the most common API.

If your application uses the :mod:`CMF` (e.g. `Plone
<http://www.plone.org>`_), use the :mod:`cmf.pt` package in addition
(see the project page for `cmf.pt
<http://pypi.python.org/pypi/cmf.pt>`_).

Add the package dependency and include the following ZCML-snippet::

  <include package="five.pt" />

Or::

  <include package="cmf.pt" />

With Zope Toolkit
-----------------

If you're looking to use Chameleon with the Zope Toolkit, the `z3c.pt
<http://pypi.python.org/pypi/z3c.pt>`_ package is a drop-in
replacement of the reference implementation :mod:`zope.pagetemplate`.

.. _pagetemplate_api_module:

API reference
-------------

This section contains an autogenerated API reference.

The ``PageTemplate*`` constructors create templates from XML files.

.. automodule:: chameleon.zpt.template

  .. autoclass:: chameleon.zpt.template.PageTemplate

  .. autoclass:: chameleon.zpt.template.PageTemplateFile

  .. autoclass:: chameleon.zpt.template.PageTextTemplate

  .. autoclass:: chameleon.zpt.template.PageTextTemplateFile

A template loader class is provided (for use with Pylons and other
platforms).

.. automodule:: chameleon.zpt.loader

  .. autoclass:: chameleon.zpt.loader.TemplateLoader
