[Checkins] SVN: zope2book/trunk/ We have a new tal appendix :)

Hanno Schlichting plone at hannosch.info
Mon Feb 16 17:21:20 EST 2009


Log message for revision 96609:
  We have a new tal appendix :)
  

Changed:
  D   zope2book/trunk/AppendixC.stx
  A   zope2book/trunk/source/AppendixC.rst
  U   zope2book/trunk/source/index.rst

-=-
Deleted: zope2book/trunk/AppendixC.stx
===================================================================
--- zope2book/trunk/AppendixC.stx	2009-02-16 21:30:29 UTC (rev 96608)
+++ zope2book/trunk/AppendixC.stx	2009-02-16 22:21:20 UTC (rev 96609)
@@ -1,1505 +0,0 @@
-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: Template Attribute
-  Language (TAL), TAL Expression Syntax (TALES), and Macro Expansion
-  TAL (METAL).  It also describes some ZPT-specific behaviors that are not part of the standards.
-
-    % reference to metal:block
-     tal:block or metal:block can be used on tag-level
-     if you have no html-tag to put your tal/metal code on.
-     for instance, outside of the html-tag.
-
-    % Anonymous User - Apr. 14, 2004 10:17 am:
-     I have found a tal function that is never used or described in 
-     any of these pages or the WWW after a search on 5 searchpages. 
-     Except in a subproduct for Zope (Plone) (but they don't explain 
-     tal usage on their site so I'll ask it here)
-       <tal:datetime define="today python:DateTime().earliestTime()">
-         ...
-       </tal:datetime>
-     First thing that intrigues me: There is no standard html tag 
-     around this tal, I thought only tal:block could do that?
-     Second thing I noticed: All the code that remained between those 
-     tags (represented by "...") appeared in the resulting page without 
-     problem, but there remained nothing visible of these "tal:datetime" 
-     tags.
-     Third thing I noticed: straight after the tal:datetime statement 
-     comes define="...", clearly working as the tal:define explained 
-     later in this apendix. Why has there been no need to write "tal:" 
-     in front of it?
-     Is this some faulty page template code, yet still beeing 
-     accepted by the browser?
-     Could this code have been replaced by a 
-     simple <tal:block tal:define="..."> ... </tal:block> or 
-     <span tal:omit-tag tal:define="..."> ... </span>?
-     Or is there a possibility to extend the tal-statements and why 
-     isn't it told here then?
-
-    % Anonymous User - Apr. 14, 2004 10:30 am:
-     You need to understand namespaces. In an HTML page, the default 
-     namespace is that of HTML. The browser will attempt to parse 
-     all tags in this namespace. To put a tag in a different namespace, 
-     which will be ignored by the browser, prefix it with the namespace, 
-     e.g. to put a tag in the 'tal' namespace, write:
-        <tal:XXXX ... />
-     The same goes for attributes. To put an attribute in the 'tal' namespace, 
-     write:   <span tal:define="..." />
-     If an element is in the 'tal' namespace, all its attributes are also in that
-     namespace. That is why it is *not* necessary to write:  
-       <tal:datetime tal:define="..." />
-     The second 'tal:' is redundant. 
-     The next thing to understand: TAL (the Template ATTRIBUTE language) only
-     pays attention to *attributes*. It ignores tags. Therefor the XXX in 
-       <tal:XXX ...> 
-     can be anything -- it will be ignored by the TAL parser. It's a good idea
-     to make it something descriptive.
-
-  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.
-
-    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.
-
-    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.
-
-    TAL Namespace
-
-      The TAL namespace URI and recommended alias are currently defined
-      as::
-
-        xmlns:tal="http://xml.zope.org/namespaces/tal"
-
-        % XX keep it simple .. 
-         syntax basics are not explained in this document; therefore, the new 
-         student - who has been directed to that fact that TAL avoids many 
-         problems of dtml and, therefore, wants to learn it - finds it inaccessible.
-         
-        % XX Here is what is missing:
-         http://dev.zope.org/Wikis/DevSite/Projects/ZPT/AttributeLanguage
-         AttributeLanguage
-         Attribute Languages
-         An attribute language is a programming language designed to mesh 
-         in a particular way with documents written using tag-structured markup, 
-         such as HTML and XML. The statements of the language are document tags 
-         with special attributes, and look like this:
-             <p ns:command="argument">Some Text</p>
-         The attribute ns:command="argument" is the statement attribute, 
-         and the entire paragraph tag is the statement element, the portion of 
-         the document on which this statement operates. Each statement attribute 
-         has three parts: the namespace prefix, the name, and the argument. 
-         The prefix identifies the language, and must be introduced by an XML 
-         namespace declaration in XML and XHTML documents, like this:
-             xmlns:ns="http://language.creator.com/namespaces/MyAttributeLanguage"
-         HTML should include these declarations, but an implementation may 
-         allow you to omit them. The statement name determines which language 
-         statement to apply to the statement element, and the argument determines 
-         how it is applied. The name is always a simple identifier, but the 
-         argument can contain just about anything, depending on the statement.
-         How to Specify an Attribute Language
-         If you create an attribute language, you need to define the following: 
-         The URI of the XML namespace, and (optionally) a recommended alias. 
-         The names, argument syntax, and meaning of the possible statements. 
-         The order in which statements on the same element are processed, and 
-         restrictions on which statements can share the same element.
-
-      This is not a URL, but merely a unique identifier.  Do not expect
-      a browser to resolve it successfully.
-
-      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.
-
-    TAL Statements   
-
-      These are the tal statements:
-
-      - tal:attributes - dynamically change
-        element attributes.
-
-      - tal:define - define variables.
-
-      - tal:condition - test conditions.
-
-      - tal:content - replace the content of an
-        element.
-
-      - tal:omit-tag - remove an element, leaving
-        the content of the element.
-
-      - tal:on-error - handle errors.
-
-      - tal:repeat - repeat an element.
-
-      - tal:replace - replace the content of an
-        element and remove the element leaving the content.
-
-      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.
-
-    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.
-
-      Any combination of statements may appear on the same elements,
-      except that the 'content' and 'replace' statements may not appear
-      together.
-
-      Due to the fact that TAL sees statements as XML attributes,
-      even in HTML documents, it cannot use the order in which
-      statements are written in the tag to determine the order in which
-      they are executed.  TAL must also forbid multiples of the same kind
-      of statement on a single element, so it is sufficient to arrange the
-      kinds of statement in a precendence list.
-
-      When an element has multiple statements, they are executed in this
-      order:
-
-      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.  
-
-        % XX Add:
-         It may not be apparent that there needs to be an ordering.  
-         The reason that there must be one is that TAL is XML based. 
-         The XML specification specifically states that XML processors 
-         are free to rewrite the terms.  In particular, you cannot assume that
-         attributes of an XML statement will be processed in the order written, 
-         particularly if there is another preprocessor involved. To avoid 
-         needless proliferation of tags, and still permit unambigous 
-         execution of complex TAL, a precedence order was chosen according
-         to the following rationalle.
-
-      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.
-
-    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-prefix ':'] Name
-        namespace-prefix     ::= Name
-
-      *Note: If you want to include a semi-colon (;) in an 'expression',
-      it must be escaped by doubling it (;;).*
-
-    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.
-
-      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.
-
-        % Anonymous User - Dec. 19, 2003 12:58 pm:
-         This seems to contradict the Order of Operations, above, where 
-         it says that attribution takes place after replacement. That 
-         way seems better than ignoring the attribution altogether.
-
-        % Anonymous User - Jan. 16, 2004 8:41 am:
-         Performing attribution after replacement wouldn't make any sense; 
-         tal:replace completely replaces the element, where would the 
-         attribute changes be made then?
-
-      If you use 'tal:attributes' on an element with an active
-      'tal:replace' command, the 'tal:attributes' statement is ignored.
-
-      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.
-
-    Examples
-
-      Replacing a link::
-
-        <a href="/sample/link.html"
-         tal:attributes="href here/sub/absolute_url">
-
-      Replacing two attributes::
-
-        <textarea rows="80" cols="20"
-         tal:attributes="rows request/rows;cols request/cols">
-
-  condition: Conditionally insert or remove an element
-
-    Syntax
-
-      'tal:condition' syntax::
-
-        argument ::= expression
-
-    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.
-
-      *Note: Zope considers missing variables, None, zero, empty strings,
-      and empty sequences false; all other values are true.*
-
-    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>
-
-      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>
-
-  content: Replace the content of an element
-
-    Syntax
-
-      'tal:content' syntax::
-
-        argument ::= (['text'] | 'structure') expression
-
-    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.
-
-      The default replacement behavior is 'text', which replaces
-      angle-brackets and ampersands with their HTML entity equivalents.
-      The 'structure' 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.
-
-    Examples
-
-      Inserting the user name::
-
-        <p tal:content="user/getUserName">Fred Farkas</p>
-
-      Inserting HTML/XML::
-
-        <p tal:content="structure here/getStory">marked <b>up</b>
-        content goes here.</p>
-
-    See Also
-
-      'tal:replace'
-
-  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
-
-      *Note: If you want to include a semi-colon (;) in an 'expression',
-      it must be escaped by doubling it (;;).*
-
-    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.
-
-      *Note: local variables are the default*
-
-      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.
-
-    Examples
-
-      Defining a global variable::
-
-        tal:define="global company_name string:Zope Corp, Inc."
-
-      Defining two variables, where the second depends on the first::
-
-        tal:define="mytitle template/title; tlen python:len(mytitle)"
-
-  omit-tag: Remove an element, leaving its contents
-
-    Syntax
-
-      'tal:omit-tag' syntax::
-
-        argument ::= [ expression ]
-
-    Description
-
-      The 'tal:omit-tag' statement leaves the contents of an
-      element in place while omitting the surrounding start and end tags.
-
-      If the expression evaluates to a *false* value, then normal
-      processing of the element continues and the tags are not omitted.
-      If the expression evaluates to a *true* value, or no
-      expression is provided, the statement element is replaced
-      with its contents. 
-
-      Zope treats empty strings, empty sequences, zero, None, and *nothing*
-      as false. All other values are considered true, including *default*.
-
-    Examples
-
-      Unconditionally omitting a tag::
-
-        <div tal:omit-tag="" comment="This tag will be removed">
-          <i>...but this text will remain.</i>
-        </div>
-
-      Conditionally omitting a tag::
-
-        <b tal:omit-tag="not:bold">I may be bold.</b>
-
-      The above example will omit the 'b' tag if the variable 'bold' is
-      false.
-
-      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>
-
-  on-error: Handle errors
-
-    Syntax
-
-      'tal:on-error' syntax::
-
-        argument ::= (['text'] | 'structure') expression
-
-    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.
-
-      A local variable 'error' is set. This variable has these
-      attributes:
-
-        '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.  
-
-    Examples
-
-      Simple error message::
-
-        <b tal:on-error="string: Username is not defined!" 
-         tal:content="here/getUsername">Ishmael</b>
-
-      Removing elements with errors::
-
-        <b tal:on-error="nothing"
-           tal:content="here/getUsername">Ishmael</b>
-
-      Calling an error-handling script::
-
-        <div tal:on-error="structure here/errorScript">
-          ...
-        </div>
-
-      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)
-
-    See Also
-
-      "Python Tutorial: Errors and
-      Exceptions":http://www.python.org/doc/current/tut/node10.html
-
-      "Python Built-in
-      Exceptions":http://www.python.org/doc/current/lib/module-exceptions.html
-
-  repeat: Repeat an element
-
-    Syntax
-
-      'tal:repeat' syntax::
-
-        argument      ::= variable_name expression
-        variable_name ::= Name
-
-    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.
-
-      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.
-
-    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'.
-
-      The following information is available from the repeat variable:
-
-        o *index* - repetition number, starting from zero.
-
-        o *number* - repetition number, starting from one.
-
-        o *even* - true for even-indexed repetitions (0, 2, 4, ...).
-
-        o *odd* - true for odd-indexed repetitions (1, 3, 5, ...).
-
-        o *start* - true for the starting repetition (index 0).
-
-        o *end* - true for the ending, or final, repetition.
-
-        o *first* - true for the first item in a group - see note below
-
-        o *last* - true for the last item in a group - see note below
-
-        o *length* - length of the sequence, which will be the total number
-          of repetitions.
-
-        o *letter* - repetition number as a lower-case letter: "a" -
-          "z", "aa" - "az", "ba" - "bz", ..., "za" - "zz", "aaa" - "aaz",
-          and so forth.
-
-        o *Letter* - upper-case version of *letter*.
-
-        o *roman* - repetition number as a lower-case roman numeral:
-          "i", "ii", "iii", "iv", "v", etc.
-
-        o *Roman* - upper-case version of *roman*.
-
-      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".
-
-      With the exception of 'start', 'end', and 'index', all of the
-      attributes of a repeat variable are methods.  Thus, when you
-      use a Python expression to access them, you must call them, as in
-      "python:repeat['item'].length()".
-
-      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".
-
-    Examples
-
-      Iterating over a sequence of strings::    
-
-        <p tal:repeat="txt python:'one', 'two', 'three'">
-           <span tal:replace="txt" />
-        </p>
-
-      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>
-
-      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>
-
-      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>
-
-      Note, the objects in the above example should already be sorted by
-      meta-type.
-
-  replace: Replace an element
-
-    Syntax
-
-      'tal:replace' syntax::
-
-        argument ::= (['text'] | 'structure') expression
-
-    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 "&amp;" to "&amp;amp;", "&lt;" to "&amp;lt;", and
-      "&gt;" to "&amp;gt;".
-
-      If the value is *nothing*, then the element is simply removed.  If
-      the value is *default*, then the element is left unchanged.
-
-    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>
-
-      Inserting HTML/XML::
-
-        <div tal:replace="structure table" />
-
-      Inserting nothing::
-
-        <div tal:replace="nothing">This element is a comment.</div>
-
-    See Also
-
-      'tal:content'
-
-  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.
-
-    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
-
-    Here are some simple examples::
-
-      a/b/c
-      path:a/b/c
-      nothing
-      path:nothing
-      python: 1 + 2
-      string:Hello, ${user/getUserName}
-
-    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.
-
-    If you do not specify a prefix, Zope assumes that the expression is
-    a *path* expression.
-
-    TALES Expression Types
-
-      These are the TALES expression types supported by Zope:
-
-      * path expressions - locate a value by its path.
-
-      * exists expressions - test whether a path is valid.
-
-      * nocall expressions - locate an object by its path.
-
-      * not expressions - negate an expression
-
-      * string expressions - format a string
-
-      * python expressions - execute a Python
-        expression
-
-    Built-in Names
-
-      These are the names always available to TALES expressions in Zope:
-
-      - *nothing* - special value used by to represent 
-         a *non-value* (e.g. void, None, Nil, NULL).
-
-      - *default* - special value used to specify that
-        existing text should not be replaced. See the documentation for
-        individual TAL statements for details on how they interpret
-        *default*.
-
-      - *options* - the *keyword* arguments passed to the template. These
-        are generally available when a template is called from Methods
-        and Scripts, rather than from the web.
-
-      - *repeat* - the 'repeat' variables; see the
-        tal:repeat documentation.
-
-      - *attrs* - a dictionary containing the initial values of the
-        attributes of the current statement tag.
-
-      - *CONTEXTS* - the list of standard names (this list).  This can be
-        used to access a built-in variable that has been hidden by a local
-        or global variable with the same name.
-
-      - *root* - the system's top-most object: the Zope root folder.
-
-      - *here* - the object to which the template is being applied.
-
-      - *container* - The folder in which the template is located.
-
-      - *template* - the template itself.
-
-      - *request* - the publishing request object.
-
-      - *user* - the authenticated user object.
-
-      - *modules* - a collection through which Python modules and
-        packages can be accessed.  Only modules which are approved by
-        the Zope security policy can be accessed.
-
-      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.
-
-    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
-
-    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.
-
-    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>
-
-      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.
-
-  TALES Nocall expressions
-
-    Syntax
-
-      Nocall expression syntax::
-
-        nocall_expression ::= 'nocall:' path_expression
-
-    Description
-
-      Nocall expressions avoid rendering the results of a path
-      expression.
-
-      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.
-
-    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>
-
-      Using nocall expressions on a functions::
-
-        <p tal:define="join nocall:modules/string/join">
-
-      This example defines a variable 'join' which is bound to the
-      'string.join' function.
-
-  TALES Not expressions
-
-    Syntax
-
-      Not expression syntax::
-
-        not_expression ::= 'not:' expression
-
-    Description
-
-      Not expression evaluates 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:
-
-      1. the number 0 is *false*
-
-      2. positive and negative numbers 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* to be *true*.
-
-    Examples
-
-      Testing a sequence::
-
-        <p tal:condition="not:here/objectIds">
-          There are no contained objects.
-        </p>
-
-  TALES Path expressions
-
-    Syntax
-
-      Path expression syntax::
-
-        PathExpr    ::= Path [ '|' Expression ]
-        Path        ::= variable [ '/' PathSegment ]*
-        variable    ::= Name
-        PathSegment ::= ( '?' variable ) | PathChar+
-        PathChar    ::= AlphaNumeric | ' ' | '_' | '-' | '.' | ',' | '~'
-
-    Description
-
-      A path expression consists of a *path* optionally followed by
-      a vertical bar (|) and alternate expression.  A path consists of
-      one or more non-empty strings separated by slashes. The first
-      string must be a variable name (a 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.
-
-      A limited amount of indirection is possible by using a variable name
-      prefixed with '?' as a path segment.  The variable must contain a
-      string, which replaces that segment before the path is traversed.
-
-      For example::
-
-        request/cookies/oatmeal
-        nothing
-        here/some-file 2001_02.html.tar.gz/foo
-        root/to/branch | default
-
-        request/name | string:Anonymous Coward
-        here/?tname/macros/?mname
-
-      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).
-
-      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.
-
-      If a traversal step fails, and no alternate expression has been
-      specified, an error results.  Otherwise, the alternate expression
-      is evaluated.
-
-      The alternate expression can be any TALES expression. For example,
-      'request/name | string:Anonymous Coward' is a valid path expression.
-      This is useful chiefly for providing default values, such as strings
-      and numbers, which are not expressable as path expressions.  Since
-      the alternate expression can be a path expression, it is possible to
-      "chain" path expressions, as in 'first | second | third | nothing'.
-
-      If no path is given the result is *nothing*.
-
-      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.  Variable names are looked up first in
-      locals, then in globals, then in the built-in list, so the
-      built-in variables 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).
-
-    Examples
-
-      Inserting a cookie variable or a property::
-
-        <span tal:replace="request/cookies/pref | here/pref">
-          preference
-        </span>
-
-      Inserting the user name::
-
-        <p tal:content="user/getUserName">
-          User name
-        </p>
-
-  TALES Python expressions
-
-    Syntax
-
-      Python expression syntax::
-
-        Any valid Python language expression
-
-    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.
-
-      Security Restrictions
-
-        Python expressions are subject to the same security restrictions
-        as Python-based scripts. These restrictions include:
-
-        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.
-
-      Built-in Functions
-
-        Python expressions have the same built-ins as Python-based
-        Scripts with a few additions.
-
-        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'.
-
-        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.
-
-        In addition, these utility functions are available: 'DateTime',
-        'test', and 'same_type'. See DTML
-        functions for more
-        information on these functions.
-
-        Finally, these functions are available in Python expressions,
-        but not in Python-based scripts:
-
-        '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:
-
-          % woller - Jan. 24, 2004 5:38 pm:
-           It is not clear at all where to go to "see ZTUtils" for instance. 
-           Or any of the other references.... 
-           There should really be some links here!
-
-        'string' -- The standard "Python string
-        module":http://www.python.org/doc/current/lib/module-string.html. Note:
-        most of the functions in the module are also available as
-        methods on string objects.
-
-        'random' -- The standard "Python random
-        module":http://www.python.org/doc/current/lib/module-random.html.
-
-        'math' -- The standard "Python math
-        module":http://www.python.org/doc/current/lib/module-math.html.
-
-        '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>
-
-      String processing (capitalize the user name)::
-
-        <p tal:content="python:user.getUserName().capitalize()">
-          User Name
-        </p>
-
-      Basic math (convert an image size to megabytes)::
-
-        <p tal:content="python:image.getSize() / 1048576.0">
-          12.2323
-        </p>
-
-      String formatting (format a float to two decimal places)::
-
-        <p tal:content="python:'%0.2f' % size">
-          13.56
-        </p>
-
-        % Anonymous User - Mar. 24, 2004 12:17 am:
-         How create 12345 to 12,345.00
-
-  TALES String expressions
-
-    Syntax
-
-      String expression syntax::
-
-        string_expression ::= ( plain_string | [ varsub ] )*
-        varsub            ::= ( '$' Path ) | ( '${' Path '}' )
-        plain_string      ::= ( '$$' | non_dollar )*
-        non_dollar        ::= any character except '$'
-
-    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 '$$'.
-
-    Examples
-
-      Basic string formatting::
-
-        <span tal:replace="string:$this and $that">
-          Spam and Eggs
-        </span>
-
-      Using paths::
-
-        <p tal:content="total: ${request/form/total}">
-          total: 12
-        </p>
-
-        % Anonymous User - Apr. 6, 2004 7:54 am:
-         # <p tal:content="total: ${request/form/total}">
-         Shouldn't this be <p tal:content="string:total: ${request/form/total}"> ?
-         Am I completely wrong or is this a typo?
-
-      Including a dollar sign::
-
-        <p tal:content="cost: $$$cost">
-          cost: $42.00
-        </p>
-
-        % Anonymous User - Apr. 6, 2004 7:55 am:
-         same comment as above comment...
-         I think that this is a typo and that the first line 
-         should be <p tal:content="string:cost: $$$cost">
-
-  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.
-
-    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.
-
-      % Anonymous User - Nov. 17, 2003 4:25 am:
-       NOT MENTIONED:
-       A single Page Template can accomodate multiple macros.
-       The method employed to mark the beginning and, above all, the 
-       end of one macro is not discussed here. Therefore, a second macro 
-       can accidently be called inadvertently when calling the first one.
-
-    METAL Namespace
-
-      The METAL namespace URI and recommended alias are currently
-      defined as::
-
-        xmlns:metal="http://xml.zope.org/namespaces/metal"
-
-      Just like the TAL namespace URI, this URI is not attached to a web
-      page; it's just a unique identifier.
-
-      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.
-
-    METAL Statements 
-
-      METAL defines a number of statements:
-
-      * metal:define-macro - Define a macro.
-
-      * metal:use-macro - Use a macro.
-
-      * metal:define-slot - Define a macro
-      customization point.
-
-      * metal:fill-slot - Customize a macro.
-
-      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.
-
-    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
-
-    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.
-
-        % Anonymous User - Nov. 17, 2003 4:27 am:
-         NOT MENTIONED:
-         Sub-tree, where does it end?
-
-      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'.
-
-    Examples
-
-      Simple macro definition::
-
-        <p metal:define-macro="copyright">
-          Copyright 2004, <em>Foobar</em> Inc.
-        </p>
-
-    See Also
-
-      metal:use-macro
-
-      metal:define-slot
-
-  define-slot: Define a macro customization point
-
-    Syntax
-
-      'metal:define-slot' syntax::
-
-        argument ::= Name
-
-    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.
-
-      The 'metal:define-slot' statement must be used inside a
-      'metal:define-macro' statement.
-
-        % Anonymous User - Nov. 17, 2003 4:30 am:
-         NOT MENTIONED:
-         "inside" a metal:define-macro implies that the macro has 
-         a beginning and an end. Inside is then before the
-         end. How does one mark the end of a macro?
-
-        % Anonymous User - Dec. 8, 2003 4:01 pm:
-         by the closing tag
-
-      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>
-
-      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.
-
-    See Also
-
-      metal:fill-slot
-
-  fill-slot: Customize a macro
-
-    Syntax
-
-      'metal:fill-slot' syntax::
-
-        argument ::= Name
-
-    Description
-
-      The 'metal:fill-slot' statement customizes a macro by replacing a
-      *slot* in the macro with the statement element (and its content).
-
-      The 'metal:fill-slot' statement must be used inside a
-      'metal:use-macro' statement.
-
-      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.
-
-    Examples
-
-     Given this macro::
-
-        <p metal:define-macro="hello">
-          Hello <b metal:define-slot="name">World</b>
-        </p>
-
-       % Anonymous User - Apr. 8, 2004 4:52 pm:
-        Why do some define-slots look like:
-        <p metal:define-slot="head_slot" />
-        while others look like:
-        <metal:headslot define-slot="head_slot" />
-         what is that "headslot" thingie? It's not the same as "head_slot"...
-
-      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>
-
-    See Also
-
-      metal:define-slot
-
-  use-macro: Use a macro
-
-    Syntax
-
-      'metal:use-macro' syntax::
-
-        argument ::= expression
-
-    Description
-
-      The 'metal:use-macro' statement replaces the statement element
-      with a macro. The statement expression describes a macro
-      definition. 
-
-      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.
-
-      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.
-
-      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.
-
-    Examples
-
-      Basic macro usage::
-
-        <p metal:use-macro="container/other.html/macros/header">
-          header macro from defined in other.html template
-        </p>
-
-      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.
-
-    See Also
-
-      metal:define-macro
-
-      metal:fill-slot
-
-  ZPT-specific Behaviors
-
-    The behavior of Zope Page Templates is almost completely described
-    by the TAL, TALES, and METAL specifications.  ZPTs do, however, have
-    a few additional features that are not described in the standards.
-
-    HTML Support Features
-
-      When the content-type of a Page Template is set to 'text/html',
-      Zope processes the template somewhat differently than with any
-      other content-type.  As mentioned under TAL Namespace, HTML
-      documents are not required to declare namespaces, and are provided
-      with 'tal' and 'metal' namespaces by default.
-
-      HTML documents are parsed using a non-XML parser that is somewhat
-      more forgiving of malformed markup.  In particular, elements that
-      are often written without closing tags, such as paragraphs and list
-      items, are not treated as errors when written that way, unless they
-      are statement elements.  This laxity can cause a confusing error in
-      at least one case;  A '<div>' element is block-level, and
-      therefore technically not allowed to
-      be nested in  a '<p>' element, so it will cause the paragraph to be 
-      implicity closed.  The closing '</p>' tag will then cause a
-      NestingError, since it is not matched up with the opening tag.  The
-      solution is to use '<span>' instead.
-
-      Unclosed statement elements are always treated as errors, so as
-      not to cause subtle errors by trying to infer where the element
-      ends.  Elements which normally do not have closing tags in
-      HTML, such as image and input elements, are not required to have
-      a closing tag, or to use the XHTML '<tag />' form.
-
-      Certain boolean attributes, such as 'checked' and
-      'selected', are treated differently by 'tal:attributes'.
-      The value is treated as true or false (as defined by
-      'tal:condition').  The attribute is set to 'attr="attr"' in the
-      true case and omitted otherwise.  If the value is 'default', then
-      it is treated as true if the attribute already exists, and false if
-      it does not.  For example, each of the following lines::
-
-        <input type="checkbox" checked tal:attributes="checked default">
-        <input type="checkbox" tal:attributes="checked string:yes">
-        <input type="checkbox" tal:attributes="checked python:42">
-
-      ...will render as::
-
-        <input type="checkbox" checked="checked">
-
-      ...while each of these::
-
-        <input type="checkbox" tal:attributes="checked default">
-        <input type="checkbox" tal:attributes="checked string:">
-        <input type="checkbox" tal:attributes="checked nothing">
-
-      ...will render as::
-
-        <input type="checkbox">
-
-      This works correctly in all browsers in which it has been tested.

