[Checkins] SVN: zope2book/trunk/source/AppendixA.rst Finished DTML reference

Hanno Schlichting plone at hannosch.info
Wed Feb 11 09:44:28 EST 2009


Log message for revision 96447:
  Finished DTML reference
  

Changed:
  U   zope2book/trunk/source/AppendixA.rst

-=-
Modified: zope2book/trunk/source/AppendixA.rst
===================================================================
--- zope2book/trunk/source/AppendixA.rst	2009-02-11 13:30:59 UTC (rev 96446)
+++ zope2book/trunk/source/AppendixA.rst	2009-02-11 14:44:28 UTC (rev 96447)
@@ -505,6 +505,7 @@
 -------------
 
 Current Item Variables
+++++++++++++++++++++++
 
 These variables describe the current item.
 
@@ -574,10 +575,11 @@
   The index of a variable of the current item.
 
 Summary Variables
++++++++++++++++++
 
-These variable summarize information about numeric item
-variables. To use these variable you must loop over objects
-(like database query results) that have numeric variables.
+These variable summarize information about numeric item variables. To use these
+variable you must loop over objects (like database query results) that have
+numeric variables.
 
 - total-*variable*
 
@@ -616,6 +618,7 @@
   The standard-deviation of an item variable with n degrees of freedom.
 
 Grouping Variables
+++++++++++++++++++
 
 These variables allow you to track changes in current item variables.
 
@@ -628,6 +631,7 @@
   True if the current item is the last with a particular value for a variable.
 
 Batch Variables
++++++++++++++++
 
 - sequence-query
 
@@ -823,7 +827,7 @@
 See Also
 --------
 
-  with tag
+with tag
 
 mime: Formats data with MIME
 ============================
@@ -850,41 +854,55 @@
 
 Both the 'mime' and 'boundry' tags have the same attributes.
 
-XXX Here we need to continue
+- encode=string
 
-  encode=string -- MIME Content-Transfer-Encoding header, defaults
-  to 'base64'.  Valid encoding options include 'base64',
-  'quoted-printable', 'uuencode', 'x-uuencode', 'uue', 'x-uue',
-  and '7bit'.  If the 'encode' attribute is set to '7bit' no
-  encoding is done on the block and the data is assumed to be in a
-  valid MIME format.
+  MIME Content-Transfer-Encoding header, defaults to 'base64'. Valid encoding
+  options include 'base64', 'quoted-printable', 'uuencode', 'x-uuencode',
+  'uue', 'x-uue', and '7bit'. If the 'encode' attribute is set to '7bit' no
+  encoding is done on the block and the data is assumed to be in a valid MIME
+  format.
 
-  type=string -- MIME Content-Type header.
+- type=string
 
-  type_expr=string -- MIME Content-Type header as a variable
-  expression. You cannot use both 'type' and 'type_expr'.
+  MIME Content-Type header.
 
-  name=string -- MIME Content-Type header name.
+- type_expr=string
 
-  name_expr=string -- MIME Content-Type header name as a variable
-  expression. You cannot use both 'name' and 'name_expr'.
+  MIME Content-Type header as a variable expression. You cannot use both 'type'
+  and 'type_expr'.
 
-  disposition=string -- MIME Content-Disposition header.
+- name=string
 
-  disposition_expr=string -- MIME Content-Disposition header as a
-  variable expression. You cannot use both 'disposition' and
-  'disposition_expr'.
+  MIME Content-Type header name.
 
-  filename=string -- MIME Content-Disposition header filename.
+- name_expr=string
 
-  filename_expr=string -- MIME Content-Disposition header filename
-  as a variable expression. You cannot use both 'filename' and
-  'filename_expr'.
+  MIME Content-Type header name as a variable expression. You cannot use both
+  'name' and 'name_expr'.
 
-  skip_expr=string -- A variable expression that if true, skips
-  the block. You can use this attribute to selectively include
-  MIME blocks.
+- disposition=string
 
+  MIME Content-Disposition header.
+
+- disposition_expr=string
+
+  MIME Content-Disposition header as a variable expression. You cannot use both
+  'disposition' and 'disposition_expr'.
+
+- filename=string
+
+  MIME Content-Disposition header filename.
+
+- filename_expr=string
+
+  MIME Content-Disposition header filename as a variable expression. You cannot
+  use both 'filename' and 'filename_expr'.
+
+- skip_expr=string
+
+  A variable expression that if true, skips the block. You can use this
+  attribute to selectively include MIME blocks.
+
 Examples
 --------
 
@@ -914,36 +932,41 @@
 statement.
 
 Syntax
+------
 
-  'raise' tag syntax::
+'raise' tag syntax::
 
-    <dtml-raise ExceptionName|ExceptionExpression>
-    </dtml-raise>
+  <dtml-raise ExceptionName|ExceptionExpression>
+  </dtml-raise>
 
-  The 'raise' tag is a block tag. It raises an exception. Exceptions
-  can be an exception class or a string. The contents of the tag are
-  passed as the error value.
+The 'raise' tag is a block tag. It raises an exception. Exceptions
+can be an exception class or a string. The contents of the tag are
+passed as the error value.
 
 Examples
+--------
 
-  Raising a KeyError::
+Raising a KeyError::
 
-    <dtml-raise KeyError></dtml-raise>
+  <dtml-raise KeyError></dtml-raise>
 
-  Raising an HTTP 404 error::
+Raising an HTTP 404 error::
 
-    <dtml-raise NotFound>Web Page Not Found</dtml-raise>
+  <dtml-raise NotFound>Web Page Not Found</dtml-raise>
 
 See Also
+--------
 
-  try tag
+try tag
 
-  "Python Tutorial: Errors and
-  Exceptions":http://www.python.org/doc/current/tut/node10.html
+`Python Tutorial Errors and Exceptions`_
 
-  "Python Built-in
-  Exceptions":http://www.python.org/doc/current/lib/module-exceptions.html
+.. _Python Tutorial Errors and Exceptions: http://www.python.org/doc/current/tut/node10.html
 
