<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Language Reference — Chameleon 2.10 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.10',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Chameleon 2.10 documentation" href="index.html" />
<link rel="next" title="Integration" href="integration.html" />
<link rel="prev" title="Library Documentation" href="library.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="integration.html" title="Integration"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="library.html" title="Library Documentation"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Chameleon 2.10 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="id1">
<h1>Language Reference<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h1>
<p>The language reference is structured such that it can be read as a
general introduction to the <em>page templates</em> language.</p>
<p>It’s split into parts that correspond to each of the main language
features.</p>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<p>You can safely <a class="reference internal" href="#tal"><em>skip this section</em></a> if you’re familiar with
how template languages work or just want to learn by example.</p>
<p>An <em>attribute language</em> is a programming language designed to render
documents written in XML or HTML markup. The input must be a
well-formed document. The output from the template is usually
XML-like but isn’t required to be well-formed.</p>
<p>The statements of the language are document tags with special
attributes, and look like this:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">namespace-prefix:command=</span><span class="s">"argument"</span><span class="nt">></span> ... <span class="nt"></p></span>
</pre></div>
</div>
<p>In the above example, the attribute
<tt class="docutils literal"><span class="pre">namespace-prefix:command="argument"</span></tt> is the statement, and the
entire paragraph tag is the statement’s element. The statement’s
element is the portion of the document on which this statement
operates.</p>
<p>The namespace prefixes are typically declared once, at the top of a
template (note that prefix declarations for the template language
namespaces are omitted from the template output):</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><html</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/1999/xhtml"</span>
<span class="na">xmlns:tal=</span><span class="s">"http://xml.zope.org/namespaces/tal"</span>
<span class="na">xmlns:metal=</span><span class="s">"http://xml.zope.org/namespaces/metal"</span>
<span class="na">xmlns:i18n=</span><span class="s">"http://xml.zope.org/namespaces/i18n"</span><span class="nt">></span>
...
<span class="nt"></html></span>
</pre></div>
</div>
<p>Thankfully, sane namespace prefix defaults are in place to let us skip
most of the boilerplate:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><html</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/1999/xhtml"</span><span class="nt">></span>
<span class="nt"><body></span>
<span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"text"</span><span class="nt">></span> ... <span class="nt"></p></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</pre></div>
</div>
<p>Note how <tt class="docutils literal"><span class="pre">tal</span></tt> is used without an explicit namespace
declaration. Chameleon sets up defaults for <tt class="docutils literal"><span class="pre">metal</span></tt> and <tt class="docutils literal"><span class="pre">i18n</span></tt> as
well.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Default prefixes are a special feature of Chameleon.</p>
</div>
</div>
<div class="section" id="basics-tal">
<span id="tal"></span><h2>Basics (TAL)<a class="headerlink" href="#basics-tal" title="Permalink to this headline">¶</a></h2>
<p>The <em>template attribute language</em> is used to create dynamic XML-like
content. It allows elements of a document to be replaced, repeated,
or omitted.</p>
<div class="section" id="statements">
<h3>Statements<a class="headerlink" href="#statements" title="Permalink to this headline">¶</a></h3>
<p>These are the available statements:</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="78%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Statement</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">tal:define</span></tt></td>
<td>Define variables.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">tal:switch</span></tt></td>
<td>Defines a switch condition</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">tal:condition</span></tt></td>
<td>Include element only if expression is true.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">tal:repeat</span></tt></td>
<td>Repeat an element.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">tal:case</span></tt></td>
<td>Includes element only if expression is equal to parent switch.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">tal:content</span></tt></td>
<td>Substitute the content of an element.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">tal:replace</span></tt></td>
<td>Replace the element with dynamic content.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">tal:omit-tag</span></tt></td>
<td>Omit the element tags, leaving only the inner content.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">tal:attributes</span></tt></td>
<td>Dynamically change or insert element attributes.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">tal:on-error</span></tt></td>
<td>Substitute the content of an element if processing fails.</td>
</tr>
</tbody>
</table>
<p>When there is only one TAL statement per element, the order in which
they are executed is simple. Starting with the root element, each
element’s statements are executed, then each of its child elements is
visited, in order, to do the same:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><html></span>
<span class="nt"><meta></span>
<span class="nt"><title</span> <span class="na">tal:content=</span><span class="s">"context.title"</span> <span class="nt">/></span>
<span class="nt"></meta></span>
<span class="nt"><body></span>
<span class="nt"><div</span> <span class="na">tal:condition=</span><span class="s">"items"</span><span class="nt">></span>
<span class="nt"><p></span>These are your items:<span class="nt"></p></span>
<span class="nt"><ul></span>
<span class="nt"><li</span> <span class="na">tal:repeat=</span><span class="s">"item items"</span> <span class="na">tal:content=</span><span class="s">"item"</span> <span class="nt">/></span>
<span class="nt"></ul></span>
<span class="nt"></div></span>
<span class="nt"></body></span>
<span class="nt"></html></span>
</pre></div>
</div>
<p>Any combination of statements may appear on the same element, except
that the <tt class="docutils literal"><span class="pre">tal:content</span></tt> and <tt class="docutils literal"><span class="pre">tal:replace</span></tt> statements may not be
used on the same element.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">tal:case</span></tt> and <tt class="docutils literal"><span class="pre">tal:switch</span></tt> statements are available
in Chameleon only.</p>
</div>
<p>TAL does not use use the order in which statements are written in the
tag to determine the order in which they are executed. When an
element has multiple statements, they are executed in the order
printed in the table above.</p>
<p>There is a reasoning behind this ordering. Because users often want
to set up variables for use in other statements contained within this
element or subelements, <tt class="docutils literal"><span class="pre">tal:define</span></tt> is executed first. Then any
switch statement. <tt class="docutils literal"><span class="pre">tal:condition</span></tt> follows, then <tt class="docutils literal"><span class="pre">tal:repeat</span></tt>, then
<tt class="docutils literal"><span class="pre">tal:case</span></tt>. We are now rendering an element; first <tt class="docutils literal"><span class="pre">tal:content</span></tt>
or <tt class="docutils literal"><span class="pre">tal:replace</span></tt>. Finally, before <tt class="docutils literal"><span class="pre">tal:attributes</span></tt>, we have
<tt class="docutils literal"><span class="pre">tal:omit-tag</span></tt> (which is implied with <tt class="docutils literal"><span class="pre">tal:replace</span></tt>).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><em>TALES</em> is used as the expression language for the “stuff in
the quotes”. The default syntax is simply Python, but
other inputs are possible — see the section on <a class="reference internal" href="#tales"><em>expressions</em></a>.</p>
</div>
<div class="section" id="tal-attributes">
<h4><tt class="docutils literal"><span class="pre">tal:attributes</span></tt><a class="headerlink" href="#tal-attributes" title="Permalink to this headline">¶</a></h4>
<p>Removes, updates or inserts element attributes.</p>
<div class="highlight-xml"><div class="highlight"><pre>tal:attributes="href request.url"
</pre></div>
</div>
<div class="section" id="id2">
<h5>Syntax<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:attributes</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= attribute_statement [';' attribute_statement]*
attribute_statement ::= (attribute_name expression | expression)
attribute_name ::= [namespace-prefix ':'] Name
namespace-prefix ::= Name
</pre></div>
</div>
</div>
<div class="section" id="description">
<h5>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">tal:attributes</span></tt> statement replaces the value of an attribute
(or drops, or creates an attribute) with a dynamic value. The value
of each expression is converted to a string, if necessary.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can qualify an attribute name with a namespace prefix,
for example <tt class="docutils literal"><span class="pre">html:table</span></tt>, if you are generating an XML document
with multiple namespaces.</p>
</div>
<p>If an attribute expression evaluates to <tt class="docutils literal"><span class="pre">None</span></tt>, the attribute is
deleted from the statement element (or simply not inserted).</p>
<p>If an attribute statement is just an expression, it must evaluate to a
Python dict (or implement the methods <tt class="docutils literal"><span class="pre">update()</span></tt> and <tt class="docutils literal"><span class="pre">items()</span></tt>
from the dictionary specification).</p>
<p>If the expression evaluates to the symbol <tt class="docutils literal"><span class="pre">default</span></tt> (a symbol which
is always available when evaluating attributes), its value is defined
as the default static attribute value. If there is no such default
value, a return value of <tt class="docutils literal"><span class="pre">default</span></tt> will drop the attribute.</p>
<p>If you use <tt class="docutils literal"><span class="pre">tal:attributes</span></tt> on an element with an active
<tt class="docutils literal"><span class="pre">tal:replace</span></tt> command, the <tt class="docutils literal"><span class="pre">tal:attributes</span></tt> statement is ignored.</p>
<p>If you use <tt class="docutils literal"><span class="pre">tal:attributes</span></tt> on an element with a <tt class="docutils literal"><span class="pre">tal:repeat</span></tt>
statement, the replacement is made on each repetition of the element,
and the replacement expression is evaluated fresh for each repetition.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want to include a semicolon (”;”) in an expression, it
must be escaped by doubling it (”;;”) <a class="footnote-reference" href="#id52" id="id3">[1]</a>.</p>
</div>
</div>
<div class="section" id="examples">
<h5>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h5>
<p>Replacing a link:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><a</span> <span class="na">href=</span><span class="s">"/sample/link.html"</span>
<span class="na">tal:attributes=</span><span class="s">"href context.url()"</span>
<span class="nt">></span>
...
<span class="nt"></a></span>
</pre></div>
</div>
<p>Replacing two attributes:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><textarea</span> <span class="na">rows=</span><span class="s">"80"</span> <span class="na">cols=</span><span class="s">"20"</span>
<span class="na">tal:attributes=</span><span class="s">"rows request.rows();cols request.cols()"</span>
<span class="nt">/></span>
</pre></div>
</div>
<p>A checkbox input:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><input</span> <span class="na">type=</span><span class="s">"input"</span> <span class="na">tal:attributes=</span><span class="s">"checked True"</span> <span class="nt">/></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="tal-condition">
<h4><tt class="docutils literal"><span class="pre">tal:condition</span></tt><a class="headerlink" href="#tal-condition" title="Permalink to this headline">¶</a></h4>
<p>Conditionally includes or omits an element:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:condition=</span><span class="s">"comments"</span><span class="nt">></span>
...
<span class="nt"></div></span>
</pre></div>
</div>
<div class="section" id="id4">
<h5>Syntax<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:condition</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= expression
</pre></div>
</div>
</div>
<div class="section" id="id5">
<h5>Description<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
<blockquote>
<div>The <tt class="docutils literal"><span class="pre">tal:condition</span></tt> statement includes the statement element in the
template only if the condition is met, and omits it otherwise. If
its expression evaluates to a <em>true</em> value, then normal processing of
the element continues, otherwise the statement element is immediately
removed from the template. For these purposes, the value <tt class="docutils literal"><span class="pre">nothing</span></tt>
is false, and <tt class="docutils literal"><span class="pre">default</span></tt> has the same effect as returning a true
value.</div></blockquote>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Like Python itself, ZPT considers None, zero, empty strings,
empty sequences, empty dictionaries, and instances which return a
nonzero value from <tt class="docutils literal"><span class="pre">__len__</span></tt> or <tt class="docutils literal"><span class="pre">__nonzero__</span></tt> false; all other
values are true, including <tt class="docutils literal"><span class="pre">default</span></tt>.</p>
</div>
</div>
<div class="section" id="id6">
<h5>Examples<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
<p>Test a variable before inserting it:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">tal:condition=</span><span class="s">"request.message"</span> <span class="na">tal:content=</span><span class="s">"request.message"</span> <span class="nt">/></span>
</pre></div>
</div>
<p>Testing for odd/even in a repeat-loop:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:repeat=</span><span class="s">"item range(10)"</span><span class="nt">></span>
<span class="nt"><p</span> <span class="na">tal:condition=</span><span class="s">"repeat.item.even"</span><span class="nt">></span>Even<span class="nt"></p></span>
<span class="nt"><p</span> <span class="na">tal:condition=</span><span class="s">"repeat.item.odd"</span><span class="nt">></span>Odd<span class="nt"></p></span>
<span class="nt"></div></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="tal-content">
<h4><tt class="docutils literal"><span class="pre">tal:content</span></tt><a class="headerlink" href="#tal-content" title="Permalink to this headline">¶</a></h4>
<p>Replaces the content of an element.</p>
<div class="section" id="id7">
<h5>Syntax<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:content</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= (['text'] | 'structure') expression
</pre></div>
</div>
</div>
<div class="section" id="id8">
<h5>Description<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
<p>Rather than replacing an entire element, you can insert text or
structure in place of its children with the <tt class="docutils literal"><span class="pre">tal:content</span></tt> statement.
The statement argument is exactly like that of <tt class="docutils literal"><span class="pre">tal:replace</span></tt>, and is
interpreted in the same fashion. If the expression evaluates to
<tt class="docutils literal"><span class="pre">nothing</span></tt>, the statement element is left childless. If the
expression evaluates to <tt class="docutils literal"><span class="pre">default</span></tt>, then the element’s contents are
evaluated.</p>
<p>The default replacement behavior is <tt class="docutils literal"><span class="pre">text</span></tt>, which replaces
angle-brackets and ampersands with their HTML entity equivalents. The
<tt class="docutils literal"><span class="pre">structure</span></tt> keyword passes the replacement text through unchanged,
allowing HTML/XML markup to be inserted. This can break your page if
the text contains unanticipated markup (eg. text submitted via a web
form), which is the reason that it is not the default.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">structure</span></tt> keyword exists to provide backwards
compatibility. In Chameleon, the <tt class="docutils literal"><span class="pre">structure:</span></tt> expression
type provides the same functionality (also for inline
expressions).</p>
</div>
</div>
<div class="section" id="id9">
<h5>Examples<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
<p>Inserting the user name:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"user.getUserName()"</span><span class="nt">></span>Fred Farkas<span class="nt"></p></span>
</pre></div>
</div>
<p>Inserting HTML/XML:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"structure context.getStory()"</span><span class="nt">></span>
Marked <span class="nt"><b></span>up<span class="nt"></b></span> content goes here.
<span class="nt"></p></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="tal-define">
<h4><tt class="docutils literal"><span class="pre">tal:define</span></tt><a class="headerlink" href="#tal-define" title="Permalink to this headline">¶</a></h4>
<p>Defines local variables.</p>
<div class="section" id="id10">
<h5>Syntax<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:define</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= define_scope [';' define_scope]*
define_scope ::= (['local'] | 'global')
define_var define_var ::= variable_name
expression variable_name ::= Name
</pre></div>
</div>
</div>
<div class="section" id="id11">
<h5>Description<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">tal:define</span></tt> statement defines variables. When you define a
local variable in a statement element, you can use that variable in
that element and the elements it contains. If you redefine a variable
in a contained element, the new definition hides the outer element’s
definition within the inner element.</p>
<p>Note that valid variable names are any Python identifier string
including underscore, although two or more leading underscores are
disallowed (used internally by the compiler). Further, names are
case-sensitive.</p>
<p>Python builtins are always “in scope”, but most of them may be
redefined (such as <tt class="docutils literal"><span class="pre">help</span></tt>). Exceptions are:: <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>,
<tt class="docutils literal"><span class="pre">len</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">str</span></tt>, <tt class="docutils literal"><span class="pre">None</span></tt>, <tt class="docutils literal"><span class="pre">True</span></tt> and <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p>In addition, the following names are reserved: <tt class="docutils literal"><span class="pre">econtext</span></tt>,
<tt class="docutils literal"><span class="pre">rcontext</span></tt>, <tt class="docutils literal"><span class="pre">translate</span></tt>, <tt class="docutils literal"><span class="pre">decode</span></tt> and <tt class="docutils literal"><span class="pre">convert</span></tt>.</p>
<p>If the expression associated with a variable evaluates to <tt class="docutils literal"><span class="pre">nothing</span></tt>,
then that variable has the value <tt class="docutils literal"><span class="pre">nothing</span></tt>, and may be used as such
in further expressions. Likewise, if the expression evaluates to
<tt class="docutils literal"><span class="pre">default</span></tt>, then the variable has the value <tt class="docutils literal"><span class="pre">default</span></tt>, and may be
used as such in further expressions.</p>
<p>You can define two different kinds of variables: <em>local</em> and
<em>global</em>. When you define a local variable in a statement element, you
can only use that variable in that element and the elements it
contains. If you redefine a local variable in a contained element, the
new definition hides the outer element’s definition within the inner
element. When you define a global variables, you can use it in any
element processed after the defining element. If you redefine a global
variable, you replace its definition for the rest of the template.</p>
<p>To set the definition scope of a variable, use the keywords <tt class="docutils literal"><span class="pre">local</span></tt>
or <tt class="docutils literal"><span class="pre">global</span></tt> in front of the assignment. The default setting is
<tt class="docutils literal"><span class="pre">local</span></tt>; thus, in practice, only the <tt class="docutils literal"><span class="pre">global</span></tt> keyword is used.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want to include a semicolon (”;”) in an expression, it
must be escaped by doubling it (”;;”) <a class="footnote-reference" href="#id52" id="id12">[1]</a>.</p>
</div>
</div>
<div class="section" id="id13">
<h5>Examples<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h5>
<p>Defining a variable:</p>
<div class="highlight-xml"><div class="highlight"><pre>tal:define="company_name 'Zope Corp, Inc.'"
</pre></div>
</div>
<p>Defining two variables, where the second depends on the first:</p>
<div class="highlight-xml"><div class="highlight"><pre>tal:define="mytitle context.title; tlen len(mytitle)"
</pre></div>
</div>
</div>
</div>
<div class="section" id="tal-switch-and-tal-case">
<h4><tt class="docutils literal"><span class="pre">tal:switch</span></tt> and <tt class="docutils literal"><span class="pre">tal:case</span></tt><a class="headerlink" href="#tal-switch-and-tal-case" title="Permalink to this headline">¶</a></h4>
<p>Defines a switch clause.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><ul</span> <span class="na">tal:switch=</span><span class="s">"len(items) % 2"</span><span class="nt">></span>
<span class="nt"><li</span> <span class="na">tal:case=</span><span class="s">"True"</span><span class="nt">></span>odd<span class="nt"></li></span>
<span class="nt"><li</span> <span class="na">tal:case=</span><span class="s">"False"</span><span class="nt">></span>even<span class="nt"></li></span>
<span class="nt"></ul></span>
</pre></div>
</div>
<div class="section" id="id14">
<h5>Syntax<a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:case</span></tt> and <tt class="docutils literal"><span class="pre">tal:switch</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= expression
</pre></div>
</div>
</div>
<div class="section" id="id15">
<h5>Description<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h5>
<p>The <em>switch</em> and <em>case</em> construct is a short-hand syntax for
evaluating a set of expressions against a parent value.</p>
<p>The <tt class="docutils literal"><span class="pre">tal:switch</span></tt> statement is used to set a new parent value and the
<tt class="docutils literal"><span class="pre">tal:case</span></tt> statement works like a condition and only allows content
if the expression matches the value.</p>
<p>Note that if the case expression is the symbol <tt class="docutils literal"><span class="pre">default</span></tt>, it always
matches the switch.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">These statements are only available in Chameleon 2.x and not
part of the ZPT specification.</p>
</div>
</div>
<div class="section" id="id16">
<h5>Examples<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h5>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><ul</span> <span class="na">tal:switch=</span><span class="s">"item.type"</span><span class="nt">></span>
<span class="nt"><li</span> <span class="na">tal:case=</span><span class="s">"'document'"</span><span class="nt">></span>
Document
<span class="nt"></li></span>
<span class="nt"><li</span> <span class="na">tal:case=</span><span class="s">"'folder'"</span><span class="nt">></span>
Folder
<span class="nt"></li></span>
<span class="nt"></ul></span>
</pre></div>
</div>
<p>Note that any and all cases that match the switch will be included.</p>
</div>
</div>
<div class="section" id="tal-omit-tag">
<h4><tt class="docutils literal"><span class="pre">tal:omit-tag</span></tt><a class="headerlink" href="#tal-omit-tag" title="Permalink to this headline">¶</a></h4>
<p>Removes an element, leaving its contents.</p>
<div class="section" id="id17">
<h5>Syntax<a class="headerlink" href="#id17" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:omit-tag</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= [ expression ]
</pre></div>
</div>
</div>
<div class="section" id="id18">
<h5>Description<a class="headerlink" href="#id18" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">tal:omit-tag</span></tt> statement leaves the contents of an element in
place while omitting the surrounding start and end tags.</p>
<p>If the expression evaluates to a <em>false</em> value, then normal processing
of the element continues and the tags are not omitted. If the
expression evaluates to a <em>true</em> value, or no expression is provided,
the statement element is replaced with its contents.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Like Python itself, ZPT considers None, zero, empty strings,
empty sequences, empty dictionaries, and instances which return a
nonzero value from <tt class="docutils literal"><span class="pre">__len__</span></tt> or <tt class="docutils literal"><span class="pre">__nonzero__</span></tt> false; all other
values are true, including <tt class="docutils literal"><span class="pre">default</span></tt>.</p>
</div>
</div>
<div class="section" id="id19">
<h5>Examples<a class="headerlink" href="#id19" title="Permalink to this headline">¶</a></h5>
<p>Unconditionally omitting a tag:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:omit-tag=</span><span class="s">""</span> <span class="na">comment=</span><span class="s">"This tag will be removed"</span><span class="nt">></span>
<span class="nt"><i></span>...but this text will remain.<span class="nt"></i></span>
<span class="nt"></div></span>
</pre></div>
</div>
<p>Conditionally omitting a tag:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><b</span> <span class="na">tal:omit-tag=</span><span class="s">"not:bold"</span><span class="nt">></span>I may be bold.<span class="nt"></b></span>
</pre></div>
</div>
<p>The above example will omit the <tt class="docutils literal"><span class="pre">b</span></tt> tag if the variable <tt class="docutils literal"><span class="pre">bold</span></tt> is false.</p>
<p>Creating ten paragraph tags, with no enclosing tag:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><span</span> <span class="na">tal:repeat=</span><span class="s">"n range(10)"</span>
<span class="na">tal:omit-tag=</span><span class="s">""</span><span class="nt">></span>
<span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"n"</span><span class="nt">></span>1<span class="nt"></p></span>
<span class="nt"></span></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="tal-repeat">
<span id="id20"></span><h4><tt class="docutils literal"><span class="pre">tal:repeat</span></tt><a class="headerlink" href="#tal-repeat" title="Permalink to this headline">¶</a></h4>
<p>Repeats an element.</p>
<div class="section" id="id21">
<h5>Syntax<a class="headerlink" href="#id21" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:repeat</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= variable_name expression
variable_name ::= Name
</pre></div>
</div>
</div>
<div class="section" id="id22">
<h5>Description<a class="headerlink" href="#id22" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">tal:repeat</span></tt> statement replicates a sub-tree of your document
once for each item in a sequence. The expression should evaluate to a
sequence. If the sequence is empty, then the statement element is
deleted, otherwise it is repeated for each value in the sequence. If
the expression is <tt class="docutils literal"><span class="pre">default</span></tt>, then the element is left unchanged, and
no new variables are defined.</p>
<p>The <tt class="docutils literal"><span class="pre">variable_name</span></tt> is used to define a local variable and a repeat
variable. For each repetition, the local variable is set to the
current sequence element, and the repeat variable is set to an
iteration object.</p>
</div>
<div class="section" id="repeat-variables">
<h5>Repeat variables<a class="headerlink" href="#repeat-variables" title="Permalink to this headline">¶</a></h5>
<p>You use repeat variables to access information about the current
repetition (such as the repeat index). The repeat variable has the
same name as the local variable, but is only accessible through the
built-in variable named <tt class="docutils literal"><span class="pre">repeat</span></tt>.</p>
<p>The following information is available from the repeat variable:</p>
<table border="1" class="docutils">
<colgroup>
<col width="13%" />
<col width="87%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Attribute</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">index</span></tt></td>
<td>Repetition number, starting from zero.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">number</span></tt></td>
<td>Repetition number, starting from one.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">even</span></tt></td>
<td>True for even-indexed repetitions (0, 2, 4, ...).</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">odd</span></tt></td>
<td>True for odd-indexed repetitions (1, 3, 5, ...).</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">start</span></tt></td>
<td>True for the starting repetition (index 0).</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">end</span></tt></td>
<td>True for the ending, or final, repetition.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">first</span></tt></td>
<td>True for the first item in a group - see note below</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">last</span></tt></td>
<td>True for the last item in a group - see note below</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">length</span></tt></td>
<td>Length of the sequence, which will be the total number of repetitions.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">letter</span></tt></td>
<td>Repetition number as a lower-case letter: “a” - “z”, “aa” - “az”, “ba” - “bz”, ..., “za” - “zz”, “aaa” - “aaz”, and so forth.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">Letter</span></tt></td>
<td>Upper-case version of <em>letter</em>.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">roman</span></tt></td>
<td>Repetition number as a lower-case roman numeral: “i”, “ii”, “iii”, “iv”, “v”, etc.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">Roman</span></tt></td>
<td>Upper-case version of <em>roman</em>.</td>
</tr>
</tbody>
</table>
<p>You can access the contents of the repeat variable using either
dictionary- or attribute-style access, e.g. <tt class="docutils literal"><span class="pre">repeat['item'].start</span></tt>
or <tt class="docutils literal"><span class="pre">repeat.item.start</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For legacy compatibility, the attributes <tt class="docutils literal"><span class="pre">odd</span></tt>, <tt class="docutils literal"><span class="pre">even</span></tt>, <tt class="docutils literal"><span class="pre">number</span></tt>, <tt class="docutils literal"><span class="pre">letter</span></tt>, <tt class="docutils literal"><span class="pre">Letter</span></tt>, <tt class="docutils literal"><span class="pre">roman</span></tt>, and <tt class="docutils literal"><span class="pre">Roman</span></tt> are callable (returning <tt class="docutils literal"><span class="pre">self</span></tt>).</p>
</div>
<p>Note that <tt class="docutils literal"><span class="pre">first</span></tt> and <tt class="docutils literal"><span class="pre">last</span></tt> are intended for use with sorted
sequences. They try to divide the sequence into group of items with
the same value.</p>
</div>
<div class="section" id="id23">
<h5>Examples<a class="headerlink" href="#id23" title="Permalink to this headline">¶</a></h5>
<p>Iterating over a sequence of strings:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">tal:repeat=</span><span class="s">"txt ('one', 'two', 'three')"</span><span class="nt">></span>
<span class="nt"><span</span> <span class="na">tal:replace=</span><span class="s">"txt"</span> <span class="nt">/></span>
<span class="nt"></p></span>
</pre></div>
</div>
<p>Inserting a sequence of table rows, and using the repeat variable
to number the rows:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><table></span>
<span class="nt"><tr</span> <span class="na">tal:repeat=</span><span class="s">"item here.cart"</span><span class="nt">></span>
<span class="nt"><td</span> <span class="na">tal:content=</span><span class="s">"repeat.item.number"</span><span class="nt">></span>1<span class="nt"></td></span>
<span class="nt"><td</span> <span class="na">tal:content=</span><span class="s">"item.description"</span><span class="nt">></span>Widget<span class="nt"></td></span>
<span class="nt"><td</span> <span class="na">tal:content=</span><span class="s">"item.price"</span><span class="nt">></span>$1.50<span class="nt"></td></span>
<span class="nt"></tr></span>
<span class="nt"></table></span>
</pre></div>
</div>
<p>Nested repeats:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><table</span> <span class="na">border=</span><span class="s">"1"</span><span class="nt">></span>
<span class="nt"><tr</span> <span class="na">tal:repeat=</span><span class="s">"row range(10)"</span><span class="nt">></span>
<span class="nt"><td</span> <span class="na">tal:repeat=</span><span class="s">"column range(10)"</span><span class="nt">></span>
<span class="nt"><span</span> <span class="na">tal:define=</span><span class="s">"x repeat.row.number;</span>
<span class="s"> y repeat.column.number;</span>
<span class="s"> z x * y"</span>
<span class="na">tal:replace=</span><span class="s">"string:$x * $y = $z"</span><span class="nt">></span>1 * 1 = 1<span class="nt"></span></span>
<span class="nt"></td></span>
<span class="nt"></tr></span>
<span class="nt"></table></span>
</pre></div>
</div>
<p>Insert objects. Separates groups of objects by type by drawing a rule
between them:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:repeat=</span><span class="s">"object objects"</span><span class="nt">></span>
<span class="nt"><h2</span> <span class="na">tal:condition=</span><span class="s">"repeat.object.first.meta_type"</span>
<span class="na">tal:content=</span><span class="s">"object.type"</span><span class="nt">></span>Meta Type<span class="nt"></h2></span>
<span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"object.id"</span><span class="nt">></span>Object ID<span class="nt"></p></span>
<span class="nt"><hr</span> <span class="na">tal:condition=</span><span class="s">"object.last.meta_type"</span> <span class="nt">/></span>
<span class="nt"></div></span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">the objects in the above example should already be sorted by
type.</p>
</div>
</div>
</div>
<div class="section" id="tal-replace">
<h4><tt class="docutils literal"><span class="pre">tal:replace</span></tt><a class="headerlink" href="#tal-replace" title="Permalink to this headline">¶</a></h4>
<p>Replaces an element.</p>
<div class="section" id="id24">
<h5>Syntax<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">tal:replace</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= ['structure'] expression
</pre></div>
</div>
</div>
<div class="section" id="id25">
<h5>Description<a class="headerlink" href="#id25" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">tal:replace</span></tt> statement replaces an element with dynamic
content. It replaces the statement element with either text or a
structure (unescaped markup). The body of the statement is an
expression with an optional type prefix. The value of the expression
is converted into an escaped string unless you provide the ‘structure’ prefix. Escaping consists of converting <tt class="docutils literal"><span class="pre">&amp;</span></tt> to
<tt class="docutils literal"><span class="pre">&amp;amp;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;</span></tt> to <tt class="docutils literal"><span class="pre">&amp;lt;</span></tt>, and <tt class="docutils literal"><span class="pre">&gt;</span></tt> to <tt class="docutils literal"><span class="pre">&amp;gt;</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the inserted object provides an <tt class="docutils literal"><span class="pre">__html__</span></tt> method, that method is called with the result inserted as structure. This feature is not implemented by ZPT.</p>
</div>
<p>If the expression evaluates to <tt class="docutils literal"><span class="pre">None</span></tt>, the element is simply removed. If the value is <tt class="docutils literal"><span class="pre">default</span></tt>, then the element is left unchanged.</p>
</div>
<div class="section" id="id26">
<h5>Examples<a class="headerlink" href="#id26" title="Permalink to this headline">¶</a></h5>
<p>Inserting a title:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><span</span> <span class="na">tal:replace=</span><span class="s">"context.title"</span><span class="nt">></span>Title<span class="nt"></span></span>
</pre></div>
</div>
<p>Inserting HTML/XML:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:replace=</span><span class="s">"structure table"</span> <span class="nt">/></span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="section" id="expressions-tales">
<span id="tales"></span><h2>Expressions (TALES)<a class="headerlink" href="#expressions-tales" title="Permalink to this headline">¶</a></h2>
<p>The <em>Template Attribute Language Expression Syntax</em> (TALES) standard
describes expressions that supply <a class="reference internal" href="#tal"><em>Basics (TAL)</em></a> and
<a class="reference internal" href="#metal"><em>Macros (METAL)</em></a> with data. TALES is <em>one</em> possible expression
syntax for these languages, but they are not bound to this definition.
Similarly, TALES could be used in a context having nothing to do with
TAL or METAL.</p>
<p>TALES expressions are described below with any delimiter or quote
markup from higher language layers removed. Here is the basic
definition of TALES syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>Expression ::= [type_prefix ':'] String
type_prefix ::= Name
</pre></div>
</div>
<p>Here are some simple examples:</p>
<div class="highlight-xml"><div class="highlight"><pre>1 + 2
None
string:Hello, ${view.user_name}
</pre></div>
</div>
<p>The optional <em>type prefix</em> determines the semantics and syntax of the
<em>expression string</em> that follows it. A given implementation of TALES
can define any number of expression types, with whatever syntax you
like. It also determines which expression type is indicated by
omitting the prefix.</p>
<div class="section" id="types">
<h3>Types<a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
<p>These are the available TALES expression types:</p>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="96%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Prefix</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">exists</span></tt></td>
<td>Evaluate the result inside an exception handler; if one of the exceptions <tt class="docutils literal"><span class="pre">AttributeError</span></tt>, <tt class="docutils literal"><span class="pre">LookupError</span></tt>, <tt class="docutils literal"><span class="pre">TypeError</span></tt>, <tt class="docutils literal"><span class="pre">NameError</span></tt>, or <tt class="docutils literal"><span class="pre">KeyError</span></tt> is raised during evaluation, the result is <tt class="docutils literal"><span class="pre">False</span></tt>, otherwise <tt class="docutils literal"><span class="pre">True</span></tt>. Note that the original result is discarded in any case.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">import</span></tt></td>
<td>Import a global symbol using dotted notation.</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">load</span></tt></td>
<td>Load a template relative to the current template or absolute.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">not</span></tt></td>
<td>Negate the expression result</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">python</span></tt></td>
<td>Evaluate a Python expression</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">string</span></tt></td>
<td>Format a string</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">structure</span></tt></td>
<td>Wraps the expression result as <em>structure</em>.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The default expression type is <tt class="docutils literal"><span class="pre">python</span></tt>.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The Zope reference engine defaults to a <tt class="docutils literal"><span class="pre">path</span></tt>
expression type, which is closely tied to the Zope
framework. This expression is not implemented in
Chameleon (but it’s available in a Zope framework
compatibility package).</p>
</div>
<p>There’s a mechanism to allow fallback to alternative expressions, if
one should fail (raise an exception). The pipe character (‘|’) is used
to separate two expressions:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:define=</span><span class="s">"page request.GET['page'] | 0"</span><span class="nt">></span>
</pre></div>
</div>
<p>This mechanism applies only to the <tt class="docutils literal"><span class="pre">python</span></tt> expression type, and by
derivation <tt class="docutils literal"><span class="pre">string</span></tt>.</p>
<div class="section" id="python">
<span id="tales-built-in-names"></span><h4><tt class="docutils literal"><span class="pre">python</span></tt><a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h4>
<p>Evaluates a Python expression.</p>
<div class="section" id="id27">
<h5>Syntax<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h5>
<p>Python expression syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>Any valid Python language expression
</pre></div>
</div>
</div>
<div class="section" id="id28">
<h5>Description<a class="headerlink" href="#id28" title="Permalink to this headline">¶</a></h5>
<p>Python expressions are executed natively within the translated
template source code. There is no built-in security apparatus.</p>
</div>
</div>
<div class="section" id="string">
<h4><tt class="docutils literal"><span class="pre">string</span></tt><a class="headerlink" href="#string" title="Permalink to this headline">¶</a></h4>
<div class="section" id="id29">
<h5>Syntax<a class="headerlink" href="#id29" title="Permalink to this headline">¶</a></h5>
<p>String expression syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>string_expression ::= ( plain_string | [ varsub ] )*
varsub ::= ( '$' Variable ) | ( '${ Expression }' )
plain_string ::= ( '$$' | non_dollar )*
non_dollar ::= any character except '$'
</pre></div>
</div>
</div>
<div class="section" id="id30">
<h5>Description<a class="headerlink" href="#id30" title="Permalink to this headline">¶</a></h5>
<p>String expressions interpret the expression string as text. If no
expression string is supplied the resulting string is <em>empty</em>. The
string can contain variable substitutions of the form <tt class="docutils literal"><span class="pre">$name</span></tt> or
<tt class="docutils literal"><span class="pre">${expression}</span></tt>, where <tt class="docutils literal"><span class="pre">name</span></tt> is a variable name, and <tt class="docutils literal"><span class="pre">expression</span></tt> is a TALES-expression. The escaped string value of the expression is inserted into the string.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To prevent a <tt class="docutils literal"><span class="pre">$</span></tt> from being interpreted this
way, it must be escaped as <tt class="docutils literal"><span class="pre">$$</span></tt>.</p>
</div>
</div>
<div class="section" id="id31">
<h5>Examples<a class="headerlink" href="#id31" title="Permalink to this headline">¶</a></h5>
<p>Basic string formatting:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><span</span> <span class="na">tal:replace=</span><span class="s">"string:$this and $that"</span><span class="nt">></span>
Spam and Eggs
<span class="nt"></span></span>
<span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"string:${request.form['total']}"</span><span class="nt">></span>
total: 12
<span class="nt"></p></span>
</pre></div>
</div>
<p>Including a dollar sign:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">tal:content=</span><span class="s">"string:$$$cost"</span><span class="nt">></span>
cost: $42.00
<span class="nt"></p></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="import">
<span id="import-expression"></span><h4><tt class="docutils literal"><span class="pre">import</span></tt><a class="headerlink" href="#import" title="Permalink to this headline">¶</a></h4>
<p>Imports a module global.</p>
</div>
<div class="section" id="structure">
<span id="structure-expression"></span><h4><tt class="docutils literal"><span class="pre">structure</span></tt><a class="headerlink" href="#structure" title="Permalink to this headline">¶</a></h4>
<p>Wraps the expression result as <em>structure</em>: The replacement text is
inserted into the document without escaping, allowing HTML/XML markup
to be inserted. This can break your page if the text contains
unanticipated markup (eg. text submitted via a web form), which is
the reason that it is not the default.</p>
</div>
<div class="section" id="load">
<span id="load-expression"></span><h4><tt class="docutils literal"><span class="pre">load</span></tt><a class="headerlink" href="#load" title="Permalink to this headline">¶</a></h4>
<p>Loads a template instance.</p>
<div class="section" id="id32">
<h5>Syntax<a class="headerlink" href="#id32" title="Permalink to this headline">¶</a></h5>
<p>Load expression syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>Relative or absolute file path
</pre></div>
</div>
</div>
<div class="section" id="id33">
<h5>Description<a class="headerlink" href="#id33" title="Permalink to this headline">¶</a></h5>
<p>The template will be loaded using the same template class as the
calling template.</p>
</div>
<div class="section" id="id34">
<h5>Examples<a class="headerlink" href="#id34" title="Permalink to this headline">¶</a></h5>
<p>Loading a template and using it as a macro:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:define=</span><span class="s">"master load: ../master.pt"</span> <span class="na">metal:use-macro=</span><span class="s">"master"</span> <span class="nt">/></span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="built-in-names">
<h3>Built-in names<a class="headerlink" href="#built-in-names" title="Permalink to this headline">¶</a></h3>
<p>These are the names always available in the TALES expression namespace:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">default</span></tt> - special value used to specify that existing text or attributes should not be replaced. See the documentation for individual TAL statements for details on how they interpret <em>default</em>.</li>
<li><tt class="docutils literal"><span class="pre">repeat</span></tt> - the <em>repeat</em> variables; see <a class="reference internal" href="#tal-repeat"><em>tal:repeat</em></a> for more
information.</li>
<li><tt class="docutils literal"><span class="pre">template</span></tt> - reference to the template which was first called; this symbol is carried over when using macros.</li>
<li><tt class="docutils literal"><span class="pre">macros</span></tt> - reference to the macros dictionary that corresponds to the current template.</li>
</ul>
</div>
</div>
<div class="section" id="macros-metal">
<span id="metal"></span><h2>Macros (METAL)<a class="headerlink" href="#macros-metal" title="Permalink to this headline">¶</a></h2>
<p>The <em>Macro Expansion Template Attribute Language</em> (METAL) standard is
a facility for HTML/XML macro preprocessing. It can be used in
conjunction with or independently of TAL and TALES.</p>
<p>Macros provide a way to define a chunk of presentation in one
template, and share it in others, so that changes to the macro are
immediately reflected in all of the places that share it.
Additionally, macros are always fully expanded, even in a template’s
source text, so that the template appears very similar to its final
rendering.</p>
<p>A single Page Template can accomodate multiple macros.</p>
<div class="section" id="namespace">
<h3>Namespace<a class="headerlink" href="#namespace" title="Permalink to this headline">¶</a></h3>
<p>The METAL namespace URI and recommended alias are currently defined
as:</p>
<div class="highlight-xml"><div class="highlight"><pre>xmlns:metal="http://xml.zope.org/namespaces/metal"
</pre></div>
</div>
<p>Just like the TAL namespace URI, this URI is not attached to a web
page; it’s just a unique identifier. This identifier must be used in
all templates which use METAL.</p>
</div>
<div class="section" id="id35">
<h3>Statements<a class="headerlink" href="#id35" title="Permalink to this headline">¶</a></h3>
<p>METAL defines a number of statements:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">metal:define-macro</span></tt> Define a macro.</li>
<li><tt class="docutils literal"><span class="pre">metal:use-macro</span></tt> Use a macro.</li>
<li><tt class="docutils literal"><span class="pre">metal:extend-macro</span></tt> Extend a macro.</li>
<li><tt class="docutils literal"><span class="pre">metal:define-slot</span></tt> Define a macro customization point.</li>
<li><tt class="docutils literal"><span class="pre">metal:fill-slot</span></tt> Customize a macro.</li>
</ul>
<p>Although METAL does not define the syntax of expression non-terminals,
leaving that up to the implementation, a canonical expression syntax
for use in METAL arguments is described in TALES Specification.</p>
<div class="section" id="define-macro">
<h4><tt class="docutils literal"><span class="pre">define-macro</span></tt><a class="headerlink" href="#define-macro" title="Permalink to this headline">¶</a></h4>
<p>Defines a macro.</p>
<div class="section" id="id36">
<h5>Syntax<a class="headerlink" href="#id36" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">metal:define-macro</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= Name
</pre></div>
</div>
</div>
<div class="section" id="id37">
<h5>Description<a class="headerlink" href="#id37" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">metal:define-macro</span></tt> statement defines a macro. The macro is named
by the statement expression, and is defined as the element and its
sub-tree.</p>
</div>
<div class="section" id="id38">
<h5>Examples<a class="headerlink" href="#id38" title="Permalink to this headline">¶</a></h5>
<p>Simple macro definition:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">metal:define-macro=</span><span class="s">"copyright"</span><span class="nt">></span>
Copyright 2011, <span class="nt"><em></span>Foobar<span class="nt"></em></span> Inc.
<span class="nt"></p></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="define-slot">
<h4><tt class="docutils literal"><span class="pre">define-slot</span></tt><a class="headerlink" href="#define-slot" title="Permalink to this headline">¶</a></h4>
<p>Defines a macro customization point.</p>
<div class="section" id="id39">
<h5>Syntax<a class="headerlink" href="#id39" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">metal:define-slot</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= Name
</pre></div>
</div>
</div>
<div class="section" id="id40">
<h5>Description<a class="headerlink" href="#id40" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">metal:define-slot</span></tt> statement defines a macro customization
point or <em>slot</em>. When a macro is used, its slots can be replaced, in
order to customize the macro. Slot definitions provide default content
for the slot. You will get the default slot contents if you decide not
to customize the macro when using it.</p>
<p>The <tt class="docutils literal"><span class="pre">metal:define-slot</span></tt> statement must be used inside a
<tt class="docutils literal"><span class="pre">metal:define-macro</span></tt> statement.</p>
<p>Slot names must be unique within a macro.</p>
</div>
<div class="section" id="id41">
<h5>Examples<a class="headerlink" href="#id41" title="Permalink to this headline">¶</a></h5>
<p>Simple macro with slot:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">metal:define-macro=</span><span class="s">"hello"</span><span class="nt">></span>
Hello <span class="nt"><b</span> <span class="na">metal:define-slot=</span><span class="s">"name"</span><span class="nt">></span>World<span class="nt"></b></span>
<span class="nt"></p></span>
</pre></div>
</div>
<p>This example defines a macro with one slot named <tt class="docutils literal"><span class="pre">name</span></tt>. When you use
this macro you can customize the <tt class="docutils literal"><span class="pre">b</span></tt> element by filling the <tt class="docutils literal"><span class="pre">name</span></tt>
slot.</p>
</div>
</div>
<div class="section" id="fill-slot">
<h4><tt class="docutils literal"><span class="pre">fill-slot</span></tt><a class="headerlink" href="#fill-slot" title="Permalink to this headline">¶</a></h4>
<p>Customize a macro.</p>
<div class="section" id="id42">
<h5>Syntax<a class="headerlink" href="#id42" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">metal:fill-slot</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= Name
</pre></div>
</div>
</div>
<div class="section" id="id43">
<h5>Description<a class="headerlink" href="#id43" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">metal:fill-slot</span></tt> statement customizes a macro by replacing a
<em>slot</em> in the macro with the statement element (and its content).</p>
<p>The <tt class="docutils literal"><span class="pre">metal:fill-slot</span></tt> statement must be used inside a
<tt class="docutils literal"><span class="pre">metal:use-macro</span></tt> statement.</p>
<p>Slot names must be unique within a macro.</p>
<p>If the named slot does not exist within the macro, the slot
contents will be silently dropped.</p>
</div>
<div class="section" id="id44">
<h5>Examples<a class="headerlink" href="#id44" title="Permalink to this headline">¶</a></h5>
<p>Given this macro:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">metal:define-macro=</span><span class="s">"hello"</span><span class="nt">></span>
Hello <span class="nt"><b</span> <span class="na">metal:define-slot=</span><span class="s">"name"</span><span class="nt">></span>World<span class="nt"></b></span>
<span class="nt"></p></span>
</pre></div>
</div>
<p>You can fill the <tt class="docutils literal"><span class="pre">name</span></tt> slot like so:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><p</span> <span class="na">metal:use-macro=</span><span class="s">"container['master.html'].macros.hello"</span><span class="nt">></span>
Hello <span class="nt"><b</span> <span class="na">metal:fill-slot=</span><span class="s">"name"</span><span class="nt">></span>Kevin Bacon<span class="nt"></b></span>
<span class="nt"></p></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="use-macro">
<h4><tt class="docutils literal"><span class="pre">use-macro</span></tt><a class="headerlink" href="#use-macro" title="Permalink to this headline">¶</a></h4>
<p>Use a macro.</p>
<div class="section" id="id45">
<h5>Syntax<a class="headerlink" href="#id45" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">metal:use-macro</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= expression
</pre></div>
</div>
</div>
<div class="section" id="id46">
<h5>Description<a class="headerlink" href="#id46" title="Permalink to this headline">¶</a></h5>
<p>The <tt class="docutils literal"><span class="pre">metal:use-macro</span></tt> statement replaces the statement element with
a macro. The statement expression describes a macro definition.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In Chameleon the expression may point to a template instance; in this case it will be rendered in its entirety.</p>
</div>
</div>
</div>
<div class="section" id="extend-macro">
<h4><tt class="docutils literal"><span class="pre">extend-macro</span></tt><a class="headerlink" href="#extend-macro" title="Permalink to this headline">¶</a></h4>
<p>Extends a macro.</p>
<div class="section" id="id47">
<h5>Syntax<a class="headerlink" href="#id47" title="Permalink to this headline">¶</a></h5>
<p><tt class="docutils literal"><span class="pre">metal:extend-macro</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre>argument ::= expression
</pre></div>
</div>
</div>
<div class="section" id="id48">
<h5>Description<a class="headerlink" href="#id48" title="Permalink to this headline">¶</a></h5>
<p>To extend an existing macro, choose a name for the macro and add a
define-macro attribute to a document element with the name as the
argument. Add an extend-macro attribute to the document element with
an expression referencing the base macro as the argument. The
extend-macro must be used in conjunction with define-macro, and must
not be used with use-macro. The element’s subtree is the macro
body.</p>
</div>
<div class="section" id="id49">
<h5>Examples<a class="headerlink" href="#id49" title="Permalink to this headline">¶</a></h5>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">metal:define-macro=</span><span class="s">"page-header"</span>
<span class="na">metal:extend-macro=</span><span class="s">"standard_macros['page-header']"</span><span class="nt">></span>
<span class="nt"><div</span> <span class="na">metal:fill-slot=</span><span class="s">"breadcrumbs"</span><span class="nt">></span>
You are here:
<span class="nt"><div</span> <span class="na">metal:define-slot=</span><span class="s">"breadcrumbs"</span><span class="nt">/></span>
<span class="nt"></div></span>
<span class="nt"></div></span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="section" id="translation-i18n">
<span id="i18n"></span><h2>Translation (I18N)<a class="headerlink" href="#translation-i18n" title="Permalink to this headline">¶</a></h2>
<p>Translation of template contents and attributes is supported via the
<tt class="docutils literal"><span class="pre">i18n</span></tt> namespace and message objects.</p>
<div class="section" id="messages">
<h3>Messages<a class="headerlink" href="#messages" title="Permalink to this headline">¶</a></h3>
<p>The translation machinery defines a message as <em>any object</em> which is
not a string or a number and which does not provide an <tt class="docutils literal"><span class="pre">__html__</span></tt>
method.</p>
<p>When any such object is inserted into the template, the translate
function is invoked first to see if it needs translation. The result
is always coerced to a native string before it’s inserted into the
template.</p>
</div>
<div class="section" id="translation-function">
<h3>Translation function<a class="headerlink" href="#translation-function" title="Permalink to this headline">¶</a></h3>
<p>The simplest way to hook into the translation machinery is to provide
a translation function to the template constructor or at
render-time. In either case it should be passed as the keyword
argument <tt class="docutils literal"><span class="pre">translate</span></tt>.</p>
<p>The function has the following signature:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">translate</span><span class="p">(</span><span class="n">msgid</span><span class="p">,</span> <span class="n">domain</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">mapping</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">context</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">target_language</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The result should be a string or <tt class="docutils literal"><span class="pre">None</span></tt>. If another type of object
is returned, it’s automatically coerced into a string.</p>
<p>If <a class="reference external" href="http://pypi.python.org/pypi/zope.i18n">zope.i18n</a> is available,
the translation machinery defaults to using its translation
function. Note that this function requires messages to conform to the
message class from <a class="reference external" href="http://pypi.python.org/pypi/zope.i18nmessageid">zope.i18nmessageid</a>; specifically,
messages must have attributes <tt class="docutils literal"><span class="pre">domain</span></tt>, <tt class="docutils literal"><span class="pre">mapping</span></tt> and
<tt class="docutils literal"><span class="pre">default</span></tt>. Example use:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">zope.i18nmessageid</span> <span class="kn">import</span> <span class="n">MessageFactory</span>
<span class="n">_</span> <span class="o">=</span> <span class="n">MessageFactory</span><span class="p">(</span><span class="s">"food"</span><span class="p">)</span>
<span class="n">apple</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s">u"Apple"</span><span class="p">)</span>
</pre></div>
</div>
<p>There’s currently no further support for other translation frameworks.</p>
</div>
<div class="section" id="using-zope-s-translation-framework">
<h3>Using Zope’s translation framework<a class="headerlink" href="#using-zope-s-translation-framework" title="Permalink to this headline">¶</a></h3>
<p>The translation function from <tt class="docutils literal"><span class="pre">zope.i18n</span></tt> relies on <em>translation
domains</em> to provide translations.</p>
<p>These are components that are registered for some translation domain
identifier and which implement a <tt class="docutils literal"><span class="pre">translate</span></tt> method that translates
messages for that domain.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To register translation domain components, the Zope Component Architecture must be used (see <a class="reference external" href="http://pypi.python.org/pypi/zope.component">zope.component</a>).</p>
</div>
<p>The easiest way to configure translation domains is to use the the
<tt class="docutils literal"><span class="pre">registerTranslations</span></tt> ZCML-directive; this requires the use of the
<a class="reference external" href="http://pypi.python.org/pypi/zope.configuration">zope.configuration</a>
package. This will set up translation domains and gettext catalogs
automatically:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><configure</span> <span class="na">xmlns=</span><span class="s">"http://namespaces.zope.org/zope"</span>
<span class="na">xmlns:i18n=</span><span class="s">"http://xml.zope.org/namespaces/i18n"</span><span class="nt">></span>
<span class="nt"><i18n:registerTranslations</span> <span class="na">directory=</span><span class="s">"locales"</span> <span class="nt">/></span>
<span class="nt"></configure></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">./locales</span></tt> directory must follow a particular directory
structure:</p>
<div class="highlight-bash"><div class="highlight"><pre>./locales/en/LC_MESSAGES
./locales/de/LC_MESSAGES
...
</pre></div>
</div>
<p>In each of the <tt class="docutils literal"><span class="pre">LC_MESSAGES</span></tt> directories, one <a class="reference external" href="http://en.wikipedia.org/wiki/GNU_gettext">GNU gettext</a> file in the <tt class="docutils literal"><span class="pre">.po</span></tt>
format must be present per translation domain:</p>
<div class="highlight-po"><div class="highlight"><pre><span class="c1"># ./locales/de/LC_MESSAGES/food.po</span>
<span class="nv">msgid</span> <span class="s">""</span>
<span class="nv">msgstr</span> <span class="s">""</span>
<span class="s">"</span><span class="py">MIME-Version:</span><span class="s"> 1.0\n"</span>
<span class="s">"</span><span class="py">Content-Type:</span><span class="s"> text/plain; charset=UTF-8\n"</span>
<span class="s">"</span><span class="py">Content-Transfer-Encoding:</span><span class="s"> 8bit\n"</span>
<span class="nv">msgid</span> <span class="s">"Apple"</span>
<span class="nv">msgstr</span> <span class="s">"Apfel"</span>
</pre></div>
</div>
<p>It may be necessary to compile the message catalog using the
<tt class="docutils literal"><span class="pre">msgfmt</span></tt> utility. This will produce a <tt class="docutils literal"><span class="pre">.mo</span></tt> file.</p>
</div>
<div class="section" id="translation-domains-without-gettext">
<h3>Translation domains without gettext<a class="headerlink" href="#translation-domains-without-gettext" title="Permalink to this headline">¶</a></h3>
<p>The following example demonstrates how to manually set up and
configure a translation domain for which messages are provided
directly:</p>
<div class="highlight-xml"><div class="highlight"><pre>from zope import component
from zope.i18n.simpletranslationdomain import SimpleTranslationDomain
food = SimpleTranslationDomain("food", {
('de', u'Apple'): u'Apfel',
})
component.provideUtility(food, food.domain)
</pre></div>
</div>
<p>An example of a custom translation domain class:</p>
<div class="highlight-xml"><div class="highlight"><pre>from zope import interface
class TranslationDomain(object):
interface.implements(ITranslationDomain)
def translate(self, msgid, mapping=None, context=None,
target_language=None, default=None):
...
component.provideUtility(TranslationDomain(), name="custom")
</pre></div>
</div>
<p>This approach can be used to integrate other translation catalog
implementations.</p>
</div>
<div class="section" id="id50">
<h3>Namespace<a class="headerlink" href="#id50" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">i18n</span></tt> namespace URI and recommended prefix are currently
defined as:</p>
<div class="highlight-xml"><div class="highlight"><pre>xmlns:i18n="http://xml.zope.org/namespaces/i18n"
</pre></div>
</div>
<p>This is not a URL, but merely a unique identifier. Do not expect a
browser to resolve it successfully.</p>
</div>
<div class="section" id="id51">
<h3>Statements<a class="headerlink" href="#id51" title="Permalink to this headline">¶</a></h3>
<p>The allowable <tt class="docutils literal"><span class="pre">i18n</span></tt> statements are:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">i18n:translate</span></tt></li>
<li><tt class="docutils literal"><span class="pre">i18n:domain</span></tt></li>
<li><tt class="docutils literal"><span class="pre">i18n:source</span></tt></li>
<li><tt class="docutils literal"><span class="pre">i18n:target</span></tt></li>
<li><tt class="docutils literal"><span class="pre">i18n:name</span></tt></li>
<li><tt class="docutils literal"><span class="pre">i18n:attributes</span></tt></li>
<li><tt class="docutils literal"><span class="pre">i18n:data</span></tt></li>
</ul>
<div class="section" id="i18n-translate">
<h4><tt class="docutils literal"><span class="pre">i18n:translate</span></tt><a class="headerlink" href="#i18n-translate" title="Permalink to this headline">¶</a></h4>
<p>This attribute is used to mark units of text for translation. If this
attribute is specified with an empty string as the value, the message
ID is computed from the content of the element bearing this attribute.
Otherwise, the value of the element gives the message ID.</p>
</div>
<div class="section" id="i18n-domain">
<h4><tt class="docutils literal"><span class="pre">i18n:domain</span></tt><a class="headerlink" href="#i18n-domain" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">i18n:domain</span></tt> attribute is used to specify the domain to be used
to get the translation. If not specified, the translation services
will use a default domain. The value of the attribute is used
directly; it is not a TALES expression.</p>
</div>
<div class="section" id="i18n-source">
<h4><tt class="docutils literal"><span class="pre">i18n:source</span></tt><a class="headerlink" href="#i18n-source" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">i18n:source</span></tt> attribute specifies the language of the text to be
translated. The default is <tt class="docutils literal"><span class="pre">nothing</span></tt>, which means we don’t provide
this information to the translation services.</p>
</div>
<div class="section" id="i18n-target">
<h4><tt class="docutils literal"><span class="pre">i18n:target</span></tt><a class="headerlink" href="#i18n-target" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">i18n:target</span></tt> attribute specifies the language of the
translation we want to get. If the value is <tt class="docutils literal"><span class="pre">default</span></tt>, the language
negotiation services will be used to choose the destination language.
If the value is <tt class="docutils literal"><span class="pre">nothing</span></tt>, no translation will be performed; this
can be used to suppress translation within a larger translated unit.
Any other value must be a language code.</p>
<p>The attribute value is a TALES expression; the result of evaluating
the expression is the language code or one of the reserved values.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="docutils literal"><span class="pre">i18n:target</span></tt> is primarily used for hints to text
extraction tools and translation teams. If you had some text that
should only be translated to e.g. German, then it probably
shouldn’t be wrapped in an <tt class="docutils literal"><span class="pre">i18n:translate</span></tt> span.</p>
</div>
</div>
<div class="section" id="i18n-name">
<h4><tt class="docutils literal"><span class="pre">i18n:name</span></tt><a class="headerlink" href="#i18n-name" title="Permalink to this headline">¶</a></h4>
<p>Name the content of the current element for use in interpolation
within translated content. This allows a replaceable component in
content to be re-ordered by translation. For example:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><span</span> <span class="na">i18n:translate=</span><span class="s">''</span><span class="nt">></span>
<span class="nt"><span</span> <span class="na">tal:replace=</span><span class="s">'context.name'</span> <span class="na">i18n:name=</span><span class="s">'name'</span> <span class="nt">/></span> was born in
<span class="nt"><span</span> <span class="na">tal:replace=</span><span class="s">'context.country_of_birth'</span> <span class="na">i18n:name=</span><span class="s">'country'</span> <span class="nt">/></span>.
<span class="nt"></span></span>
</pre></div>
</div>
<p>would cause this text to be passed to the translation service:</p>
<div class="highlight-xml"><div class="highlight"><pre>"${name} was born in ${country}."
</pre></div>
</div>
</div>
<div class="section" id="i18n-attributes">
<h4><tt class="docutils literal"><span class="pre">i18n:attributes</span></tt><a class="headerlink" href="#i18n-attributes" title="Permalink to this headline">¶</a></h4>
<p>This attribute will allow us to translate attributes of HTML tags,
such as the <tt class="docutils literal"><span class="pre">alt</span></tt> attribute in the <tt class="docutils literal"><span class="pre">img</span></tt> tag. The
<tt class="docutils literal"><span class="pre">i18n:attributes</span></tt> attribute specifies a list of attributes to be
translated with optional message IDs for each; if multiple attribute
names are given, they must be separated by semicolons. Message IDs
used in this context must not include whitespace.</p>
<p>Note that the value of the particular attributes come either from the
HTML attribute value itself or from the data inserted by
<tt class="docutils literal"><span class="pre">tal:attributes</span></tt>.</p>
<p>If an attibute is to be both computed using <tt class="docutils literal"><span class="pre">tal:attributes</span></tt> and
translated, the translation service is passed the result of the TALES
expression for that attribute.</p>
<p>An example:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><img</span> <span class="na">src=</span><span class="s">"http://foo.com/logo"</span> <span class="na">alt=</span><span class="s">"Visit us"</span>
<span class="na">tal:attributes=</span><span class="s">"alt context.greeting"</span>
<span class="na">i18n:attributes=</span><span class="s">"alt"</span>
<span class="nt">></span>
</pre></div>
</div>
<p>In this example, we let <tt class="docutils literal"><span class="pre">tal:attributes</span></tt> set the value of the <tt class="docutils literal"><span class="pre">alt</span></tt>
attribute to the text “Stop by for a visit!”. This text will be
passed to the translation service, which uses the result of language
negotiation to translate “Stop by for a visit!” into the requested
language. The example text in the template, “Visit us”, will simply
be discarded.</p>
<p>Another example, with explicit message IDs:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><img</span> <span class="na">src=</span><span class="s">"../icons/uparrow.png"</span> <span class="na">alt=</span><span class="s">"Up"</span>
<span class="na">i18n:attributes=</span><span class="s">"src up-arrow-icon; alt up-arrow-alttext"</span>
<span class="nt">></span>
</pre></div>
</div>
<p>Here, the message ID <tt class="docutils literal"><span class="pre">up-arrow-icon</span></tt> will be used to generate the
link to an icon image file, and the message ID ‘up-arrow-alttext’ will
be used for the “alt” text.</p>
</div>
<div class="section" id="i18n-data">
<h4><tt class="docutils literal"><span class="pre">i18n:data</span></tt><a class="headerlink" href="#i18n-data" title="Permalink to this headline">¶</a></h4>
<p>Since TAL always returns strings, we need a way in ZPT to translate
objects, one of the most obvious cases being <tt class="docutils literal"><span class="pre">datetime</span></tt> objects. The
<tt class="docutils literal"><span class="pre">data</span></tt> attribute will allow us to specify such an object, and
<tt class="docutils literal"><span class="pre">i18n:translate</span></tt> will provide us with a legal format string for that
object. If <tt class="docutils literal"><span class="pre">data</span></tt> is used, <tt class="docutils literal"><span class="pre">i18n:translate</span></tt> must be used to give
an explicit message ID, rather than relying on a message ID computed
from the content.</p>
</div>
</div>
<div class="section" id="relation-with-tal-processing">
<h3>Relation with TAL processing<a class="headerlink" href="#relation-with-tal-processing" title="Permalink to this headline">¶</a></h3>
<p>The attributes defined in the <tt class="docutils literal"><span class="pre">i18n</span></tt> namespace modify the behavior
of the TAL interpreter for the <tt class="docutils literal"><span class="pre">tal:attributes</span></tt>, <tt class="docutils literal"><span class="pre">tal:content</span></tt>,
<tt class="docutils literal"><span class="pre">tal:repeat</span></tt>, and <tt class="docutils literal"><span class="pre">tal:replace</span></tt> attributes, but otherwise do not
affect TAL processing.</p>
<p>Since these attributes only affect TAL processing by causing
translations to occur at specific times, using these with a TAL
processor which does not support the <tt class="docutils literal"><span class="pre">i18n</span></tt> namespace degrades well;
the structural expectations for a template which uses the <tt class="docutils literal"><span class="pre">i18n</span></tt>
support is no different from those for a page which does not. The
only difference is that translations will not be performed in a legacy
processor.</p>
</div>
<div class="section" id="relation-with-metal-processing">
<h3>Relation with METAL processing<a class="headerlink" href="#relation-with-metal-processing" title="Permalink to this headline">¶</a></h3>
<p>When using translation with METAL macros, the internationalization
context is considered part of the specific documents that page
components are retrieved from rather than part of the combined page.
This makes the internationalization context lexical rather than
dynamic, making it easier for a site builder to understand the
behavior of each element with respect to internationalization.</p>
<p>Let’s look at an example to see what this means:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><html</span> <span class="na">i18n:translate=</span><span class="s">''</span> <span class="na">i18n:domain=</span><span class="s">'EventsCalendar'</span>
<span class="na">metal:use-macro=</span><span class="s">"container['master.html'].macros.thismonth"</span><span class="nt">></span>
<span class="nt"><div</span> <span class="na">metal:fill-slot=</span><span class="s">'additional-notes'</span><span class="nt">></span>
<span class="nt"><ol</span> <span class="na">tal:condition=</span><span class="s">"context.notes"</span><span class="nt">></span>
<span class="nt"><li</span> <span class="na">tal:repeat=</span><span class="s">"note context.notes"</span><span class="nt">></span>
<span class="nt"><tal:block</span> <span class="na">tal:omit-tag=</span><span class="s">""</span>
<span class="na">tal:condition=</span><span class="s">"note.heading"</span><span class="nt">></span>
<span class="nt"><strong</span> <span class="na">tal:content=</span><span class="s">"note.heading"</span><span class="nt">></span>
Note heading goes here
<span class="nt"></strong></span>
<span class="nt"><br</span> <span class="nt">/></span>
<span class="nt"></tal:block></span>
<span class="nt"><span</span> <span class="na">tal:replace=</span><span class="s">"note/description"</span><span class="nt">></span>
Some longer explanation for the note goes here.
<span class="nt"></span></span>
<span class="nt"></li></span>
<span class="nt"></ol></span>
<span class="nt"></div></span>
<span class="nt"></html></span>
</pre></div>
</div>
<p>And the macro source:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><html</span> <span class="na">i18n:domain=</span><span class="s">'CalendarService'</span><span class="nt">></span>
<span class="nt"><div</span> <span class="na">tal:replace=</span><span class="s">'python:DateTime().Month()'</span>
<span class="na">i18n:translate=</span><span class="s">''</span><span class="nt">></span>January<span class="nt"></div></span>
<span class="c"><!-- really hairy TAL code here ;-) --></span>
<span class="nt"><div</span> <span class="na">define-slot=</span><span class="s">"additional-notes"</span><span class="nt">></span>
Place for the application to add additional notes if desired.
<span class="nt"></div></span>
<span class="nt"></html></span>
</pre></div>
</div>
<p>Note that the macro is using a different domain than the application
(which it should be). With lexical scoping, no special markup needs
to be applied to cause the slot-filler in the application to be part
of the same domain as the rest of the application’s page components.
If dynamic scoping were used, the internationalization context would
need to be re-established in the slot-filler.</p>
</div>
<div class="section" id="extracting-translatable-message">
<h3>Extracting translatable message<a class="headerlink" href="#extracting-translatable-message" title="Permalink to this headline">¶</a></h3>
<p>Translators use <a class="reference external" href="http://www.gnu.org/software/hello/manual/gettext/PO-Files.html">PO files</a>
when translating messages. To create and update PO files you need to
do two things: <em>extract</em> all messages from python and templates files
and store them in a <tt class="docutils literal"><span class="pre">.pot</span></tt> file, and for each language <em>update</em> its
<tt class="docutils literal"><span class="pre">.po</span></tt> file. Chameleon facilitates this by providing extractors for
<a class="reference external" href="http://babel.edgewall.org/">Babel</a>. To use this you need modify
<tt class="docutils literal"><span class="pre">setup.py</span></tt>. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"mypackage"</span><span class="p">,</span>
<span class="n">install_requires</span> <span class="o">=</span> <span class="p">[</span>
<span class="s">"Babel"</span><span class="p">,</span>
<span class="p">],</span>
<span class="n">message_extractors</span> <span class="o">=</span> <span class="p">{</span> <span class="s">"src"</span><span class="p">:</span> <span class="p">[</span>
<span class="p">(</span><span class="s">"**.py"</span><span class="p">,</span> <span class="s">"chameleon_python"</span><span class="p">,</span> <span class="bp">None</span> <span class="p">),</span>
<span class="p">(</span><span class="s">"**.pt"</span><span class="p">,</span> <span class="s">"chameleon_xml"</span><span class="p">,</span> <span class="bp">None</span> <span class="p">),</span>
<span class="p">]},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This tells Babel to scan the <tt class="docutils literal"><span class="pre">src</span></tt> directory while using the
<tt class="docutils literal"><span class="pre">chameleon_python</span></tt> extractor for all <tt class="docutils literal"><span class="pre">.py</span></tt> files and the
<tt class="docutils literal"><span class="pre">chameleon_xml</span></tt> extractor for all <tt class="docutils literal"><span class="pre">.pt</span></tt> files.</p>
<p>You can now use Babel to manage your PO files:</p>
<div class="highlight-bash"><div class="highlight"><pre>python setup.py extract_messages --output-file<span class="o">=</span>i18n/mydomain.pot
python setup.py update_catalog <span class="se">\</span>
-l nl <span class="se">\</span>
-i i18n/mydomain.pot <span class="se">\</span>
-o i18n/nl/LC_MESSAGES/mydomain.po
python setup.py compile_catalog <span class="se">\</span>
--directory i18n --locale nl
</pre></div>
</div>
<p>You can also configure default options in a <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file. For example:</p>
<div class="highlight-xml"><div class="highlight"><pre>[compile_catalog]
domain = mydomain
directory = i18n
[extract_messages]
copyright_holder = Acme Inc.
output_file = i18n/mydomain.pot
charset = UTF-8
[init_catalog]
domain = mydomain
input_file = i18n/mydomain.pot
output_dir = i18n
[update_catalog]
domain = mydomain
input_file = i18n/mydomain.pot
output_dir = i18n
previous = true
</pre></div>
</div>
<p>You can now use the Babel commands directly:</p>
<div class="highlight-xml"><div class="highlight"><pre>python setup.py extract_messages
python setup.py update_catalog
python setup.py compile_catalog
</pre></div>
</div>
</div>
</div>
<div class="section" id="operator">
<h2>${...} operator<a class="headerlink" href="#operator" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">${...}</span></tt> notation is short-hand for text insertion. The
Python-expression inside the braces is evaluated and the result
included in the output (all inserted text is escaped by default):</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">id=</span><span class="s">"section-${index + 1}"</span><span class="nt">></span>
${content}
<span class="nt"></div></span>
</pre></div>
</div>
<p>To escape this behavior, prefix the notation with a backslash
character: <tt class="docutils literal"><span class="pre">\${...}</span></tt>.</p>
<p>Note that if an object implements the <tt class="docutils literal"><span class="pre">__html__</span></tt> method, the result
of this method will be inserted as-is (without XML escaping).</p>
</div>
<div class="section" id="code-blocks">
<h2>Code blocks<a class="headerlink" href="#code-blocks" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre"><?python</span> <span class="pre">...</span> <span class="pre">?></span></tt> notation allows you to embed Python code in
templates:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><div></span>
<span class="cp"><?python numbers = map(str, range(1, 10)) ?></span>
Please input a number from the range ${", ".join(numbers)}.
<span class="nt"></div></span>
</pre></div>
</div>
<p>The scope of name assignments is up to the nearest macro definition,
or the template, if macros are not used.</p>
<p>Note that code blocks can span multiple line and start on the next
line of where the processing instruction begins:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="cp"><?python</span>
<span class="cp"> foo = [1, 2, 3]</span>
<span class="cp">?></span>
</pre></div>
</div>
<p>You can use this to debug templates:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><div></span>
<span class="cp"><?python import pdb; pdb.set_trace() ?></span>
<span class="nt"></div></span>
</pre></div>
</div>
</div>
<div class="section" id="markup-comments">
<h2>Markup comments<a class="headerlink" href="#markup-comments" title="Permalink to this headline">¶</a></h2>
<p>You can apply the ”!” and ”?” modifiers to change how comments are
processed:</p>
<p>Drop</p>
<blockquote>
<div><tt class="docutils literal"><span class="pre"><!--!</span> <span class="pre">This</span> <span class="pre">comment</span> <span class="pre">will</span> <span class="pre">be</span> <span class="pre">dropped</span> <span class="pre">from</span> <span class="pre">output</span> <span class="pre">--></span></tt></div></blockquote>
<p>Verbatim</p>
<blockquote>
<div><p><tt class="docutils literal"><span class="pre"><!--?</span> <span class="pre">This</span> <span class="pre">comment</span> <span class="pre">will</span> <span class="pre">be</span> <span class="pre">included</span> <span class="pre">verbatim</span> <span class="pre">--></span></tt></p>
<p>That is, evaluation of <tt class="docutils literal"><span class="pre">${...}</span></tt> expressions is disabled if the
comment opens with the ”?” character.</p>
</div></blockquote>
</div>
<div class="section" id="language-extensions">
<span id="new-features"></span><h2>Language extensions<a class="headerlink" href="#language-extensions" title="Permalink to this headline">¶</a></h2>
<p>Chameleon extends the <em>page template</em> language with a new expression
types and language features. Some take inspiration from <a class="reference external" href="http://genshi.edgewall.org/">Genshi</a>.</p>
<blockquote>
<div><p><em>New expression types</em></p>
<blockquote>
<div><p>The <a class="reference internal" href="#structure-expression"><em>structure</em></a> expression wraps an
expression result as <em>structure</em>:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div></span>${structure: body.text}<span class="nt"></div></span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#import-expression"><em>import</em></a> expression imports module globals:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:define=</span><span class="s">"compile import: re.compile"</span><span class="nt">></span>
...
<span class="nt"></div></span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#load-expression"><em>load</em></a> expression loads templates
relative to the current template:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:define=</span><span class="s">"compile load: main.pt"</span><span class="nt">></span>
...
<span class="nt"></div></span>
</pre></div>
</div>
</div></blockquote>
<p><em>Tuple unpacking</em></p>
<blockquote>
<div><p>The <tt class="docutils literal"><span class="pre">tal:define</span></tt> and <tt class="docutils literal"><span class="pre">tal:repeat</span></tt> statements support tuple
unpacking:</p>
<div class="highlight-xml"><div class="highlight"><pre>tal:define="(a, b, c) [1, 2, 3]"
</pre></div>
</div>
<p>Extended <a class="reference external" href="http://www.python.org/dev/peps/pep-3132/">iterable unpacking</a> using the asterisk
character is not currently supported (even for versions of
Python that support it natively).</p>
</div></blockquote>
<p><em>Dictionary lookup as fallback after attribute error</em></p>
<blockquote>
<div><p>If attribute lookup (using the <tt class="docutils literal"><span class="pre">obj.<name></span></tt> syntax) raises an
<tt class="docutils literal"><span class="pre">AttributeError</span></tt> exception, a secondary lookup is attempted
using dictionary lookup — <tt class="docutils literal"><span class="pre">obj['<name>']</span></tt>.</p>
<p>Behind the scenes, this is done by rewriting all
attribute-lookups to a custom lookup call:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">lookup_attr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">key</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">return</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">key</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">AttributeError</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">get</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">__getitem__</span>
<span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">exc</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">return</span> <span class="n">get</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">exc</span>
</pre></div>
</div>
</div></blockquote>
<p><em>Inline string substitution</em></p>
<blockquote>
<div><p>In element attributes and in the text or tail of an element,
string expression interpolation is available using the
<tt class="docutils literal"><span class="pre">${...}</span></tt> syntax:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><span</span> <span class="na">class=</span><span class="s">"content-${item_type}"</span><span class="nt">></span>
${title or item_id}
<span class="nt"></span></span>
</pre></div>
</div>
</div></blockquote>
<p><em>Code blocks</em></p>
<blockquote>
<div><p>Using <tt class="docutils literal"><span class="pre"><?python</span> <span class="pre">...</span> <span class="pre">?></span></tt> notation, you can embed Python
statements in your templates:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><div></span>
<span class="cp"><?python numbers = map(str, range(1, 10)) ?></span>
Please input a number from the range ${", ".join(numbers)}.
<span class="nt"></div></span>
</pre></div>
</div>
</div></blockquote>
<p><em>Literal content</em></p>
<blockquote>
<div><p>While the <tt class="docutils literal"><span class="pre">tal:content</span></tt> and <tt class="docutils literal"><span class="pre">tal:repeat</span></tt> attributes both
support the <tt class="docutils literal"><span class="pre">structure</span></tt> keyword which inserts the content as
a literal (without XML-escape), an object may also provide an
<tt class="docutils literal"><span class="pre">__html__</span></tt> method to the same effect.</p>
<p>The result of the method will be inserted as <em>structure</em>.</p>
<p>This is particularly useful for content which is substituted
using the expression operator: <tt class="docutils literal"><span class="pre">"${...}"</span></tt> since the
<tt class="docutils literal"><span class="pre">structure</span></tt> keyword is not allowed here.</p>
</div></blockquote>
<p><em>Switch statement</em></p>
<blockquote>
<div>Two new attributes have been added: <tt class="docutils literal"><span class="pre">tal:switch</span></tt> and
<tt class="docutils literal"><span class="pre">tal:case</span></tt>. A case attribute works like a condition and only
allows content if the value matches that of the nearest parent
switch value.</div></blockquote>
</div></blockquote>
</div>
<div class="section" id="incompatibilities-and-differences">
<h2>Incompatibilities and differences<a class="headerlink" href="#incompatibilities-and-differences" title="Permalink to this headline">¶</a></h2>
<p>There are a number of incompatibilities and differences between the
Chameleon language implementation and the Zope reference
implementation (ZPT):</p>
<blockquote>
<div><p><em>Default expression</em></p>
<blockquote>
<div>The default expression type is Python.</div></blockquote>
<p><em>Template arguments</em></p>
<blockquote>
<div><p>Arguments passed by keyword to the render- or call method are
inserted directly into the template execution namespace. This is
different from ZPT where these are only available through the
<tt class="docutils literal"><span class="pre">options</span></tt> dictionary.</p>
<p>Zope:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:content=</span><span class="s">"options/title"</span> <span class="nt">/></span>
</pre></div>
</div>
<p>Chameleon:</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><div</span> <span class="na">tal:content=</span><span class="s">"title"</span> <span class="nt">/></span>
</pre></div>
</div>
</div></blockquote>
<p><em>Special symbols</em></p>
<blockquote>
<div>The <tt class="docutils literal"><span class="pre">CONTEXTS</span></tt> symbol is not available.</div></blockquote>
</div></blockquote>
<p>The <a class="reference external" href="http://pypi.python.org/pypi/z3c.pt">z3c.pt</a> package works as a
compatibility layer. The template classes in this package provide a
implementation which is fully compatible with ZPT.</p>
</div>
<div class="section" id="notes">
<h2>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h2>
<table class="docutils footnote" frame="void" id="id52" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id12">2</a>)</em> <p>This has been changed in 2.x. Previously, it was up to the
expression engine to parse the expression values including any
semicolons and since for instance Python-expressions can never
end in a semicolon, it was possible to clearly distinguish
between the different uses of the symbol, e.g.</p>
<div class="highlight-xml"><div class="highlight"><pre>tal:define="text 'Hello world; goodbye world'"
</pre></div>
</div>
<p>The semicolon appearing in the definition above is part of the
Python-expression simply because it makes the expression
valid. Meanwhile:</p>
<div class="highlight-xml"><div class="highlight"><pre>tal:define="text1 'Hello world'; text2 'goodbye world'"
</pre></div>
</div>
<p>The semicolon here must denote a second variable definition
because there is no valid Python-expression that includes it.</p>
<p>While this behavior works well in practice, it is incompatible
with the reference specification, and also blurs the interface
between the compiler and the expression engine. In 2.x we
therefore have to escape the semicolon by doubling it (as
defined by the specification):</p>
<div class="last highlight-xml"><div class="highlight"><pre>tal:define="text 'Hello world;; goodbye world'"
</pre></div>
</div>
</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Language Reference</a><ul>
<li><a class="reference internal" href="#syntax">Syntax</a></li>
<li><a class="reference internal" href="#basics-tal">Basics (TAL)</a><ul>
<li><a class="reference internal" href="#statements">Statements</a><ul>
<li><a class="reference internal" href="#tal-attributes"><tt class="docutils literal"><span class="pre">tal:attributes</span></tt></a></li>
<li><a class="reference internal" href="#tal-condition"><tt class="docutils literal"><span class="pre">tal:condition</span></tt></a></li>
<li><a class="reference internal" href="#tal-content"><tt class="docutils literal"><span class="pre">tal:content</span></tt></a></li>
<li><a class="reference internal" href="#tal-define"><tt class="docutils literal"><span class="pre">tal:define</span></tt></a></li>
<li><a class="reference internal" href="#tal-switch-and-tal-case"><tt class="docutils literal"><span class="pre">tal:switch</span></tt> and <tt class="docutils literal"><span class="pre">tal:case</span></tt></a></li>
<li><a class="reference internal" href="#tal-omit-tag"><tt class="docutils literal"><span class="pre">tal:omit-tag</span></tt></a></li>
<li><a class="reference internal" href="#tal-repeat"><tt class="docutils literal"><span class="pre">tal:repeat</span></tt></a></li>
<li><a class="reference internal" href="#tal-replace"><tt class="docutils literal"><span class="pre">tal:replace</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#expressions-tales">Expressions (TALES)</a><ul>
<li><a class="reference internal" href="#types">Types</a><ul>
<li><a class="reference internal" href="#python"><tt class="docutils literal"><span class="pre">python</span></tt></a></li>
<li><a class="reference internal" href="#string"><tt class="docutils literal"><span class="pre">string</span></tt></a></li>
<li><a class="reference internal" href="#import"><tt class="docutils literal"><span class="pre">import</span></tt></a></li>
<li><a class="reference internal" href="#structure"><tt class="docutils literal"><span class="pre">structure</span></tt></a></li>
<li><a class="reference internal" href="#load"><tt class="docutils literal"><span class="pre">load</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#built-in-names">Built-in names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#macros-metal">Macros (METAL)</a><ul>
<li><a class="reference internal" href="#namespace">Namespace</a></li>
<li><a class="reference internal" href="#id35">Statements</a><ul>
<li><a class="reference internal" href="#define-macro"><tt class="docutils literal"><span class="pre">define-macro</span></tt></a></li>
<li><a class="reference internal" href="#define-slot"><tt class="docutils literal"><span class="pre">define-slot</span></tt></a></li>
<li><a class="reference internal" href="#fill-slot"><tt class="docutils literal"><span class="pre">fill-slot</span></tt></a></li>
<li><a class="reference internal" href="#use-macro"><tt class="docutils literal"><span class="pre">use-macro</span></tt></a></li>
<li><a class="reference internal" href="#extend-macro"><tt class="docutils literal"><span class="pre">extend-macro</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#translation-i18n">Translation (I18N)</a><ul>
<li><a class="reference internal" href="#messages">Messages</a></li>
<li><a class="reference internal" href="#translation-function">Translation function</a></li>
<li><a class="reference internal" href="#using-zope-s-translation-framework">Using Zope’s translation framework</a></li>
<li><a class="reference internal" href="#translation-domains-without-gettext">Translation domains without gettext</a></li>
<li><a class="reference internal" href="#id50">Namespace</a></li>
<li><a class="reference internal" href="#id51">Statements</a><ul>
<li><a class="reference internal" href="#i18n-translate"><tt class="docutils literal"><span class="pre">i18n:translate</span></tt></a></li>
<li><a class="reference internal" href="#i18n-domain"><tt class="docutils literal"><span class="pre">i18n:domain</span></tt></a></li>
<li><a class="reference internal" href="#i18n-source"><tt class="docutils literal"><span class="pre">i18n:source</span></tt></a></li>
<li><a class="reference internal" href="#i18n-target"><tt class="docutils literal"><span class="pre">i18n:target</span></tt></a></li>
<li><a class="reference internal" href="#i18n-name"><tt class="docutils literal"><span class="pre">i18n:name</span></tt></a></li>
<li><a class="reference internal" href="#i18n-attributes"><tt class="docutils literal"><span class="pre">i18n:attributes</span></tt></a></li>
<li><a class="reference internal" href="#i18n-data"><tt class="docutils literal"><span class="pre">i18n:data</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#relation-with-tal-processing">Relation with TAL processing</a></li>
<li><a class="reference internal" href="#relation-with-metal-processing">Relation with METAL processing</a></li>
<li><a class="reference internal" href="#extracting-translatable-message">Extracting translatable message</a></li>
</ul>
</li>
<li><a class="reference internal" href="#operator">${...} operator</a></li>
<li><a class="reference internal" href="#code-blocks">Code blocks</a></li>
<li><a class="reference internal" href="#markup-comments">Markup comments</a></li>
<li><a class="reference internal" href="#language-extensions">Language extensions</a></li>
<li><a class="reference internal" href="#incompatibilities-and-differences">Incompatibilities and differences</a></li>
<li><a class="reference internal" href="#notes">Notes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="library.html"
title="previous chapter">Library Documentation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="integration.html"
title="next chapter">Integration</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/reference.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="integration.html" title="Integration"
>next</a> |</li>
<li class="right" >
<a href="library.html" title="Library Documentation"
>previous</a> |</li>
<li><a href="index.html">Chameleon 2.10 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008-2011 by Malthe Borch and the Repoze Community.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
