 |
 |
 |
plasTeX 2.0 — A Python Framework for Processing LaTeX Documents |  |
 |
 |
|
|
|
plasTeX 2.0 — A Python Framework for Processing LaTeX Documents | |
|
|
The Zope Page Template (ZPT) language is actually just a set of XML attributes that can be applied to markup of an DTD. These attributes tell the ZPT interpreter how to process the element. There are seven different attributes that you can use to direct the processing of an XML or HTML file (in order of evaluation): define, condition, repeat, content, replace, attributes, and omit-tag. These attributes are described in section . For a more complete description, see the official ZPT documentation at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/ZPT.stx.
The Template Attribute Language Expression Syntax (TALES) is used by the attribute language described in the next section. The TALES syntax is used to evaluate expressions based on objects in the template namespace. The results of these expressions can be used to define variables, produce output, or be used as booleans. There are also several operators used to modify the behavior or interpretation of an expression. The expressions and their modifiers are described below.
A “path” is the most basic form on an expression in ZPT. The basic form is shown below.
[path:]string [ | TALES expression ]
The path: operator is actually optional on all paths. Leaving it off makes no difference. The “string” in the above syntax is a ’/’ delimited string of names. Each name refers to a property of the previous name in the string. Properties can include attributes, methods, or keys in a dictionary. These properties can in turn have properties of their own. Some examples of paths are shown below.
# Access the parentNode attribute of chapter, then get its title chapter/parentNode/title # Get the key named 'foo' from the dictionary bar bar/foo # Call the title method on the string in the variable booktitle booktitle/title
It is possible to specify multiple paths separated by a pipe (|). These paths are evaluated from left to right. The first one to return a non-None value is used.
# Look for the title on the current chapter node as well as its parents chapter/title | chapter/parentNode/title | chapter/parentNode/parentNode/title # Look for the value of the option otherwise get its default value myoptions/encoding | myoptions/defaultencoding
There are a few keywords that can be used in place of a path in a TALES expression as well.
Name |
Purpose |
nothing |
same as None in Python |
default |
keeps whatever the existing value of the element or attribute is |
options |
dictionary of values passed in to the template when instatiated |
repeat |
|
attrs |
dictonary of the original attributes of the element |
CONTEXTS |
dictionary containing all of the above |
This operator returns true if the path exists. If the path does not exist, the operator returns false. The syntax is as follows.
exists:path
The “path” in the code above is a path as described in section . This operator is commonly combined with the not: operator.
By default, if a property that is retrieved is callable, it will be called automatically. Using the nocall: operator, prevents this execution from happening. The syntax is shown below.
nocall:path
The not: operator simply negates the boolean result of the path. If the path is a boolean true, the not: operator will return false, and vice versa. The syntax is shown below.
not:path
The string: operator allows you to combine literal strings and paths into one string. Paths are inserted into the literal string using a syntax much like that of Python Templates: $path or ${path}. The general syntax is:
string:text
Here are some examples of using the string: operator.
string:Next - ${section/links/next}
string:($pagenumber)
string:[${figure/number}] ${figure/caption}
The python: operator allows you to evaluate a Python expression. The syntax is as follows.
python:python-code
The “python-code” in the expression above can include any of the Python built-in functions and operators as well as four new functions that correspond to the TALES operators: path, string, exists, and nocall. Each of these functions takes a string containing the path to be evaluated (e.g. path(’foo/bar’), exists(’chapter/title’), etc.).
When using Python operators, you must escape any characters that would not be legal in an XML/HTML document (i.e. <>&). For example, to write an expression to test if a number was less than or greater than two numbers, you would need to do something like the following example.
# See if the figure number is less than 2 or greater than 4
python: path('figure/number') < 2 or path('figure/number') > 4
The stripped: operator only exists in the SimpleTAL distribution provided by plasTeX. It evaluates the given path and removes any markup from that path. Essentially, it is a way to get a plain text representation of the path. The syntax is as follows.
stripped:path
The tal:define attribute allows you to define a variable for use later in the template. Variables can be specifies as local (only for use in the scope of the current element) or global (for use anywhere in the template). The syntax of the define attribute is shown below.
tal:define="[ local | global ] name expression [; define-expression ]"
The define attributes sets the value of “name” to “expression.” By default, the scope of the variable is local, but can be specified as global by including the “global” keyword before the name of the variable. As shown in the grammar above, you can specify multiple variables in one tal:define attribute by separating the define expressions by semi-colons.
Examples of using the tal:define attribute are shown belaw.
<p tal:define="global title document/title;
next self/links/next;
previous self/links/previous;
length python:len(self);
up string:Up - ${self/links/up}">
...
</p>
The tal:condition attribute allows you to conditionally include an element. The syntax is shown below.
tal:condition="expression"
The tal:condition attribute is very simple. If the expression evaluates to true, the element and its children will be evaluated and included in the output. If the expression evaluates to false, the element and its children will not be evaluated or included in the output. Valid expressions for the tal:condition attribute are the same as those for the expressions in the tal:define attribute.
<p tal:condition="python:len(self)">
<b tal:condition="self/caption">Caption for paragraph</b>
...
</p>
The tal:repeat attribute allows you to repeat an element multiple times; the syntax is shown below.
tal:repeat="name expression"
When the tal:repeat attribute is used on an element, the result of“expression” is iterated over, and a new element is generated for each item in the iteration. The value of the current item is set to “name” much like in the tal:define attribute.
Within the scope of the repeated element, another variable is available: repeat . This variable contains several properties related to the loop.
Name |
Purpose |
index |
number of the current iteration starting from zero |
number |
number of the current iteration starting from one |
even |
is true if the iteration number is even |
odd |
is true if the iteration number is odd |
start |
is true if this is the first iteration |
end |
is true if this is the last iteration; This is never true if the repeat expression returns an iterator |
length |
the length of the sequence being iterated over; This is set to sys.maxint for iterators. |
letter |
lower case letter corresponding to the current iteration number starting with ’a’ |
Letter |
upper case letter corresponding to the current iteration number starting with ’A’ |
roman |
lower case Roman numeral corresponding to the current iteration number starting with ’i’ |
Roman |
upper case Roman numeral corresponding to the current iteration number starting with ’I’ |
To access the properties listed above, you must use the property of the repeat variable that corresponds to the repeat variable name. For example, if your repeat variable name is “item”, you would access the above variables using the expressions repeat/item/index , repeat/item/number , repeat/item/even , etc.
A simple example of the tal:repeat attribute is shown below.
<ol> <li tal:repeat="option options" tal:content="option/name">option name</li> </ol>
One commonly used feature of rendering tables is alternating row colors. This is a little bit tricky with ZPT since the tal:condition attribute is evaluated before the tal:repeat directive. You can get around this by using the metal: namespace. This is the namespace used by ZPT’s macro language1 You can create another element around the element you want to be conditional. This wrapper element is simply there to do the iterating, but is not included in the output. The example below shows how to do alternating row colors in an HTML table.
<table>
<metal:block tal:repeat="employee employees">
<!-- even rows -->
<tr tal:condition="repeat/employee/even" style="background-color: white">
<td tal:content="employee/name"></td>
<td tal:content="employee/title"></td>
</tr>
<!-- odd rows -->
<tr tal:condition="repeat/employee/odd" style="background-color: gray">
<td tal:content="employee/name"></td>
<td tal:content="employee/title"></td>
</tr>
</metal:block>
</table>
The tal:content attribute evaluates an expression and replaces the content of the element with the result of the expression. The syntax is shown below.
tal:content="[ text | structure ] expression"
The text and structure options in the tal:content attribute indicate whether or not the content returned by the expression should be escaped (i.e. "&<> replaced by ", &, <, and >, respectively). When the text option is used, these special characters are escaped; this is the default behavior. When the structure option is specified, the result of the expression is assumed to be valid markup and is not escaped.
In SimpleTAL, the default behavior is the same as using the text option. However, in plasTeX, 99.9% of the time the content returned by the expression is valid markup, so the default was changed to structure in the SimpleTAL package distributed with plasTeX.
The tal:replace attribute is much like the tal:content attribute. They both evaluate an expression and include the content of that expression in the output, and they both have a text and structure option to indicate escaping of special characters. The difference is that when the tal:replace attribute is used, the element with the tal:replace attribute on it is not included in the output. Only the content of the evaluated expression is returned. The syntax of the tal:replace attribute is shown below.
tal:replace="[ text | structure ] expression"
The tal:attributes attribute allows you to programatically create attributes on the element. The syntax is shown below.
tal:attributes="name expression [; attribute-expression ]"
The syntax of the tal:attributes attribute is very similar to that of the tal:define attribute. However, in the case of the tal:attributes attribute, the name is the name of the attribute to be created on the element and the expression is evaluated to get the value of the attribute. If an error occurs or None is returned by the expression, then the attribute is removed from the element.
Just as in the case of the tal:define attribute, you can specify multiple attributes separated by semi-colons (;). If a semi-colon character is needed in the expression, then it must be represented by a double semi-colon (;;).
An example of using the tal:attributes is shown below.
<a tal:attributes="href self/links/next/url;
title self/links/next/title">link text</a>
The tal:omit-tag attribute allows you to conditionally omit an element. The syntax is shown below.
tal:omit-tag="expression"
If the value of “expression” evaluates to true (or is empty), the element is omitted; however, the content of the element is still sent to the output. If the expression evaluates to false, the element is included in the output.
Footnotes
|
|
|
plasTeX 2.0 — A Python Framework for Processing LaTeX Documents | |
|
|