+`Python Built-in Exceptions`_
+
+.. _Python Built-in Exceptions: http://www.python.org/doc/current/lib/module-exceptions.html
+
 return: Returns data
 ====================
 
@@ -951,769 +974,850 @@
 the Python 'return' statement.
 
 Syntax
+------
 
-  'return' tag syntax::
+'return' tag syntax::
 
-    <dtml-return ReturnVariable|expr="ReturnExpression">
+  <dtml-return ReturnVariable|expr="ReturnExpression">
 
-  Stops execution of DTML and returns a variable or expression. The
-  DTML output is not returned. Usually a return expression is more
-  useful than a return variable. Scripts largely obsolete this tag.
+Stops execution of DTML and returns a variable or expression. The
+DTML output is not returned. Usually a return expression is more
+useful than a return variable. Scripts largely obsolete this tag.
 
-    % Anonymous User - June 20, 2002 6:52 pm:
-     Reference Ch. 12 Scripting Zope http://www.zope.org/Documentation/ZopeBook/ScriptingZope.stx
-
 Examples
 
-  Returning a variable::
+Returning a variable::
 
-    <dtml-return result>    
+  <dtml-return result>
 
-  Returning a Python dictionary::
+Returning a Python dictionary::
 
-    <dtml-return expr="{'hi':200, 'lo':5}">
+  <dtml-return expr="{'hi':200, 'lo':5}">
 
 sendmail: Sends email with SMTP
 ===============================
 
-The 'sendmail' tag sends an email message
-using SMTP.
+The 'sendmail' tag sends an email message using SMTP.
 
 Syntax
+------
 
-  'sendmail' tag syntax::
+'sendmail' tag syntax::
 
-    <dtml-sendmail>
-    </dtml-sendmail>
+  <dtml-sendmail>
+  </dtml-sendmail>
 
-  The 'sendmail' tag is a block tag. It either requires a 'mailhost'
-  or a 'smtphost' argument, but not both. The tag block is sent as
-  an email message. The beginning of the block describes the email
-  headers. The headers are separated from the body by a blank
-  line. Alternately the 'To', 'From' and 'Subject' headers can be
-  set with tag arguments.
+The 'sendmail' tag is a block tag. It either requires a 'mailhost' or a
+'smtphost' argument, but not both. The tag block is sent as an email message.
+The beginning of the block describes the email headers. The headers are
+separated from the body by a blank line. Alternately the 'To', 'From' and
+'Subject' headers can be set with tag arguments.
 
 Attributes
+----------
 
-  mailhost -- The name of a Zope MailHost object
-  to use to send email. You cannot specify both a mailhost and a smtphost.
+- mailhost
 
-  smtphost -- The name of a SMTP server used to send email. You
-  cannot specify both a mailhost and a smtphost.
+  The name of a Zope MailHost object to use to send email. You cannot specify
+  both a mailhost and a smtphost.
 
-  port -- If the smtphost attribute is used, then the port attribute
-  is used to specify a port number to connect to. If not specified,
-  then port 25 will be used.
+- smtphost
 
-  mailto -- The recipient address or a list of recipient addresses
-  separated by commas. This can also be specified with the 'To' header.
+  The name of a SMTP server used to send email. You cannot specify both a
+  mailhost and a smtphost.
 
-  mailfrom -- The sender address. This can also be specified with
-  the 'From' header.
+- port
 
-  subject -- The email subject. This can also be specified with the
-  'Subject' header.
+  If the smtphost attribute is used, then the port attribute is used to specify
+  a port number to connect to. If not specified, then port 25 will be used.
 
+- mailto
+
+  The recipient address or a list of recipient addresses separated by commas.
+  This can also be specified with the 'To' header.
+
+- mailfrom
+
+  The sender address. This can also be specified with the 'From' header.
+
+- subject
+
+  The email subject. This can also be specified with the 'Subject' header.
+
 Examples
+--------
 
-  Sending an email message using a Mail Host::
+Sending an email message using a Mail Host::
 
-    <dtml-sendmail mailhost="mailhost">
-    To: <dtml-var recipient>
-    From: <dtml-var sender>
-    Subject: <dtml-var subject>
+  <dtml-sendmail mailhost="mailhost">
+  To: <dtml-var recipient>
+  From: <dtml-var sender>
+  Subject: <dtml-var subject>
 
-    Dear <dtml-var recipient>,
+  Dear <dtml-var recipient>,
 
-    You order number <dtml-var order_number> is ready.
-    Please pick it up at your soonest convenience.
-    </dtml-sendmail>
+  You order number <dtml-var order_number> is ready.
+  Please pick it up at your soonest convenience.
+  </dtml-sendmail>
 
 See Also
+--------
 
-  "RFC 821 (SMTP Protocol)":http://www.ietf.org/rfc/rfc0821.txt
+`RFC 821 (SMTP Protocol)`_
 
-  mime tag
+.. _RFC 821 (SMTP Protocol): http://www.ietf.org/rfc/rfc0821.txt
 
+mime tag
+
 sqlgroup: Formats complex SQL expressions
 =========================================
 
-The 'sqlgroup' tag formats complex boolean SQL expressions. You can
-use it along with the 'sqltest' tag to build dynamic SQL queries
-that tailor themselves to the environment. This tag is used in SQL
-Methods.
+The 'sqlgroup' tag formats complex boolean SQL expressions. You can use it
+along with the 'sqltest' tag to build dynamic SQL queries that tailor
+themselves to the environment. This tag is used in SQL Methods.
 
-  % Anonymous User - May 2, 2002 9:13 am:
-   there is a sql-delimiter not documented here
-
 Syntax
+------
 
-  'sqlgroup' tag syntax::
+'sqlgroup' tag syntax::
 
-    <dtml-sqlgroup>
-    [<dtml-or>]
-    [<dtml-and>]
-    ...
-    </dtml-sqlgroup>
+  <dtml-sqlgroup>
+  [<dtml-or>]
+  [<dtml-and>]
+  ...
+  </dtml-sqlgroup>
 