Added: zope2book/trunk/source/AppendixC.rst
===================================================================
--- zope2book/trunk/source/AppendixC.rst	                        (rev 0)
+++ zope2book/trunk/source/AppendixC.rst	2009-02-16 22:21:20 UTC (rev 96609)
@@ -0,0 +1,1380 @@
+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: Template Attribute Language (TAL),
+TAL Expression Syntax (TALES), and Macro Expansion TAL (METAL). It also
+describes some ZPT-specific behaviors that are not part of the standards.
+
+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.
+
+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.
+
+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.
+
+TAL Namespace
++++++++++++++
+
+The TAL namespace URI and recommended alias are currently defined
+as::
+
+  xmlns:tal="http://xml.zope.org/namespaces/tal"
+
+This is not a URL, but merely a unique identifier. Do not expect a browser to
+resolve it successfully.
+
+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.
+
+TAL Statements
+++++++++++++++
+
+These are the tal statements:
+
+- tal:attributes - dynamically change element attributes.
+
+- tal:define - define variables.
+
+- tal:condition - test conditions.
+
+- tal:content - replace the content of an element.
+
+- tal:omit-tag - remove an element, leaving the content of the element.
+
+- tal:on-error - handle errors.
+
+- tal:repeat - repeat an element.
+
+- tal:replace - replace the content of an element and remove the element
+  leaving the content.
+
+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.
+
+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.
+
+Any combination of statements may appear on the same elements, except that the
+`content` and `replace` statements may not appear together.
+
+Due to the fact that TAL sees statements as XML attributes, even in HTML
+documents, it cannot use the order in which statements are written in the tag
+to determine the order in which they are executed. TAL must also forbid
+multiples of the same kind of statement on a single element, so it is
+sufficient to arrange the kinds of statement in a precedence list.
+
+When an element has multiple statements, they are executed in this order:
+
+
+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. % XX Add: It may not be apparent that there needs to be
+an ordering. The reason that there must be one is that TAL is XML based. The
+XML specification specifically states that XML processors are free to rewrite
+the terms. In particular, you cannot assume that attributes of an XML statement
+will be processed in the order written, particularly if there is another
+preprocessor involved. To avoid needless proliferation of tags, and still
+permit unambigous execution of complex TAL, a precedence order was chosen
+according to the following rationalle.
+
+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.
+
+attributes: Replace element attributes
+======================================
+
+Syntax
+++++++
+
+tal:attributes syntax::
+
+  argument             ::= attribute_statement [';' attribute_statement]*
+  attribute_statement  ::= attribute_name expression
+  attribute_name       ::= [namespace-prefix ':'] Name
+  namespace-prefix     ::= Name
+
+*Note: If you want to include a semi-colon (;) in an `expression`, it must be
+escaped by doubling it (;;).*
+
+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.
+
+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.
+
+If you use `tal:attributes` on an element with an active `tal:replace` command,
+the `tal:attributes` statement is ignored.
+
+
+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.
+
+Examples
+++++++++
+
+Replacing a link::
+
+  <a href="/sample/link.html"
+     tal:attributes="href here/sub/absolute_url">
+
+Replacing two attributes::
+
+  <textarea
+    rows="80" cols="20"
+    tal:attributes="rows request/rows;cols request/cols">
+
+condition: Conditionally insert or remove an element
+====================================================
+
+Syntax
+++++++
+
+tal:condition syntax::
+
+  argument ::= expression
+
+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.
+
+*Note: Zope considers missing variables, None, zero, empty strings, and empty
+sequences false; all other values are true.*
+
+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>
+
+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>
+
+content: Replace the content of an element
+==========================================
+
+Syntax
+++++++
+
+tal:content syntax::
+
+  argument ::= (['text'] | 'structure') expression
+
+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.
+
+The default replacement behavior is `text`, which replaces angle-brackets and
+ampersands with their HTML entity equivalents. The `structure` 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.
+
+Examples
+++++++++
+
+Inserting the user name::
+
+  <p tal:content="user/getUserName">Fred Farkas</p>
+
+Inserting HTML/XML::
+
+  <p tal:content="structure here/getStory">
+    marked <b>up</b> content goes here.
+  </p>
+
+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
+
+*Note: If you want to include a semi-colon (;) in an `expression`, it must be
+escaped by doubling it (;;).*
+
+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.
+
+*Note: local variables are the default*
+
+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.
+
+Examples
+++++++++
+
+Defining a global variable::
+
+  tal:define="global company_name string:Zope Corp, Inc."
+
+Defining two variables, where the second depends on the first::
+
+  tal:define="mytitle template/title; tlen python:len(mytitle)"
+
+
+omit-tag: Remove an element, leaving its contents
+=================================================
+
+Syntax
+++++++
+
+tal:omit-tag syntax::
+
+  argument ::= [ expression ]
+
+Description
++++++++++++
+
+The `tal:omit-tag` statement leaves the contents of an element in place while
+omitting the surrounding start and end tags.
+
+If the expression evaluates to a *false* value, then normal processing of the
+element continues and the tags are not omitted. If the expression evaluates to
+a *true* value, or no expression is provided, the statement element is replaced
+with its contents.
+
+Zope treats empty strings, empty sequences, zero, None, and *nothing* as false.
+All other values are considered true, including *default*.
+
+Examples
+++++++++
+
+Unconditionally omitting a tag::
+
+  <div tal:omit-tag="" comment="This tag will be removed">
+    <i>...but this text will remain.</i>
+  </div>
+
+Conditionally omitting a tag::
+
+  <b tal:omit-tag="not:bold">
+    I may be bold.
+  </b>
+
+The above example will omit the `b` tag if the variable `bold` is false.
+
+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>
+
+
+on-error: Handle errors
+=======================
+
+Syntax
+++++++
+
+tal:on-error syntax::
+
+  argument ::= (['text'] | 'structure') expression
+
+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.
+
+A local variable `error` is set. This variable has these attributes:
+
+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.
+
+Examples
+++++++++
+
+Simple error message::
+
+  <b tal:on-error="string: Username is not defined!" 
+     tal:content="here/getUsername">Ishmael</b>
+
+Removing elements with errors::
+
+  <b tal:on-error="nothing"
+     tal:content="here/getUsername">Ishmael</b>
+
+Calling an error-handling script::
+
+  <div tal:on-error="structure here/errorScript">
+  ...
+  </div>
+
+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)
+
+
+repeat: Repeat an element
+=========================
+
+Syntax
+++++++
+
+tal:repeat syntax::
+
+  argument      ::= variable_name expression
+  variable_name ::= Name
+
+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.
+
+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.
+
+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`.
+
+
+The following information is available from the repeat variable:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- *index*- - repetition number, starting from zero.
+
+- *number*- - repetition number, starting from one.
+
+- *even*- - true for even-indexed repetitions (0, 2, 4, ...).
+
+- *odd*- - true for odd-indexed repetitions (1, 3, 5, ...).
+
+- *start*- - true for the starting repetition (index 0).
+
+- *end*- - true for the ending, or final, repetition.
+
+- *first*- - true for the first item in a group - see note below
+
+- *last*- - true for the last item in a group - see note below
+
+- *length*- - length of the sequence, which will be the total number of
+  repetitions.
+
+- *letter*- - repetition number as a lower-case letter: "a" - "z", "aa" - "az",
+  "ba" - "bz", ..., "za" - "zz", "aaa" - "aaz", and so forth.
+
+- *Letter*- - upper-case version of - *letter*- .
+
+- *roman*- - repetition number as a lower-case roman numeral: "i", "ii", "iii",
+  "iv", "v", etc.
+
+- *Roman*- - upper-case version of - *roman*- .
+
+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".
+
+With the exception of `start`, `end`, and `index`, all of the attributes of a
+repeat variable are methods. Thus, when you use a Python expression to access
+them, you must call them, as in "python:repeat['item'].length()".
+
+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".
+
+Examples
+++++++++
+
+Iterating over a sequence of strings::
+
+  <p tal:repeat="txt python: ('one', 'two', 'three')">
+    <span tal:replace="txt" />
+  </p>
+
+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>
+
+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>
+
+
+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>
+
+Note, the objects in the above example should already be sorted by meta-type.
+
+replace: Replace an element
+===========================
+
+Syntax
+++++++
+
+tal:replace syntax::
+
+  argument ::= (['text'] | 'structure') expression
+
+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 "&amp;" to
+"&amp;amp;", "&lt;" to "&amp;lt;", and "&gt;" to "&amp;gt;".
+
+If the value is *nothing*, then the element is simply removed. If the value is
+*default*, then the element is left unchanged.
+
+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>
+
+Inserting HTML/XML::
+
+  <div tal:replace="structure table" />
+
+Inserting nothing::
+
+  <div tal:replace="nothing">
+    This element is a comment.
+  </div>
+
+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.
+
+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
+
+Here are some simple examples::
+
+  a/b/c
+  path:a/b/c
+  nothing
+  path:nothing
+  python: 1 + 2
+  string:Hello, ${user/getUserName}
+
+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.
+
+If you do not specify a prefix, Zope assumes that the expression is a *path*
+expression.
+
+TALES Expression Types
+++++++++++++++++++++++
+
+These are the TALES expression types supported by Zope:
+
+- path expressions - locate a value by its path.
+
+- exists expressions - test whether a path is valid.
+
+- nocall expressions - locate an object by its path.
+
+- not expressions - negate an expression
+
+- string expressions - format a string
+
+- python expressions - execute a Python expression
+
+Built-in Names
+++++++++++++++
+
+These are the names always available to TALES expressions in Zope:
+
+- *nothing*- - special value used by to represent a - *non-value*- (e.g. void,
+  None, Nil, NULL).
+
+- *default*- - special value used to specify that existing text should not be
+  replaced. See the documentation for individual TAL statements for details on
+  how they interpret - *default*- .
+
+- *options*- - the - *keyword*- arguments passed to the template. These are
+  generally available when a template is called from Methods and Scripts,
+  rather than from the web.
+
+- *repeat*- - the repeat variables; see the tal:repeat documentation.
+
+- *attrs*- - a dictionary containing the initial values of the attributes of
+  the current statement tag.
+
+- *CONTEXTS*- - the list of standard names (this list). This can be used to
+  access a built-in variable that has been hidden by a local or global variable
+  with the same name.
+
+- *root*- - the system's top-most object: the Zope root folder.
+
+- *here*- - the object to which the template is being applied.
+
+- *container*- - The folder in which the template is located.
+
+- *template*- - the template itself.
+
+- *request*- - the publishing request object.
+
+- *user*- - the authenticated user object.
+
+- *modules*- - a collection through which Python modules and packages can be
+  accessed. Only modules which are approved by the Zope security policy can be
+  accessed.
+
+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.
+
+TALES Exists expressions
+========================
+
+Syntax
+++++++
+
+Exists expression syntax::
+
+  exists_expressions ::= 'exists:' path_expression
+
+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.
+
+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>
+
+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.
+
+TALES Nocall expressions
+========================
+
+Syntax
+++++++
+
+Nocall expression syntax::
+
+  nocall_expression ::= 'nocall:' path_expression
+
+Description
++++++++++++
+
+Nocall expressions avoid rendering the results of a path expression.
+
+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.
+
+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>
+
+Using nocall expressions on a functions::
+
+  <p tal:define="join nocall:modules/string/join">
+
+This example defines a variable:: `join` which is bound to the `string.join`
+function.
+
+TALES Not expressions
+=====================
+
+Syntax
+++++++
+
+Not expression syntax::
+
+  not_expression ::= 'not:' expression
+
+Description
++++++++++++
+
+Not expression evaluates 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:
+
+1. the number 0 is *false*
+
+2. positive and negative numbers 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* to be
+*true*.
+
+Examples
+++++++++
+
+Testing a sequence::
+
+  <p tal:condition="not:here/objectIds">
+    There are no contained objects.
+  </p>
+
+TALES Path expressions
+======================
+
+Syntax
+++++++
+
+Path expression syntax::
+
+  PathExpr    ::= Path [ '|' Expression ]
+  Path        ::= variable [ '/' PathSegment ]*
+  variable    ::= Name
+  PathSegment ::= ( '?' variable ) | PathChar+
+  PathChar    ::= AlphaNumeric | ' ' | '_' | '-' | '.' | ',' | '~'
+
+Description
++++++++++++
+
+A path expression consists of a *path* optionally followed by a vertical bar
+(|) and alternate expression. A path consists of one or more non-empty strings
+separated by slashes. The first string must be a variable name (a 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.
+
+A limited amount of indirection is possible by using a variable name prefixed
+with `?` as a path segment. The variable must contain a string, which replaces
+that segment before the path is traversed.
+
+For example::
+
+  request/cookies/oatmeal
+  nothing
+  here/some-file 2001_02.html.tar.gz/foo
+  root/to/branch | default
+  request/name | string:Anonymous Coward
+  here/?tname/macros/?mname
+
+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).
+
+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.
+
+If a traversal step fails, and no alternate expression has been specified, an
+error results. Otherwise, the alternate expression is evaluated.
+
+The alternate expression can be any TALES expression. For example::
+
+  request/name | string:Anonymous Coward
+
+is a valid path expression. This is useful chiefly for providing default
+values, such as strings and numbers, which are not expressable as path
+expressions. Since the alternate expression can be a path expression, it is
+possible to "chain" path expressions, as in::
+
+  first | second | third | nothing
+
+If no path is given the result is *nothing*.
+
+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. Variable names are looked up first
+in locals, then in globals, then in the built-in list, so the built-in
+variables 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).
+
+Examples
+++++++++
+
+Inserting a cookie variable or a property::
+
+  <span tal:replace="request/cookies/pref | here/pref">
+    preference
+  </span>
+
+Inserting the user name::
+
+  <p tal:content="user/getUserName">
+    User name
+  </p>
+
+TALES Python expressions
+========================
+
+Syntax
+++++++
+
+Python expression syntax::
+
+  Any valid Python language expression
+
+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.
+
+Security Restrictions
+~~~~~~~~~~~~~~~~~~~~~
+
+Python expressions are subject to the same security restrictions as
+Python-based scripts. These restrictions include:
+
+
+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.
+
+Built-in Functions
+~~~~~~~~~~~~~~~~~~
+
+Python expressions have the same built-ins as Python-based Scripts with a few
+additions.
+
+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
+
+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.
+
+These functions are available in Python expressions, but not in Python-based
+scripts:
+
+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:
+
+string
+  The standard `Python string module
+  <http://www.python.org/doc/current/lib/module-string.html>`_ Note: most of
+  the functions in the module are also available as methods on string objects.
+
+random
+
+The standard 
+  `Python random module
+  <http://www.python.org/doc/current/lib/module-random.html>`_
+
+math
+  The standard `Python math module
+  <http://www.python.org/doc/current/lib/module-math.html>`_ .
+
+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>
+
+String processing (capitalize the user name)::
+
+  <p tal:content="python:user.getUserName().capitalize()">
+    User Name
+  </p>
+
+Basic math (convert an image size to megabytes)::
+
+  <p tal:content="python:image.getSize() / 1048576.0">
+    12.2323
+  </p>
+
+String formatting (format a float to two decimal places)::
+
+  <p tal:content="python:'%0.2f' % size">
+    13.56
+  </p>
+
+TALES String expressions
+========================
+
+Syntax
+++++++
+
+String expression syntax::
+
+  string_expression ::= ( plain_string | [ varsub ] )*
+  varsub            ::= ( '$' Path ) | ( '${' Path '}' )
+  plain_string      ::= ( '$$' | non_dollar )*
+  non_dollar        ::= any character except '$'
+
+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 `$$`.
+
+Examples
+++++++++
+
+Basic string formatting::
+
+  <span tal:replace="string:$this and $that">
+    Spam and Eggs
+  </span>
+
+Using paths::
+
+  <p tal:content="string:total: ${request/form/total}">
+    total: 12
+  </p>
+
+Including a dollar sign::
+
+  <p tal:content="string:cost: $$$cost">
+    cost: $42.00
+  </p>
+
+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.
+
+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
+
+METAL Namespace
++++++++++++++++
+
+The METAL namespace URI and recommended alias are currently defined as::
+
+  xmlns:metal="http://xml.zope.org/namespaces/metal"
+
+Just like the TAL namespace URI, this URI is not attached to a web page; it's
+just a unique identifier.
+
+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.
+
+METAL Statements
+++++++++++++++++
+
+METAL defines a number of statements:
+
+- metal:define-macro - Define a macro.
+
+- metal:use-macro - Use a macro.
+
+- metal:define-slot - Define a macro customization point.
+
+- metal:fill-slot - Customize a macro.
+
+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.
+
+define-macro: Define a macro
+============================
+
+Syntax
+++++++
+
+metal:define-macro syntax::
+
+  argument ::= Name
+
+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.
+
+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
+
+Examples
+++++++++
+
+Simple macro definition::
+
+  <p metal:define-macro="copyright">
+    Copyright 2009, <em>Foobar</em> Inc.
+  </p>
+
+
+define-slot: Define a macro customization point
+===============================================
+
+Syntax
+++++++
+
+metal:define-slot syntax::
+
+  argument ::= Name
+
+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.
+
+The `metal:define-slot` statement must be used inside a `metal:define-macro`
+statement.
+
+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>
+
+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.
+
+fill-slot: Customize a macro
+============================
+
+Syntax
+++++++
+
+metal:fill-slot syntax::
+
+  argument ::= Name
+
+Description
++++++++++++
+
+The `metal:fill-slot` statement customizes a macro by replacing a *slot* in the
+macro with the statement element (and its content).
+
+The `metal:fill-slot` statement must be used inside a `metal:use-macro`
+statement. 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.
+
+Examples
+++++++++
+
+Given this macro::
+
+  <p metal:define-macro="hello">
+    Hello <b metal:define-slot="name">World</b>
+  </p>
+
+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>
+
+use-macro: Use a macro
+======================
+
+Syntax
+++++++
+
+metal:use-macro syntax::
+
+  argument ::= expression
+
+Description
++++++++++++
+
+The `metal:use-macro` statement replaces the statement element with a macro.
+The statement expression describes a macro definition.
+
+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.
+
+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.
+
+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.
+
+Examples
+++++++++
+
+Basic macro usage::
+
+  <p metal:use-macro="container/other.html/macros/header">
+    header macro from defined in other.html template
+  </p>
+
+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.
+
+ZPT-specific Behaviors
+======================
+
+The behavior of Zope Page Templates is almost completely described by the TAL,
+TALES, and METAL specifications. ZPTs do, however, have a few additional
+features that are not described in the standards.
+
+HTML Support Features
++++++++++++++++++++++
+
+When the content-type of a Page Template is set to `text/html`, Zope processes
+the template somewhat differently than with any other content-type. As
+mentioned under TAL Namespace, HTML documents are not required to declare
+namespaces, and are provided with `tal` and `metal` namespaces by default.
+
+HTML documents are parsed using a non-XML parser that is somewhat more
+forgiving of malformed markup. In particular, elements that are often written
+without closing tags, such as paragraphs and list items, are not treated as
+errors when written that way, unless they are statement elements. This laxity
+can cause a confusing error in at least one case; a `<div>` element is
+block-level, and therefore technically not allowed to be nested in a `<p>`
+element, so it will cause the paragraph to be implicitly closed. The closing
+`</p>` tag will then cause a NestingError, since it is not matched up with the
+opening tag. The solution is to use `<span>` instead.
+
+Unclosed statement elements are always treated as errors, so as not to cause
+subtle errors by trying to infer where the element ends. Elements which
+normally do not have closing tags in HTML, such as image and input elements,
+are not required to have a closing tag, or to use the XHTML `<tag />` form.
+
+Certain boolean attributes, such as `checked` and `selected`, are treated
+differently by `tal:attributes`. The value is treated as true or false (as
+defined by `tal:condition`). The attribute is set to `attr="attr"` in the true
+case and omitted otherwise. If the value is `default`, then it is treated as
+true if the attribute already exists, and false if it does not. For example,
+each of the following lines::
+
+  <input type="checkbox" checked tal:attributes="checked default">
+  <input type="checkbox" tal:attributes="checked string:yes">
+  <input type="checkbox" tal:attributes="checked python:42">
+
+will render as::
+
+  <input type="checkbox" checked="checked">
+
+while each of these::
+
+  <input type="checkbox" tal:attributes="checked default">
+  <input type="checkbox" tal:attributes="checked string:">
+  <input type="checkbox" tal:attributes="checked nothing">
+
+will render as::
+
+  <input type="checkbox">
+
+This works correctly in all browsers in which it has been tested.
+

Modified: zope2book/trunk/source/index.rst
===================================================================
--- zope2book/trunk/source/index.rst	2009-02-16 21:30:29 UTC (rev 96608)
+++ zope2book/trunk/source/index.rst	2009-02-16 22:21:20 UTC (rev 96609)
@@ -36,6 +36,7 @@
    MaintainingZope.rst
    AppendixA.rst
    AppendixB.rst
+   AppendixC.rst
    AppendixD.rst
    AppendixE.rst
    Contributions.rst



More information about the Checkins mailing list