The Zope Book by Michel Pelletier and Amos Latteier ISBN 0735711372 (Covers Zope 2.5)
Zope.org | Book Status | Buy The Book | Download PDF | Download HTML | Microsoft HTML Help
The contents of this book are licensed under the Open Publication License v1.0 without any options Appendix C: Zope Page Templates Reference

Appendix C: Zope Page Templates Reference

Zope Page Templates are an HTML/XML generation tool. This appendix is a reference to Zope Page Templates standards: Tag Attribute Language (TAL), TAL Expression Syntax (TALES), and Macro Expansion TAL (METAL).

 Comment

TAL Overview

The Template Attribute Language (TAL) standard is an attribute language used to create dynamic templates. It allows elements of a document to be replaced, repeated, or omitted.

 Comment

The statements of TAL are XML attributes from the TAL namespace. These attributes can be applied to an XML or HTML document in order to make it act as a template.

 Comment

A TAL statement has a name (the attribute name) and a body (the attribute value). For example, an content statement might look like tal:content="string:Hello". The element on which a statement is defined is its statement element. Most TAL statements require expressions, but the syntax and semantics of these expressions are not part of TAL. TALES is recommended for this purpose.

Anonymous User - June 28, 2002 11:20 am:
 this should probably read:
 "a content statement"
 Comment

TAL Namespace

The TAL namespace URI and recommended alias are currently defined as:


xmlns:tal="http://xml.zope.org/namespaces/tal"


 Comment

This is not a URL, but merely a unique identifier. Do not expect a browser to resolve it successfully.

 Comment

Zope does not require an XML namespace declaration when creating templates with a content-type of text/html. However, it does require an XML namespace declaration for all other content-types.

Anonymous User - July 3, 2002 1:27 pm:
 Could you give an example of a well-formed xml-Template? You refered to this in chapter 5.
 Comment

TAL Statements

These are the tal statements:

Expressions used in statements may return values of any type, although most statements will only accept strings, or will convert values into a string representation. The expression language must define a value named nothing that is not a string. In particular, this value is useful for deleting elements or attributes.

 Comment

Order of Operations

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.

 Comment

Any combination of statements may appear on the same elements, except that the content and replace statements may not appear together.

 Comment

When an element has multiple statements, they are executed in this order:

 Comment

  1. define
  2. condition
  3. repeat
  4. content or replace
  5. attributes
  6. omit-tag

Since the on-error statement is only invoked when an error occurs, it does not appear in the list.

Anonymous User - May 10, 2002 4:00 pm:
 Please add to the end of this paragraph:

 If multiple statements appearing within an element have the same
 precedence level, the order of execution of those statements
 within the precedence group is undefined.
 Comment

The reasoning behind this ordering goes like this: You often want to set up variables for use in other statements, so define comes first. The very next thing to do is decide whether this element will be included at all, so condition is next; since the condition may depend on variables you just set, it comes after define. It is valuable be able to replace various parts of an element with different values on each iteration of a repeat, so repeat is next. It makes no sense to replace attributes and then throw them away, so attributes is last. The remaining statements clash, because they each replace or edit the statement element.

Anonymous User - May 10, 2002 4:03 pm:
 Please replace from start of sentence to colon with following
 (reason to do this; as it stands, it says what was done, without why
 it was done, which is equally as important.) --

 The reasoning behind these precedences begins with the fact that TAL
 statements are being writtten as XML attributes.  By definition, XML
 attributes are un-ordered, and XML tools may, and do, rewrite attributes
 in any order they wish.  But, for TAL to be useful as a tmplating language,
 there has to be a predictable order of operations.  This order was
 chosen by the following rationale:
 Comment

See Also

TALES Overview

METAL Overview

tal:attributes

tal:define

tal:condition

tal:content

tal:omit-tag

tal:on-error

tal:repeat

tal:replace

attributes: Replace element attributes

Syntax

tal:attributes syntax:


argument             ::= attribute_statement [';' attribute_statement]*
attribute_statement  ::= attribute_name expression
attribute_name       ::= [namespace ':'] Name
namespace            ::= Name