-  The 'sqlgroup' tag is a block tag. It is divided into blocks with
-  one or more optional 'or' and 'and' tags. 'sqlgroup' tags can be
-  nested to produce complex logic.
+The 'sqlgroup' tag is a block tag. It is divided into blocks with
+one or more optional 'or' and 'and' tags. 'sqlgroup' tags can be
+nested to produce complex logic.
 
 Attributes
+----------
 
-  required=boolean -- Indicates whether the group is required. If it
-  is not required and contains nothing, it is excluded from the DTML
-  output.
+- required=boolean
 
-  where=boolean -- If true, includes the string "where". This is
-  useful for the outermost 'sqlgroup' tag in a SQL 'select' query.
+  Indicates whether the group is required. If it is not required and contains
+  nothing, it is excluded from the DTML output.
 
+- where=boolean
+
+  If true, includes the string "where". This is useful for the outermost
+  'sqlgroup' tag in a SQL 'select' query.
+
 Examples
+--------
 
-  Sample usage::
+Sample usage::
 
-    select * from employees 
-    <dtml-sqlgroup where>
-      <dtml-sqltest salary op="gt" type="float" optional>
-    <dtml-and>
-      <dtml-sqltest first type="nb" multiple optional>
-    <dtml-and>
-      <dtml-sqltest last type="nb" multiple optional>
-    </dtml-sqlgroup>  
+  select * from employees 
+  <dtml-sqlgroup where>
+    <dtml-sqltest salary op="gt" type="float" optional>
+  <dtml-and>
+    <dtml-sqltest first type="nb" multiple optional>
+  <dtml-and>
+    <dtml-sqltest last type="nb" multiple optional>
+  </dtml-sqlgroup>  
 
-  If 'first' is 'Bob' and 'last' is 'Smith, McDonald' it renders::
+If 'first' is 'Bob' and 'last' is 'Smith, McDonald' it renders::
 
-    select * from employees
-    where
-    (first='Bob'
-     and
-     last in ('Smith', 'McDonald')
-    )
+  select * from employees
+  where
+  (first='Bob'
+   and
+   last in ('Smith', 'McDonald')
+  )
 
-  If 'salary' is 50000 and 'last' is 'Smith' it renders::
+If 'salary' is 50000 and 'last' is 'Smith' it renders::
 
-    select * from employees
-    where 
-    (salary > 50000.0
-     and
-     last='Smith'
-    )
+  select * from employees
+  where 
+  (salary > 50000.0
+   and
+   last='Smith'
+  )
 
-  Nested 'sqlgroup' tags::
+Nested 'sqlgroup' tags::
 
-    select * from employees
-    <dtml-sqlgroup where>
-      <dtml-sqlgroup>
-         <dtml-sqltest first op="like" type="nb">
-      <dtml-and>
-         <dtml-sqltest last op="like" type="nb">
-      <dtml-sqlgroup>
-    <dtml-or>
-      <dtml-sqltest salary op="gt" type="float">
+  select * from employees
+  <dtml-sqlgroup where>
+    <dtml-sqlgroup>
+       <dtml-sqltest first op="like" type="nb">
+    <dtml-and>
+       <dtml-sqltest last op="like" type="nb">
     </dtml-sqlgroup>
+  <dtml-or>
+    <dtml-sqltest salary op="gt" type="float">
+  </dtml-sqlgroup>
 
-    % Anonymous User - May 22, 2002 11:37 am:
-     Looks like the 3rd <dtml-sqlgroup> should be a close tag: </dtml-sqlgroup>
+Given sample arguments, this template renders to SQL like so::
 
-  Given sample arguments, this template renders to SQL like so::
-
-    select * form employees
-    where
+  select * form employees
+  where
+  (
     (
-      (
-       name like 'A*'
-       and
-       last like 'Smith'
-       )
-     or
-     salary > 20000.0
-    )
+     name like 'A*'
+     and
+     last like 'Smith'
+     )
+   or
+   salary > 20000.0
+  )
 
 See Also
+--------
 
-  sqltest tag
+sqltest tag
 
 sqltest: Formats SQL condition tests
 ====================================
 
-The 'sqltest' tag inserts a condition test into SQL code. It tests a
-column against a variable. This tag is used in SQL Methods.
+The 'sqltest' tag inserts a condition test into SQL code. It tests a column
+against a variable. This tag is used in SQL Methods.
 
 Syntax
+------
 
-  'sqltest' tag syntax::
+'sqltest' tag syntax::
 
-    <dtml-sqltest Variable|expr="VariableExpression">
+  <dtml-sqltest Variable|expr="VariableExpression">
 
-  The 'sqltest' tag is a singleton. It inserts a SQL condition test
-  statement. It is used to build SQL queries. The 'sqltest' tag
-  correctly escapes the inserted variable. The named variable or
-  variable expression is tested against a SQL column using the
-  specified comparison operation.
+The 'sqltest' tag is a singleton. It inserts a SQL condition test statement. It
+is used to build SQL queries. The 'sqltest' tag correctly escapes the inserted
+variable. The named variable or variable expression is tested against a SQL
+column using the specified comparison operation.
 
 Attributes
+----------
 
-  type=string -- The type of the variable. Valid types include:
-  'string', 'int', 'float' and 'nb'. 'nb' means non-blank string,
-  and should be used instead of 'string' unless you want to test for
-  blank values. The type attribute is required and is used to
-  properly escape inserted variable.
+- type=string
 
-  column=string -- The name of the SQL column to test against. This
-  attribute defaults to the variable name.
+  The type of the variable. Valid types include: 'string', 'int', 'float' and
+  'nb'. 'nb' means non-blank string, and should be used instead of 'string'
+  unless you want to test for blank values. The type attribute is required and
+  is used to properly escape inserted variable.
 
-  multiple=boolean -- If true, then the variable may be a sequence
-  of values to test the column against.
+- column=string
 
-  optional=boolean -- If true, then the test is optional and will
-  not be rendered if the variable is empty or non-existent.
+  The name of the SQL column to test against. This attribute defaults to the
+  variable name.
 
