<html>
<head>
<title>Appendix A: DTML Reference</title>
</head>
<body bgcolor="#FFFFFF">
<h1>Appendix A: DTML Reference</h1>
<p> DTML is the <em>Document Template Markup Language</em>, 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.</p><h2> call: Call a method</h2>
<p> The <code>call</code> tag lets you call a method without inserting the results
into the DTML output.</p><h3> Syntax</h3>
<p> <code>call</code> tag syntax:<pre> <dtml-call Variable|expr="Expression"></pre>
</p><p> If the call tag uses a variable, the methods arguments are passed
automatically by DTML just as with the <code>var</code> tag. If the method is
specified in a expression, then you must pass the arguments yourself.</p><h3> Examples</h3>
<p> Calling by variable name:<pre> <dtml-call UpdateInfo></pre>
</p><p> This calls the <code>UpdateInfo</code> object automatically passing arguments.</p><p> Calling by expression:<pre> <dtml-call expr="RESPONSE.setHeader('content-type', 'text/plain')"></pre>
</p><h3> See Also</h3>
<p> var tag</p><h2> comment: Comments DTML</h2>
<p> The comment tag lets you document your DTML with comments. You can
also use it to temporarily disable DTML tags by commenting them out.</p><h3> Syntax</h3>
<p> <code>comment</code> tag syntax:<pre> <dtml-comment>
</dtml-comment></pre>
</p><p> The <code>comment</code> tag is a block tag. The contents of the block are
not executed, nor are they inserted into the DTML output.</p><h3> Examples</h3>
<p> Documenting DTML:<pre> <dtml-comment>
This content is not executed and does not appear in the
output.
</dtml-comment></pre>
</p><p> Commenting out DTML:<pre> <dtml-comment>
This DTML is disabled and will not be executed.
<dtml-call someMethod>
</dtml-comment></pre>
</p><h2> functions: DTML Functions</h2>
<p> DTML utility functions provide some Python built-in functions and
some DTML-specific functions.</p><h3> Functions</h3>
<dl>
<dt> abs(number)</dt>
<dd>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.</dd>
<dt> chr(integer)</dt>
<dd>Return a string of one character whose ASCII code
is the integer, e.g., <code>chr(97)</code> returns the string <code>a</code>. This is
the inverse of ord(). The argument must be in the range 0 to 255,
inclusive; <code>ValueError</code> will be raised if the integer is outside
that range.</dd>
<dt> DateTime()</dt>
<dd>Returns a Zope <code>DateTime</code> object given constructor
arguments. See the DateTime API reference for more
information on constructor arguments.</dd>
<dt> divmod(number, number)</dt>
<dd>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 <code>(a / b, a % b)</code>. For floating point
numbers the result is <code>(q, a % b)</code>, where <em>q</em> is usually
<code>math.floor(a / b)</code> but may be 1 less than that. In any case 'q *
b + a % b' is very close to <em>a</em>, if <code>a % b</code> is non-zero it has the
same sign as <em>b</em>, and <code>0 <= abs(a % b) < abs(b)</code>.</dd>
<dt> float(number)</dt>
<dd>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
<code>string.atof(number)</code>. 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.</dd>
<dt> getattr(object, string)</dt>
<dd>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, <code>getattr(x, "foobar")</code> is equivalent
to <code>x.foobar</code>. If the named attribute does not exist, default is
returned if provided, otherwise <code>AttributeError</code> is raised.</dd>
<dt> getitem(variable, render=0)</dt>
<dd>Returns the value of a DTML variable.
If <code>render</code> is true, the variable is rendered. See the <code>render</code>
function.</dd>
<dt> hasattr(object, string)</dt>
<dd>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.)</dd>
<dt> hash(object)</dt>
<dd>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).</dd>
<dt> has_key(variable)</dt>
<dd>Returns true if the DTML namespace contains the
named variable.</dd>
<dt> hex(integer)</dt>
<dd>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, <code>hex(-1)</code>
yields <code>0xffffffff</code>. 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 <code>OverflowError</code>
exception.</dd>
<dt> int(number)</dt>
<dd>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 <code>radix</code> parameter gives the
base for the conversion and may be any integer in the range 2 to
36. If <code>radix</code> is specified and the number is not a string,
<code>TypeError</code> 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.</dd>
<dt> len(sequence)</dt>
<dd>Return the length (the number of items) of an
object. The argument may be a sequence (string, tuple or list) or a
mapping (dictionary).</dd>
<dt> max(s)</dt>
<dd>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.</dd>
<dt> min(s)</dt>
<dd>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.</dd>
<dt> namespace([name=value]...)</dt>
<dd>Returns a new DTML namespace object.
Keyword argument <code>name=value</code> pairs are pushed into the new
namespace.</dd>
<dt> oct(integer)</dt>
<dd>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, <code>oct(-1)</code> yields
<code>037777777777</code>. 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.</dd>
<dt> ord(character)</dt>
<dd>Return the ASCII value of a string of one
character. E.g., <code>ord("a")</code> returns the integer 97. This is the
inverse of <code>chr()</code>.</dd>
<dt> pow(x, y [,z])</dt>
<dd>Return <em>x</em> to the power <em>y</em>; if <em>z</em> is present,
return <em>x</em> to the power <em>y</em>, modulo <em>z</em> (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., <code>pow(2, -1)</code> or <code>pow(2, 35000)</code> is not
allowed.</dd>
<dt> range([start,] stop [,step])</dt>
<dd>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 <em> step' less than </em>stop<em>; if
</em>step<em> is negative, the last element is the largest 'start + i </em>
step' greater than <em>stop</em>. <em>step</em> must not be zero (or else
<code>ValueError</code> is raised).</dd>
<dt> round(x [,n])</dt>
<dd>Return the floating point value <em>x</em> rounded to <em>n</em>
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).</dd>
<dt> render(object)</dt>
<dd>Render <code>object</code>. For DTML objects this
evaluates the DTML code with the current namespace. For other
objects, this is equivalent to <code>str(object)</code>.</dd>
<dt> reorder(s [,with] [,without])</dt>
<dd>Reorder the items in s according
to the order given in <code>with</code> and without the items mentioned in
<code>without</code>. 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.</dd>
<dt> SecurityCalledByExecutable()</dt>
<dd>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).</dd>
<dt> SecurityCheckPermission(permission, object)</dt>
<dd>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.</dd>
<dt> SecurityGetUser()</dt>
<dd>Return the current user object. This is
normally the same as the <code>REQUEST.AUTHENTICATED_USER</code>
object. However, the <code>AUTHENTICATED_USER</code> object is insecure since
it can be replaced.</dd>
<dt> SecurityValidate([object] [,parent] [,name] [,value])</dt>
<dd>Return
true if the value is accessible to the current user. <code>object</code> is
the object the value was accessed in, <code>parent</code> is the container of
the value, and <code>name</code> 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.</dd>
<dt> SecurityValidateValue(object)</dt>
<dd>Return true if the object is
accessible to the current user. This function is the same as
calling <code>SecurityValidate(None, None, None, object)</code>.</dd>
<dt> str(object)</dt>
<dd>Return a string containing a nicely printable
representation of an object. For strings, this returns the string
itself. </dd>
<dt> test(condition, result [,condition, result]... [,default])</dt>
<dd>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.</dd>
<dt> unichr(number)</dt>
<dd>Return a unicode string representing the value of
number as a unicode character. This is the inverse of ord() for
unicode characters. </dd>
<dt> unicode(string[, encoding[, errors ] ])</dt>
<dd>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.</dd>
</dl>
<h3> Attributes</h3>
<dl>
<dt> None</dt>
<dd>The <code>None</code> object is equivalent to the Python built-in object
<code>None</code>. This is usually used to represent a Null or false value.</dd>
</dl>
<h3> See Also</h3>
<p> <code>string</code> module</p><p> <code>random</code> module</p><p> <code>math</code> module</p><p> <code>sequence</code> module</p><p> <a href="http://www.python.org/doc/current/lib/built-in-funcs.html">Built-in Python Functions</a></p><h2> if: Tests Conditions</h2>
<p> The <code>if</code> tags allows you to test conditions and to take different
actions depending on the conditions. The <code>if</code> tag mirrors Python's
<code>if/elif/else</code> condition testing statements.</p><h3> Syntax</h3>
<p> If tag syntax:<pre> <dtml-if ConditionVariable|expr="ConditionExpression">
[<dtml-elif ConditionVariable|expr="ConditionExpression">]
...
[<dtml-else>]
</dtml-if></pre>
</p><p> The <code>if</code> tag is a block tag. The <code>if</code> tag and optional <code>elif</code> tags
take a condition variable name or a condition expression, but not
both. If the condition name or expression evaluates to true then
the <code>if</code> 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.</p><p> If the initial condition is false, each <code>elif</code> condition is tested
in turn. If any <code>elif</code> condition is true, its block is
executed. Finally the optional <code>else</code> block is executed if none of
the <code>if</code> and <code>elif</code> conditions were true. Only one block will be
executed.</p><h3> Examples</h3>
<p> Testing for a variable:<pre> <dtml-if snake>
The snake variable is true
</dtml-if></pre>
</p><p> Testing for expression conditions:<pre> <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></pre>
</p><h3> See Also</h3>
<p> <a href="http://www.python.org/doc/current/tut/node6.html#SECTION006100000000000000000">Python Tutorial: If Statements</a></p><h2> in: Loops over sequences</h2>
<p> The <code>in</code> tag gives you powerful controls for looping over sequences
and performing batch processing.</p><h3> Syntax</h3>
<p> <code>in</code> tag syntax:<pre> <dtml-in SequenceVariable|expr="SequenceExpression">
[<dtml-else>]
</dtml-in></pre>
</p><p> The <code>in</code> 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 <code>in</code> block.</p><p> If there are no items in the sequence variable or expression, the
optional <code>else</code> block is executed.</p><h3> Attributes</h3>
<dl>
<dt> mapping</dt>
<dd>Iterates over mapping objects rather than
instances. This allows values of the mapping objects to be
accessed as DTML variables.</dd>
<dt> reverse</dt>
<dd>Reverses the sequence.</dd>
<dt> sort=string</dt>
<dd>Sorts the sequence by the given attribute name.</dd>
<dt> start=int</dt>
<dd>The number of the first item to be shown, where
items are numbered from 1.</dd>
<dt> end=int</dt>
<dd>The number of the last item to be shown, where items
are numbered from 1.</dd>
<dt> size=int</dt>
<dd>The size of the batch.</dd>
<dt> skip_unauthorized</dt>
<dd>Don't raise an exception if an unauthorized
item is encountered.</dd>
<dt> orphan=int</dt>
<dd>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.<p> 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.</p><p> The default value is 0.</p></dd>
<dt> overlap=int</dt>
<dd>The number of items to overlap between batches. The
default is no overlap.</dd>
<dt> previous</dt>
<dd>Iterates once if there is a previous batch. Sets batch
variables for previous sequence. </dd>
<dt> next</dt>
<dd>Iterates once if there is a next batch. Sets batch variables
for the next sequence.</dd>
<dt> prefix=string</dt>
<dd>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 (_).</dd>
<dt> sort_expr=expression</dt>
<dd>Sorts the sequence by an attribute named
by the value of the expression. This allows you to sort on
different attributes.</dd>
<dt> reverse_expr=expression</dt>
<dd>Reverses the sequence if the expression
evaluates to true. This allows you to selectively reverse the
sequence.</dd>
</dl>
<h3> Tag Variables</h3>
<h4> Current Item Variables</h4>
<p> These variables describe the
current item.<dl>
<dt> sequence-item</dt>
<dd>The current item.</dd>
<dt> sequence-key</dt>
<dd>The current key. When looping over tuples of the
form <code>(key,value)</code>, the <code>in</code> tag interprets them as
<code>(sequence-key, sequence-item)</code>. </dd>
<dt> sequence-index</dt>
<dd>The index starting with 0 of the current item.</dd>
<dt> sequence-number</dt>
<dd>The index starting with 1 of the current item.</dd>
<dt> sequence-roman</dt>
<dd>The index in lowercase Roman numerals of the
current item.</dd>
<dt> sequence-Roman</dt>
<dd>The index in uppercase Roman numerals of the
current item.</dd>
<dt> sequence-letter</dt>
<dd>The index in lowercase letters of the current
item.</dd>
<dt> sequence-Letter</dt>
<dd>The index in uppercase letters of the current
item.</dd>
<dt> sequence-start</dt>
<dd>True if the current item is the first item.</dd>
<dt> sequence-end</dt>
<dd>True if the current item is the last item.</dd>
<dt> sequence-even</dt>
<dd>True if the index of the current item is even.</dd>
<dt> sequence-odd</dt>
<dd>True if the index of the current item is odd.</dd>
<dt> sequence-length</dt>
<dd>The length of the sequence.</dd>
<dt> sequence-var-<em>variable</em></dt>
<dd>A variable in the current item. For
example, <code>sequence-var-title</code> is the <code>title</code> 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.</dd>
<dt> sequence-index-<em>variable</em></dt>
<dd>The index of a variable of the
current item.</dd>
</dl>
</p><h4> Summary Variables</h4>
<p> 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.<dl>
<dt> total-<em>variable</em></dt>
<dd>The total of all occurrences of an item variable. </dd>
<dt> count-<em>variable</em></dt>
<dd>The number of occurrences of an item variable.</dd>
<dt> min-<em>variable</em></dt>
<dd>The minimum value of an item variable.</dd>
<dt> max-<em>variable</em></dt>
<dd>The maximum value of an item variable.</dd>
<dt> mean-<em>variable</em></dt>
<dd>The mean value of an item variable.</dd>
<dt> variance-<em>variable</em></dt>
<dd>The variance of an item variable with
count-1 degrees of freedom. </dd>
<dt> variance-n-<em>variable</em></dt>
<dd>The variance of an item variable with
n degrees of freedom. </dd>
<dt> standard-deviation-<em>variable</em></dt>
<dd>The standard-deviation of an
item variable with count-1 degrees of freedom.</dd>
<dt> standard-deviation-n-<em>variable</em></dt>
<dd>The standard-deviation of
an item variable with n degrees of freedom.</dd>
</dl>
</p><h4> Grouping Variables</h4>
<p> These variables allow you to track changes in current item
variables.<dl>
<dt> first-<em>variable</em></dt>
<dd>True if the current item is the first with
a particular value for a variable.</dd>
<dt> last-<em>variable</em></dt>
<dd>True if the current item is the last with a
particular value for a variable.</dd>
</dl>
</p><h4> Batch Variables</h4>
<dl>
<dt> sequence-query</dt>
<dd>The query string with the <code>start</code> variable
removed. You can use this variable to construct links to next
and previous batches.</dd>
<dt> sequence-step-size</dt>
<dd>The batch size.</dd>
<dt> previous-sequence</dt>
<dd>True if the current batch is not the
first one. Note, this variable is only true for the first loop
iteration. </dd>
<dt> previous-sequence-start-index</dt>
<dd>The starting index of the
previous batch.</dd>
<dt> previous-sequence-start-number</dt>
<dd>The starting number of the
previous batch. Note, this is the same as
<code>previous-sequence-start-index</code> + 1.</dd>
<dt> previous-sequence-end-index</dt>
<dd>The ending index of the previous
batch. </dd>
<dt> previous-sequence-end-number</dt>
<dd>The ending number of the
previous batch. Note, this is the same as
<code>previous-sequence-end-index</code> + 1.</dd>
<dt> previous-sequence-size</dt>
<dd>The size of the previous batch.</dd>
<dt> previous-batches</dt>
<dd>A sequence of mapping objects with
information about all previous batches. Each mapping object has
these keys <code>batch-start-index</code>, <code>batch-end-index</code>, and
<code>batch-size</code>.</dd>
<dt> next-sequence</dt>
<dd>True if the current batch is not the last
batch. Note, this variable is only true for the last loop
iteration. </dd>
<dt> next-sequence-start-index</dt>
<dd>The starting index of the next
sequence. </dd>
<dt> next-sequence-start-number</dt>
<dd>The starting number of the next
sequence. Note, this is the same as <code>next-sequence-start-index</code>
+ 1.</dd>
<dt> next-sequence-end-index</dt>
<dd>The ending index of the next
sequence. </dd>
<dt> next-sequence-end-number</dt>
<dd>The ending number of the next
sequence. Note, this is the same as <code>next-sequence-end-index</code>
+ 1.</dd>
<dt> next-sequence-size</dt>
<dd>The size of the next index.</dd>
<dt> next-batches</dt>
<dd>A sequence of mapping objects with information
about all following batches. Each mapping object has these keys
<code>batch-start-index</code>, <code>batch-end-index</code>, and <code>batch-size</code>.</dd>
</dl>
<h3> Examples</h3>
<p> Looping over sub-objects:<pre> <dtml-in objectValues>
title: <dtml-var title><br>
</dtml-in></pre>
</p><p> Looping over two sets of objects, using prefixes:<pre> <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></pre>
</p><p> Looping over a list of <code>(key, value)</code> tuples:<pre> <dtml-in objectItems>
id: <dtml-var sequence-key>, title: <dtml-var title><br>
</dtml-in> </pre>
</p><p> Creating alternate colored table cells:<pre> <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></pre>
</p><p> Basic batch processing:<pre> <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></pre>
</p><p> This example creates <em>Previous</em> and <em>Next</em> links to navigate
between batches. Note, by using <code>sequence-query</code>, you do not lose
any GET variables as you navigate between batches.</p><h2> let: Defines DTML variables</h2>
<p> The <code>let</code> tag defines variables in the DTML namespace.</p><h3> Syntax</h3>
<p> <code>let</code> tag syntax:<pre> <dtml-let [Name=Variable][Name="Expression"]...>
</dtml-let></pre>
</p><p> The <code>let</code> tag is a block tag. Variables are defined by tag
arguments. Defined variables are pushed onto the DTML namespace
while the <code>let</code> block is executed. Variables are defined by
attributes. The <code>let</code> 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.</p><h3> Examples</h3>
<p> Basic usage:<pre> <dtml-let name="'Bob'" ids=objectIds>
name: <dtml-var name>
ids: <dtml-var ids>
</dtml-let></pre>
</p><p> Using the <code>let</code> tag with the <code>in</code> tag:<pre> <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></pre>
</p><p> This yields:<pre> 1 * 0 = 0
2 * 1 = 2
3 * 2 = 6
4 * 3 = 12</pre>
</p><h3> See Also</h3>
<p> with tag</p><h2> mime: Formats data with MIME</h2>
<p> The <code>mime</code> tag allows you to create MIME encoded data. It is chiefly
used to format email inside the <code>sendmail</code> tag.</p><h3> Syntax</h3>
<p> <code>mime</code> tag syntax:<pre> <dtml-mime>
[<dtml-boundry>]
...
</dtml-mime></pre>
</p><p> The <code>mime</code> tag is a block tag. The block is can be divided by one
or more <code>boundry</code> tags to create a multi-part MIME message. <code>mime</code>
tags may be nested. The <code>mime</code> tag is most often used inside the
<code>sendmail</code> tag.</p><h3> Attributes</h3>
<p> Both the <code>mime</code> and <code>boundry</code> tags
have the same attributes.<dl>
<dt> encode=string</dt>
<dd>MIME Content-Transfer-Encoding header, defaults
to <code>base64</code>. Valid encoding options include <code>base64</code>,
<code>quoted-printable</code>, <code>uuencode</code>, <code>x-uuencode</code>, <code>uue</code>, <code>x-uue</code>,
and <code>7bit</code>. If the <code>encode</code> attribute is set to <code>7bit</code> no
encoding is done on the block and the data is assumed to be in a
valid MIME format.</dd>
<dt> type=string</dt>
<dd>MIME Content-Type header.</dd>
<dt> type_expr=string</dt>
<dd>MIME Content-Type header as a variable
expression. You cannot use both <code>type</code> and <code>type_expr</code>.</dd>
<dt> name=string</dt>
<dd>MIME Content-Type header name.</dd>
<dt> name_expr=string</dt>
<dd>MIME Content-Type header name as a variable
expression. You cannot use both <code>name</code> and <code>name_expr</code>.</dd>
<dt> disposition=string</dt>
<dd>MIME Content-Disposition header.</dd>
<dt> disposition_expr=string</dt>
<dd>MIME Content-Disposition header as a
variable expression. You cannot use both <code>disposition</code> and
<code>disposition_expr</code>.</dd>
<dt> filename=string</dt>
<dd>MIME Content-Disposition header filename.</dd>
<dt> filename_expr=string</dt>
<dd>MIME Content-Disposition header filename
as a variable expression. You cannot use both <code>filename</code> and
<code>filename_expr</code>.</dd>
<dt> skip_expr=string</dt>
<dd>A variable expression that if true, skips
the block. You can use this attribute to selectively include
MIME blocks.</dd>
</dl>
</p><h3> Examples</h3>
<p> Sending a file attachment:<pre> <dtml-sendmail>
To: <dtml-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></pre>
</p><h3> See Also</h3>
<p> <a href="http://www.python.org/doc/current/lib/module-mimetools.html">Python Library: mimetools</a></p><h2> raise: Raises an exception </h2>
<p> The <code>raise</code> tag raises an exception, mirroring the Python <code>raise</code>
statement.</p><h3> Syntax</h3>
<p> <code>raise</code> tag syntax:<pre> <dtml-raise ExceptionName|ExceptionExpression>
</dtml-raise></pre>
</p><p> The <code>raise</code> 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.</p><h3> Examples</h3>
<p> Raising a KeyError:<pre> <dtml-raise KeyError></dtml-raise></pre>
</p><p> Raising an HTTP 404 error:<pre> <dtml-raise NotFound>Web Page Not Found</dtml-raise></pre>
</p><h3> See Also</h3>
<p> try tag</p><p> <a href="http://www.python.org/doc/current/tut/node10.html">Python Tutorial: Errors and
Exceptions</a></p><p> <a href="http://www.python.org/doc/current/lib/module-exceptions.html">Python Built-in
Exceptions</a></p><h2> return: Returns data</h2>
<p> The <code>return</code> tag stops executing DTML and returns data. It mirrors
the Python <code>return</code> statement.</p><h3> Syntax</h3>
<p> <code>return</code> tag syntax:<pre> <dtml-return ReturnVariable|expr="ReturnExpression"></pre>
</p><p> 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.</p><h3> Examples</h3>
<p> Returning a variable:<pre> <dtml-return result> </pre>
</p><p> Returning a Python dictionary:<pre> <dtml-return expr="{'hi':200, 'lo':5}"></pre>
</p><h2> sendmail: Sends email with SMTP</h2>
<p> The <code>sendmail</code> tag sends an email message
using SMTP.</p><h3> Syntax</h3>
<p> <code>sendmail</code> tag syntax:<pre> <dtml-sendmail>
</dtml-sendmail></pre>
</p><p> The <code>sendmail</code> tag is a block tag. It either requires a <code>mailhost</code>
or a <code>smtphost</code> 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 <code>To</code>, <code>From</code> and <code>Subject</code> headers can be
set with tag arguments.</p><h3> Attributes</h3>
<dl>
<dt> mailhost</dt>
<dd>The name of a Zope MailHost object
to use to send email. You cannot specify both a mailhost and a smtphost.</dd>
<dt> smtphost</dt>
<dd>The name of a SMTP server used to send email. You
cannot specify both a mailhost and a smtphost.</dd>
<dt> port</dt>
<dd>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.</dd>
<dt> mailto</dt>
<dd>The recipient address or a list of recipient addresses
separated by commas. This can also be specified with the <code>To</code> header.</dd>
<dt> mailfrom</dt>
<dd>The sender address. This can also be specified with
the <code>From</code> header.</dd>
<dt> subject</dt>
<dd>The email subject. This can also be specified with the
<code>Subject</code> header.</dd>
</dl>
<h3> Examples</h3>
<p> Sending an email message using a Mail Host:<pre> <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></pre>
</p><h3> See Also</h3>
<p> <a href="http://www.ietf.org/rfc/rfc0821.txt">RFC 821 (SMTP Protocol)</a></p><p> mime tag</p><h2> sqlgroup: Formats complex SQL expressions</h2>
<p> The <code>sqlgroup</code> tag formats complex boolean SQL expressions. You can
use it along with the <code>sqltest</code> tag to build dynamic SQL queries
that tailor themselves to the environment. This tag is used in SQL
Methods.</p><h3> Syntax</h3>
<p> <code>sqlgroup</code> tag syntax:<pre> <dtml-sqlgroup>
[<dtml-or>]
[<dtml-and>]
...
</dtml-sqlgroup></pre>
</p><p> The <code>sqlgroup</code> tag is a block tag. It is divided into blocks with
one or more optional <code>or</code> and <code>and</code> tags. <code>sqlgroup</code> tags can be
nested to produce complex logic.</p><h3> Attributes</h3>
<dl>
<dt> required=boolean</dt>
<dd>Indicates whether the group is required. If it
is not required and contains nothing, it is excluded from the DTML
output.</dd>
<dt> where=boolean</dt>
<dd>If true, includes the string "where". This is
useful for the outermost <code>sqlgroup</code> tag in a SQL <code>select</code> query.</dd>
</dl>
<h3> Examples</h3>
<p> Sample usage:<pre> 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> </pre>
</p><p> If <code>first</code> is <code>Bob</code> and <code>last</code> is <code>Smith, McDonald</code> it renders:<pre> select * from employees
where
(first='Bob'
and
last in ('Smith', 'McDonald')
)</pre>
</p><p> If <code>salary</code> is 50000 and <code>last</code> is <code>Smith</code> it renders:<pre> select * from employees
where
(salary > 50000.0
and
last='Smith'
)</pre>
</p><p> Nested <code>sqlgroup</code> tags:<pre> 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></pre>
</p><p> Given sample arguments, this template renders to SQL like so:<pre> select * form employees
where
(
(
name like 'A*'
and
last like 'Smith'
)
or
salary > 20000.0
)</pre>
</p><h3> See Also</h3>
<p> sqltest tag</p><h2> sqltest: Formats SQL condition tests</h2>
<p> The <code>sqltest</code> tag inserts a condition test into SQL code. It tests a
column against a variable. This tag is used in SQL Methods.</p><h3> Syntax</h3>
<p> <code>sqltest</code> tag syntax:<pre> <dtml-sqltest Variable|expr="VariableExpression"></pre>
</p><p> The <code>sqltest</code> tag is a singleton. It inserts a SQL condition test
statement. It is used to build SQL queries. The <code>sqltest</code> tag
correctly escapes the inserted variable. The named variable or
variable expression is tested against a SQL column using the
specified comparison operation.</p><h3> Attributes</h3>
<dl>
<dt> type=string</dt>
<dd>The type of the variable. Valid types include:
<code>string</code>, <code>int</code>, <code>float</code> and <code>nb</code>. <code>nb</code> means non-blank string,
and should be used instead of <code>string</code> unless you want to test for
blank values. The type attribute is required and is used to
properly escape inserted variable.</dd>
<dt> column=string</dt>
<dd>The name of the SQL column to test against. This
attribute defaults to the variable name.</dd>
<dt> multiple=boolean</dt>
<dd>If true, then the variable may be a sequence
of values to test the column against.</dd>
<dt> optional=boolean</dt>
<dd>If true, then the test is optional and will
not be rendered if the variable is empty or non-existent.</dd>
<dt> op=string</dt>
<dd>The comparison operation. Valid comparisons include: <dl>
<dt> eq</dt>
<dd>equal to</dd>
<dt> gt</dt>
<dd>greater than</dd>
<dt> lt</dt>
<dd>less than</dd>
<dt> ne</dt>
<dd>not equal to</dd>
<dt> ge</dt>
<dd>greater than or equal to</dd>
<dt> le</dt>
<dd>less than or equal to</dd>
</dl>
<p> The comparison defaults to equal to. If the comparison is not
recognized it is used anyway. Thus you can use comparisons such
as <code>like</code>.</p></dd>
</dl>
<h3> Examples</h3>
<p> Basic usage:<pre> select * from employees
where <dtml-sqltest name type="nb"></pre>
</p><p> If the <code>name</code> variable is <code>Bob</code> then this renders:<pre> select * from employees
where name = 'Bob'</pre>
</p><p> Multiple values:<pre> select * from employees
where <dtml-sqltest empid type=int multiple></pre>
</p><p> If the <code>empid</code> variable is <code>(12,14,17)</code> then this renders:<pre> select * from employees
where empid in (12, 14, 17)</pre>
</p><h3> See Also</h3>
<p> sqlgroup tag</p><p> sqlvar tag</p><h2> sqlvar: Inserts SQL variables</h2>
<p> The <code>sqlvar</code> tag safely inserts variables into SQL code. This tag is
used in SQL Methods.</p><h3> Syntax</h3>
<p> <code>sqlvar</code> tag syntax:<pre> <dtml-sqlvar Variable|expr="VariableExpression"></pre>
</p><p> The <code>sqlvar</code> tag is a singleton. Like the <code>var</code> tag, the <code>sqlvar</code>
tag looks up a variable and inserts it. Unlike the var tag, the
formatting options are tailored for SQL code.</p><h3> Attributes</h3>
<dl>
<dt> type=string</dt>
<dd>The type of the variable. Valid types include:
<code>string</code>, <code>int</code>, <code>float</code> and <code>nb</code>. <code>nb</code> means non-blank string and
should be used in place of <code>string</code> unless you want to use blank
strings. The type attribute is required and is used to properly
escape inserted variable.</dd>
<dt> optional=boolean</dt>
<dd>If true and the variable is null or
non-existent, then nothing is inserted.</dd>
</dl>
<h3> Examples</h3>
<p> Basic usage:<pre> select * from employees
where name=<dtml-sqlvar name type="nb"></pre>
</p><p> This SQL quotes the <code>name</code> string variable.</p><h3> See Also</h3>
<p> sqltest tag</p><h2> tree: Inserts a tree widget</h2>
<p> The <code>tree</code> tag displays a dynamic tree widget by querying Zope
objects.</p><h3> Syntax</h3>
<p> <code>tree</code> tag syntax:<pre> <dtml-tree [VariableName|expr="VariableExpression"]>
</dtml-tree></pre>
</p><p> The <code>tree</code> 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 <code>tree</code> block is rendered for each tree node, with the
current node pushed onto the DTML namespace.</p><p> 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.</p><h3> Attributes</h3>
<dl>
<dt> branches=string</dt>
<dd>Finds tree branches by calling the named
method. The default method is <code>tpValues</code> which most Zope objects
support. </dd>
<dt> branches_expr=string</dt>
<dd>Finds tree branches by evaluating the
expression.</dd>
<dt> id=string</dt>
<dd>The name of a method or id to determine tree
state. It defaults to <code>tpId</code> which most Zope objects support. This
attribute is for advanced usage only.</dd>
<dt> url=string</dt>
<dd>The name of a method or attribute to determine tree
item URLs. It defaults to <code>tpURL</code> which most Zope objects
support. This attribute is for advanced usage only.</dd>
<dt> leaves=string</dt>
<dd>The name of a DTML Document or Method used to
render nodes that don't have any children. Note: this document
should begin with <code><dtml-var standard_html_header></code> and end with
<code><dtml-var standard_html_footer></code> in order to ensure proper
display in the tree.</dd>
<dt> header=string</dt>
<dd>The name of a DTML Document or Method displayed
before expanded nodes. If the header is not found, it is skipped.</dd>
<dt> footer=string</dt>
<dd>The name of a DTML Document or Method displayed
after expanded nodes. If the footer is not found, it is skipped.</dd>
<dt> nowrap=boolean</dt>
<dd>If true then rather than wrap, nodes may be
truncated to fit available space.</dd>
<dt> sort=string</dt>
<dd>Sorts the branches by the named attribute.</dd>
<dt> reverse</dt>
<dd>Reverses the order of the branches.</dd>
<dt> assume_children=boolean</dt>
<dd>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.</dd>
<dt> single=boolean</dt>
<dd>Allows only one branch to be expanded at a
time. When you expand a new branch, any other expanded branches
close. </dd>
<dt> skip_unauthorized</dt>
<dd>Skips nodes that the user is unauthorized to
see, rather than raising an error.</dd>
<dt> urlparam=string</dt>
<dd>A query string which is included in the
expanding and contracting widget links. This attribute is for
advanced usage only.</dd>
<dt> prefix=string</dt>
<dd>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 (_).</dd>
</dl>
<h3> Tag Variables</h3>
<dl>
<dt> tree-item-expanded</dt>
<dd>True if the current node is expanded.</dd>
<dt> tree-item-url</dt>
<dd>The URL of the current node.</dd>
<dt> tree-root-url</dt>
<dd>The URL of the root node.</dd>
<dt> tree-level</dt>
<dd>The depth of the current node. Top-level nodes have
a depth of zero.</dd>
<dt> tree-colspan</dt>
<dd>The number of levels deep the tree is being
rendered. This variable along with the <code>tree-level</code> variable can
be used to calculate table rows and colspan settings when
inserting table rows into the tree table.</dd>
<dt> tree-state</dt>
<dd>The tree state expressed as a list of ids and
sub-lists of ids. This variable is for advanced usage only.</dd>
</dl>
<h3> Tag Control Variables</h3>
<p> You can control the tree tag by setting
these variables.<dl>
<dt> expand_all</dt>
<dd>If this variable is true then the entire tree is
expanded. </dd>
<dt> collapse_all</dt>
<dd>If this variable is true then the entire tree is
collapsed.</dd>
</dl>
</p><h3> Examples</h3>
<p> Display a tree rooted in the current object:<pre> <dtml-tree>
<dtml-var title_or_id>
</dtml-tree></pre>
</p><p> Display a tree rooted in another object, using a custom branches
method:<pre> <dtml-tree expr="folder.object" branches="objectValues">
Node id : <dtml-var getId>
</dtml-tree></pre>
</p><h2> try: Handles exceptions</h2>
<p> The <code>try</code> tag allows exception handling in DTML, mirroring the
Python <code>try/except</code> and <code>try/finally</code> constructs.</p><h3> Syntax</h3>
<p> The <code>try</code> tag has two different syntaxes, <code>try/except/else</code> and
<code>try/finally</code>.</p><p> <code>try/except/else</code> Syntax:<pre> <dtml-try>
<dtml-except [ExceptionName] [ExceptionName]...>
...
[<dtml-else>]
</dtml-try></pre>
</p><p> The <code>try</code> tag encloses a block in which exceptions can be caught and
handled. There can be one or more <code>except</code> tags that handles
zero or more exceptions. If an <code>except</code> tag does not specify an
exception, then it handles all exceptions.</p><p> When an exception is raised, control jumps to the first <code>except</code>
tag that handles the exception. If there is no <code>except</code> tag to
handle the exception, then the exception is raised normally.</p><p> If no exception is raised, and there is an <code>else</code> tag, then the
<code>else</code> tag will be executed after the body of the <code>try</code> tag.</p><p> The <code>except</code> and <code>else</code> tags are optional.</p><p> <code>try/finally</code> Syntax:<pre> <dtml-try>
<dtml-finally>
</dtml-try></pre>
</p><p> The <code>finally</code> tag cannot be used in the same <code>try</code> block as the
<code>except</code> and <code>else</code> tags. If there is a <code>finally</code> tag, its block
will be executed whether or not an exception is raised in the
<code>try</code> block.</p><h3> Attributes</h3>
<dl>
<dt> except</dt>
<dd>Zero or more exception names. If no exceptions are
listed then the except tag will handle all exceptions.</dd>
</dl>
<h3> Tag Variables</h3>
<p> Inside the <code>except</code> block these variables
are defined.<dl>
<dt> error_type</dt>
<dd>The exception type.</dd>
<dt> error_value</dt>
<dd>The exception value.</dd>
<dt> error_tb</dt>
<dd>The traceback.</dd>
</dl>
</p><h3> Examples</h3>
<p> Catching a math error:<pre> <dtml-try>
<dtml-var expr="1/0">
<dtml-except ZeroDivisionError>
You tried to divide by zero.
</dtml-try></pre>
</p><p> Returning information about the handled exception:<pre> <dtml-try>
<dtml-call dangerousMethod>
<dtml-except>
An error occurred.
Error type: <dtml-var error_type>
Error value: <dtml-var error_value>
</dtml-try></pre>
</p><p> Using finally to make sure to perform clean up regardless
of whether an error is raised or not:<pre> <dtml-call acquireLock>
<dtml-try>
<dtml-call someMethod>
<dtml-finally>
<dtml-call releaseLock>
</dtml-try></pre>
</p><h3> See Also</h3>
<p> raise tag</p><p> <a href="http://www.python.org/doc/current/tut/node10.html">Python Tutorial: Errors and
Exceptions</a></p><p> <a href="http://www.python.org/doc/current/lib/module-exceptions.html">Python Built-in
Exceptions</a></p><h2> unless: Tests a condition</h2>
<p> The <code>unless</code> tag provides a shortcut for testing negative
conditions. For more complete condition testing use the <code>if</code> tag. </p><h3> Syntax</h3>
<p> <code>unless</code> tag syntax:<pre> <dtml-unless ConditionVariable|expr="ConditionExpression">
</dtml-unless></pre>
</p><p> The <code>unless</code> tag is a block tag. If the condition variable or
expression evaluates to false, then the contained block is
executed. Like the <code>if</code> tag, variables that are not present are
considered false.</p><h3> Examples</h3>
<p> Testing a variable:<pre> <dtml-unless testMode>
<dtml-call dangerousOperation>
</dtml-unless></pre>
</p><p> The block will be executed if <code>testMode</code> does not exist, or exists
but is false.</p><h3> See Also</h3>
<p> if tag</p><h2> var: Inserts a variable</h2>
<p> The <code>var</code> tags allows you insert variables into
DTML output.</p><h3> Syntax</h3>
<p> <code>var</code> tag syntax:<pre> <dtml-var Variable|expr="Expression"></pre>
</p><p> The <code>var</code> tag is a singleton tag. The <code>var</code> 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.</p><p> <code>var</code> tag entity syntax:<pre> &dtml-variableName;</pre>
</p><p> Entity syntax is a short cut which inserts and HTML quotes the
variable. It is useful when inserting variables into HTML
tags.</p><p> <code>var</code> tag entity syntax with attributes:<pre> &dtml.attribute1[.attribute2]...-variableName;</pre>
</p><p> 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, <code>&dtml.-variableName;</code>.</p><h3> Attributes</h3>
<dl>
<dt> html_quote</dt>
<dd>Convert characters that have special meaning in
HTML to HTML character entities.</dd>
<dt> missing=string</dt>
<dd>Specify a default value in case Zope cannot find
the variable.</dd>
<dt> fmt=string</dt>
<dd>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 <a href="http://www.python.org/doc/current/lib/typesseq-strings.html">Python Library
Reference</a>
If the format string is not a built-in format, then it is assumed
to be a method of the object, and it called.<dl>
<dt> whole-dollars</dt>
<dd>Formats the variable as dollars.</dd>
<dt> dollars-and-cents</dt>
<dd>Formats the variable as dollars and cents.</dd>
<dt> collection-length</dt>
<dd>The length of the variable, assuming it is
a sequence.</dd>
<dt> structured-text</dt>
<dd>Formats the variable as Structured Text. For
more information on Structured Text see <a href="http://www.zope.org/Members/millejoh/structuredText">Structured Text
How-To</a> on
the Zope.org web site.</dd>
</dl>
</dd>
<dt> null=string</dt>
<dd>A default value to use if the variable is None.</dd>
<dt> lower</dt>
<dd>Converts upper-case letters to lower case. </dd>
<dt> upper</dt>
<dd>Converts lower-case letters to upper case. </dd>
<dt> capitalize</dt>
<dd>Capitalizes the first character of the inserted
word. </dd>
<dt> spacify</dt>
<dd>Changes underscores in the inserted value to spaces.</dd>
<dt> thousands_commas</dt>
<dd>Inserts commas every three
digits to the left of a decimal point in values containing
numbers for example <code>12000</code> becomes <code>12,000</code>.</dd>
<dt> url</dt>
<dd>Inserts the URL of the object, by calling its
<code>absolute_url</code> method.</dd>
<dt> url_quote</dt>
<dd>Converts characters that have special meaning in
URLs to HTML character entities.</dd>
<dt> url_quote_plus</dt>
<dd>URL quotes character, like <code>url_quote</code> but also
converts spaces to plus signs.</dd>
<dt> sql_quote</dt>
<dd>Converts single quotes to pairs of single
quotes. This is needed to safely include values in SQL strings.</dd>
<dt> newline_to_br</dt>
<dd>Convert newlines (including carriage returns) to
HTML break tags.</dd>
<dt> size=arg</dt>
<dd>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).</dd>
<dt> etc=arg</dt>
<dd>Specifies a string to add to the end of a string
which has been truncated (by setting the <code>size</code> attribute listed
above). By default, this is <code>...</code></dd>
</dl>
<h3> Examples</h3>
<p> Inserting a simple variable into a document:<pre> <dtml-var standard_html_header></pre>
</p><p> Truncation:<pre> <dtml-var colors size=10 etc=", etc."></pre>
</p><p> will produce the following output if <em>colors</em> is the string 'red
yellow green':<pre> red yellow, etc.</pre>
</p><p> C-style string formatting:<pre> <dtml-var expr="23432.2323" fmt="%.2f"></pre>
</p><p> renders to:<pre> 23432.23</pre>
</p><p> Inserting a variable, <em>link</em>, inside an HTML <code>A</code> tag with the entity
syntax:<pre> <a href="&dtml-link;">Link</a></pre>
</p><p> Inserting a link to a document <code>doc</code>, using entity syntax with
attributes:<pre> <a href="&dtml.url-doc;"><dtml-var doc fmt="title_or_id"></a></pre>
</p><p> This creates an HTML link to an object using its URL and
title. This example calls the object's <code>absolute_url</code> method for
the URL (using the <code>url</code> attribute) and its <code>title_or_id</code> method
for the title.</p><h2> with: Controls DTML variable look up</h2>
<p> The <code>with</code> tag pushes an object onto the DTML namespace. Variables
will be looked up in the pushed object first.</p><h3> Syntax</h3>
<p> <code>with</code> tag syntax:<pre> <dtml-with Variable|expr="Expression">
</dtml-with></pre>
</p><p> The <code>with</code> tag is a block tag. It pushes the named variable or
variable expression onto the DTML namespace for the duration of
the <code>with</code> block. Thus names are looked up in the pushed object
first. </p><h3> Attributes</h3>
<dl>
<dt> only</dt>
<dd>Limits the DTML namespace to only include the one defined
in the <code>with</code> tag.</dd>
<dt> mapping</dt>
<dd>Indicates that the variable or expression is a mapping
object. This ensures that variables are looked up correctly in the
mapping object.</dd>
</dl>
<h3> Examples</h3>
<p> Looking up a variable in the REQUEST:<pre> <dtml-with REQUEST only>
<dtml-if id>
<dtml-var id>
<dtml-else>
'id' was not in the request.
</dtml-if>
</dtml-with></pre>
</p><p> Pushing the first child on the DTML namespace:<pre> <dtml-with expr="objectValues()[0]">
First child's id: <dtml-var id>
</dtml-with></pre>
</p><h3> See Also</h3>
<p> let tag</p></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
8b32d38f0094104a5fd847636983daa8
>
files
>
31