Anonymous User - May 23, 2002 12:40 pm:
 This leaves it unclear whether a namespace
 represents a prefix or the actual URI for the
 namespace.  Please be specific.  If "prefix" is
 meant, consider writing

 namespace-prefix ::=Name
 Comment

Note: If you want to include a semi-colon (;) in an expression, it must be escaped by doubling it (;;).

 Comment

Description

The tal:attributes statement replaces the value of an attribute (or creates an attribute) with a dynamic value. You can qualify an attribute name with a namespace prefix, for example html:table, if you are generating an XML document with multiple namespaces. The value of each expression is converted to a string, if necessary.

 Comment

If the expression associated with an attribute assignment evaluates to nothing, then that attribute is deleted from the statement element. If the expression evaluates to default, then that attribute is left unchanged. Each attribute assignment is independent, so attributes may be assigned in the same statement in which some attributes are deleted and others are left alone.

 Comment

If you use tal:attributes on an element with an active tal:replace command, the tal:attributes statement is ignored.

 Comment

If you use tal:attributes on an element with a tal:repeat statement, the replacement is made on each repetition of the element, and the replacement expression is evaluated fresh for each repetition.

 Comment

Examples

Replacing a link:


<a href="/sample/link.html"
 tal:attributes="href here/sub/absolute_url">


 Comment

Replacing two attributes:


<textarea rows="80" cols="20"
 tal:attributes="rows request/rows;cols request/cols">


 Comment

condition: Conditionally insert or remove an element

Syntax

tal:condition syntax:


argument ::= expression


 Comment

Description

The tal:condition statement includes the statement element in the template only if the condition is met, and omits it otherwise. If its expression evaluates to a true value, then normal processing of the element continues, otherwise the statement element is immediately removed from the template. For these purposes, the value nothing is false, and default has the same effect as returning a true value.

 Comment

Note: Zope considers missing variables, None, zero, empty strings, and empty sequences false; all other values are true.

 Comment

Examples

Test a variable before inserting it (the first example tests for existence and truth, while the second only tests for existence):


<p tal:condition="request/message | nothing"
 tal:content="request/message">message goes here</p>

<p tal:condition="exists:request/message"
 tal:content="request/message">message goes here</p>


 Comment

Test for alternate conditions:


<div tal:repeat="item python:range(10)">
<p tal:condition="repeat/item/even">Even</p>
<p tal:condition="repeat/item/odd">Odd</p>
</div>


 Comment

content: Replace the content of an element

Syntax

tal:content syntax:


argument ::= (['text'] | 'structure') expression


 Comment

Description

Rather than replacing an entire element, you can insert text or structure in place of its children with the tal:content statement. The statement argument is exactly like that of tal:replace, and is interpreted in the same fashion. If the expression evaluates to nothing, the statement element is left childless. If the expression evaluates to default, then the element's contents are unchanged.

 Comment

Note: The default replacement behavior is text.

 Comment

Examples

Inserting the user name:


<p tal:content="user/getUserName">Fred Farkas</p>


 Comment

Inserting HTML/XML:


<p tal:content="structure here/getStory">marked <b>up</b>
content goes here.</p>


Anonymous User - May 23, 2002 12:43 pm:
 This snippet is unclear unless we know what getStory
 returns.  Is it HTML?  Be clear.  

 Also, what would happen if you said "structure" but
 only text were returned, or vice-versa?