-  op=string -- The comparison operation. Valid comparisons include: 
+- multiple=boolean
 
-    eq -- equal to
+  If true, then the variable may be a sequence of values to test the column
+  against.
 
-    gt -- greater than
+- optional=boolean
 
-    lt -- less than
+  If true, then the test is optional and will not be rendered if the variable
+  is empty or non-existent.
 
-    ne -- not equal to
+- op=string
 
-    ge -- greater than or equal to
+  The comparison operation. Valid comparisons include: 
 
-    le -- less than or equal to
+  eq -- equal to
 
-    The comparison defaults to equal to. If the comparison is not
-    recognized it is used anyway. Thus you can use comparisons such
-    as 'like'.
+  gt -- greater than
 
+  lt -- less than
+
+  ne -- not equal to
+
+  ge -- greater than or equal to
+
+  le -- less than or equal to
+
+  The comparison defaults to equal to. If the comparison is not
+  recognized it is used anyway. Thus you can use comparisons such
+  as 'like'.
+
 Examples
+--------
 
-  Basic usage::
+Basic usage::
 
-    select * from employees
-      where <dtml-sqltest name type="nb">
+  select * from employees
+    where <dtml-sqltest name type="nb">
 
-  If the 'name' variable is 'Bob' then this renders::
+If the 'name' variable is 'Bob' then this renders::
 
-    select * from employees
-      where name = 'Bob'
+  select * from employees
+    where name = 'Bob'
 
-  Multiple values::
+Multiple values::
 
-    select * from employees
-      where <dtml-sqltest empid type=int multiple>
+  select * from employees
+    where <dtml-sqltest empid type=int multiple>
 
-  If the 'empid' variable is '(12,14,17)' then this renders::
+If the 'empid' variable is '(12,14,17)' then this renders::
 
-    select * from employees
-      where empid in (12, 14, 17)
+  select * from employees
+    where empid in (12, 14, 17)
 
 See Also
+--------
 
-  sqlgroup tag
+sqlgroup tag
 
-  sqlvar tag
+sqlvar tag
 
 sqlvar: Inserts SQL variables
 =============================
 
-The 'sqlvar' tag safely inserts variables into SQL code. This tag is
-used in SQL Methods.
+The 'sqlvar' tag safely inserts variables into SQL code. This tag is used in
+SQL Methods.
 
 Syntax
+------
 
-  'sqlvar' tag syntax::
+'sqlvar' tag syntax::
 
-    <dtml-sqlvar Variable|expr="VariableExpression">
+  <dtml-sqlvar Variable|expr="VariableExpression">
 
-  The 'sqlvar' tag is a singleton. Like the 'var' tag, the 'sqlvar'
-  tag looks up a variable and inserts it. Unlike the var tag, the
-  formatting options are tailored for SQL code.
+The 'sqlvar' tag is a singleton. Like the 'var' tag, the 'sqlvar' tag looks up
+a variable and inserts it. Unlike the var tag, the formatting options are
+tailored for SQL code.
 
 Attributes
+----------
 
-  type=string -- The type of the variable. Valid types include:
-  'string', 'int', 'float' and 'nb'. 'nb' means non-blank string and
-  should be used in place of 'string' unless you want to use blank
-  strings. The type attribute is required and is used to properly
-  escape inserted variable.
+- type=string
 
-  optional=boolean -- If true and the variable is null or
-  non-existent, then nothing is inserted.
+  The type of the variable. Valid types include: 'string', 'int', 'float' and
+  'nb'. 'nb' means non-blank string and should be used in place of 'string'
+  unless you want to use blank strings. The type attribute is required and is
+  used to properly escape inserted variable.
 
+- optional=boolean
+
+  If true and the variable is null or non-existent, then nothing is inserted.
+
 Examples
+--------
 
-  Basic usage::
+Basic usage::
 
-    select * from employees 
-      where name=<dtml-sqlvar name type="nb">
+  select * from employees 
+    where name=<dtml-sqlvar name type="nb">
 
-  This SQL quotes the 'name' string variable.
+This SQL quotes the 'name' string variable.
 
 See Also
+--------
 
-  sqltest tag
+sqltest tag
 
 tree: Inserts a tree widget
 ===========================
 
-The 'tree' tag displays a dynamic tree widget by querying Zope
-objects.
+The 'tree' tag displays a dynamic tree widget by querying Zope objects.
 
 Syntax
+------
 
-  'tree' tag syntax::
+'tree' tag syntax::
 
-    <dtml-tree [VariableName|expr="VariableExpression"]>
-    </dtml-tree>
+  <dtml-tree [VariableName|expr="VariableExpression"]>
+  </dtml-tree>
 
-  The 'tree' tag is a block tag. It renders a dynamic tree widget in
-  HTML. The root of the tree is given by variable name or
-  expression, if present, otherwise it defaults to the current
-  object. The 'tree' block is rendered for each tree node, with the
-  current node pushed onto the DTML namespace.
+The 'tree' tag is a block tag. It renders a dynamic tree widget in
+HTML. The root of the tree is given by variable name or
+expression, if present, otherwise it defaults to the current
+object. The 'tree' block is rendered for each tree node, with the
+current node pushed onto the DTML namespace.
 
-    % Anonymous User - July 15, 2002 10:50 pm:
-     This doesn't work for me (Zope 2.5.1) unless I give it the name of the root folder. <dtml-tree folder
-     [options]>, not <dtml-tree [options]>.
+Tree state is set in HTTP cookies. Thus for trees to work, cookies
+must be enabled. Also you can only have one tree per page.
 
-  Tree state is set in HTTP cookies. Thus for trees to work, cookies
-  must be enabled. Also you can only have one tree per page.
-
 Attributes
+----------
 
-  branches=string -- Finds tree branches by calling the named
-  method. The default method is 'tpValues' which most Zope objects
-  support. 
+- branches=string
 
-  branches_expr=string -- Finds tree branches by evaluating the
-  expression.
+  Finds tree branches by calling the named method. The default method is
+  'tpValues' which most Zope objects support.
 
