[Checkins] SVN: zope2book/trunk/ Started on the DTML appendix... checkpoint halfway
Hanno Schlichting
plone at hannosch.info
Tue Feb 10 12:15:42 EST 2009
Log message for revision 96396:
Started on the DTML appendix... checkpoint halfway
Changed:
D zope2book/trunk/AppendixA.stx
A zope2book/trunk/source/AppendixA.rst
U zope2book/trunk/source/index.rst
-=-
Deleted: zope2book/trunk/AppendixA.stx
===================================================================
--- zope2book/trunk/AppendixA.stx 2009-02-10 17:12:50 UTC (rev 96395)
+++ zope2book/trunk/AppendixA.stx 2009-02-10 17:15:41 UTC (rev 96396)
@@ -1,1710 +0,0 @@
-Appendix A: DTML Reference
-
- DTML is the *Document Template Markup Language*, a handy presentation and
- templating language that comes with Zope. This Appendix is a reference to
- all of DTMLs markup tags and how they work.
-
- % Anonymous User - Jan. 8, 2004 11:55 am:
- <dtml-call Variable|expr="Expression">
- <dtml-comment>[this space not executed]</dtml-comment>
- functions: DTML Functions
- <dtml-if ConditionVariable|expr="ConditionExpression">
- [<dtml-elif ConditionVariable|expr="ConditionExpression">]
- ...
- [<dtml-else>]
- </dtml-if [comment]>
- <dtml-in SequenceVariable|expr="SequenceExpression">
- [<dtml-else>]
- </dtml-in [comment]>
- <dtml-let [Name=Variable][Name="Expression"]...>
- </dtml-let>
- <dtml-mime>
- [<dtml-boundary>]
- ...
- </dtml-mime>
- <dtml-raise ExceptionName|ExceptionExpression>[errormessage]</dtml-raise>
- <dtml-return ReturnVariable|expr="ReturnExpression">
- <dtml-sendmail>
- </dtml-sendmail>
- <dtml-sqlgroup [where]>
- [<dtml-or>]
- [<dtml-and>]
- ...
- </dtml-sqlgroup>
- <dtml-sqltest Variable|expr="VariableExpression">
- <dtml-sqlvar Variable|expr="VariableExpression">
- <dtml-tree [VariableName|expr="VariableExpression"]>
- </dtml-tree>
- <dtml-try>
- <dtml-except [ExceptionName] [ExceptionName]...>
- ...
- [<dtml-else>]
- </dtml-try>
- <dtml-try>
- <dtml-finally>
- </dtml-try>
- <dtml-unless ConditionVariable|expr="ConditionExpression">
- </dtml-unless>
- <dtml-var Variable|expr="Expression">
- &dtml-variableName;
- <dtml-with Variable|expr="Expression">
- </dtml-with>
-
- call: Call a method
-
- The 'call' tag lets you call a method without inserting the results
- into the DTML output.
-
- Syntax
-
- 'call' tag syntax::
-
- <dtml-call Variable|expr="Expression">
-
- If the call tag uses a variable, the methods arguments are passed
- automatically by DTML just as with the 'var' tag. If the method is
- specified in a expression, then you must pass the arguments yourself.
-
- Examples
-
- Calling by variable name::
-
- <dtml-call UpdateInfo>
-
- This calls the 'UpdateInfo' object automatically passing arguments.
-
- Calling by expression::
-
- <dtml-call expr="RESPONSE.setHeader('content-type', 'text/plain')">
-
- See Also
-
- var tag
-
- comment: Comments DTML
-
- The comment tag lets you document your DTML with comments. You can
- also use it to temporarily disable DTML tags by commenting them out.
-
- Syntax
-
- 'comment' tag syntax::
-
- <dtml-comment>
- </dtml-comment>
-
- The 'comment' tag is a block tag. The contents of the block are
- not executed, nor are they inserted into the DTML output.
-
- Examples
-
- Documenting DTML::
-
- <dtml-comment>
- This content is not executed and does not appear in the
- output.
- </dtml-comment>
-
- Commenting out DTML::
-
- <dtml-comment>
- This DTML is disabled and will not be executed.
- <dtml-call someMethod>
- </dtml-comment>
-
- Zope still validates the DTML inside the comment block and will not save any comments that are not valid DTML. It is also not possible to comment in a way that breaks code flow, for example you cannot inproperly nest a comment and a dtml-in.
-
- functions: DTML Functions
-
- DTML utility functions provide some Python built-in functions and
- some DTML-specific functions.
-
- % aho - Apr. 30, 2002 2:35 pm:
- <dtml-call "REQUEST.set('newnumber_as_string', _.str(newnumber_value))">
-
- % Anonymous User - May 8, 2002 7:52 am:
- the examples below contain erroneous href's
-
- Functions
-
- abs(number) -- Return the absolute value of a number. The argument may
- be a plain or long integer or a floating point number. If the argument
- is a complex number, its magnitude is returned.
-
- chr(integer) -- Return a string of one character whose ASCII code
- is the integer, e.g., 'chr(97)' returns the string 'a'. This is
- the inverse of ord(). The argument must be in the range 0 to 255,
- inclusive; 'ValueError' will be raised if the integer is outside
- that range.
-
- DateTime() -- Returns a Zope 'DateTime' object given constructor
- arguments. See the DateTime API reference for more
- information on constructor arguments.
-
- divmod(number, number) -- Take two numbers as arguments and return
- a pair of numbers consisting of their quotient and remainder when
- using long division. With mixed operand types, the rules for
- binary arithmetic operators apply. For plain and long integers,
- the result is the same as '(a / b, a % b)'. For floating point
- numbers the result is '(q, a % b)', where *q* is usually
- 'math.floor(a / b)' but may be 1 less than that. In any case 'q *
- b + a % b' is very close to *a*, if 'a % b' is non-zero it has the
- same sign as *b*, and '0 <= abs(a % b) < abs(b)'.
-
- float(number) -- Convert a string or a number to floating
- point. If the argument is a string, it must contain a possibly
- signed decimal or floating point number, possibly embedded in
- whitespace; this behaves identical to
- 'string.atof(number)'. Otherwise, the argument may be a plain or
- long integer or a floating point number, and a floating point
- number with the same value (within Python's floating point
- precision) is returned.
-
- getattr(object, string) -- Return the value of the named
- attributed of object. name must be a string. If the string is the
- name of one of the object's attributes, the result is the value of
- that attribute. For example, 'getattr(x, "foobar")' is equivalent
- to 'x.foobar'. If the named attribute does not exist, default is
- returned if provided, otherwise 'AttributeError' is raised.
-
- getitem(variable, render=0) -- Returns the value of a DTML variable.
- If 'render' is true, the variable is rendered. See the 'render'
- function.
-
- hasattr(object, string) -- The arguments are an object and a
- string. The result is 1 if the string is the name of one of the
- object's attributes, 0 if not. (This is implemented by calling
- getattr(object, name) and seeing whether it raises an exception or
- not.)
-
- hash(object) -- Return the hash value of the object (if it has
- one). Hash values are integers. They are used to quickly compare
- dictionary keys during a dictionary lookup. Numeric values that compare
- equal have the same hash value (even if they are of different types,
- e.g. 1 and 1.0).
-
- has_key(variable) -- Returns true if the DTML namespace contains the
- named variable.
-
- hex(integer) -- Convert an integer number (of any size) to a
- hexadecimal string. The result is a valid Python expression. Note: this
- always yields an unsigned literal, e.g. on a 32-bit machine, 'hex(-1)'
- yields '0xffffffff'. When evaluated on a machine with the same word
- size, this literal is evaluated as -1; at a different word size, it
- may turn up as a large positive number or raise an 'OverflowError'
- exception.
-
- int(number) -- Convert a string or number to a plain integer. If
- the argument is a string, it must contain a possibly signed
- decimal number representable as a Python integer, possibly
- embedded in whitespace; this behaves identical to
- 'string.atoi(number[, radix]'). The 'radix' parameter gives the
- base for the conversion and may be any integer in the range 2 to
- 36. If 'radix' is specified and the number is not a string,
- 'TypeError' is raised. Otherwise, the argument may be a plain or
- long integer or a floating point number. Conversion of floating
- point numbers to integers is defined by the C semantics; normally
- the conversion truncates towards zero.
-
- len(sequence) -- Return the length (the number of items) of an
- object. The argument may be a sequence (string, tuple or list) or a
- mapping (dictionary).
-
- max(s) -- With a single argument s, return the largest item of a
- non-empty sequence (e.g., a string, tuple or list). With more than one
- argument, return the largest of the arguments.
-
- min(s) -- With a single argument s, return the smallest item of
- a non-empty sequence (e.g., a string, tuple or list). With more than
- one argument, return the smallest of the arguments.
-
- namespace([name=value]...) -- Returns a new DTML namespace object.
- Keyword argument 'name=value' pairs are pushed into the new
- namespace.
-
- oct(integer) -- Convert an integer number (of any size) to an octal
- string. The result is a valid Python expression. Note: this always
- yields an unsigned literal, e.g. on a 32-bit machine, 'oct(-1)' yields
- '037777777777'. When evaluated on a machine with the same word size,
- this literal is evaluated as -1; at a different word size, it may
- turn up as a large positive number or raise an OverflowError
- exception.
-
- ord(character) -- Return the ASCII value of a string of one
- character. E.g., 'ord("a")' returns the integer 97. This is the
- inverse of 'chr()'.
-
- pow(x, y [,z]) -- Return *x* to the power *y*; if *z* is present,
- return *x* to the power *y*, modulo *z* (computed more efficiently
- than 'pow(x, y) % z'). The arguments must have numeric types. With
- mixed operand types, the rules for binary arithmetic operators
- apply. The effective operand type is also the type of the result;
- if the result is not expressible in this type, the function raises
- an exception; e.g., 'pow(2, -1)' or 'pow(2, 35000)' is not
- allowed.
-
- range([start,] stop [,step]) -- This is a versatile function to
- create lists containing arithmetic progressions. The arguments
- must be plain integers. If the step argument is omitted, it
- defaults to 1. If the start argument is omitted, it defaults to
- 0. The full form returns a list of plain integers '[start, start
- + step, start + 2 * step, ...]'. If step is positive, the last
- element is the largest 'start + i * step' less than *stop*; if
- *step* is negative, the last element is the largest 'start + i *
- step' greater than *stop*. *step* must not be zero (or else
- 'ValueError' is raised).
-
- round(x [,n]) -- Return the floating point value *x* rounded to *n*
- digits after the decimal point. If n is omitted, it defaults to
- zero. The result is a floating point number. Values are rounded to the
- closest multiple of 10 to the power minus n; if two multiples are
- equally close, rounding is done away from 0 (so e.g. round(0.5) is 1.0
- and round(-0.5) is -1.0).
-
- render(object) -- Render 'object'. For DTML objects this
- evaluates the DTML code with the current namespace. For other
- objects, this is equivalent to 'str(object)'.
-
- reorder(s [,with] [,without]) -- Reorder the items in s according
- to the order given in 'with' and without the items mentioned in
- 'without'. Items from s not mentioned in with are removed. s,
- with, and without are all either sequences of strings or
- sequences of key-value tuples, with ordering done on the
- keys. This function is useful for constructing ordered select
- lists.
-
- SecurityCalledByExecutable() -- Return a true if the current
- object (e.g. DTML document or method) is being called by an
- executable (e.g. another DTML document or method, a script or a
- SQL method).
-
- SecurityCheckPermission(permission, object) -- Check whether the
- security context allows the given permission on the given
- object. For example, 'SecurityCheckPermission("Add Documents,
- Images, and Files", this())' would return true if the current user
- was authorized to create documents, images, and files in the
- current location.
-
- SecurityGetUser() -- Return the current user object. This is
- normally the same as the 'REQUEST.AUTHENTICATED_USER'
- object. However, the 'AUTHENTICATED_USER' object is insecure since
- it can be replaced.
-
- SecurityValidate([object] [,parent] [,name] [,value]) -- Return
- true if the value is accessible to the current user. 'object' is
- the object the value was accessed in, 'parent' is the container of
- the value, and 'name' is the named used to access the value (for
- example, if it was obtained via 'getattr'). You may omit some of
- the arguments, however it is best to provide all available
- arguments.
-
- SecurityValidateValue(object) -- Return true if the object is
- accessible to the current user. This function is the same as
- calling 'SecurityValidate(None, None, None, object)'.
-
- str(object) -- Return a string containing a nicely printable
- representation of an object. For strings, this returns the string
- itself.
-
- test(condition, result [,condition, result]... [,default]) --
- Takes one or more condition, result pairs and returns the result
- of the first true condition. Only one result is returned, even if
- more than one condition is true. If no condition is true and a
- default is given, the default is returned. If no condition is true
- and there is no default, None is returned.
-
- unichr(number) -- Return a unicode string representing the value of
- number as a unicode character. This is the inverse of ord() for
- unicode characters.
-
- unicode(string[, encoding[, errors ] ]) -- Decodes string using the
- codec for encoding. Error handling is done according to errors. The
- default behavior is to decode UTF-8 in strict mode, meaning that
- encoding errors raise ValueError.
-
- Attributes
-
- None -- The 'None' object is equivalent to the Python built-in object
- 'None'. This is usually used to represent a Null or false value.
-
- See Also
-
- 'string' module
-
- "Documentation":http://www.python.org/doc/current/lib/module-string.html
-
- 'random' module
-
- "Documentation":http://www.python.org/doc/current/lib/module-random.html
-
- 'math' module
-
- "Documentation":http://www.python.org/doc/current/lib/module-math.html
-
- 'sequence' module
-
- "Built-in Python Functions":http://www.python.org/doc/current/lib/built-in-funcs.html
-
- % aho - Apr. 30, 2002 2:57 pm:
- An example:
- <dtml-call "REQUEST.set('form', 'Hobbies_v5')">
- <dtml-call "REQUEST.set('version_suffix',
- _.string.rfind(form, '_v')
- )">
- <dtml-call "REQUEST.set('old_form_name',
- form[:version_suffix - _.len(form)])">
- new form name: <dtml-var form>
- version suffix starts at position : <dtml-var version_suffix>
- old form name: <dtml-var old_form_name>
- ---
- The output of the example code should be:
- new form name: Hobbies_v5
- version suffix starts at position : 7
- old form name: Hobbies
-
- if: Tests Conditions
-
- The 'if' tags allows you to test conditions and to take different
- actions depending on the conditions. The 'if' tag mirrors Python's
- 'if/elif/else' condition testing statements.
-
- Syntax
-
- If tag syntax::
-
- <dtml-if ConditionVariable|expr="ConditionExpression">
- [<dtml-elif ConditionVariable|expr="ConditionExpression">]
- ...
- [<dtml-else>]
- </dtml-if>
-
- The 'if' tag is a block tag. The 'if' tag and optional 'elif' tags
- take a condition variable name or a condition expression, but not
- both. If the condition name or expression evaluates to true then
- the 'if' block is executed. True means not zero, an empty string
- or an empty list. If the condition variable is not found then the
- condition is considered false.
-
- If the initial condition is false, each 'elif' condition is tested
- in turn. If any 'elif' condition is true, its block is
- executed. Finally the optional 'else' block is executed if none of
- the 'if' and 'elif' conditions were true. Only one block will be
- executed.
-
- Examples
-
- Testing for a variable::
-
- <dtml-if snake>
- The snake variable is true
- </dtml-if>
-
- Testing for expression conditions::
-
- <dtml-if expr="num > 5">
- num is greater than five
- <dtml-elif expr="num < 5">
- num is less than five
- <dtml-else>
- num must be five
- </dtml-if>
-
- See Also
-
- "Python Tutorial: If Statements":http://www.python.org/doc/current/tut/node6.html#SECTION006100000000000000000
-
- in: Loops over sequences
-
- The 'in' tag gives you powerful controls for looping over sequences
- and performing batch processing.
-
- Syntax
-
- 'in' tag syntax::
-
- <dtml-in SequenceVariable|expr="SequenceExpression">
- [<dtml-else>]
- </dtml-in>
-
- a commenting identifier at the end tag is allowed and will be ignored like::
-
- </dtml-in my_short_sequ_name>
-
- same for '</dtml-if>' and '</dtml-let>'
-
- The 'in' block is repeated once for each item in the sequence
- variable or sequence expression. The current item is pushed on to
- the DTML namespace during each executing of the 'in' block.
-
- If there are no items in the sequence variable or expression, the
- optional 'else' block is executed.
-
- Attributes
-
- mapping -- Iterates over mapping objects rather than
- instances. This allows values of the mapping objects to be
- accessed as DTML variables.
-
- reverse -- Reverses the sequence.
-
- sort=string -- Sorts the sequence by the given attribute name.
-
- start=int -- The number of the first item to be shown, where
- items are numbered from 1.
-
- end=int -- The number of the last item to be shown, where items
- are numbered from 1.
-
- size=int -- The size of the batch.
-
- skip_unauthorized -- Don't raise an exception if an unauthorized
- item is encountered.
-
- orphan=int -- The desired minimum batch size. This controls how
- sequences are split into batches. If a batch smaller than the
- orphan size would occur, then no split is performed, and a batch
- larger than the batch size results.
-
- For example, if the sequence size is 12, the batch size is 10
- the orphan size is 3, then the result is one batch with all 12
- items since splitting the items into two batches would result in
- a batch smaller than the orphan size.
-
- % htrd - Apr. 24, 2002 9:06 am:
- (Re http://collector.zope.org/Zope/358)
- no_push_item
- inhibit pushing "sequence-item" onto the namespace stack while evaluating the body of the dtml-in
-
- % Anonymous User - May 8, 2002 7:59 am:
- the default value in earlier zope versions was 3
-
- % Anonymous User - May 8, 2002 8:03 am:
- below: prefix
- this is also a newer addition,
- maybe its possible to add since which zope version
-
- The default value is 0.
-
- overlap=int -- The number of items to overlap between batches. The
- default is no overlap.
-
- previous -- Iterates once if there is a previous batch. Sets batch
- variables for previous sequence.
-
- next -- Iterates once if there is a next batch. Sets batch variables
- for the next sequence.
-
- prefix=string -- Provide versions of the tag variables that start
- with this prefix instead of "sequence", and that use underscores
- (_) instead of hyphens (-). The prefix must start with a letter and
- contain only alphanumeric characters and underscores (_).
-
- sort_expr=expression -- Sorts the sequence by an attribute named
- by the value of the expression. This allows you to sort on
- different attributes.
-
- reverse_expr=expression -- Reverses the sequence if the expression
- evaluates to true. This allows you to selectively reverse the
- sequence.
-
- Tag Variables
-
- Current Item Variables
-
- These variables describe the
- current item.
-
- sequence-item -- The current item.
-
- sequence-key -- The current key. When looping over tuples of the
- form '(key,value)', the 'in' tag interprets them as
- '(sequence-key, sequence-item)'.
-
- sequence-index -- The index starting with 0 of the current item.
-
- sequence-number -- The index starting with 1 of the current item.
-
- sequence-roman -- The index in lowercase Roman numerals of the
- current item.
-
- sequence-Roman -- The index in uppercase Roman numerals of the
- current item.
-
- sequence-letter -- The index in lowercase letters of the current
- item.
-
- sequence-Letter -- The index in uppercase letters of the current
- item.
-
- sequence-start -- True if the current item is the first item.
-
- sequence-end -- True if the current item is the last item.
-
- sequence-even -- True if the index of the current item is even.
-
- sequence-odd -- True if the index of the current item is odd.
-
- sequence-length -- The length of the sequence.
-
- sequence-var-*variable* -- A variable in the current item. For
- example, 'sequence-var-title' is the 'title' variable of the
- current item. Normally you can access these variables directly
- since the current item is pushed on the DTML namespace. However
- these variables can be useful when displaying previous and next
- batch information.
-
- sequence-index-*variable* -- The index of a variable of the
- current item.
-
- % rboylan - July 22, 2002 7:40 pm:
- How does this work if you want to use these variables in an expression? I tried, but got errors because (I
- think) - is not part of python names.
-
- % Anonymous User - Aug. 3, 2002 4:39 pm:
- rboylan, here is an example:
- <dtml-if expr="_['sequence-length'] > 1">
- do something..
- </dtml-if>
-
- % Anonymous User - Aug. 7, 2002 12:44 am:
- When a sql search returns no results, will the value of sequence-length be zero? Whenever I run my script and
- there are no results, I either get an error about sequence not being defined, or a blank screen.
-
- % Anonymous User - Aug. 21, 2002 10:50 am:
- no results? - use <dtml-else>:
- <dtml-in ... >
- ...
- <dtml-else>
- ...
- </dtml-in>
-
- 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.
-
- total-*variable* -- The total of all occurrences of an item variable.
-
- count-*variable* -- The number of occurrences of an item variable.
-
- min-*variable* -- The minimum value of an item variable.
-
- max-*variable* -- The maximum value of an item variable.
-
- mean-*variable* -- The mean value of an item variable.
-
- variance-*variable* -- The variance of an item variable with
- count-1 degrees of freedom.
-
- variance-n-*variable* -- The variance of an item variable with
- n degrees of freedom.
-
- standard-deviation-*variable* -- The standard-deviation of an
- item variable with count-1 degrees of freedom.
-
- standard-deviation-n-*variable* -- The standard-deviation of
- an item variable with n degrees of freedom.
-
- % Anonymous User - Apr. 23, 2002 11:57 am:
- An example would be helpful here.
-
- % Anonymous User - May 29, 2002 8:01 pm:
- Examples:
- mean-variable
- <dtml-in "objectValues(['Image'])"><dtml-if sequence-end><dtml-var mean-width></dtml-if></dtml-in>
- returns the mean value (average) of the width for all images in the current folder.
- <dtml-in "objectValues(['Image'])"><dtml-if sequence-end><dtml-var total-width></dtml-if></dtml-in>
- returns the total value (sum) of the width for all images in the current folder.
- <dtml-in "objectValues(['Image'])"><dtml-if sequence-end><dtml-var count-description></dtml-if></dtml-in>
- returns how many images have a variable called description.
- <dtml-in "objectValues(['Image'])"><dtml-if sequence-end><dtml-var max-width></dtml-if></dtml-in>
- returns the max value of the width over all images in the current folder.
-
- Grouping Variables
-
- These variables allow you to track changes in current item
- variables.
-
- first-*variable* -- True if the current item is the first with
- a particular value for a variable.
-
- last-*variable* -- True if the current item is the last with a
- particular value for a variable.
-
- Batch Variables
-
- sequence-query -- The query string with the 'start' variable
- removed. You can use this variable to construct links to next
- and previous batches.
-
- sequence-step-size -- The batch size.
-
- previous-sequence -- True if the current batch is not the
- first one. Note, this variable is only true for the first loop
- iteration.
-
- previous-sequence-start-index -- The starting index of the
- previous batch.
-
- previous-sequence-start-number -- The starting number of the
- previous batch. Note, this is the same as
- 'previous-sequence-start-index' + 1.
-
- previous-sequence-end-index -- The ending index of the previous
- batch.
-
- previous-sequence-end-number -- The ending number of the
- previous batch. Note, this is the same as
- 'previous-sequence-end-index' + 1.
-
- previous-sequence-size -- The size of the previous batch.
-
- previous-batches -- A sequence of mapping objects with
- information about all previous batches. Each mapping object has
- these keys 'batch-start-index', 'batch-end-index', and
- 'batch-size'.
-
- next-sequence -- True if the current batch is not the last
- batch. Note, this variable is only true for the last loop
- iteration.
-
- next-sequence-start-index -- The starting index of the next
- sequence.
-
- next-sequence-start-number -- The starting number of the next
- sequence. Note, this is the same as 'next-sequence-start-index'
- + 1.
-
- next-sequence-end-index -- The ending index of the next
- sequence.
-
- next-sequence-end-number -- The ending number of the next
- sequence. Note, this is the same as 'next-sequence-end-index'
- + 1.
-
- next-sequence-size -- The size of the next index.
-
- next-batches -- A sequence of mapping objects with information
- about all following batches. Each mapping object has these keys
- 'batch-start-index', 'batch-end-index', and 'batch-size'.
-
- Examples
-
- Looping over sub-objects::
-
- <dtml-in objectValues>
- title: <dtml-var title><br>
- </dtml-in>
-
- Looping over two sets of objects, using prefixes::
-
- <dtml-let rows="(1,2,3)" cols="(4,5,6)">
- <dtml-in rows prefix="row">
- <dtml-in cols prefix="col">
- <dtml-var expr="row_item * col_item"><br>
- <dtml-if col_end>
- <dtml-var expr="col_total_item * row_mean_item">
- </dtml-if>
- </dtml-in>
- </dtml-in>
- </dtml-let>
-
- Looping over a list of '(key, value)' tuples::
-
- <dtml-in objectItems>
- id: <dtml-var sequence-key>, title: <dtml-var title><br>
- </dtml-in>
-
- Creating alternate colored table rows::
-
- <table>
- <dtml-in objectValues>
- <tr <dtml-if sequence-odd>bgcolor="#EEEEEE"
- <dtml-else>bgcolor="#FFFFFF">
- </dtml-if>
- <td><dtml-var title></td>
- </tr>
- </dtml-in>
- </table>
-
- % Anonymous User - Jan. 30, 2004 5:49 am:
- the closing '>' for '<tr' should be located after the '</dtml-if>' and not behind the '...FFF"' ! (pius)
-
- Basic batch processing::
-
- <p>
- <dtml-in largeSequence size=10 start=start previous>
- <a href="<dtml-var absolute_url><dtml-var sequence-query>start=<dtml-var previous-sequence-start-number>">Previous</a>
- </dtml-in>
-
- <dtml-in largeSequence size=10 start=start next>
- <a href="<dtml-var absolute_url><dtml-var sequence-query>start=<dtml-var next-sequence-start-number>">Next</a>
- </dtml-in>
- </p>
-
- <p>
- <dtml-in largeSequence size=10 start=start>
- <dtml-var sequence-item>
- </dtml-in>
- </p>
-
- This example creates *Previous* and *Next* links to navigate
- between batches. Note, by using 'sequence-query', you do not lose
- any GET variables as you navigate between batches.
-
- let: Defines DTML variables
-
- The 'let' tag defines variables in the DTML namespace.
-
- Syntax
-
- 'let' tag syntax::
-
- <dtml-let [Name=Variable][Name="Expression"]...>
- </dtml-let>
-
- The 'let' tag is a block tag. Variables are defined by tag
- arguments. Defined variables are pushed onto the DTML namespace
- while the 'let' block is executed. Variables are defined by
- attributes. The 'let' tag can have one or more attributes with
- arbitrary names. If the attributes are defined with double quotes
- they are considered expressions, otherwise they are looked up by
- name. Attributes are processed in order, so later attributes can
- reference, and/or overwrite earlier ones.
-
- Examples
-
- Basic usage::
-
- <dtml-let name="'Bob'" ids=objectIds>
- name: <dtml-var name>
- ids: <dtml-var ids>
- </dtml-let>
-
- Using the 'let' tag with the 'in' tag::
-
- <dtml-in expr="(1,2,3,4)">
- <dtml-let num=sequence-item
- index=sequence-index
- result="num*index">
- <dtml-var num> * <dtml-var index> = <dtml-var result>
- </dtml-let>
- </dtml-in>
-
- This yields::
-
- 1 * 0 = 0
- 2 * 1 = 2
- 3 * 2 = 6
- 4 * 3 = 12
-
- See Also
-
- with tag
-
- mime: Formats data with MIME
-
- The 'mime' tag allows you to create MIME encoded data. It is chiefly
- used to format email inside the 'sendmail' tag.
-
- Syntax
-
- 'mime' tag syntax::
-
- <dtml-mime>
- [<dtml-boundry>]
- ...
- </dtml-mime>
-
- The 'mime' tag is a block tag. The block is can be divided by one
- or more 'boundry' tags to create a multi-part MIME message. 'mime'
- tags may be nested. The 'mime' tag is most often used inside the
- 'sendmail' tag.
-
- Attributes
-
- Both the 'mime' and 'boundry' tags
- have the same attributes.
-
- 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.
-
- type=string -- MIME Content-Type header.
-
- type_expr=string -- MIME Content-Type header as a variable
- expression. You cannot use both 'type' and 'type_expr'.
-
- name=string -- MIME Content-Type header name.
-
- name_expr=string -- MIME Content-Type header name as a variable
- expression. You cannot use both 'name' and 'name_expr'.
-
- 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
-
- Sending a file attachment::
-
- <dtml-sendmail>
- To: <dtml-var recipient>
- Subject: Resume
- <dtml-mime type="text/plain" encode="7bit">
-
- Hi, please take a look at my resume.
-
- <dtml-boundary type="application/octet-stream" disposition="attachment"
- encode="base64" filename_expr="resume_file.getId()"><dtml-var expr="resume_file.read()"></dtml-mime>
- </dtml-sendmail>
-
- See Also
-
- "Python Library: mimetools":http://www.python.org/doc/current/lib/module-mimetools.html
-
- raise: Raises an exception
-
- The 'raise' tag raises an exception, mirroring the Python 'raise'
- statement.
-
- Syntax
-
- 'raise' tag syntax::
-
- <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.
-
- Examples
-
- Raising a KeyError::
-
- <dtml-raise KeyError></dtml-raise>
-
- Raising an HTTP 404 error::
-
- <dtml-raise NotFound>Web Page Not Found</dtml-raise>
-
- See Also
-
- try tag
-
- "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
-
- return: Returns data
-
- The 'return' tag stops executing DTML and returns data. It mirrors
- the Python 'return' statement.
-
- Syntax
-
- 'return' tag syntax::
-
- <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.
-
- % 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::
-
- <dtml-return result>
-
- Returning a Python dictionary::
-
- <dtml-return expr="{'hi':200, 'lo':5}">
-
- sendmail: Sends email with SMTP
-
- The 'sendmail' tag sends an email message
- using SMTP.
-
- Syntax
-
- 'sendmail' tag syntax::
-
- <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.
-
- Attributes
-
- mailhost -- The name of a Zope MailHost object
- to use to send email. You cannot specify both a mailhost and a smtphost.
-
- smtphost -- The name of a SMTP server used 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.
-
- 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::
-
- <dtml-sendmail mailhost="mailhost">
- To: <dtml-var recipient>
- From: <dtml-var sender>
- Subject: <dtml-var subject>
-
- Dear <dtml-var recipient>,
-
- 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
-
- 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.
-
- % Anonymous User - May 2, 2002 9:13 am:
- there is a sql-delimiter not documented here
-
- Syntax
-
- 'sqlgroup' tag syntax::
-
- <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.
-
- Attributes
-
- required=boolean -- 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::
-
- 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::
-
- select * from employees
- where
- (first='Bob'
- and
- last in ('Smith', 'McDonald')
- )
-
- If 'salary' is 50000 and 'last' is 'Smith' it renders::
-
- select * from employees
- where
- (salary > 50000.0
- and
- last='Smith'
- )
-
- 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">
- </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::
-
- select * form employees
- where
- (
- (
- name like 'A*'
- and
- last like 'Smith'
- )
- or
- salary > 20000.0
- )
-
- See Also
-
- 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.
-
- Syntax
-
- 'sqltest' tag syntax::
-
- <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.
-
- 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.
-
- column=string -- The name of the SQL column to test against. This
- attribute defaults to the variable name.
-
- multiple=boolean -- If true, then the variable may be a sequence
- of values to test the column against.
-
- optional=boolean -- If true, then the test is optional and will
- not be rendered if the variable is empty or non-existent.
-
- op=string -- The comparison operation. Valid comparisons include:
-
- eq -- equal to
-
- 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::
-
- select * from employees
- where <dtml-sqltest name type="nb">
-
- If the 'name' variable is 'Bob' then this renders::
-
- select * from employees
- where name = 'Bob'
-
- Multiple values::
-
- select * from employees
- where <dtml-sqltest empid type=int multiple>
-
- If the 'empid' variable is '(12,14,17)' then this renders::
-
- select * from employees
- where empid in (12, 14, 17)
-
- See Also
-
- sqlgroup tag
-
- sqlvar tag
-
- sqlvar: Inserts SQL variables
-
- The 'sqlvar' tag safely inserts variables into SQL code. This tag is
- used in SQL Methods.
-
- Syntax
-
- 'sqlvar' tag syntax::
-
- <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.
-
- 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.
-
- optional=boolean -- If true and the variable is null or
- non-existent, then nothing is inserted.
-
- Examples
-
- Basic usage::
-
- select * from employees
- where name=<dtml-sqlvar name type="nb">
-
- This SQL quotes the 'name' string variable.
-
- See Also
-
- sqltest tag
-
- tree: Inserts a tree widget
-
- The 'tree' tag displays a dynamic tree widget by querying Zope
- objects.
-
- Syntax
-
- 'tree' tag syntax::
-
- <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.
-
- % 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.
-
- Attributes
-
- branches=string -- Finds tree branches by calling the named
- method. The default method is 'tpValues' which most Zope objects
- support.
-
- % Anonymous User - Dec. 12, 2003 7:52 pm:
- Hmmm. I'd think the following would make a tree containing only folders:
- <dtml-tree branches="objectValues('Folder')" single=true>
- [whatever]
- </dtml-tree>
- But no dice. In fact, I can't get even get ... branches="objectValues()" ... to work, or ...
- branches=objectValues() ...
- Any hints?
-
- % Anonymous User - Dec. 12, 2003 8:17 pm:
- Hint: branches_expr=objectValues('Folder')
-
- branches_expr=string -- Finds tree branches by evaluating the
- expression.
-
- 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.
-
- 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.
-
- 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.
-
- header=string -- The name of a DTML Document or Method displayed
- before expanded nodes. If the header is not found, it is skipped.
-
- footer=string -- The name of a DTML Document or Method displayed
- after expanded nodes. If the footer is not found, it is skipped.
-
- 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-url -- The URL of the current node.
-
- tree-root-url -- 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.
-
- expand_all -- If this variable is true then the entire tree is
- expanded.
-
- collapse_all -- If this variable is true then the entire tree is
- collapsed.
-
- % Anonymous User - May 21, 2002 7:24 am:
- Could someone please post an example for this. I really need to start with an expanded tree!
-
- % Anonymous User - Aug. 14, 2002 2:25 pm:
- <dtml-let expand_all="'true'">
- <dtml-tree>
- ...
- </dtml-tree>
- </dtml-let>
-
- Examples
-
- Display a tree rooted in the current object::
-
- <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::
-
- <dtml-tree expr="folder.object" branches="objectValues">
- Node id : <dtml-var getId>
- </dtml-tree>
-
- % rklahn - Aug. 19, 2002 7:29 pm:
- It is often useful to generate a tree of your parent, from a DTML document. I think it would be helpful if an
- example was provided that performed this function, such as:
- <dtml-tree expr="aq_parent" skip_unauthorized="1">
- <a href="&dtml-absolute_url;"><dtml-var title_or_id></a>
- </dtml-tree>
-
- try: Handles exceptions
-
- 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'.
-
- 'try/except/else' Syntax::
-
- <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.
-
- 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.
-
- The 'except' and 'else' tags are optional.
-
- 'try/finally' Syntax::
-
- <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.
-
- Attributes
-
- 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.
-
- error_type -- The exception type.
-
- error_value -- The exception value.
-
- error_tb -- The traceback.
-
- Examples
-
- Catching a math error::
-
- <dtml-try>
- <dtml-var expr="1/0">
- <dtml-except ZeroDivisionError>
- You tried to divide by zero.
- </dtml-try>
-
- 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>
-
- 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>
-
- See Also
-
- raise tag
-
- "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
-
- unless: Tests a condition
-
- The 'unless' tag provides a shortcut for testing negative
- conditions. For more complete condition testing use the 'if' tag.
-
- Syntax
-
- 'unless' tag syntax::
-
- <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.
-
- Examples
-
- Testing a variable::
-
- <dtml-unless testMode>
- <dtml-call dangerousOperation>
- </dtml-unless>
-
- The block will be executed if 'testMode' does not exist, or exists
- but is false.
-
- See Also
-
- if tag
-
- var: Inserts a variable
-
- 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::
-
- <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.
-
- 'var' tag entity syntax::
-
- &dtml-variableName;
-
- 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::
-
- &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;'.
-
- Attributes
-
- html_quote -- Convert characters that have special meaning in
- HTML to HTML character entities.
-
- missing=string -- Specify a default value in case Zope cannot find
- the variable.
-
- 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.
-
- whole-dollars -- Formats the variable as dollars.
-
- dollars-and-cents -- Formats the variable as dollars and cents.
-
- collection-length -- The length of the variable, assuming it is
- a sequence.
-
- 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.
-
- null=string -- A default value to use if the variable is None.
-
- lower -- Converts upper-case letters to lower case.
-
- upper -- Converts lower-case letters to upper case.
-
- capitalize -- Capitalizes the first character of the inserted
- word.
-
- spacify -- Changes underscores in the inserted value to spaces.
-
- thousands_commas -- 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 '...'
-
- Examples
-
- Inserting a simple variable into a document::
-
- <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::
-
- <dtml-var colors size=10 etc=", etc.">
-
- will produce the following output if *colors* is the string 'red
- yellow green'::
-
- red yellow, etc.
-
- C-style string formatting::
-
- <dtml-var expr="23432.2323" fmt="%.2f">
-
- renders to::
-
- 23432.23
-
- Inserting a variable, *link*, inside an HTML 'A' tag with the entity
- syntax::
-
- <a href="&dtml-link;">Link</a>
-
- 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>
-
- 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.
-
- Syntax
-
- 'with' tag syntax::
-
- <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.
-
- Attributes
-
- only -- 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::
-
- <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::
-
- <dtml-with expr="objectValues()[0]">
- First child's id: <dtml-var id>
- </dtml-with>
-
- See Also
-
- let tag
\ No newline at end of file
Copied: zope2book/trunk/source/AppendixA.rst (from rev 96389, zope2book/trunk/AppendixA.stx)
===================================================================
--- zope2book/trunk/source/AppendixA.rst (rev 0)
+++ zope2book/trunk/source/AppendixA.rst 2009-02-10 17:15:41 UTC (rev 96396)
@@ -0,0 +1,1719 @@
+##########################
+Appendix A: DTML Reference
+##########################
+
+DTML is the *Document Template Markup Language*, a handy presentation and
+templating language that comes with Zope. This Appendix is a reference to all
+of DTMLs markup tags and how they work.
+
+call: Call a method
+===================
+
+The 'call' tag lets you call a method without inserting the results into the
+DTML output.
+
+Syntax
+------
+
+'call' tag syntax::
+
+ <dtml-call Variable|expr="Expression">
+
+If the call tag uses a variable, the methods arguments are passed automatically
+by DTML just as with the 'var' tag. If the method is specified in a expression,
+then you must pass the arguments yourself.
+
+Examples
+--------
+
+Calling by variable name::
+
+ <dtml-call UpdateInfo>
+
+This calls the 'UpdateInfo' object automatically passing arguments.
+
+Calling by expression::
+
+ <dtml-call expr="RESPONSE.setHeader('content-type', 'text/plain')">
+
+See Also
+--------
+
+var tag
+
+
+comment: Comments DTML
+======================
+
+The comment tag lets you document your DTML with comments. You can also use it
+to temporarily disable DTML tags by commenting them out.
+
+Syntax
+------
+
+'comment' tag syntax::
+
+ <dtml-comment>
+ </dtml-comment>
+
+The 'comment' tag is a block tag. The contents of the block are not executed,
+nor are they inserted into the DTML output.
+
+Examples
+--------
+
+Documenting DTML::
+
+ <dtml-comment>
+ This content is not executed and does not appear in the output.
+ </dtml-comment>
+
+Commenting out DTML::
+
+ <dtml-comment>
+ This DTML is disabled and will not be executed.
+ <dtml-call someMethod>
+ </dtml-comment>
+
+Zope still validates the DTML inside the comment block and will not save any
+comments that are not valid DTML. It is also not possible to comment in a way
+that breaks code flow, for example you cannot inproperly nest a comment and a
+dtml-in.
+
+
+functions: DTML Functions
+=========================
+
+DTML utility functions provide some Python built-in functions and some
+DTML-specific functions.
+
+Functions
+---------
+
+- abs(number)
+
+ Return the absolute value of a number. The argument may be a plain or long
+ integer or a floating point number. If the argument is a complex number, its
+ magnitude is returned.
+
+- chr(integer)
+
+ Return a string of one character whose ASCII code is the integer, e.g.,
+ 'chr(97)' returns the string 'a'. This is the inverse of ord(). The argument
+ must be in the range 0 to 255, inclusive; 'ValueError' will be raised if the
+ integer is outside that range.
+
+- DateTime()
+
+ Returns a Zope 'DateTime' object given constructor arguments. See the
+ DateTime API reference for more information on constructor arguments.
+
+- divmod(number, number)
+
+ Take two numbers as arguments and return a pair of numbers consisting of
+ their quotient and remainder when using long division. With mixed operand
+ types, the rules for binary arithmetic operators apply. For plain and long
+ integers, the result is the same as '(a / b, a % b)'. For floating point
+ numbers the result is '(q, a % b)', where *q* is usually 'math.floor(a / b)'
+ but may be 1 less than that. In any case 'q * b + a % b' is very close to
+ *a*, if 'a % b' is non-zero it has the same sign as *b*, and '0 <= abs(a % b)
+ < abs(b)'.
+
+- float(number)
+
+ Convert a string or a number to floating point. If the argument is a string,
+ it must contain a possibly signed decimal or floating point number, possibly
+ embedded in whitespace; this behaves identical to 'string.atof(number)'.
+ Otherwise, the argument may be a plain or long integer or a floating point
+ number, and a floating point number with the same value (within Python's
+ floating point precision) is returned.
+
+- getattr(object, string)
+
+ Return the value of the named attributed of object. name must be a string. If
+ the string is the name of one of the object's attributes, the result is the
+ value of that attribute. For example, 'getattr(x, "foobar")' is equivalent to
+ 'x.foobar'. If the named attribute does not exist, default is returned if
+ provided, otherwise 'AttributeError' is raised.
+
+- getitem(variable, render=0)
+
+ Returns the value of a DTML variable. If 'render' is true, the variable is
+ rendered. See the 'render' function.
+
+- hasattr(object, string)
+
+ The arguments are an object and a string. The result is 1 if the string is
+ the name of one of the object's attributes, 0 if not. (This is implemented by
+ calling getattr(object, name) and seeing whether it raises an exception or
+ not.)
+
+- hash(object)
+
+ Return the hash value of the object (if it has one). Hash values are
+ integers. They are used to quickly compare dictionary keys during a
+ dictionary lookup. Numeric values that compare equal have the same hash value
+ (even if they are of different types, e.g. 1 and 1.0).
+
+- has_key(variable)
+
+ Returns true if the DTML namespace contains the named variable.
+
+- hex(integer)
+
+ Convert an integer number (of any size) to a hexadecimal string. The result
+ is a valid Python expression. Note: this always yields an unsigned literal,
+ e.g. on a 32-bit machine, 'hex(-1)' yields '0xffffffff'. When evaluated on a
+ machine with the same word size, this literal is evaluated as -1; at a
+ different word size, it may turn up as a large positive number or raise an
+ 'OverflowError' exception.
+
+- int(number)
+
+ Convert a string or number to a plain integer. If the argument is a string,
+ it must contain a possibly signed decimal number representable as a Python
+ integer, possibly embedded in whitespace; this behaves identical to
+ 'string.atoi(number[, radix]'). The 'radix' parameter gives the base for the
+ conversion and may be any integer in the range 2 to 36. If 'radix' is
+ specified and the number is not a string, 'TypeError' is raised. Otherwise,
+ the argument may be a plain or long integer or a floating point number.
+ Conversion of floating point numbers to integers is defined by the C
+ semantics; normally the conversion truncates towards zero.
+
+- len(sequence)
+
+ Return the length (the number of items) of an object. The argument may be a
+ sequence (string, tuple or list) or a mapping (dictionary).
+
+- max(s)
+
+ With a single argument s, return the largest item of a non-empty sequence
+ (e.g., a string, tuple or list). With more than one argument, return the
+ largest of the arguments.
+
+- min(s)
+
+ With a single argument s, return the smallest item of a non-empty sequence
+ (e.g., a string, tuple or list). With more than one argument, return the
+ smallest of the arguments.
+
+- namespace([name=value]...)
+
+ Returns a new DTML namespace object. Keyword argument 'name=value' pairs are
+ pushed into the new namespace.
+
+- oct(integer)
+
+ Convert an integer number (of any size) to an octal string. The result is a
+ valid Python expression. Note: this always yields an unsigned literal, e.g.
+ on a 32-bit machine, 'oct(-1)' yields '037777777777'. When evaluated on a
+ machine with the same word size, this literal is evaluated as -1; at a
+ different word size, it may turn up as a large positive number or raise an
+ OverflowError exception.
+
+- ord(character)
+
+ Return the ASCII value of a string of one character. E.g., 'ord("a")' returns
+ the integer 97. This is the inverse of 'chr()'.
+
+- pow(x, y [,z])
+
+ Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
+ modulo *z* (computed more efficiently than 'pow(x, y) % z'). The arguments
+ must have numeric types. With mixed operand types, the rules for binary
+ arithmetic operators apply. The effective operand type is also the type of
+ the result; if the result is not expressible in this type, the function
+ raises an exception; e.g., 'pow(2, -1)' or 'pow(2, 35000)' is not allowed.
+
+- range([start,] stop [,step])
+
+ This is a versatile function to create lists containing arithmetic
+ progressions. The arguments must be plain integers. If the step argument is
+ omitted, it defaults to 1. If the start argument is omitted, it defaults to
+ 0. The full form returns a list of plain integers '[start, start + step,
+ start + 2 * step, ...]'. If step is positive, the last element is the largest
+ 'start + i * step' less than *stop*; if *step* is negative, the last element
+ is the largest 'start + i * step' greater than *stop*. *step* must not be
+ zero (or else 'ValueError' is raised).
+
+- round(x [,n])
+
+ Return the floating point value *x* rounded to *n* digits after the decimal
+ point. If n is omitted, it defaults to zero. The result is a floating point
+ number. Values are rounded to the closest multiple of 10 to the power minus
+ n; if two multiples are equally close, rounding is done away from 0 (so e.g.
+ round(0.5) is 1.0 and round(-0.5) is -1.0).
+
+- render(object)
+
+ Render 'object'. For DTML objects this evaluates the DTML code with the
+ current namespace. For other objects, this is equivalent to 'str(object)'.
+
+- reorder(s [,with] [,without])
+
+ Reorder the items in s according to the order given in 'with' and without the
+ items mentioned in 'without'. Items from s not mentioned in with are removed.
+ s, with, and without are all either sequences of strings or sequences of
+ key-value tuples, with ordering done on the keys. This function is useful for
+ constructing ordered select lists.
+
+- SecurityCalledByExecutable()
+
+ Return a true if the current object (e.g. DTML document or method) is being
+ called by an executable (e.g. another DTML document or method, a script or a
+ SQL method).
+
+- SecurityCheckPermission(permission, object)
+
+ Check whether the security context allows the given permission on the given
+ object. For example, 'SecurityCheckPermission("Add Documents, Images, and
+ Files", this())' would return true if the current user was authorized to
+ create documents, images, and files in the current location.
+
+- SecurityGetUser()
+
+ Return the current user object. This is normally the same as the
+ 'REQUEST.AUTHENTICATED_USER' object. However, the 'AUTHENTICATED_USER' object
+ is insecure since it can be replaced.
+
+- SecurityValidate([object] [,parent] [,name] [,value])
+
+ Return true if the value is accessible to the current user. 'object' is the
+ object the value was accessed in, 'parent' is the container of the value, and
+ 'name' is the named used to access the value (for example, if it was obtained
+ via 'getattr'). You may omit some of the arguments, however it is best to
+ provide all available arguments.
+
+- SecurityValidateValue(object)
+
+ Return true if the object is accessible to the current user. This function is
+ the same as calling 'SecurityValidate(None, None, None, object)'.
+
+- str(object)
+
+ Return a string containing a nicely printable representation of an object.
+ For strings, this returns the string itself.
+
+- test(condition, result [,condition, result]... [,default])
+
+ Takes one or more condition, result pairs and returns the result of the first
+ true condition. Only one result is returned, even if more than one condition
+ is true. If no condition is true and a default is given, the default is
+ returned. If no condition is true and there is no default, None is returned.
+
+- unichr(number)
+
+ Return a unicode string representing the value of number as a unicode
+ character. This is the inverse of ord() for unicode characters.
+
+- unicode(string[, encoding[, errors ] ])
+
+ Decodes string using the codec for encoding. Error handling is done according
+ to errors. The default behavior is to decode UTF-8 in strict mode, meaning
+ that encoding errors raise ValueError.
+
+Attributes
+----------
+
+- None
+
+ The 'None' object is equivalent to the Python built-in object 'None'. This is
+ usually used to represent a Null or false value.
+
+See Also
+--------
+
+- `string module`_
+
+.. _string module: http://www.python.org/doc/current/lib/module-string.html
+
+- `random module`_
+
+.. _random module: http://www.python.org/doc/current/lib/module-random.html
+
+- `math module`_
+
+.. _math module: http://www.python.org/doc/current/lib/module-math.html
+
+- `sequence module`_
+
+.. _sequence module: http://www.python.org/doc/current/lib/built-in-funcs.html
+
+
+if: Tests Conditions
+====================
+
+The 'if' tags allows you to test conditions and to take different actions
+depending on the conditions. The 'if' tag mirrors Python's 'if/elif/else'
+condition testing statements.
+
+Syntax
+------
+
+If tag syntax::
+
+ <dtml-if ConditionVariable|expr="ConditionExpression">
+ [<dtml-elif ConditionVariable|expr="ConditionExpression">]
+ ...
+ [<dtml-else>]
+ </dtml-if>
+
+The 'if' tag is a block tag. The 'if' tag and optional 'elif' tags
+take a condition variable name or a condition expression, but not
+both. If the condition name or expression evaluates to true then
+the 'if' block is executed. True means not zero, an empty string
+or an empty list. If the condition variable is not found then the
+condition is considered false.
+
+If the initial condition is false, each 'elif' condition is tested
+in turn. If any 'elif' condition is true, its block is
+executed. Finally the optional 'else' block is executed if none of
+the 'if' and 'elif' conditions were true. Only one block will be
+executed.
+
+Examples
+--------
+
+Testing for a variable::
+
+ <dtml-if snake>
+ The snake variable is true
+ </dtml-if>
+
+Testing for expression conditions::
+
+ <dtml-if expr="num > 5">
+ num is greater than five
+ <dtml-elif expr="num < 5">
+ num is less than five
+ <dtml-else>
+ num must be five
+ </dtml-if>
+
+See Also
+--------
+
+`Python Tutorial If Statements`_
+
+.. _Python Tutorial If Statements: http://docs.python.org/tutorial/controlflow.html#if-statements
+
+
+in: Loops over sequences
+========================
+
+The 'in' tag gives you powerful controls for looping over sequences
+and performing batch processing.
+
+Syntax
+------
+
+'in' tag syntax::
+
+ <dtml-in SequenceVariable|expr="SequenceExpression">
+ [<dtml-else>]
+ </dtml-in>
+
+a commenting identifier at the end tag is allowed and will be ignored like::
+
+ </dtml-in my_short_sequ_name>
+
+same for '</dtml-if>' and '</dtml-let>'
+
+The 'in' block is repeated once for each item in the sequence
+variable or sequence expression. The current item is pushed on to
+the DTML namespace during each executing of the 'in' block.
+
+If there are no items in the sequence variable or expression, the
+optional 'else' block is executed.
+
+Attributes
+----------
+
+- mapping
+
+ Iterates over mapping objects rather than instances. This allows values of
+ the mapping objects to be accessed as DTML variables.
+
+- reverse
+
+ Reverses the sequence.
+
+- sort=string
+
+ Sorts the sequence by the given attribute name.
+
+- start=int
+
+ The number of the first item to be shown, where items are numbered from 1.
+
+- end=int
+
+ The number of the last item to be shown, where items are numbered from 1.
+
+- size=int
+
+ The size of the batch.
+
+- skip_unauthorized
+
+ Don't raise an exception if an unauthorized item is encountered.
+
+- orphan=int
+
+ The desired minimum batch size. This controls how sequences are split into
+ batches. If a batch smaller than the orphan size would occur, then no split
+ is performed, and a batch larger than the batch size results.
+
+ For example, if the sequence size is 12, the batch size is 10 the orphan size
+ is 3, then the result is one batch with all 12 items since splitting the
+ items into two batches would result in a batch smaller than the orphan size.
+
+ The default value is 0.
+
+- overlap=int
+
+ The number of items to overlap between batches. The default is no overlap.
+
+- previous
+
+ Iterates once if there is a previous batch. Sets batch variables for previous
+ sequence.
+
+- next
+
+ Iterates once if there is a next batch. Sets batch variables for the next
+ sequence.
+
+- prefix=string
+
+ Provide versions of the tag variables that start with this prefix instead of
+ "sequence", and that use underscores (_) instead of hyphens (-). The prefix
+ must start with a letter and contain only alphanumeric characters and
+ underscores (_).
+
+- sort_expr=expression
+
+ Sorts the sequence by an attribute named by the value of the expression. This
+ allows you to sort on different attributes.
+
+- reverse_expr=expression
+
+ Reverses the sequence if the expression evaluates to true. This allows you to
+ selectively reverse the sequence.
+
+Tag Variables
+-------------
+
+Current Item Variables
+
+These variables describe the current item.
+
+- sequence-item
+
+ The current item.
+
+- sequence-key
+
+ The current key. When looping over tuples of the form '(key,value)', the 'in'
+ tag interprets them as '(sequence-key, sequence-item)'.
+
+- sequence-index
+
+ The index starting with 0 of the current item.
+
+- sequence-number
+
+ The index starting with 1 of the current item.
+
+- sequence-roman
+
+ The index in lowercase Roman numerals of the current item.
+
+- sequence-Roman
+
+ The index in uppercase Roman numerals of the current item.
+
+- sequence-letter
+
+ The index in lowercase letters of the current item.
+
+- sequence-Letter
+
+ The index in uppercase letters of the current item.
+
+- sequence-start
+
+ True if the current item is the first item.
+
+- sequence-end
+
+ True if the current item is the last item.
+
+- sequence-even
+
+ True if the index of the current item is even.
+
+- sequence-odd
+
+ True if the index of the current item is odd.
+
+- sequence-length
+
+ The length of the sequence.
+
+- sequence-var-*variable*
+
+ A variable in the current item. For example, 'sequence-var-title' is the
+ 'title' variable of the current item. Normally you can access these variables
+ directly since the current item is pushed on the DTML namespace. However
+ these variables can be useful when displaying previous and next batch
+ information.
+
+- sequence-index-*variable*
+
+ 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.
+
+- total-*variable*
+
+ The total of all occurrences of an item variable.
+
+- count-*variable*
+
+ The number of occurrences of an item variable.
+
+- min-*variable*
+
+ The minimum value of an item variable.
+
+- max-*variable*
+
+ The maximum value of an item variable.
+
+- mean-*variable*
+
+ The mean value of an item variable.
+
+- variance-*variable*
+
+ The variance of an item variable with count-1 degrees of freedom.
+
+- variance-n-*variable*
+
+ The variance of an item variable with n degrees of freedom.
+
+- standard-deviation-*variable*
+
+ The standard-deviation of an item variable with count-1 degrees of freedom.
+
+- standard-deviation-n-*variable*
+
+ 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.
+
+- first-*variable*
+
+ True if the current item is the first with a particular value for a variable.
+
+- last-*variable*
+
+ True if the current item is the last with a particular value for a variable.
+
+Batch Variables
+
+- sequence-query
+
+ The query string with the 'start' variable removed. You can use this variable
+ to construct links to next and previous batches.
+
+- sequence-step-size
+
+ The batch size.
+
+- previous-sequence
+
+ True if the current batch is not the first one. Note, this variable is only
+ true for the first loop iteration.
+
+- previous-sequence-start-index
+
+ The starting index of the previous batch.
+
+- previous-sequence-start-number
+
+ The starting number of the previous batch. Note, this is the same as
+ 'previous-sequence-start-index' + 1.
+
+- previous-sequence-end-index
+
+ The ending index of the previous batch.
+
+- previous-sequence-end-number
+
+ The ending number of the previous batch. Note, this is the same as
+ 'previous-sequence-end-index' + 1.
+
+- previous-sequence-size
+
+ The size of the previous batch.
+
+- previous-batches
+
+ A sequence of mapping objects with information about all previous batches.
+ Each mapping object has these keys 'batch-start-index', 'batch-end-index',
+ and 'batch-size'.
+
+- next-sequence
+
+ True if the current batch is not the last batch. Note, this variable is only
+ true for the last loop iteration.
+
+- next-sequence-start-index
+
+ The starting index of the next sequence.
+
+- next-sequence-start-number
+
+ The starting number of the next sequence. Note, this is the same as
+ 'next-sequence-start-index' + 1.
+
+- next-sequence-end-index
+
+ The ending index of the next sequence.
+
+- next-sequence-end-number
+
+ The ending number of the next sequence. Note, this is the same as
+ 'next-sequence-end-index' + 1.
+
+- next-sequence-size
+
+ The size of the next index.
+
+- next-batches
+
+ A sequence of mapping objects with information about all following batches.
+ Each mapping object has these keys 'batch-start-index', 'batch-end-index',
+ and 'batch-size'.
+
+Examples
+--------
+
+Looping over sub-objects::
+
+ <dtml-in objectValues>
+ title: <dtml-var title><br>
+ </dtml-in>
+
+Looping over two sets of objects, using prefixes::
+
+ <dtml-let rows="(1,2,3)" cols="(4,5,6)">
+ <dtml-in rows prefix="row">
+ <dtml-in cols prefix="col">
+ <dtml-var expr="row_item * col_item"><br>
+ <dtml-if col_end>
+ <dtml-var expr="col_total_item * row_mean_item">
+ </dtml-if>
+ </dtml-in>
+ </dtml-in>
+ </dtml-let>
+
+Looping over a list of '(key, value)' tuples::
+
+ <dtml-in objectItems>
+ id: <dtml-var sequence-key>, title: <dtml-var title><br>
+ </dtml-in>
+
+Creating alternate colored table rows::
+
+ <table>
+ <dtml-in objectValues>
+ <tr <dtml-if sequence-odd>bgcolor="#EEEEEE"
+ <dtml-else>bgcolor="#FFFFFF"
+ </dtml-if>>
+ <td><dtml-var title></td>
+ </tr>
+ </dtml-in>
+ </table>
+
+Basic batch processing::
+
+ <p>
+ <dtml-in largeSequence size=10 start=start previous>
+ <a href="<dtml-var absolute_url>
+ <dtml-var sequence-query>start=<dtml-var previous-sequence-start-number>">
+ Previous
+ </a>
+ </dtml-in>
+
+ <dtml-in largeSequence size=10 start=start next>
+ <a href="<dtml-var absolute_url>
+ <dtml-var sequence-query>start=<dtml-var next-sequence-start-number>">
+ Next
+ </a>
+ </dtml-in>
+ </p>
+
+ <p>
+ <dtml-in largeSequence size=10 start=start>
+ <dtml-var sequence-item>
+ </dtml-in>
+ </p>
+
+This example creates *Previous* and *Next* links to navigate between batches.
+Note, by using 'sequence-query', you do not lose any GET variables as you
+navigate between batches.
+
+let: Defines DTML variables
+===========================
+
+The 'let' tag defines variables in the DTML namespace.
+
+Syntax
+------
+
+'let' tag syntax::
+
+ <dtml-let [Name=Variable][Name="Expression"]...>
+ </dtml-let>
+
+The 'let' tag is a block tag. Variables are defined by tag arguments. Defined
+variables are pushed onto the DTML namespace while the 'let' block is executed.
+Variables are defined by attributes. The 'let' tag can have one or more
+attributes with arbitrary names. If the attributes are defined with double
+quotes they are considered expressions, otherwise they are looked up by name.
+Attributes are processed in order, so later attributes can reference, and/or
+overwrite earlier ones.
+
+Examples
+--------
+
+Basic usage::
+
+ <dtml-let name="'Bob'" ids=objectIds>
+ name: <dtml-var name>
+ ids: <dtml-var ids>
+ </dtml-let>
+
+Using the 'let' tag with the 'in' tag::
+
+ <dtml-in expr="(1,2,3,4)">
+ <dtml-let num=sequence-item
+ index=sequence-index
+ result="num*index">
+ <dtml-var num> * <dtml-var index> = <dtml-var result>
+ </dtml-let>
+ </dtml-in>
+
+This yields::
+
+ 1 * 0 = 0
+ 2 * 1 = 2
+ 3 * 2 = 6
+ 4 * 3 = 12
+
+See Also
+--------
+
+ with tag
+
+mime: Formats data with MIME
+============================
+
+The 'mime' tag allows you to create MIME encoded data. It is chiefly used to
+format email inside the 'sendmail' tag.
+
+Syntax
+------
+
+'mime' tag syntax::
+
+ <dtml-mime>
+ [<dtml-boundry>]
+ ...
+ </dtml-mime>
+
+The 'mime' tag is a block tag. The block is can be divided by one or more
+'boundry' tags to create a multi-part MIME message. 'mime' tags may be nested.
+The 'mime' tag is most often used inside the 'sendmail' tag.
+
+Attributes
+----------
+
+Both the 'mime' and 'boundry' tags have the same attributes.
+
+XXX Here we need to continue
+
+ 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.
+
+ type=string -- MIME Content-Type header.
+
+ type_expr=string -- MIME Content-Type header as a variable
+ expression. You cannot use both 'type' and 'type_expr'.
+
+ name=string -- MIME Content-Type header name.
+
+ name_expr=string -- MIME Content-Type header name as a variable
+ expression. You cannot use both 'name' and 'name_expr'.
+
+ 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
+--------
+
+Sending a file attachment::
+
+ <dtml-sendmail>
+ To: <dtml-var recipient>
+ Subject: Resume
+ <dtml-mime type="text/plain" encode="7bit">
+
+ Hi, please take a look at my resume.
+
+ <dtml-boundary type="application/octet-stream" disposition="attachment"
+ encode="base64" filename_expr="resume_file.getId()"><dtml-var expr="resume_file.read()"></dtml-mime>
+ </dtml-sendmail>
+
+See Also
+
+`Python Library mimetools`_
+
+.. _Python Library mimetools: http://www.python.org/doc/current/lib/module-mimetools.html
+
+raise: Raises an exception
+==========================
+
+The 'raise' tag raises an exception, mirroring the Python 'raise'
+statement.
+
+Syntax
+
+ 'raise' tag syntax::
+
+ <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.
+
+Examples
+
+ Raising a KeyError::
+
+ <dtml-raise KeyError></dtml-raise>
+
+ Raising an HTTP 404 error::
+
+ <dtml-raise NotFound>Web Page Not Found</dtml-raise>
+
+See Also
+
+ try tag
+
+ "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
+
+return: Returns data
+====================
+
+The 'return' tag stops executing DTML and returns data. It mirrors
+the Python 'return' statement.
+
+Syntax
+
+ 'return' tag syntax::
+
+ <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.
+
+ % 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::
+
+ <dtml-return result>
+
+ Returning a Python dictionary::
+
+ <dtml-return expr="{'hi':200, 'lo':5}">
+
+sendmail: Sends email with SMTP
+===============================
+
+The 'sendmail' tag sends an email message
+using SMTP.
+
+Syntax
+
+ 'sendmail' tag syntax::
+
+ <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.
+
+Attributes
+
+ mailhost -- The name of a Zope MailHost object
+ to use to send email. You cannot specify both a mailhost and a smtphost.
+
+ smtphost -- The name of a SMTP server used 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.
+
+ 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::
+
+ <dtml-sendmail mailhost="mailhost">
+ To: <dtml-var recipient>
+ From: <dtml-var sender>
+ Subject: <dtml-var subject>
+
+ Dear <dtml-var recipient>,
+
+ 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
+
+ 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.
+
+ % Anonymous User - May 2, 2002 9:13 am:
+ there is a sql-delimiter not documented here
+
+Syntax
+
+ 'sqlgroup' tag syntax::
+
+ <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.
+
+Attributes
+
+ required=boolean -- 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::
+
+ 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::
+
+ select * from employees
+ where
+ (first='Bob'
+ and
+ last in ('Smith', 'McDonald')
+ )
+
+ If 'salary' is 50000 and 'last' is 'Smith' it renders::
+
+ select * from employees
+ where
+ (salary > 50000.0
+ and
+ last='Smith'
+ )
+
+ 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">
+ </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::
+
+ select * form employees
+ where
+ (
+ (
+ name like 'A*'
+ and
+ last like 'Smith'
+ )
+ or
+ salary > 20000.0
+ )
+
+See Also
+
+ 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.
+
+Syntax
+
+ 'sqltest' tag syntax::
+
+ <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.
+
+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.
+
+ column=string -- The name of the SQL column to test against. This
+ attribute defaults to the variable name.
+
+ multiple=boolean -- If true, then the variable may be a sequence
+ of values to test the column against.
+
+ optional=boolean -- If true, then the test is optional and will
+ not be rendered if the variable is empty or non-existent.
+
+ op=string -- The comparison operation. Valid comparisons include:
+
+ eq -- equal to
+
+ 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::
+
+ select * from employees
+ where <dtml-sqltest name type="nb">
+
+ If the 'name' variable is 'Bob' then this renders::
+
+ select * from employees
+ where name = 'Bob'
+
+ Multiple values::
+
+ select * from employees
+ where <dtml-sqltest empid type=int multiple>
+
+ If the 'empid' variable is '(12,14,17)' then this renders::
+
+ select * from employees
+ where empid in (12, 14, 17)
+
+See Also
+
+ sqlgroup tag
+
+ sqlvar tag
+
+sqlvar: Inserts SQL variables
+=============================
+
+The 'sqlvar' tag safely inserts variables into SQL code. This tag is
+used in SQL Methods.
+
+Syntax
+
+ 'sqlvar' tag syntax::
+
+ <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.
+
+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.
+
+ optional=boolean -- If true and the variable is null or
+ non-existent, then nothing is inserted.
+
+Examples
+
+ Basic usage::
+
+ select * from employees
+ where name=<dtml-sqlvar name type="nb">
+
+ This SQL quotes the 'name' string variable.
+
+See Also
+
+ sqltest tag
+
+tree: Inserts a tree widget
+===========================
+
+The 'tree' tag displays a dynamic tree widget by querying Zope
+objects.
+
+Syntax
+
+ 'tree' tag syntax::
+
+ <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.
+
+ % 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.
+
+Attributes
+
+ branches=string -- Finds tree branches by calling the named
+ method. The default method is 'tpValues' which most Zope objects
+ support.
+
+ branches_expr=string -- Finds tree branches by evaluating the
+ expression.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ header=string -- The name of a DTML Document or Method displayed
+ before expanded nodes. If the header is not found, it is skipped.
+
+ footer=string -- The name of a DTML Document or Method displayed
+ after expanded nodes. If the footer is not found, it is skipped.
+
+ 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-url -- The URL of the current node.
+
+ tree-root-url -- 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.
+
+ expand_all -- 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::
+
+ <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::
+
+ <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.
+
+Syntax
+
+ The 'try' tag has two different syntaxes, 'try/except/else' and
+ 'try/finally'.
+
+ 'try/except/else' Syntax::
+
+ <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.
+
+ 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.
+
+ The 'except' and 'else' tags are optional.
+
+ 'try/finally' Syntax::
+
+ <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.
+
+Attributes
+
+ 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.
+
+ error_type -- The exception type.
+
+ error_value -- The exception value.
+
+ error_tb -- The traceback.
+
+Examples
+
+ Catching a math error::
+
+ <dtml-try>
+ <dtml-var expr="1/0">
+ <dtml-except ZeroDivisionError>
+ You tried to divide by zero.
+ </dtml-try>
+
+ 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>
+
+ 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>
+
+See Also
+
+ raise tag
+
+ "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
+
+unless: Tests a condition
+=========================
+
+The 'unless' tag provides a shortcut for testing negative
+conditions. For more complete condition testing use the 'if' tag.
+
+Syntax
+
+ 'unless' tag syntax::
+
+ <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.
+
+Examples
+
+ Testing a variable::
+
+ <dtml-unless testMode>
+ <dtml-call dangerousOperation>
+ </dtml-unless>
+
+ The block will be executed if 'testMode' does not exist, or exists
+ but is false.
+
+See Also
+
+ if tag
+
+var: Inserts a variable
+
+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::
+
+ <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.
+
+ 'var' tag entity syntax::
+
+ &dtml-variableName;
+
+ 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::
+
+ &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;'.
+
+Attributes
+
+ html_quote -- Convert characters that have special meaning in
+ HTML to HTML character entities.
+
+ missing=string -- Specify a default value in case Zope cannot find
+ the variable.
+
+ 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.
+
+ whole-dollars -- Formats the variable as dollars.
+
+ dollars-and-cents -- Formats the variable as dollars and cents.
+
+ collection-length -- The length of the variable, assuming it is
+ a sequence.
+
+ 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.
+
+ null=string -- A default value to use if the variable is None.
+
+ lower -- Converts upper-case letters to lower case.
+
+ upper -- Converts lower-case letters to upper case.
+
+ capitalize -- Capitalizes the first character of the inserted
+ word.
+
+ spacify -- Changes underscores in the inserted value to spaces.
+
+ thousands_commas -- 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 '...'
+
+Examples
+
+ Inserting a simple variable into a document::
+
+ <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::
+
+ <dtml-var colors size=10 etc=", etc.">
+
+ will produce the following output if *colors* is the string 'red
+ yellow green'::
+
+ red yellow, etc.
+
+ C-style string formatting::
+
+ <dtml-var expr="23432.2323" fmt="%.2f">
+
+ renders to::
+
+ 23432.23
+
+ Inserting a variable, *link*, inside an HTML 'A' tag with the entity
+ syntax::
+
+ <a href="&dtml-link;">Link</a>
+
+ 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>
+
+ 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.
+
+Syntax
+
+ 'with' tag syntax::
+
+ <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.
+
+Attributes
+
+ only -- 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::
+
+ <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::
+
+ <dtml-with expr="objectValues()[0]">
+ First child's id: <dtml-var id>
+ </dtml-with>
+
+See Also
+
+ let tag
Modified: zope2book/trunk/source/index.rst
===================================================================
--- zope2book/trunk/source/index.rst 2009-02-10 17:12:50 UTC (rev 96395)
+++ zope2book/trunk/source/index.rst 2009-02-10 17:15:41 UTC (rev 96396)
@@ -16,8 +16,8 @@
ZopeArchitecture.rst
InstallingZope.rst
Contributions.rst
+ AppendixA.rst
-
Indices and tables
------------------
More information about the Checkins
mailing list