fdrake - May 24, 2002 4:41 pm:
 getStory() is expected to return HTML (or XML if you're using XML instead).
 Nested TAL markup will be interpreted.

 If it returns plain text it needs to be valid when parsed as an HTML fragment,
 so it depends on whether the < or & characters are included.
 Comment

See Also

tal:replace

 Comment

define: Define variables

Syntax

tal:define syntax:


argument       ::= define_scope [';' define_scope]*
define_scope   ::= (['local'] | 'global') define_var
define_var     ::= variable_name expression
variable_name  ::= Name


 Comment

Note: If you want to include a semi-colon (;) in an expression, it must be escaped by doubling it (;;).

 Comment

Description

The tal:define statement defines variables. You can define two different kinds of TAL variables: local and global. 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.

 Comment

Note: local variables are the default

 Comment

If the expression associated with a variable evaluates to nothing, then that variable has the value nothing, and may be used as such in further expressions. Likewise, if the expression evaluates to default, then the variable has the value default, and may be used as such in further expressions.

 Comment

Examples

Defining a global variable:


tal:define="global company_name string:Zope Corp, Inc."


 Comment

Defining two variables, where the second depends on the first:


tal:define="mytitle template/title; tlen python:len(mytitle)"


 Comment

omit-tag: Remove an element, leaving its contents

Syntax

tal:omit-tag syntax:


argument ::= [ expression ]


 Comment

Description

The tal:omit-tag statement leaves the contents of a tag in place while omitting the surrounding start and end tag.

 Comment

If its expression evaluates to a false value, then normal processing of the element continues and the tag is not omitted. If the expression evaluates to a true value, or there is no expression, the statement tag is replaced with its contents.

 Comment

Zope treats empty strings, empty sequences, zero, None, nothing, and default at false. All other values are considered true.

 Comment

Examples

Unconditionally omitting a tag:


<div tal:omit-tag="" comment="This tag will be removed">
  <i>...but this text will remain.</i>
</div>


 Comment

Conditionally omitting a tag:


<b tal:omit-tag="not:bold">I may be bold.</b>


 Comment

The above example will omit the b tag if the variable bold is false.

 Comment

Creating ten paragraph tags, with no enclosing tag:


<span tal:repeat="n python:range(10)"
      tal:omit-tag="">
  <p tal:content="n">1</p>
</span>


 Comment

on-error: Handle errors

Syntax

tal:on-error syntax:


argument ::= (['text'] | 'structure') expression


 Comment

Description

The tal:on-error statement provides error handling for your template. When a TAL statement produces an error, the TAL interpreter searches for a tal:on-error statement on the same element, then on the enclosing element, and so forth. The first tal:on-error found is invoked. It is treated as a tal:content statement.

 Comment

A local variable error is set. This variable has these attributes:

 Comment
type
the exception type
value
the exception instance
traceback
the traceback object

The simplest sort of tal:on-error statement has a literal error string or nothing for an expression. A more complex handler may call a script that examines the error and either emits error text or raises an exception to propagate the error outwards.

 Comment

Examples

Simple error message:


<b tal:on-error="string: Username is not defined!" 
 tal:content="here/getUsername">Ishmael</b>


 Comment

Removing elements with errors:


<b tal:on-error="nothing"
   tal:content="here/getUsername">Ishmael</b>


 Comment

Calling an error-handling script:


<div tal:on-error="structure here/errorScript">
  ...
</div>


 Comment

Here's what the error-handling script might look like:


## Script (Python) "errHandler"
##bind namespace=_
##
error=_['error']
if error.type==ZeroDivisionError:
    return "<p>Can't divide by zero.</p>"
else
    return """<p>An error ocurred.</p>
              <p>Error type: %s</p>
              <p>Error value: %s</p>""" % (error.type,
                                           error.value)


 Comment

See Also

Python Tutorial: Errors and Exceptions

 Comment

Python Built-in Exceptions

 Comment

repeat: Repeat an element

Syntax

tal:repeat syntax:


argument      ::= variable_name expression
variable_name ::= Name


 Comment

Description

The tal:repeat 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 default, then the element is left unchanged, and no new variables are defined.

 Comment

The variable_name 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.

 Comment

Repeat Variables

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 repeat.

 Comment

The following information is available from the repeat variable:

You can access the contents of the repeat variable using path expressions or Python expressions. In path expressions, you write a three-part path consisting of the name repeat, the statement variable's name, and the name of the information you want, for example, repeat/item/start. In Python expressions, you use normal dictionary notation to get the repeat variable, then attribute access to get the information, for example, "python:repeat['item'].start".

 Comment

Note that first and last are intended for use with sorted sequences. They try to divide the sequence into group of items with the same value. If you provide a path, then the value obtained by following that path from a sequence item is used for grouping, otherwise the value of the item is used. You can provide the path by passing it as a parameter, as in "python:repeat['item'].first('color')", or by appending it to the path from the repeat variable, as in "repeat/item/first/color".

 Comment

Examples

Iterating over a sequence of strings::

 Comment

Inserting a sequence of table rows, and using the repeat variable to number the rows:


<table>
  <tr tal:repeat="item here/cart">
      <td tal:content="repeat/item/number">1</td>
      <td tal:content="item/description">Widget</td>
      <td tal:content="item/price">$1.50</td>
  </tr>
</table>


 Comment

Nested repeats:


<table border="1">
  <tr tal:repeat="row python:range(10)">
    <td tal:repeat="column python:range(10)">
      <span tal:define="x repeat/row/number; 
                        y repeat/column/number; 
                        z python:x*y"
            tal:replace="string:$x * $y = $z">1 * 1 = 1</span>
    </td>
  </tr>
</table>


 Comment

Insert objects. Seperates groups of objects by meta-type by drawing a rule between them:


<div tal:repeat="object objects">
  <h2 tal:condition="repeat/object/first/meta_type"
    tal:content="object/meta_type">Meta Type</h2>
  <p tal:content="object/getId">Object ID</p>
  <hr tal:condition="repeat/object/last/meta_type" />
</div>


 Comment

Note, the objects in the above example should already be sorted by meta-type.

 Comment

replace: Replace an element

Syntax

tal:replace syntax:


argument ::= (['text'] | 'structure') expression


 Comment

Description

The tal:replace 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 if you prefix the expression with text or omit the prefix, and is inserted unchanged if you prefix it with structure. Escaping consists of converting "&" to "&amp;", "<" to "&lt;", and ">" to "&gt;".

 Comment

If the value is nothing, then the element is simply removed. If the value is default, then the element is left unchanged.

 Comment

Examples

The two ways to insert the title of a template:


<span tal:replace="template/title">Title</span>
<span tal:replace="text template/title">Title</span>


 Comment

Inserting HTML/XML:


<div tal:replace="structure table" />


 Comment

Inserting nothing:


<div tal:replace="nothing">This element is a comment.</div>


 Comment

See Also

tal:content

 Comment

TALES Overview

The Template Attribute Language Expression Syntax (TALES) standard describes expressions that supply TAL and METAL with data. TALES is one 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.

 Comment

TALES expressions are described below with any delimiter or quote markup from higher language layers removed. Here is the basic definition of TALES syntax:


Expression  ::= [type_prefix ':'] String
type_prefix ::= Name


 Comment

Here are some simple examples:


a/b/c
path:a/b/c
nothing
path:nothing
python: 1 + 2
string:Hello, ${user/getUserName}


 Comment

The optional type prefix determines the semantics and syntax of the expression string 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.

 Comment

If you do not specify a prefix, Zope assumes that the expression is a path expression.

 Comment

TALES Expression Types

These are the TALES expression types supported by Zope:

Built-in Names

These are the names that always available to TALES expressions in Zope:

Note the names root, here, container, template, request, user, and modules are optional names supported by Zope, but are not required by the TALES standard.

 Comment

See Also

TAL Overview

METAL Overview

exists expressions

nocall expressions

not expressions

string expressions

path expressions

python expressions

TALES Exists expressions

Syntax

Exists expression syntax:


exists_expressions ::= 'exists:' path_expression


 Comment

Description

Exists expressions test for the existence of paths. An exists expression returns true when the path expressions following it expression returns a value. It is false when the path expression cannot locate an object.

 Comment

Examples

Testing for the existence of a form variable:


<p tal:condition="not:exists:request/form/number">
  Please enter a number between 0 and 5
</p>


 Comment

Note that in this case you can't use the expression, not:request/form/number, since that expression will be true if the number variable exists and is zero.

 Comment

TALES Nocall expressions

Syntax

Nocall expression syntax:


nocall_expression ::= 'nocall:' path_expression


 Comment

Description

Nocall expressions avoid rendering the results of a path expression.

 Comment

An ordinary path expression tries to render the object that it fetches. This means that if the object is a function, Script, Method, or some other kind of executable thing, then expression will evaluate to the result of calling the object. This is usually what you want, but not always. For example, if you want to put a DTML Document into a variable so that you can refer to its properties, you can't use a normal path expression because it will render the Document into a string.

 Comment

Examples

Using nocall to get the properties of a document:


<span tal:define="doc nocall:here/aDoc"
      tal:content="string:${doc/getId}: ${doc/title}">
Id: Title</span>


 Comment

Using nocall expressions on a functions:


<p tal:define="join nocall:modules/string/join">


 Comment

This example defines a variable join which is bound to the string.join function.

 Comment

TALES Not expressions

Syntax

Not expression syntax:


not_expression ::= 'not:' expression


 Comment

Description

Not expression evaluate the expression string (recursively) as a full expression, and returns the boolean negation of its value. If the expression supplied does not evaluate to a boolean value, not will issue a warning and coerce the expression's value into a boolean type based on the following rules:

 Comment

  1. the number 0 is false
  2. numbers > 0 are true
  3. an empty string or other sequence is false
  4. a non-empty string or other sequence is true
  5. a non-value (e.g. void, None, Nil, NULL, etc) is false
  6. all other values are implementation-dependent.

If no expression string is supplied, an error should be generated.

Zope considers all objects not specifically listed above as false (including negative numbers) to be true.

 Comment

Examples

Testing a sequence:


<p tal:condition="not:here/objectIds">
  There are no contained objects.
</p>


 Comment

TALES Path expressions

Syntax

Path expression syntax:


PathExpr  ::= Path [ '|' Path ]*
Path      ::= variable [ '/' URL_Segment ]*
variable  ::= Name


 Comment

Description

A path expression consists of one or more paths separated by vertical bars (|). A path consists of one or more non-empty strings separated by slashes. The first string must be a variable name (built-in variable or a user defined variable), and the remaining strings, the path segments, may contain letters, digits, spaces, and the punctuation characters underscore, dash, period, comma, and tilde.

efge - Apr. 24, 2002 11:41 am:
 The foo/?bar syntax should be mentionned here.
Anonymous User - Aug. 3, 2002 12:26 pm:
 And meanwhile, could someone explain it briefly in a comment? I was just coming here for that very
 explanation.
Anonymous User - Aug. 3, 2002 12:40 pm:
 Ah. I think I figured it out. It appears that the '?' is a sort of escape, so that normally problematic path
 segment names (those that use a slash as part of the name, for instance) can be used. More or less?
 Comment

For example:


request/cookies/oatmeal
nothing
here/some-file 2001_02.html.tar.gz/foo
root/to/branch | default
request/name | string:Anonymous Coward


 Comment

When a path expression is evaluated, Zope attempts to traverse the path, from left to right, until it succeeds or runs out of paths segments. To traverse a path, it first fetches the object stored in the variable. For each path segment, it traverses from the current object to the subobject named by the path segment. Subobjects are located according to standard Zope traversal rules (via getattr, getitem, or traversal hooks).

 Comment

Once a path has been successfully traversed, the resulting object is the value of the expression. If it is a callable object, such as a method or template, it is called.

 Comment

If a traversal step fails, evaluation immediately proceeds to the next path. If there are no further paths, an error results.

 Comment

The expression in a series of paths seperated by vertical bars can be any TALES expression. For example, 'request/name | string:Anonymous Coward'. This is useful chiefly for providing default values such as strings and numbers which are not expressable as path expressions.

 Comment

If no path is given the result is nothing.

 Comment

Since every path must start with a variable name, you need a set of starting variables that you can use to find other objects and values. See the TALES overview for a list of built-in variables. Since variable names are looked up first in locals, then in globals, then in this list, these names act just like built-ins in Python; They are always available, but they can be shadowed by a global or local variable declaration. You can always access the built-in names explicitly by prefixing them with CONTEXTS. (e.g. CONTEXTS/root, CONTEXTS/nothing, etc).

 Comment

Examples

Inserting a cookie variable or a property:


<span tal:replace="request/cookies/pref | here/pref">
  preference
</span>


 Comment

Inserting the user name:


<p tal:content="user/getUserName">
  User name
</p>


 Comment

TALES Python expressions

Syntax

Python expression syntax:


Any valid Python language expression


 Comment

Description

Python expressions evaluate Python code in a security-restricted environment. Python expressions offer the same facilities as those available in Python-based Scripts and DTML variable expressions.

 Comment

Security Restrictions

Python expressions are subject to the same security restrictions as Python-based scripts. These restrictions include:

 Comment

access limits
Python expressions are subject to Zope permission and role security restrictions. In addition, expressions cannot access objects whose names begin with underscore.
write limits
Python expressions cannot change attributes of Zope objects.

Despite these limits malicious Python expressions can cause problems. See The Zope Book for more information.

 Comment

Built-in Functions

Python expressions have the same built-ins as Python-based Scripts with a few additions.

 Comment

These standard Python built-ins are available: None, abs, apply, callable, chr, cmp, complex, delattr, divmod, filter, float, getattr, hash, hex, int, isinstance, issubclass, list, len, long, map, max, min, oct, ord, repr, round, setattr, str, tuple.

 Comment

The range and pow functions are available and work the same way they do in standard Python; however, they are limited to keep them from generating very large numbers and sequences. This limitation helps protect against denial of service attacks.

 Comment

In addition, these utility functions are available: DateTime, test, and same_type. See DTML functions for more information on these functions.

 Comment

Finally, these functions are available in Python expressions, but not in Python-based scripts:

 Comment

path(string)
Evaluate a TALES path expression.
string(string)
Evaluate a TALES string expression.
exists(string)
Evaluates a TALES exists expression.
nocall(string)
Evaluates a TALES nocall expression.

Python Modules

A number of Python modules are available by default. You can make more modules available. You can access modules either via path expressions (for example 'modules/string/join') or in Python with the modules mapping object (for example 'modules["string"].join'). Here are the default modules:

 Comment

string
The standard Python string module. Note: most of the functions in the module are also available as methods on string objects.
random
The standard Python random module.
math
The standard Python math module.
sequence
A module with a powerful sorting function. See sequence for more information.
Products.PythonScripts.standard
Various HTML formatting functions available in DTML. See Products.PythonScripts.standard for more information.
ZTUtils
Batch processing facilities similar to those offered by dtml-in. See ZTUtils for more information.
AccessControl
Security and access checking facilities. See AccessControl for more information.

Examples

Using a module usage (pick a random choice from a list):


<span tal:replace="python:modules['random'].choice(['one', 
                     'two', 'three', 'four', 'five'])">
  a random number between one and five