-  id=string -- The name of a method or id to determine tree
-  state. It defaults to 'tpId' which most Zope objects support. This
-  attribute is for advanced usage only.
+- branches_expr=string
 
-  url=string -- The name of a method or attribute to determine tree
-  item URLs. It defaults to 'tpURL' which most Zope objects
-  support. This attribute is for advanced usage only.
+  Finds tree branches by evaluating the expression.
 
-  leaves=string -- The name of a DTML Document or Method used to
-  render nodes that don't have any children. Note: this document
-  should begin with '<dtml-var standard_html_header>' and end with
-  '<dtml-var standard_html_footer>' in order to ensure proper
-  display in the tree.
+- id=string
 
-  header=string -- The name of a DTML Document or Method displayed
-  before expanded nodes. If the header is not found, it is skipped.
+  The name of a method or id to determine tree state. It defaults to 'tpId'
+  which most Zope objects support. This attribute is for advanced usage only.
 
-  footer=string -- The name of a DTML Document or Method displayed
-  after expanded nodes. If the footer is not found, it is skipped.
+- url=string
 
-  nowrap=boolean -- If true then rather than wrap, nodes may be
-  truncated to fit available space.
+  The name of a method or attribute to determine tree item URLs. It defaults to
+  'tpURL' which most Zope objects support. This attribute is for advanced usage
+  only.
 
-  sort=string -- Sorts the branches by the named attribute.
+- leaves=string
 
-  reverse -- Reverses the order of the branches.
+  The name of a DTML Document or Method used to render nodes that don't have
+  any children. Note: this document should begin with '<dtml-var
+  standard_html_header>' and end with '<dtml-var standard_html_footer>' in
+  order to ensure proper display in the tree.
 
-  assume_children=boolean -- Assumes that nodes have children. This
-  is useful if fetching and querying child nodes is a costly
-  process. This results in plus boxes being drawn next to all nodes.
+- header=string
 
-  single=boolean -- Allows only one branch to be expanded at a
-  time. When you expand a new branch, any other expanded branches
-  close. 
+  The name of a DTML Document or Method displayed before expanded nodes. If the
+  header is not found, it is skipped.
 
-  skip_unauthorized -- Skips nodes that the user is unauthorized to
-  see, rather than raising an error.
+- footer=string
 
-  urlparam=string -- A query string which is included in the
-  expanding and contracting widget links. This attribute is for
-  advanced usage only.
+  The name of a DTML Document or Method displayed after expanded nodes. If the
+  footer is not found, it is skipped.
 
-  prefix=string -- Provide versions of the tag variables that start
-  with this prefix instead of "tree", and that use underscores
-  (_) instead of hyphens (-).  The prefix must start with a letter and
-  contain only alphanumeric characters and underscores (_).
+- nowrap=boolean
 
+  If true then rather than wrap, nodes may be truncated to fit available space.
+
+- sort=string
+
+  Sorts the branches by the named attribute.
+
+- reverse
+
+  Reverses the order of the branches.
+
+- assume_children=boolean
+
+  Assumes that nodes have children. This is useful if fetching and querying
+  child nodes is a costly process. This results in plus boxes being drawn next
+  to all nodes.
+
+- single=boolean
+
+  Allows only one branch to be expanded at a time. When you expand a new
+  branch, any other expanded branches close.
+
+- skip_unauthorized
+
+  Skips nodes that the user is unauthorized to see, rather than raising an
+  error.
+
+- urlparam=string
+
+  A query string which is included in the expanding and contracting widget
+  links. This attribute is for advanced usage only.
+
+- prefix=string
+
+  Provide versions of the tag variables that start with this prefix instead of
+  "tree", and that use underscores (_) instead of hyphens (-). The prefix must
+  start with a letter and contain only alphanumeric characters and underscores
+  (_).
+
 Tag Variables
+-------------
 
-  tree-item-expanded -- True if the current node is expanded.
+- tree-item-expanded
 
-  tree-item-url -- The URL of the current node.
+  True if the current node is expanded.
 
-  tree-root-url -- The URL of the root node.
+- tree-item-url
 
-  tree-level -- The depth of the current node. Top-level nodes have
-  a depth of zero.
+  The URL of the current node.
 
-  tree-colspan -- The number of levels deep the tree is being
-  rendered. This variable along with the 'tree-level' variable can
-  be used to calculate table rows and colspan settings when
-  inserting table rows into the tree table.
+- tree-root-url
 
-  tree-state -- The tree state expressed as a list of ids and
-  sub-lists of ids. This variable is for advanced usage only.
+  The URL of the root node.
 
+- tree-level
+
+  The depth of the current node. Top-level nodes have a depth of zero.
+
+- tree-colspan
+
+  The number of levels deep the tree is being rendered. This variable along
+  with the 'tree-level' variable can be used to calculate table rows and
+  colspan settings when inserting table rows into the tree table.
+
+- tree-state
+
+  The tree state expressed as a list of ids and sub-lists of ids. This variable
+  is for advanced usage only.
+
 Tag Control Variables
+---------------------
 
-  You can control the tree tag by setting
-  these variables.
+You can control the tree tag by setting these variables.
 
-    expand_all -- If this variable is true then the entire tree is
-    expanded. 
+- expand_all
 
-    collapse_all -- If this variable is true then the entire tree is
-    collapsed.
+  If this variable is true then the entire tree is expanded.
 
+- collapse_all
+
+  If this variable is true then the entire tree is collapsed.
+
 Examples
+--------
 
-  Display a tree rooted in the current object::
+Display a tree rooted in the current object::
 
-    <dtml-tree>
-      <dtml-var title_or_id>
-    </dtml-tree>
+  <dtml-tree>
+    <dtml-var title_or_id>
+  </dtml-tree>
 
-    % Anonymous User - June 4, 2002 8:00 am:
-     Is there a way to prevent the tree of showing the user folder?
-     And how can I change the order of the displayed folders?
+Display a tree rooted in another object, using a custom branches
+method::
 
