Fri, 12 Oct 2001 15:46:33 -0400

Update of /cvs-repository/Products/PageTemplates/help
In directory cvs.zope.org:/tmp/cvs-serv4471

Added Files:
      Tag: zpt-1_4_0
	PageTemplate_Edit.stx metal-define-macro.stx 
	metal-define-slot.stx metal-fill-slot.stx metal-use-macro.stx 
	metal.stx tal-attributes.stx tal-condition.stx tal-content.stx 
	tal-define.stx tal-omit-tag.stx tal-on-error.stx 
	tal-repeat.stx tal-replace.stx tal.stx tales-exists.stx 
	tales-nocall.stx tales-not.stx tales-path.stx tales-python.stx 
	tales-string.stx tales.stx 
Log Message:
Add help to branch.

=== Added File Products/PageTemplates/help/PageTemplate_Edit.stx ===
Edit View: Edit A Page Template

    Description

        This view allows you to edit the template's text, upload new
        text, or change the content type and title of the template.

    Template Text

        The text in a template must be well-formed HTML if the content
        type is 'text/html'.  Otherwise, it must be well-formed XML.
        Either way, it may include "TAL":tal.stx or "METAL":metal.stx
        markup containing "TALES":tales.stx expressions.

    Controls

        'Title' -- Allows you to specify the Zope title of the template.

        'Content-Type' -- Allows you to specify the content-type that
        will be given to renderings of this template.

    Buttons and Other Form Elements

        'Save Changes' -- saves changes you make to the body, title, or
          content type.

        'Taller'/'Shorter'/'Wider'/'Narrower' -- make the body textarea
          taller, shorter, wider, or narrower.

        'File' -- upload a file into this template.

    File Upload Details

        Files uploaded into a template must be valid HTML or XML text.

=== Added File Products/PageTemplates/help/metal-define-macro.stx ===
metal: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 2001, <em>Foobar</em> Inc.
      </p>

  See Also

    "metal:use-macro":metal-use-macro.stx

    "metal:define-slot":metal-define-slot.stx

=== Added File Products/PageTemplates/help/metal-define-slot.stx ===
metal: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.

  See Also

    "metal:fill-slot":metal-fill-slot.stx

=== Added File Products/PageTemplates/help/metal-fill-slot.stx ===
metal: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>

  See Also

    "metal:define-slot":metal-define-slot.stx

=== Added File Products/PageTemplates/help/metal-use-macro.stx ===
metal: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":metal-define-slot.stx 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-define-macro.stx

    "metal:fill-slot":metal-fill-slot.stx

=== Added File Products/PageTemplates/help/metal.stx ===
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":tal.stx and
  "TALES":tales.stx.

  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.

  METAL Statements 

    METAL defines a number of statements:

    * "metal:define-macro":metal-define-macro.stx - Define a macro.

    * "metal:use-macro":metal-use-macro.stx - Use a macro.

    * "metal:define-slot":metal-define-slot.stx - Define a macro
    customization point.

    * "metal:fill-slot":metal-fill-slot.stx - 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":tales.stx.

  See Also

    "TAL Overview":tal.stx

    "TALES Overview":tales.stx

    "metal:define-macro":metal-define-macro.stx

    "metal:use-macro":metal-use-macro.stx

    "metal:define-slot":metal-define-slot.stx

    "metal:fill-slot":metal-fill-slot.stx

=== Added File Products/PageTemplates/help/tal-attributes.stx ===
tal:attributes - Replace element attributes

  Syntax

    'tal:attributes' syntax::

      argument             ::= attribute_statement [';' attribute_statement]*
      attribute_statement  ::= attribute_name expression
      attribute_name       ::= [namespace ':'] Name
      namespace            ::= 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">

=== Added File Products/PageTemplates/help/tal-condition.stx ===
tal: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 for variable before inserting it::

      <p tal:condition="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>

=== Added File Products/PageTemplates/help/tal-content.stx ===
tal: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.

    *Note: The default replacement behavior is 'text'.*

  Examples

    Inserting the user name::

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

    Inserting HTML/XML::

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

  See Also

    "'tal:replace'":tal-replace.stx

=== Added File Products/PageTemplates/help/tal-define.stx ===
tal: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)"

=== Added File Products/PageTemplates/help/tal-omit-tag.stx ===
tal: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 a tag in place
    while omitting the surrounding start and end tag.

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

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

  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>

=== Added File Products/PageTemplates/help/tal-on-error.stx ===
tal: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

=== Added File Products/PageTemplates/help/tal-repeat.stx ===
tal: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 *length* - length of the sequence, which will be the total number
        of repetitions.

      o *letter* - count reps with lower-case letters: "a" - "z", "aa" - "az",
        "ba" - "bz", ..., "za" - "zz", "aaa" - "aaz", and so forth.

      o *Letter* - upper-case version of *letter*.

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

  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>