</span>


 Comment

String processing (capitalize the user name):


<p tal:content="python:user.getUserName().capitalize()">
  User Name
</p>


Anonymous User - July 3, 2002 4:19 pm:
 I am really no expert in python, but 
 tal:content="python:user.getUserName().upper()
 works fine. The given example does not work (no captialize).
Anonymous User - July 9, 2002 12:28 am:
 There is definitely a capitalize string method. Perhaps you had the same typo that you put in your comment
 (captialize rather than capitalize). The upper method converts the whole string to upper case, where-as
 capitalize only upper cases the first letter of the string.
 Comment

Basic math (convert an image size to megabytes):


<p tal:content="python:image.getSize() / 1048576.0">
  12.2323
</p>


 Comment

String formatting (format a float to two decimal places):


<p tal:content="python:'%0.2f' % size">
  13.56
</p>


 Comment

TALES String expressions

Syntax

String expression syntax:


string_expression ::= ( plain_string | [ varsub ] )*
varsub            ::= ( '$' Path ) | ( '${' Path '}' )
plain_string      ::= ( '$$' | non_dollar )*
non_dollar        ::= any character except '$'


 Comment

Description

String expressions interpret the expression string as text. If no expression string is supplied the resulting string is empty. The string can contain variable substitutions of the form $name or ${path}, where name is a variable name, and path is a path expression. The escaped string value of the path expression is inserted into the string. To prevent a $ from being interpreted this way, it must be escaped as $$.

 Comment