-  Display a tree rooted in another object, using a custom branches
-  method::
+  <dtml-tree expr="folder.object" branches="objectValues">
+    Node id : <dtml-var getId>
+  </dtml-tree>
 
-    <dtml-tree expr="folder.object" branches="objectValues">
-      Node id : <dtml-var getId>
-    </dtml-tree>
-
 try: Handles exceptions
 =======================
 
-The 'try' tag allows exception handling in DTML, mirroring the
-Python 'try/except' and 'try/finally' constructs.
+The 'try' tag allows exception handling in DTML, mirroring the Python
+'try/except' and 'try/finally' constructs.
 
 Syntax
+------
 
-  The 'try' tag has two different syntaxes, 'try/except/else' and
-  'try/finally'.
+The 'try' tag has two different syntaxes, 'try/except/else' and 'try/finally'.
 
-  'try/except/else' Syntax::
+'try/except/else' Syntax::
 
-    <dtml-try>
-    <dtml-except [ExceptionName] [ExceptionName]...>
-    ... 
-    [<dtml-else>]
-    </dtml-try>
+  <dtml-try>
+  <dtml-except [ExceptionName] [ExceptionName]...>
+  ... 
+  [<dtml-else>]
+  </dtml-try>
 
-  The 'try' tag encloses a block in which exceptions can be caught and
-  handled. There can be one or more 'except' tags that handles
-  zero or more exceptions. If an 'except' tag does not specify an
-  exception, then it handles all exceptions.
+The 'try' tag encloses a block in which exceptions can be caught and handled.
+There can be one or more 'except' tags that handles zero or more exceptions. If
+an 'except' tag does not specify an exception, then it handles all exceptions.
 
-  When an exception is raised, control jumps to the first 'except'
-  tag that handles the exception. If there is no 'except' tag to
-  handle the exception, then the exception is raised normally.
+When an exception is raised, control jumps to the first 'except' tag that
+handles the exception. If there is no 'except' tag to handle the exception,
+then the exception is raised normally.
 
-  If no exception is raised, and there is an 'else' tag, then the
-  'else' tag will be executed after the body of the 'try' tag.
+If no exception is raised, and there is an 'else' tag, then the 'else' tag will
+be executed after the body of the 'try' tag.
 
-  The 'except' and 'else' tags are optional.
+The 'except' and 'else' tags are optional.
 
-  'try/finally' Syntax::
+'try/finally' Syntax::
 
-    <dtml-try>
-    <dtml-finally>
-    </dtml-try>
+  <dtml-try>
+  <dtml-finally>
+  </dtml-try>
 
-  The 'finally' tag cannot be used in the same 'try' block as the
-  'except' and 'else' tags. If there is a 'finally' tag, its block
-  will be executed whether or not an exception is raised in the
-  'try' block.
+The 'finally' tag cannot be used in the same 'try' block as the 'except' and
+'else' tags. If there is a 'finally' tag, its block will be executed whether or
+not an exception is raised in the 'try' block.
 
 Attributes
+----------
 
-  except -- Zero or more exception names. If no exceptions are
-  listed then the except tag will handle all exceptions.
+- except
 
+  Zero or more exception names. If no exceptions are listed then the except tag
+  will handle all exceptions.
+
 Tag Variables
+-------------
 
-  Inside the 'except' block these variables
-  are defined.
+Inside the 'except' block these variables are defined.
 
-    error_type -- The exception type.
+- error_type
 
-    error_value -- The exception value.
+  The exception type.
 
-    error_tb -- The traceback.
+- error_value
 
+  The exception value.
+
+- error_tb
+
+  The traceback.
+
 Examples
+--------
 
-  Catching a math error::
+Catching a math error::
 
-    <dtml-try>
-    <dtml-var expr="1/0">
-    <dtml-except ZeroDivisionError>
-    You tried to divide by zero.
-    </dtml-try>
+  <dtml-try>
+  <dtml-var expr="1/0">
+  <dtml-except ZeroDivisionError>
+  You tried to divide by zero.
+  </dtml-try>
 
-  Returning information about the handled exception::
+Returning information about the handled exception::
 
-    <dtml-try>
-    <dtml-call dangerousMethod>
-    <dtml-except>
-    An error occurred.
-    Error type: <dtml-var error_type>
-    Error value: <dtml-var error_value>
-    </dtml-try>
+  <dtml-try>
+  <dtml-call dangerousMethod>
+  <dtml-except>
+  An error occurred.
+  Error type: <dtml-var error_type>
+  Error value: <dtml-var error_value>
+  </dtml-try>
 
-  Using finally to make sure to perform clean up regardless
-  of whether an error is raised or not::
+Using finally to make sure to perform clean up regardless of whether an error
+is raised or not::
 
-    <dtml-call acquireLock>
-    <dtml-try>
-    <dtml-call someMethod>
-    <dtml-finally>
-    <dtml-call releaseLock>
-    </dtml-try>
+  <dtml-call acquireLock>
+  <dtml-try>
+  <dtml-call someMethod>
+  <dtml-finally>
+  <dtml-call releaseLock>
+  </dtml-try>
 
 See Also
+--------
 
-  raise tag
+raise tag
 
-  "Python Tutorial: Errors and
-  Exceptions":http://www.python.org/doc/current/tut/node10.html
+`Python Tutorial Errors and Exceptions`_
 
-  "Python Built-in
-  Exceptions":http://www.python.org/doc/current/lib/module-exceptions.html
+.. _Python Tutorial Errors and Exceptions: http://www.python.org/doc/current/tut/node10.html
 
+`Python Built-in Exceptions`_
+
+.. _Python Built-in Exceptions: http://www.python.org/doc/current/lib/module-exceptions.html
+
 unless: Tests a condition
 =========================
 
-The 'unless' tag provides a shortcut for testing negative
-conditions. For more complete condition testing use the 'if' tag. 
+The 'unless' tag provides a shortcut for testing negative conditions. For more
+complete condition testing use the 'if' tag.
 
 Syntax
+------
 
-  'unless' tag syntax::
+'unless' tag syntax::
 