=== Added File Products/PageTemplates/help/tal-replace.stx ===
tal: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'":tal-content.stx

=== Added File Products/PageTemplates/help/tal.stx ===
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.

  TAL Statements   

    These are the tal statements:

    - "tal:attributes":tal-attributes.stx - dynamically change
      element attributes.

    - "tal:define":tal-define.stx - define variables.

    - "tal:condition":tal-condition.stx - test conditions.

    - "tal:content":tal-content.stx - replace the content of an
      element.

    - "tal:omit-tag":tal-omit-tag.stx - remove an element, leaving
      the content of the element.

    - "tal:on-error":tal-on-error.stx - handle errors.

    - "tal:repeat":tal-repeat.stx - repeat an element.

    - "tal:replace":tal-replace.stx - 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.

    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.  

    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":tales.stx

    "METAL Overview":metal.stx

    "tal:attributes":tal-attributes.stx

    "tal:define":tal-define.stx

    "tal:condition":tal-condition.stx

    "tal:content":tal-content.stx

    "tal:omit-tag":tal-omit-tag.stx

    "tal:on-error":tal-on-error.stx

    "tal:repeat":tal-repeat.stx

    "tal:replace":tal-replace.stx

=== Added File Products/PageTemplates/help/tales-exists.stx ===
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.

=== Added File Products/PageTemplates/help/tales-nocall.stx ===
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.

=== Added File Products/PageTemplates/help/tales-not.stx ===
TALES Not expressions

  Syntax

    Not expression syntax::

      not_expression ::= 'not:' expression

  Description

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

    1. the number 0 is *false*

    2. numbers > 0 are *true*

    3. an empty string or other sequence is *false*

    4. a non-empty string or other sequence is *true*

    5. a *non-value* (e.g. void, None, Nil, NULL, etc) is *false*

    6. all other values are implementation-dependent.

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

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

  Examples

    Testing a sequence::

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

=== Added File Products/PageTemplates/help/tales-path.stx ===
TALES Path expressions

  Syntax

    Path expression syntax::

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

  Description

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

    For example::

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

    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, evaluation immediately proceeds to the next
    path.  If there are no further paths, an error results.

    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.  Since variable names are looked up first in locals,
    then in globals, then in this list, these names act just like
    built-ins in Python; They are always available, but they can be
    shadowed by a global or local variable declaration. You can always
    access the built-in names explicitly by prefixing them with
    *CONTEXTS*. (e.g. CONTEXTS/root, CONTEXTS/nothing, etc).

  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>

=== Added File Products/PageTemplates/help/tales-python.stx ===
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.  See The Zope Book for more information.

    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":/Control_Panel/Products/OFSP/Help/DateTime.py,
      'test', and 'same_type'.

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

      'path(string)' -- Evaluate a TALES "path":tales-path.stx
      expression.

      'string(string)' -- Evaluate a TALES "string":tales-string.stx
      expression.

      'exists(string)' -- Evaluates a TALES "exists":tales-exists.stx
      expression.

      'nocall(string)' -- Evaluates a TALES "nocall":tales-nocall.stx
      expression.

    Python Modules

      A number of Python modules are available by default. You can
      make more modules available. See XXX for more information. 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 XXX
      for more information.

      'Products.PythonScripts.standard' -- Various HTML formatting
      functions available in DTML. See XXX for more information.

      'ZPTUtils.Batch' -- Batch processing facilities similar to those
      offered by 'dtml-in'. See XXX for more information.

      'ZTUtils.Tree' -- Tree processing facilities similar to those
      offered by 'dtml-tree'. See XXX for more information.

      'ZTUtils.SimpleTree' -- Simplified tree processing facilities
      similar to those offered by 'dtml-tree'. See XXX for more
      information.

      'AccessControl.XXX' -- XXX what is available from this package?

  Examples

    Basic module usage::

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

=== Added File Products/PageTemplates/help/tales-string.stx ===
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":tales-path.stx.
    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>

    Including a dollar sign::

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

=== Added File Products/PageTemplates/help/tales.stx ===
TALES Overview

  The *Template Attribute Language Expression Syntax* (TALES) standard
  describes expressions that supply "TAL":tal.stx and
  "METAL":metal.stx 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":tales-path.stx expressions - locate a value by its path.

    * "exists":tales-exists.stx expressions - test whether a path is valid.

    * "nocall":tales-nocall.stx expressions - locate an object by its path.

    * "not":tales-not.stx expressions - negate an expression

    * "string":tales-string.stx expressions - format a string

    * "python":tales-python.stx expressions - execute a Python
      expression

  Built-in Names

    These are the names that 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":tal-repeat.stx 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":tal.stx

    "METAL Overview":metal.stx

    "exists":tales-exists.stx expressions

    "nocall":tales-nocall.stx expressions

    "not":tales-not.stx expressions

    "string":tales-string.stx expressions

    "path":tales-path.stx expressions

    "python":tales-python.stx expressions