Examples

Basic string formatting:


<span tal:replace="string:$this and $that">
  Spam and Eggs
</span>


 Comment

Using paths:


<p tal:content="total: ${request/form/total}">
  total: 12
</p>


 Comment

Including a dollar sign:


<p tal:content="cost: $$$cost">
  cost: $42.00
</p>


 Comment

METAL Overview

The Macro Expansion Template Attribute Language (METAL) standard is a facility for HTML/XML macro preprocessing. It can be used in conjunction with or independently of TAL and TALES.

 Comment

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.

 Comment

METAL Namespace

The METAL namespace URI and recommended alias are currently defined as:


xmlns:metal="http://xml.zope.org/namespaces/metal"


 Comment

Just like the TAL namespace URI, this URI is not attached to a web page; it's just a unique identifier.

 Comment

Zope does not require an XML namespace declaration when creating templates with a content-type of text/html. However, it does require an XML namespace declaration for all other content-types.

 Comment

METAL Statements

METAL defines a number of statements:

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.

 Comment

See Also

TAL Overview

TALES Overview

metal:define-macro

metal:use-macro

metal:define-slot

metal:fill-slot

define-macro: Define a macro

Syntax

metal:define-macro syntax:


argument ::= Name


 Comment

Description

The metal:define-macro statement defines a macro. The macro is named by the statement expression, and is defined as the element and its sub-tree.

 Comment