-    <dtml-unless ConditionVariable|expr="ConditionExpression">
-    </dtml-unless>
+  <dtml-unless ConditionVariable|expr="ConditionExpression">
+  </dtml-unless>
 
-  The 'unless' tag is a block tag. If the condition variable or
-  expression evaluates to false, then the contained block is
-  executed. Like the 'if' tag, variables that are not present are
-  considered false.
+The 'unless' tag is a block tag. If the condition variable or expression
+evaluates to false, then the contained block is executed. Like the 'if' tag,
+variables that are not present are considered false.
 
 Examples
+--------
 
-  Testing a variable::
+Testing a variable::
 
-    <dtml-unless testMode>
-      <dtml-call dangerousOperation>
-    </dtml-unless>
+  <dtml-unless testMode>
+    <dtml-call dangerousOperation>
+  </dtml-unless>
 
-  The block will be executed if 'testMode' does not exist, or exists
-  but is false.
+The block will be executed if 'testMode' does not exist, or exists but is
+false.
 
 See Also
+--------
 
-  if tag
+if tag
 
 var: Inserts a variable
+=======================
 
-The 'var' tags allows you insert variables into
-DTML output.
+The 'var' tags allows you insert variables into DTML output.
 
-  % Anonymous User - July 2, 2002 12:11 pm:
-   Is there some place where all predefined variables are listed, e.g. bobobase_modification_time? If so, a link
-   to them at this point seems well-positioned to me.
-
 Syntax
+------
 
-  'var' tag syntax::
+'var' tag syntax::
 
-    <dtml-var Variable|expr="Expression">
+  <dtml-var Variable|expr="Expression">
 
-    % Anonymous User - Mar. 5, 2004 1:57 pm:
-     The difference between using <dtml-var Variable> and <dtml expr="Expression"> is never mentioned nor linked
-     to other parts of the documentation.
+The 'var' tag is a singleton tag. The 'var' tag finds a variable by searching
+the DTML namespace which usually consists of current object, the current
+object's containers, and finally the web request. If the variable is found, it
+is inserted into the DTML output. If not found, Zope raises an error.
 
-  The 'var' tag is a singleton tag.  The 'var' tag finds a variable
-  by searching the DTML namespace which usually consists of current
-  object, the current object's containers, and finally the web
-  request.  If the variable is found, it is inserted into the DTML
-  output. If not found, Zope raises an error.
+'var' tag entity syntax::
 
-  'var' tag entity syntax::
+  &dtml-variableName;
 
-    &dtml-variableName;
+Entity syntax is a short cut which inserts and HTML quotes the variable. It is
+useful when inserting variables into HTML tags.
 
-  Entity syntax is a short cut which inserts and HTML quotes the
-  variable. It is useful when inserting variables into HTML
-  tags.
+'var' tag entity syntax with attributes::
 
-  'var' tag entity syntax with attributes::
+  &dtml.attribute1[.attribute2]...-variableName;
 
-    &dtml.attribute1[.attribute2]...-variableName;
+To a limited degree you may specify attributes with the entity syntax. You may
+include zero or more attributes delimited by periods. You cannot provide
+arguments for attributes using the entity syntax. If you provide zero or more
+attributes, then the variable is not automatically HTML quoted. Thus you can
+avoid HTML quoting with this syntax, '&dtml.-variableName;'.
 
-  To a limited degree you may specify attributes with the entity
-  syntax. You may include zero or more attributes delimited by
-  periods. You cannot provide arguments for attributes using the
-  entity syntax. If you provide zero or more attributes, then the
-  variable is not automatically HTML quoted. Thus you can avoid HTML
-  quoting with this syntax, '&dtml.-variableName;'.
-
 Attributes
+----------
 
-  html_quote -- Convert characters that have special meaning in
-  HTML to HTML character entities.
+- html_quote
 
-  missing=string -- Specify a default value in case Zope cannot find
-  the variable.
+  Convert characters that have special meaning in HTML to HTML character
+  entities.
 
-  fmt=string -- Format a variable. Zope provides a few built-in
-  formats including C-style format strings. For more information on
-  C-style format strings see the "Python Library
-  Reference":http://www.python.org/doc/current/lib/typesseq-strings.html
-  If the format string is not a built-in format, then it is assumed
-  to be a method of the object, and it called.
+- missing=string
 
-    whole-dollars -- Formats the variable as dollars.
+  Specify a default value in case Zope cannot find the variable.
 
-    dollars-and-cents -- Formats the variable as dollars and cents.
+- fmt=string
 
-    collection-length -- The length of the variable, assuming it is
-    a sequence.
+  Format a variable. Zope provides a few built-in formats including C-style
+  format strings. For more information on C-style format strings see the
+  `Python Library Reference`_. If the format string is not a built-in format,
+  then it is assumed to be a method of the object, and it called.
 
-    structured-text -- Formats the variable as Structured Text. For
-    more information on Structured Text see "Structured Text
-    How-To":http://www.zope.org/Members/millejoh/structuredText on
-    the Zope.org website.
+  * collection-length
 
-  null=string -- A default value to use if the variable is None.
+    The length of the variable, assuming it is a sequence.
 
-  lower -- Converts upper-case letters to lower case. 
+- null=string
 
-  upper -- Converts lower-case letters to upper case. 
+  A default value to use if the variable is None.
 
-  capitalize -- Capitalizes the first character of the inserted
-  word. 
+- lower
 
-  spacify -- Changes underscores in the inserted value to spaces.
+  Converts upper-case letters to lower case. 
 
-  thousands_commas -- Inserts commas every three
-  digits to the left of a decimal point in values containing
-  numbers for example '12000' becomes '12,000'.
+- upper
 
-  url -- Inserts the URL of the object, by calling its
-  'absolute_url' method.
+  Converts lower-case letters to upper case. 
 
-  url_quote -- Converts characters that have special meaning in
-  URLs to HTML character entities.
+- capitalize
 
-  url_quote_plus -- URL quotes character, like 'url_quote' but also
-  converts spaces to plus signs.
+  Capitalizes the first character of the inserted word.
 
