Skip to content.

plope

Personal tools
You are here: Home » Books » 2_7Edition » Appendix A: DTML Reference
 
 
Views
  • State: visible
Previous Page Up one Level Next Page Appendix A: DTML Reference Comments On/Off Table of Contents Sections Index

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

random module

Documentation

math module

Documentation

sequence module

Built-in Python Functions

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

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

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

Python Built-in Exceptions

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)

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

Python Built-in Exceptions

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 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 on the Zope.org web site.
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

Previous Page Up one Level Next Page Appendix A: DTML Reference Comments On/Off Table of Contents