In Zope, a macro definition is available as a sub-object of a template's macros object. For example, to access a macro named header in a template named master.html, you could use the path expression master.html/macros/header.

 Comment

Examples

Simple macro definition:


<p metal:define-macro="copyright">
  Copyright 2001, <em>Foobar</em> Inc.
</p>


 Comment

See Also

metal:use-macro

metal:define-slot

define-slot: Define a macro customization point

Syntax

metal:define-slot syntax:


argument ::= Name


 Comment

Description

The metal:define-slot statement defines a macro customization point or slot. 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.

 Comment

The metal:define-slot statement must be used inside a metal:define-macro statement.

 Comment

Slot names must be unique within a macro.

Examples

Simple macro with slot:


<p metal:define-macro="hello">
  Hello <b metal:define-slot="name">World</b>
</p>


 Comment

This example defines a macro with one slot named name. When you use this macro you can customize the b element by filling the name slot.

 Comment

See Also

metal:fill-slot

fill-slot: Customize a macro

Syntax

metal:fill-slot syntax:


argument ::= Name


 Comment

Description

The metal:fill-slot statement customizes a macro by replacing a slot in the macro with the statement element (and its content).

 Comment

The metal:fill-slot statement must be used inside a metal:use-macro statement.

 Comment

Slot names must be unique within a macro.