-  sql_quote -- Converts single quotes to pairs of single
-  quotes. This is needed to safely include values in SQL strings.
+- spacify
 
-  newline_to_br -- Convert newlines (including carriage returns) to
-  HTML break tags.
+  Changes underscores in the inserted value to spaces.
 
-  size=arg -- Truncates the variable at the given length
-  (Note: if a space occurs in the second half of the truncated
-  string, then the string is further truncated to the right-most space).
+- thousands_commas
 
-  etc=arg -- Specifies a string to add to the end of a string
-  which has been truncated (by setting the 'size' attribute listed
-  above).  By default, this is '...'
+  Inserts commas every three digits to the left of a decimal point in values
+  containing numbers for example '12000' becomes '12,000'.
 
+- url
+
+  Inserts the URL of the object, by calling its 'absolute_url' method.
+
+- url_quote
+
+  Converts characters that have special meaning in URLs to HTML character
+  entities.
+
+- url_quote_plus
+
+  URL quotes character, like 'url_quote' but also converts spaces to plus
+  signs.
+
+- sql_quote
+
+  Converts single quotes to pairs of single quotes. This is needed to safely
+  include values in SQL strings.
+
+- newline_to_br
+
+  Convert newlines (including carriage returns) to HTML break tags.
+
+- size=arg
+
+  Truncates the variable at the given length (Note: if a space occurs in the
+  second half of the truncated string, then the string is further truncated to
+  the right-most space).
+
+- etc=arg
+
+  Specifies a string to add to the end of a string which has been truncated (by
+  setting the 'size' attribute listed above). By default, this is '...'
+
+.. _Python Library Reference: http://www.python.org/doc/current/lib/typesseq-strings.html
+
 Examples
+--------
 
-  Inserting a simple variable into a document::
+Inserting a simple variable into a document::
 
-    <dtml-var standard_html_header>
+  <dtml-var standard_html_header>
 
-    % mcdonc - Aug. 14, 2002 11:47 am:
-     Need docs for url_unquote_plus and url_unquote (added in 2.6)
+Truncation::
 
-  Truncation::
+  <dtml-var colors size=10 etc=", etc.">
 
-    <dtml-var colors size=10 etc=", etc.">
+will produce the following output if *colors* is the string 'red yellow
+green'::
 
-  will produce the following output if *colors* is the string 'red
-  yellow green'::
+  red yellow, etc.
 
-    red yellow, etc.
+C-style string formatting::
 
-  C-style string formatting::
+  <dtml-var expr="23432.2323" fmt="%.2f">
 
-    <dtml-var expr="23432.2323" fmt="%.2f">
+renders to::
 
-  renders to::
+  23432.23
 
-    23432.23
+Inserting a variable, *link*, inside an HTML 'A' tag with the entity syntax::
 
-  Inserting a variable, *link*, inside an HTML 'A' tag with the entity
-  syntax::
+  <a href="&dtml-link;">Link</a>
 
-    <a href="&dtml-link;">Link</a>
+Inserting a link to a document 'doc', using entity syntax with attributes::
 
-  Inserting a link to a document 'doc', using entity syntax with
-  attributes::
+  <a href="&dtml.url-doc;"><dtml-var doc fmt="title_or_id"></a>
 
-    <a href="&dtml.url-doc;"><dtml-var doc fmt="title_or_id"></a>
+This creates an HTML link to an object using its URL and title. This example
+calls the object's 'absolute_url' method for the URL (using the 'url'
+attribute) and its 'title_or_id' method for the title.
 
-  This creates an HTML link to an object using its URL and
-  title. This example calls the object's 'absolute_url' method for
-  the URL (using the 'url' attribute) and its 'title_or_id' method
-  for the title.
-
 with: Controls DTML variable look up
 ====================================
 
-The 'with' tag pushes an object onto the DTML namespace. Variables
-will be looked up in the pushed object first.
+The 'with' tag pushes an object onto the DTML namespace. Variables will be
+looked up in the pushed object first.
 
 Syntax
+------
 
-  'with' tag syntax::
+'with' tag syntax::
 
-    <dtml-with Variable|expr="Expression">
-    </dtml-with>
+  <dtml-with Variable|expr="Expression">
+  </dtml-with>
 
-  The 'with' tag is a block tag. It pushes the named variable or
-  variable expression onto the DTML namespace for the duration of
-  the 'with' block. Thus names are looked up in the pushed object
-  first. 
+The 'with' tag is a block tag. It pushes the named variable or variable
+expression onto the DTML namespace for the duration of the 'with' block. Thus
+names are looked up in the pushed object first.
 
 Attributes
+----------
 
-  only -- Limits the DTML namespace to only include the one defined
-  in the 'with' tag.
+- only
 
-  mapping -- Indicates that the variable or expression is a mapping
-  object. This ensures that variables are looked up correctly in the
-  mapping object.
+  Limits the DTML namespace to only include the one defined in the 'with' tag.
 
+- mapping
+
+  Indicates that the variable or expression is a mapping object. This ensures
+  that variables are looked up correctly in the mapping object.
+
 Examples
+--------
 
-  Looking up a variable in the REQUEST::
+Looking up a variable in the REQUEST::
 
-    <dtml-with REQUEST only>
-      <dtml-if id>
-        <dtml-var id>
-      <dtml-else>
-        'id' was not in the request.
-      </dtml-if>
-    </dtml-with>
+  <dtml-with REQUEST only>
+    <dtml-if id>
+      <dtml-var id>
+    <dtml-else>
+      'id' was not in the request.
+    </dtml-if>
+  </dtml-with>
 
-  Pushing the first child on the DTML namespace::
+Pushing the first child on the DTML namespace::
 
-    <dtml-with expr="objectValues()[0]">
-      First child's id: <dtml-var id>
-    </dtml-with>
+  <dtml-with expr="objectValues()[0]">
+    First child's id: <dtml-var id>
+  </dtml-with>
 
 See Also
+--------
 
-  let tag
+let tag



More information about the Checkins mailing list