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 - Apr. 16, 2002 4:24 pm: A TOC would be welcome here, so we could jump to a particuliar section instead of the reference of scrolling the whole doc.
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.
Anonymous User - Mar. 3, 2004 1:23 pm: Hi..it would be really great if there is a tutorial guiding users to create an application with these tags..I dont see zopezoo to be much of a help!!
inflatables - Oct. 14, 2005 11:35 pm: <dtml-call Variable|expr="Expression"> ------------------------------------- http://www.inflatables-china.net
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
<dtml-call UpdateInfo>
Anonymous User - June 10, 2004 11:59 am: How can I use the return value of the function I called?
This calls the UpdateInfo
object automatically passing arguments.
<dtml-call expr="RESPONSE.setHeader('content-type', 'text/plain')">
srinichandra - Mar. 3, 2004 1:25 pm: Hi..I am a fresh user of Zope..is there a place where I can see the application of these tags??
Anonymous User - July 29, 2005 3:02 pm: This is a good one.
See Also
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.
Anonymous User - June 6, 2005 7:08 am: sdfsdfdsf
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
<dtml-comment> This content is not executed and does not appear in the output. </dtml-comment>
<dtml-comment> This DTML is disabled and will not be executed. <dtml-call someMethod> </dtml-comment>
Anonymous User - Apr. 29, 2002 2:00 pm: This explanation is misleading and partially incorrect. Zope will not save any comments that are not valid DTML. So you cannot not comment: using <dtml-in myExample> to loop ... This produces a Zope error. This is counter-intuitive and cripples good documentation practices. Zope collector Issue 370 http://collector.zope.org/Zope/370
Anonymous User - May 16, 2002 5:53 pm: Also, it appears (at least in Zope 2.32-ish) that DTML commands inside comments ARE parsed, since errors in syntax or references to objects, methods, etc. that are invalid will cause Zope to complain about the file. Normal programming language syntax would dictate that NOTHING after a start-comment token should be parsed until an end-comment token is encountered.
Anonymous User - July 26, 2002 3:31 pm: Agreed with the normal prg lang syntax...
Anonymous User - Dec. 31, 2003 10:55 am: Perhaps: <dtml-comment parser=off> ... stuff ... </dtml-comment>
functions: DTML Functions
DTML utility functions provide some Python built-in functions and some DTML-specific functions.
Anonymous User - Apr. 17, 2002 11:18 am: A short example of function usage would really help beginner .
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 stringa
. 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 usuallymath.floor(a / b)
but may be 1 less than that. In any caseq * b + a % b
is very close to a, ifa % b
is non-zero it has the same sign as b, and0 <= 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 tox.foobar
. If the named attribute does not exist, default is returned if provided, otherwiseAttributeError
is raised. - getitem(variable, render=0)
- Returns the value of a DTML variable.
If
render
is true, the variable is rendered. See therender
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)
yields0xffffffff
. 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 anOverflowError
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]
). Theradix
parameter gives the base for the conversion and may be any integer in the range 2 to 36. Ifradix
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)
yields037777777777
. 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 ofchr()
. - 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)
orpow(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 largeststart + i * step
less than stop; if step is negative, the last element is the largeststart + i * step
greater than stop. step must not be zero (or elseValueError
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 tostr(object)
. - reorder(s [,with] [,without])
- Reorder the items in s according
to the order given in
with
and without the items mentioned inwithout
. 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, theAUTHENTICATED_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, andname
is the named used to access the value (for example, if it was obtained viagetattr
). 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 objectNone
. This is usually used to represent a Null or false value.
See Also
string
module
See the Python string module documentation.
random
module
See the Python random module documentation.
math
module
See the Python math module documentation.
sequence
module
Anonymous User - Aug. 8, 2002 11:06 pm: So- am I to understand that DTML/Python can do all these, yet it cannot add/subtract/divide/multiply? My faith in open-source grows weaker every day.
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
<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
<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
<dtml-in SequenceVariable|expr="SequenceExpression"> [<dtml-else>] </dtml-in>
Anonymous User - May 8, 2002 7:56 am: a commenting identifier at the end tag is allowed and will be ignored like </dtml-in my_short_sequ_name> same for if / let (dunno abt other tags)
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
- 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)
, thein
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 thetitle
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>
Anonymous User - May 30, 2004 9:49 pm: What in the heck does "The index of a variable of the current item" actually mean? Is it just me, or is the explanation for sequence-index-variable weak?
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 - 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
, andbatch-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
, andbatch-size
.
Examples
<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>
<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
<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.
Anonymous User - Aug. 17, 2004 12:40 pm: This is so frustrating. It is too difficult to do something simple like a dtml-in call to a method that can accept values. My syntactical brain wants to do this: <dtml-in mySqlMethod(intValue)> or at least this: <dtml-in expr="mySqlMethod(intValue)"> but that won't work, so I'm stuck trying things like this: <dtml-let intValue=myValue> <dtml-in mySqlMethod> The problem is that I can't find a way to set that intValue to an integer! I've tried all combinations of the following: <dtml-let intValue=253> <!-- bad! --> <dtml-let intValue="253"> <!-- but not an int! --> <dtml-let intValue="int(253)"> <!-- int()'s not valid?!? --> The frustration comes not so much from my annoyance with syntax, but from a total lack of documentation over what I can only believe is a very common case. And, while I'm at it, the Add Comment page claims there is a Preview Comment button, while there is no such thing.
Anonymous User - Nov. 16, 2004 11:00 am: I'm only a beginner, but I'd try the following: <dtml-in "mySqlMethod(some_column='intValue')"> GaryH
Examples
<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>
1 * 0 = 0 2 * 1 = 2 3 * 2 = 6 4 * 3 = 12
See Also
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
<dtml-mime> [<dtml-boundry>] ... </dtml-mime>
Anonymous User - Apr. 6, 2002 8:09 pm: /boundry/boundary
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.
Anonymous User - Apr. 6, 2002 8:11 pm: dtml-boundary should also be a block tag. It's current form does not allow looping because there is no close tag </dtml-boundary>
Attributes
mime
and
boundry
tags
have the same attributes.
- encode=string
- MIME Content-Transfer-Encoding header, defaults
to
base64
. Valid encoding options includebase64
,quoted-printable
,uuencode
,x-uuencode
,uue
,x-uue
, and7bit
. If theencode
attribute is set to7bit
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
andtype_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
andname_expr
. - disposition=string
- MIME Content-Disposition header.
- disposition_expr=string
- MIME Content-Disposition header as a
variable expression. You cannot use both
disposition
anddisposition_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
andfilename_expr
. - skip_expr=string
- A variable expression that if true, skips the block. You can use this attribute to selectively include MIME blocks.
Examples
<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>
Anonymous User - June 10, 2002 5:47 am: There's a <dtml-recipient> tag?!?! I think line 2 of the code is supposed to read: To: &dtml-recipient;
Anonymous User - Aug. 19, 2004 10:18 am: It is not a tag. It is simply a different method of printing a variable in DTML.
See Also
Python mimetools module documentation.
raise: Raises an exception
The raise
tag raises an exception, mirroring the Python raise
statement.
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
<dtml-raise KeyError></dtml-raise>
<dtml-raise NotFound>Web Page Not Found</dtml-raise>
See Also
Python Tutorial: Errors and Exceptions
return: Returns data
The return
tag stops executing DTML and returns data. It mirrors
the Python return
statement.
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
<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
<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
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
<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 SQLselect
query.
Examples
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' )
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: 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
<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
andnb
.nb
means non-blank string, and should be used instead ofstring
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
select * from employees where <dtml-sqltest name type="nb">
If the name
variable is Bob
then this renders:
select * from employees where name = 'Bob'
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
sqlvar: Inserts SQL variables
The sqlvar
tag safely inserts variables into SQL code. This tag is
used in SQL Methods.
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
andnb
.nb
means non-blank string and should be used in place ofstring
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
select * from employees where name=<dtml-sqlvar name type="nb">
This SQL quotes the name
string variable.
See Also
tree: Inserts a tree widget
The tree
tag displays a dynamic tree widget by querying Zope
objects.
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
.
<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.
<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
except
block these variables
are defined.
- error_type
- The exception type.
- error_value
- The exception value.
- error_tb
- The traceback.
Examples
<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
Python Tutorial: Errors and 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
<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
<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
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
<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.
&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
becomes12,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)
<dtml-var colors size=10 etc=", etc.">
will produce the following output if colors is the string 'red yellow green':
red yellow, etc.
<dtml-var expr="23432.2323" fmt="%.2f">
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
<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>