If the named slot does not exist within the macro, the slot contents will be silently dropped.

 Comment

Examples

Given this macro:


<p metal:define-macro="hello">
  Hello <b metal:define-slot="name">World</b>
</p>


 Comment

You can fill the name slot like so:


<p metal:use-macro="container/master.html/macros/hello">
  Hello <b metal:fill-slot="name">Kevin Bacon</b>
</p>


 Comment

See Also

metal:define-slot

use-macro: Use a macro

Syntax

metal:use-macro syntax:


argument ::= expression


 Comment

Description

The metal:use-macro statement replaces the statement element with a macro. The statement expression describes a macro definition.

 Comment

In Zope the expression will generally be a path expression referring to a macro defined in another template. See "metal:define-macro" for more information.

 Comment

The effect of expanding a macro is to graft a subtree from another document (or from elsewhere in the current document) in place of the statement element, replacing the existing sub-tree. Parts of the original subtree may remain, grafted onto the new subtree, if the macro has slots. See metal:define-slot for more information. If the macro body uses any macros, they are expanded first.

 Comment

When a macro is expanded, its metal:define-macro attribute is replaced with the metal:use-macro attribute from the statement element. This makes the root of the expanded macro a valid use-macro statement element.

 Comment

Examples

Basic macro usage:


<p metal:use-macro="container/other.html/macros/header">
  header macro from defined in other.html template
</p>


 Comment

This example refers to the header macro defined in the other.html template which is in the same folder as the current template. When the macro is expanded, the p element and its contents will be replaced by the macro. Note: there will still be a metal:use-macro attribute on the replacement element.

 Comment

See Also

metal:define-macro

metal:fill-slot

Powered by Zope