1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
Chameleon
=========
Chameleon is an HTML/XML template engine for `Python
<http://www.python.org>`_.
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
<http://www.zope.org>`_ invention [1]_, but available here as a
:ref:`standalone library <no-dependencies>` that you can use in any
script or application running Python 2.5 and up (including 3.x and
`pypy <http://pypy.org>`_). It comes with a set of :ref:`new features
<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 <fast>`.
*Found a bug?* Please report issues to the `issue tracker <http://github.com/malthe/chameleon/issues>`_.
*Need help?* Post to the Pylons `discussion list <http://groups.google.com/group/pylons-discuss/>`_ or join the ``#pyramid`` channel on `Freenode IRC <http://freenode.net/>`_.
Getting the code
----------------
You can `download <http://pypi.python.org/pypi/Chameleon#downloads>`_ the
package from the Python package index or install the latest release
using setuptools or the newer `distribute
<http://packages.python.org/distribute/>`_ (required for Python 3.x)::
$ easy_install Chameleon
.. _no-dependencies:
There are no required library dependencies on Python 2.7 and up
[2]_. On 2.5 and 2.6, the `ordereddict
<http://pypi.python.org/pypi/ordereddict>`_ and `unittest2
<http://pypi.python.org/pypi/unittest2>`_ packages are set as
dependencies.
The project is hosted in a `GitHub repository
<http://github.com/malthe/chameleon>`_. Code contributions are
welcome. The easiest way is to use the `pull request
<http://help.github.com/pull-requests/>`_ 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
<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:
.. code-block:: genshi
<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:
.. code-block:: genshi
<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 — ${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 :ref:`load <load-expression>` 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
<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 <http://www.gnu.org/s/gettext/>`_ translation strings from
the markup::
"You have ${amount} dollars in your account."
If you use a web framework such as `Pyramid
<https://docs.pylonsproject.org/docs/pyramid.html>`_, 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 <language-reference>`.
If you're already familiar with the page template language, you can
skip ahead to the :ref:`getting started <getting-started-with-cpt>`
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 <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
<http://pypi.python.org/pypi/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 <http://www.gnu.org/s/gettext/>`_.
There is built-in support for the `zope.i18n
<http://pypi.python.org/pypi/zope.i18n>`_ package. If this
package is installed, it will be used by default. The
`translationstring
<http://pypi.python.org/pypi/translationstring>`_ package
offers some of the same helper and utility classes, without the
Zope application interface.
.. [3] This syntax was taken from `Genshi <http://genshi.edgewall.org/>`_.
.. [4] See the `WebHelpers
<https://docs.pylonsproject.org/projects/webhelpers/dev/modules/html/__init__.html>`_
library which provide a simple wrapper around this method.
|
