[ZPT] CVS: Products/PageTemplates/help - tal-omit-tag.stx:1.1 tales-no-call.stx:1.1 tales-not.stx:1.1 tales-path.stx:1.1 tales-python.stx:1.1 tales-string.stx:1.1 tales.stx:1.1 tal.stx:1.2

[Amos Latteier]

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

Modified Files:
	tal.stx 
Added Files:
	tal-omit-tag.stx tales-no-call.stx tales-not.stx 
	tales-path.stx tales-python.stx tales-string.stx tales.stx 
Log Message:
a little more work on tal reference (forgot omit-tag)and a first cut at tales reference.

=== Added File Products/PageTemplates/help/tal-omit-tag.stx ===
omit-tag - Remove an element, leaving its contents

  Syntax

    XXX

  Description

    XXX

  Examples

    XXX

=== Added File Products/PageTemplates/help/tales-no-call.stx ===
TALES No call expressions

  Syntax

    XXX

  Description

    XXX

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

  Syntax

    XXX

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


=== 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. The semantics of traversal
    (and what it means to be callable) are implementation-dependent.

    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 explicitely by prefixing them with
    *CONTEXTS*. (e.g. CONTEXTS/root, CONTEXTS/nothing, etc).

  Examples

    XXX







=== Added File Products/PageTemplates/help/tales-python.stx ===
TALES Python expressions

  Syntax

    XXX

  Description
  
    XXX

  Examples

    XXX

=== 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
    '${name}', where 'name' 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

    XXX

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

  The *Template Attribute Language Expression Syntax* (TALES) standard
  describes expressions that suppy "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:

    * "no-call":tales-no-call.stx expression - don't call a value

    * "not:tales-not.stx expressions - negate a value
  
    * "string":tales-string.stx expressions - format a string

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

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

  Built-in Names

   These are the names that are built-in the TALES in Zope:

   - *nothing* - special singleton value used by TAL to represent 
      a *non-value* (e.g. void, None, Nil, NULL).

   - *default* - special singleton value used by TAL to specify that
     existing text should not be replaced.

   - *options* - the *keyword* arguments passed to the template.

   - *repeat* - the 'repeat' variables (see RepeatVariable).

   - *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 builtin variable that has been hidden by a local
     or global variable with the same name.

   - *root* - the system's top-most object.

   - *here* - the object to which the template is being applied.

   - *container* - the template's container object.

   - *template* - the template itself.

   - *request* - the publishing request object.

   - *user* - the authenticated user object.

   - *modules* - a collection through which all Python modules and
     packages can be accessed.  Some or many of these may not be
     usable in TALES, however, depending on the security policies
     of the template's implementation.

    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

    "no-call":tales-no-call.stx expression

    "not:tales-not.stx expressions
  
    "string":tales-string.stx expressions

    "path":tales-path.stx expressions

    "python":tales-python.stx expressions
  

=== Products/PageTemplates/help/tal.stx 1.1 => 1.2 ===
 
-  The *Template Attribute Language* is an attribute language used to
-  create dynamic templates.  It allows elements of a document to be
-  replaced, repeated, or omitted.
+  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
@@ -16,21 +16,45 @@
   expressions are not part of TAL. TALES is recommended for this
   purpose.
 
-  The TAL namespace URI and recommended alias are currently defined
-  as::
+  TAL Namespace
 
-    xmlns:tal="http://xml.zope.org/namespaces/tal"
+    The TAL namespace URI and recommended alias are currently defined
+    as::
 
-  This is not a URL, but merely a unique identifier.  Do not expect a
-  browser to resolve it successfully.
+      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* (see [TALES]) that is not a string.
-    In particular, this value is useful for deleting elements or
+    define a value named *nothing* that is not a string.  In
+    particular, this value is useful for deleting elements or
     attributes.
 
   Order of Operations
@@ -47,17 +71,17 @@
     When an element has multiple statements, they are executed in this
     order:
 
-	- 'define'
+    1. 'define'
 
-	- 'condition'
+    2. 'condition'
 
-	- 'repeat'
+    3. 'repeat'
 
-	- 'content' or 'replace'
+    4. 'content' or 'replace'
 
-	- 'attributes'
+    5. 'attributes'
 
-	- 'omit-tag'
+    6. 'omit-tag'
 
     Since the 'on-error' statement is only invoked when an error occurs,
     it does not appear in the list.  
@@ -77,4 +101,20 @@
   See Also
 
     "TALES Overview":tales.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