General Information

DTML Tag Syntax

Two syntaxes are currently supported 1 by document templates. This section describes a syntax that is based on HTML server-side includes. The next section describes a syntax that is based on standard Python string formats. The syntax used depends on the document template class used (or subclassed). The server-side-include syntax described here is used by the classes DocumentTemplate.HTML and DocumentTemplate.HTMLFile.

The syntax used by DTML to indicate text substitution is based on the use of DTML tags. A DTML tag is of the form:

The tag name controls the tag type. The tag typically has one or more attributes that indicate where the tag gets it's data and other information that controls how data are inserted. Sometimes attribute values can be omitted and quotes around attribute values can be omitted if the values don't contain spaces, tabs, new-line characters, equal signs or double quotes.

The most common tag is the var tag. The var tag is used to substitute variable data into text. Suppose we wanted to create a greeting with a variable input_name . We might use a document template like the following:

Hello !

This example uses two attributes, name and capitalize . The name attribute is used to specify a variable name. Typically, variable names refer to data in World-Wide-Web (Web) requests, or properties of objects. Because the name attribute is so commonly used, a short-hand version of the name attribute is allowed in which the attribute name is omitted, as in:

Hello !

When using the short-hand form of the name attribute, the value must be unquoted and the attribute must be the first attribute in the tag.

A similar short-hand notation is used for the expr attribute. The expr attribute is used to provide computational expressions as in:

This may be shortened by eliminating the attribute name, as in:

When using the short-hand form of the expr attribute, the value must be quoted and the attribute must be the first attribute in the tag.

The capitalize attribute illustrates the use of attributes that need not have values 2 . The capitalize attribute indicates that the inserted text should be capitalized. For example, suppose the document template source above was evaluated with an input name of " world ", then the text output would be:

Hello World!

The var tag is said to be an empty tag , because it doesn't contain any other tags. Some tags are said to be non-empty because they bracket text that may contain other DTML tags. Non-empty tags have matching end tags . The name of the end tag is the name of the start tag except that it has a " / " or an " end " prefix. A commonly used non-empty tag is the if tag. An example of an if tag is:

Hello .

In this example, if the variable, input_name , has not been provided, or is an empty string, then the greeting is omitted. End tags do not have attributes.

A non-empty tag may also have intermediate tags. These intermediate tags serve to break the non-empty tag into two or more sections. For example the if tag can use an intermediate else tag, as in:

Hello .

Have we been introduced?

Note that in this case, the alternate form of the end tag is used.

Sometimes, intermediate tags may have attributes, as in:

Hello .

Hi .

Have we been introduced?

In the example above, there is one non-empty tag, if , that uses two intermediate tags, elif and else , and an end tag, /if .

Any number of line endings, tabs, and spaces may be used between the pound character (#), the tag name, attributes, and the end of a tag. For example, the following are all valid tags:

Alternate Python String Format Syntax

This section describes the extended Python string format syntax. The extended Python string format syntax is used by the classes DocumentTemplate.String and DocumentTemplate.File. This format is based on the insertion-by-name format strings of python with additional format characters, '[' and ']' to indicate block boundaries. In addition, attributes may be used within formats to control how insertion is done. For example:

%(date fmt=DayOfWeek upper)s

causes the contents of variable 'date' to be inserted using custom format 'DayOfWeek' and with all lower case letters converted to upper case.

Document template strings use an extended form of python string formatting. To insert a named value, simply include text of the form:

%(name)x',

where 'name' is the name of the value and 'x' is a format specification, such as '12.2d'. To introduce a block such as an 'if' or an 'in' or a block continuation, such as an 'else', use '[' as the format specification. To terminate a block, use ']' as the format specification, as in:

%(if input_name)[
Hello %(var input_name size=16 etc="...")s.
%(elif nick_name)[
Hi %(var nick_name capitalize)s.
%(else)[
Have we been introduced?
%(/if)]

Common tag attributes

This section described two attributes that are used by most DTML tags. Both of these attributes are used to identify or compute data to be used by the tag.

The name attribute

The name attribute is used to obtain data by name. The data is looked up using the rules described in the section See Name lookup below. The name attribute is special because the attribute name may be omitted, as described in the section See DTML Tag Syntax above.

When a value is looked up with the name attribute, it is also called, if possible. If the value is a document template, it is rendered before being given to the tag that uses the name attribute.

If the value is a function 3 that can be called with no arguments, then the result of calling the function will be given to the tag using the name attribute.

When the name attribute is used in an if , elif , unless , in or with tag, the value associated with the name is cached so that references to the name in enclosed text are faster than the initial reference. This is especially important when the name refers to a function that is computationally expensive. For example, in:

The var tag uses the cached value for reallyExpensiveFunction . Note that tags like the in and with tag that introduce new variables may introduce a new value for the given name that override the cached value.

The expr attribute

The expr attribute allows more or less arbitrarily complex expressions to be evaluated.

Expression Syntax

The expression syntax is that of Python. Table See Expression examples provides some simple expression examples that illustrate the expression syntax and capabilities.

Expression examples
Expression	Explanation
x2+3*	Numeric expressions
func(a,b)	Function call
obj.title	Get attribute title from obj
obj.meth(a,b)	Invoke method 4 meth of obj with arguments a and b
(age < 12 or age > 65) and status == 'student'	A boolean (true/false) test.
REQUEST['HTTP_REFERER']	Lookup a value from REQUEST using a key ' HTTP_REFERER '

The expression used in an expr attribute is enclosed in double quotes and double quotes are not allowed in the expression.

Variable Lookup

The variable names used in an expr expression are looked up according to the rules described in See Name lookup below. Looked up values are not "called" as they are when the name attribute is used. In the sample expressions in table See Expression examples , the names x , func , a , b , obj , age , and status are variable names, while the names meth and title are object attribute names.

Variable names must begin with a letter and contain only letters, digits, and underscore characters. To access a variable with a name that doesn't follow these rules, it is necessary to use the special variable, _, described in See The special name-space variable, _ , below.

The special name-space variable, _

A special variables, _ , is defined for use in expr expressions. The _ variable provides access to the DTML "name space", which is an object used to lookup variables when rendering DTML. The _ variable can be used to lookup names directly:

The _ variable is especially useful for accessing variables with names that contain special characters, like dashes, as in the case above.

The _ variable has a method, has_key that can be used to check whether a variable can be looked up:

Note that when a value is looked up with the _ variable, and the value is callable, then it is called automatically, as is done with the name attribute. Sometimes, you don't want to have the value called automatically. To avoid calling the value, look it up with the getitem method of the _ variable. The getitem method accepts two arguments, the name to be looked up and a flag indicating whether the value is to be called:

The variable _ provides access to a number of useful general purpose objects and functions as attributes. The available attributes are shown in table See Available attributes in the special variable, _ .

Available attributes in the special variable, _
Name	Description
abs(X)	Return the absolute value of a number.
chr(I)	Return a string of one character whose ASCII code is the integer I , e.g., chr(97) returns the string 'a' . This is the inverse of ord() . The argument must be in the range 0-255, inclusive.
divmod(A,B)	Take two numbers as arguments and return a pair of integers consisting of their integer quotient and remainder. With mixed operand types, the rules for binary arithmetic operators apply. For integers, the result is the same as (A/B,A%B) . For floating point numbers the result is the same as (math.floor(A/B),A%B) .
float(X)	Convert a number to floating point. The argument may be a plain or long integer or a floating point number.
getattr(O,name)	Get a named attribute from an object.
getitem(name,flag)	Lookup a name in the namespace. If the value is callable and the flag is true, then the result of calling the value is returned, otherwise the value is returned.
hash(O)	Return the 32-bit integer hash value of the object.
hex(X)	Convert an integer to a hexadecimal string.
int(X)	Convert a number to an integer.
len(S)	Return the length (the number of items) of a collection of objects.
math	The math module (table See Attributes defined by the math module. ), which defines mathematical functions.
max(S)	Return the largest item of a non-empty sequence.
min(S)	Return the smallest item of a non-empty sequence.
namespace( name1=value1, name2=value2, ...)	The namespace function can be used with the in tag to assign variables for use within a section of DTML. The function accepts any number of "keyword" arguments, which are given as name=value pairs.
None	A special value that means "nothing".
oct(X)	Convert an integer.
ord(C)	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)	Return X to the power Y . 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.
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 ).
str(O)	Return a string containing a representation of an object.
string	The string module (table See Attributes defined by the string module ), which defines string functions.
whrandom	The whrandom module (table See Attributes defined by the whrandom module ), which defines random-number generating functions using the Wichmann-Hill pseudo-random number generator.

Attributes defined by the math module.
Name	Description
acos(X)	Compute the inverse cosine, in radians, of X.
asin(X)	Compute the inverse sine, in radians, of X.
atan(X)	Compute the inverse tangent, in radians, of X.
atan2(X,Y)	Computes the inverse tangent, in radians, of the quotient of X and Y.
ceil(X)	Returns the smallest integer that is greater than X.
cos(X)	Compute the cosine of X, which is in radians.
cosh(X)	Compute the hyperbolic cosine of X.
e	The base of the natural logarithms.
exp(X)	Compute the exponential function of X, or e to the power X, where e is the base of the natural logarithms.
fabs(X)	Compute a floating-point absolute value of the number, X.
floor(X)	Returns the largest integer that is less than X.
fmod(X,Y)	Return the remainder of the division of X by Y.
frexp(X)	Return the mantissa and exponent in base 2 of the floating-point value of X, such that absolute value mantissa is between 0.5 and 1.0 or is 0.
hypot(X,Y)	Compute the hypotenuse of a right triangle with sides X and Y.
ldexp(X,Y)	Returns X times two to the power of Y.
log(X)	Compute the natural (base e) logarithm of X.
log10(X)	Compute the common (base 10) logarithm of X.
modf(X)	Break a number into its whole and fractional parts.
pi	The mathematical constant, pi
pow(X,Y)	Raise X to the power Y.
sin(X)	Compute the sine of X.
sinh(X)	Compute the hyperbolic sine of X.
sqrt(X)	Compute the square-root of X.
tan(X)	Compute the tangent of X.
tanh(X)	Compute the hyperbolic tangent of X.

Attributes defined by the string module
Name	Description
digits	The string '0123456789'.
hexdigits	The string `0123456789abcdefABCDEF'.
letters	The concatenation of the strings lowercase' and uppercase' described below.
lowercase	A string containing all the characters that are considered lowercase letters. On most systems this is the string `abcdefghijklmnopqrstuvwxyz'.
octdigits	The string `01234567'.
uppercase	A string containing all the characters that are considered uppercase letters. On most systems this is the string `ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
whitespace	A string containing all characters that are considered "white space". On most systems this includes the characters space, tab, line feed, return, form feed, and vertical tab.
atof(S)	Convert a string to a floating point number.
atoi(S[, BASE])	Convert string S to an integer in the given BASE. The string must consist of one or more digits, optionally preceded by a sign (+' or -'). The BASE defaults to 10. If it is 0, a default base is chosen depending on the leading characters of the string (after stripping the sign): '0x' or '0X' means 16, '0' means 8, anything else means 10. If BASE is 16, a leading '0x' or '0X' is always accepted.
capitalize(W)	Capitalize the first character of the argument.
capwords(S)	Convert sequences of spaces, tabs, new-line characters, and returns to single spaces and convert every lower-case letter at the beginning of the string or that follows space to an uppercase letter.
find(S, SUB[, START])	Return the lowest index in S not smaller than START where the sub-string SUB is found. Return -1 when SUB does not occur as a sub-string of S with index at least START. If START is omitted, it defaults to 0. If START is negative, then it is added to the length of the string.
rfind(S, SUB[, START])	Like find but find the highest index.
index(S, SUB[, START])	Like find but raise a ValueError exception when the substring is not found.
rindex(S, SUB[, START])	Like rfind but raise ValueError exception when the substring is not found.
count(S, SUB[, START])	Return the number of (non-overlapping) occurrences of substring SUB in string S with index at least START. If START is omitted, it defaults to 0'. If START is negative, then it is added to the length of the string..
lower(S)	Convert letters to lower case.
maketrans(FROM, TO)	Return a translation table suitable for passing to string.translate, that will map each character in FROM into the character at the same position in TO; FROM and TO must have the same length.
split(S[, SEP[, MAX]])	Return a list of the words of the string S. If the optional second argument SEP is absent or None, the words are separated by arbitrary strings of white-space characters (space, tab, new line, return, form feed). If the second argument SEP is present and not None, it specifies a string to be used as the word separator. The returned list will then have one more items than the number of non-overlapping occurrences of the separator in the string. The optional third argument MAX defaults to 0. If it is nonzero, at most MAX number of splits occur, and the remainder of the string is returned as the final element of the list (thus, the list will have at most MAX+1 elements).
join(WORDS[, SEP])	Concatenate a list or tuple of words with intervening occurrences of SEP. The default value for SEP is a single space character. It is always true that string.join(string.split(S, SEP), SEP) equals S.
lstrip(S)	Remove leading white space from the string S.
rstrip(S)	Remove trailing white space from the string S.
strip(S)	Remove leading and trailing white space from the string S.
swapcase(S)	Convert lower case letters to upper case and vice versa.
translate(S, TABLE[, DELS])	Delete all characters from S that are in DELS (if present), and then translate the characters using TABLE, which must be a 256-character string giving the translation for each character value, indexed by its ordinal.
upper(S)	Convert letters to upper case.
ljust(S, WIDTH) rjust(S, WIDTH) center(S, WIDTH)	These functions respectively left-justify, right-justify and center a string in a field of given width. They return a string that is at least WIDTH characters wide, created by padding the string S with spaces until the given width on the right, left or both sides. The string is never truncated.
zfill(S, WIDTH)	Pad a numeric string on the left with zero digits until the given width is reached. Strings starting with a sign are handled correctly.

Attributes defined by the whrandom module
Name	Description
choice (seq)	Chooses a random element from the non-empty sequence seq and returns it.
randint (a, b)	Returns a random integer N such that a<=N<=b
random()	Returns a random real number N such that 0<=N<1.
seed(X, Y, Z)	Initializes the random number generator from the integers X, Y and Z.
uniform (a, b)	Returns a random real number N such that a<=N<b.

For example, to get an attribute for a given name, use:

Access Control

Document templates provide a basic level of access control by preventing access to names beginning with an underscore 5 . Additional control may be provided by providing document templates with a 'validate' method. This would typically be done by subclassing one or more of the DocumentTemplate classes.

If provided, the 'validate' method will be called when objects are accessed as instance attributes or when they are accessed through keyed access in an expression. The 'validate' method will be called with five arguments:

The containing object that the object was accessed from,

The actual containing object that the object was found in, which may be different from the containing object the object was accessed from, if the containing object supports acquisition,
The name used to access the object,
The object, and
The name-space object used to render the document template.

If a document template was called from Bobo, then the name-space object will have an attribute, AUTHENTICATED_USER that is the user object that was found if and when Bobo authenticated a user.

Name lookup

When a variable name is used in a DTML tag, such as a var tag, or in an expr attribute expression, data matching the name must be looked up. Table See Simplest-case steps for looking up names shows the steps taken to look up data in the simplest case.

Simplest-case steps for looking up names
Step	Rule
1	The mapping object and keyword arguments supplied when calling the document template are searched, with keyword arguments taking precedence over the mapping object.
2	Attributes, including inherited and acquired attributes, of the client passed in the call to the document template are searched.
3	Search Bobo-defined Web-request data (table See Bobo-defined Web-request variables, ).
4	Search variables defined in Web-request form data.
5	Search variables defined in Web-request cookies.
6	Search variables named URLn , where n is a digit. URL0 is the Request URL without a query string. URL1 is the same as URL0 except that the last name in the URL is removed. URL2 is the same as URL0 except that the last two names are removed, and so on. For example, If the request URL is http://digicool.com/A/B , then URL0 , URL1 , and URL2 are http://digicool.com/A/B , http://digicool.com/A , and http://digicool.com . URL3 is undefined.
7	Search CGI-defined Web-request variables. See table See CGI-defined Web-request variables for a description of CGI-defined variables.
8	Search HTTP Headers. The variable names associated with HTTP headers consists of the HTTP header name, converted to upper case, with the Prefix, HTTP_ . For example, an HTTP Referer header, if present, can be accessed using the variable name HTTP_REFERER .
9	Search variables named BASEn , where n is a digit. BASE0 is the prefix of the request URL up to but not including the name of the module published by Bobo. BASE1 is the request URL up to and including the name of the module published by Bobo. BASE2 is the request URL up to the name following the name of the module published by Bobo, and so on. For example, assume that a module published by Bobo has the URL: http://digicool.com/Demos/Plutonia , and that a request URL is http://digicool.com/Demos/Plutonia/Marketing Then BASE0 is http://digicool.com/Demos, BASE1 is http://digicool.com/Demos/Plutonia, and BASE2 is http://digicool.com/Demos/Plutonia/Marketing . BASE3 is undefined.

There are two situations that modify the search rules for the simplest case. If a document template is called in a DTML expr attribute expression, then additional variables may be passed in. Variables passed in take precedence over all variables described in table See Simplest-case steps for looking up names . .

Bobo-defined Web-request variables,
Name	Description
AUTHENTICATED_USER	An object that represents an authenticated user. When inserted into a DTML document, the value is the user name. This object currently provides no public attributes. Note that this variable may not be defined in Documents that are not protected by security information.
AUTHENTICATION_PATH	This is the path to the object containing the user database that contained the definition for the authenticated user.
PARENTS	A sequence of ancestors of the object that was accessed in the current request.
REQUEST	An object that represents the current request. This object may be used in an expr expression to lookup request data, including variables described in this table, CGI-defined variables (table See CGI-defined Web-request variables ), form variables, cookies, and HTTP headers. In addition, expr expressions may use request attributes defined in table See Attributes of the REQUEST variable .
RESPONSE	An object that represents the response to the current request. This object is primarily useful in expr expressions using attributes defined in table See Attributes of the RESPONSE variable. .
URL	The URL used to invoke the request without the query string, if any.

Attributes of the REQUEST variable
Name	Description
cookies	If an HTTP Cookie was included in the request, then this attribute is a dictionary containing the cookie data. This allows cookie data to be looked up, even if a cookie name is the same as a form variable or an object attribute name.
form	If a request was initiated by submitting a form, then the form attribute is a dictionary containing the form data. This allows form data to be looked up, even if a form name is the same as an object attribute name.
has_key(name)	Determine whether the REQUEST defines a given name.
set(name, value)	Set a variable in the request.

Attributes of the RESPONSE variable.
Name	Description
setStatus(status)	Sets the HTTP status code of the response; the argument may either be an integer or a string from { OK, Created, Accepted, NoContent, MovedPermanently, MovedTemporarily, NotModified, BadRequest, Unauthorized, Forbidden, NotFound, InternalError, NotImplemented, BadGateway, ServiceUnavailable } that will be converted to the correct integer value.
setHeader(name, value)	Sets an HTTP return header name with value value , clearing the previous value set for the header, if one exists.
getStatus()	Returns the current HTTP status code as an integer.
setBase(base)	Set the base URL for the returned document.
expireCookie(name)	Cause an HTTP cookie to be removed from the browser The response will include an HTTP header that will remove the cookie corresponding to "name" on the client, if one exists. This is accomplished by sending a new cookie with an expiration date that has already passed.
setCookie(name,value,...)	Causes the response to include an HTTP header that sets a cookie on cookie-enabled browsers with a key name and value value . This overwrites any previously set value for the cookie in the Response object. Additional cookie parameters can be included by supplying keyword arguments. The valid cookie parameters are expires , domain , path , max_age , comment , and secure .
getHeader(name)	Returns the value associated with a HTTP return header, or None if no such header has been set in the response yet.
appendHeader(name, value)	Sets an HTTP return header "name" with value "value", appending it following a comma if there was a previous value set for the header.
redirect(location)	Cause a redirection without raising an error.

CGI-defined Web-request variables
Name	Description
SERVER_SOFTWARE	The name and version of the information server software answering the request. Format: name/version
SERVER_NAME	The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.
GATEWAY_INTERFACE	The revision of the CGI specification to which this server complies. Format: CGI/revision.
SERVER_PROTOCOL	The name and revision of the information protcol this request came in with. Format: protocol/revision
SERVER_PORT	The port number to which the request was sent.
REQUEST_METHOD	The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", etc.
PATH_INFO	The part of the request URL, not counting the query string, following the name of the module published by Bobo.
PATH_TRANSLATED	The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it.
SCRIPT_NAME	A virtual path to the script being executed, used for self-referencing URLs.
QUERY_STRING	The information which follows the ? in the URL which referenced this script. This is the query information.
REMOTE_HOST	The hostname making the request. If the server does not have this information, it should set REMOTE_ADDR and leave this unset.
REMOTE_ADDR	The IP address of the remote host making the request.
AUTH_TYPE	If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user.
REMOTE_USER	If the server supports user authentication, and the script is protected, this is the username they have authenticated as.
REMOTE_IDENT	If the HTTP server supports RFC 931 identification, then this variable will be set to the remote user name retrieved from the server. Usage of this variable should be limited to logging only.
CONTENT_TYPE	For queries which have attached information, such as HTTP POST and PUT, this is the content type of the data.
CONTENT_LENGTH	The length of the said content as given by the client.

Some DTML tags define additional variables. Variables defined by DTML tags take precedence over variables described in table See Simplest-case steps for looking up names . If tags are nested, variables defined in nested tags take precedence over variables defined in tags that are nested in.

Names may not begin with an underscore, except in the special case of the _ variable used in an expr attribute expression.

Using Document Templates from Python

Document templates are made available using the DocumentTemplate package 6 . The DocumentTemplate package defines four classes to be used depending on whether source is stored in Python strings or in external files and on whether the HTML server-side include syntax or the extended Python string format syntax is used. The four document template classes are shown in table See Document template classes .

Document template classes
Class name	Description
DocumentTemplate.HTML	Source is provided as a Python string in HTML server-side-include syntax.
DocumentTemplate.HTMLFile	Source is provided as an external file in HTML server-side-include syntax.
DocumentTemplate.String	Source is provided as a Python string in extended Python string format syntax.
DocumentTemplate.File	Source is provided as an external file in extended Python string format syntax.

Creating document templates

Document templates are created by calling one of the classes listed in table See Document template classes . The source is passed as the first argument. An optional mapping argument may be provided that contains names to be added to the document template name-space when called and default values. An optional third argument may be provided to specify a __name__ attribute for the document template. The standard document template creation arguments are listed in table See Standard document template creation arguments. .

Standard document template creation arguments.
Argument number	Argument name	Description
1	source_string or file_name	The document template source. For classes String and HTML, this must be a string. For classes File and HTMLFile, this is the name of an external file.
2	mapping	A mapping object containing initial names and default values for the document template name-space.
3	__name__	A value to use for the __name__ attribute of the document template object. This value can be used by programming tools to identify the object. For example, Bobo tracebacks include __name__ values for instances of methods listed in tracebacks. For classes String and HTML, the default __name__ value is '<string>' and for File and HTMLFile classes, the default value is the file name.

In addition to the standard creation arguments, additional keyword arguments may be provided to provide additional names and default values for the document template name-space. For example, in:

results=DocumentTemplate.HTMLFile('results.dtml',
{'table_name': 'search results', 'database': 'data'},
pid=os.getpid(),
time=time.time
)

A document template is created using server-side-include syntax source from an external file named 'results.dtml' and with an initial name space that included the names 'table_name', 'database', 'pid', and 'time'.

Using document templates

To generate text using a document template, the document template must be called. Arguments may be provided to supply an object from which to get data, a mapping object to get data from, or keyword arguments containing additional data. The standard arguments for calling document templates are shown in table See Standard arguments for calling document templates. .

Standard arguments for calling document templates.
Argument number	Argument name	Description
1	client	An object with attributes to be included in the document template name space.
2	mapping	A mapping objects with names and values to be added to the name space.

Both of the standard argument may be omitted. If the mapping argument is to be provided positionally without a client, then a None must be passed as the client value, as in:

return results(None, {'search_results': r})

Keyword arguments may be used to provide values, as in:

return results(search_results=r)

Using document templates with Bobo

Document templates may be published directly with Bobo. Bobo treats document templates as if they were Python functions that accept the arguments named ' self ' and ' REQUEST '. The object traversed to get to the document template is passed as the ' self ' argument and the request object is passed as the ' REQUEST ' argument. Typically, document templates are defined as class attributes and passed class instances and request data, so instance and request data can be used to generate text.

Document templates may also be used in Python functions called by document templates, as in:

def getResults(self, key, REQUEST):
result_data=self.search(key)
return self.resultTemplate(seld, REQUEST, search_results=result_data)

Be sure to call the document template. A common mistake is to return the document template directly, as in:

def getResults(self, key, REQUEST):
result_data=self.search(key)
return self.resultTemplate

Bobo does not attempt to call an object returned from a published object. Results of calling a published function are simply converted to strings and returned. When a document template is converted to a string, the document template source is returned. In the example above, the document template source, rather than the rendered template is returned.

Special formats that may be used with the *var* tag *fmt* attribute
Special Format	Description
whole-dollars	Show a numeric value with a dollar symbol.
dollars-and-cents	Show a numeric value with a dollar symbol and two decimal places.
collection-length	Get the length of a collection of objects.

C-style specifiers for the *fmt* attribute
Code	Description
d	Signed decimal integers
e	Scientific notation
E	Scientific notation (uppercase E)
f	Decimal floating point
g	Shorter of e or f
G	Shorter of E or F
I	Signed decimal integers
o	Unsigned octal
s	String of characters
u	Unsigned decimal integers
x	Unsigned hexadecimal lowercase
X	Unsigned hexadecimal uppercase

Iterative insertion, the in tag

It is sometimes necessary to insert a sequence of values.

The in tag is used to iterate over a sequence of objects. For example, an employee directory listing might be created with DTML source like that shown in figure See DTML source to create an employee phone listing . In this example, employees is either a sequence of employees, or a function that computes a sequence of employees. Each employee has name and phone attributes. These attributes are accessed using var tags. An in -tag sort attribute is used to sort employees by name in the output. The in tag attributes are listed in table See in tag attributes .

DTML source to create an employee phone listing
<table> <tr><th>Name</th><th>Phone number</th></tr> <!--#in employees sort=name--> <tr> <td><!--#var name--></td> <td><!--#var phone--></td> </tr> <!--#/in--> </table>

in tag attributes
Name	Needs an argument	Description
name	yes	The name of the variable to be inserted. See The name attribute
expr	yes	An expression that evaluates to the value to be inserted. See The expr attribute
mapping	no	Normally, the attributes of items in the sequence are displayed. Sometimes, the items should be treated as mapping objects, meaning that items are to be looked up.
sort	yes	The sort attribute is used to cause a sequence of objects to be sorted before text insertion is performed. The attribute value is the name of the attribute (or key if the mapping attribute was provided) that items should be sorted on.
start	yes	The name of a (request) variable that specifies the number of the row to start a batch on 8 .
size	yes	The batch sizea.
orphan	yes	The desired minimum batch sizea.
overlap	yes	The number of rows to overlap between batchesa.
previous	no	If the previous attribute is included, then iterative insertion will not be performed. The text following the in tag will be inserted and batch processinga variables associated with information about a previous batch will be made available.
next	no	The next attribute has the same meaning and use as the previous attribute, except that variables associated with the next batch are provideda.

In the previous example, an empty table would be displayed if there were no employees. It might be better to avoid showing an empty table and simply provide a message indicating that there are no employees. This can be done using the in tag in combination with the if tag, as shown in figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag. . In this example, the if tag is used with the employees variable. Sequences of objects are false if they are empty and true if they are not. If there are no employees, the condition in the if tag is false and the text following the else tag is inserted.

DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag.
<!--#if employees--> <table> <tr><th>Name</th><th>Phone number</th></tr> <!--#in employees sort=name--> <tr> <td><!--#var name--></td> <td><!--#var phone--></td> </tr> <!--#/in--> </table> <!--#else--> Sorry, there are no employees. <!--#/if-->

The else tag as an intermediate tag in the in tag

In the previous example (figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag. ), an in tag is combined with an if tag to avoid showing an empty table if a sequence of employees was empty. An alternative approach is to use an intermediate else tag in an in tag. If an in tag has an intermediate else tag, then the text following the else tag is inserted if the sequence used in the in tag is empty. Figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an else tag in an in tag. shows DTML source that uses an else tag in the in tag to avoid showing an empty table. The output from this source is the same as the output from the source shown in figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag. . The source in figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an else tag in an in tag. is actually more complex that the source in figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag. . The added complexity is due to the fact that the table header and footer had to be moved inside the in tag and the insertion of the table header and footer had to be conditioned on whether or not an item was the first item, last item, or neither, using the variables sequence-start and sequence-end (table See Item variables defined by the in tag ).

DTML source to create an employee phone listing, while properly handling the case of no employees, using an else tag in an in tag.
<!--#in employees sort=name--> <!--#if sequence-start--> <table> <tr><th>Name</th><th>Phone number</th></tr> <!--#/if--> <tr> <td><!--#var name--></td> <td><!--#var phone--></td> </tr> <!--#if sequence-end--> </table> <!--#/if--> <!--#else--> Sorry, there are no employees. <!--#/in-->

In most cases, it's best to use an in tag inside an if tag, as illustrated in figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag. . One case in which it may be best to use an else tag within an in tag is when the sequence used by the in tag is computed using an expr attribute and the computation is expensive. Use of the else tag in the in tag avoids having to define and evaluate the expression twice

When a name attribute is used in an in tag within an if tag, the sequence is only evaluated once, because the if tag caches the value associated with a name attribute.

Variables defined by the in tag

When text is inserted with an in tag, a copy of the text is inserted for each item in the sequence. Tags in the inserted text have access to variables not available outside the in tag. These include:

Attributes of the current item,
Item variables defined by the in tag (table See Item variables defined by the in tag ),
Summary statistic variables defined by the in tag (table See Summary statistic variables defined by the in tag ), and
Batch-processing variables defined by the in tag (table See Batch-processing variables ).

In addition, for each of the variables listed in tables See Item variables defined by the in tag , See Batch-processing variables , and See Attributes of batch objects used when iterating over next-batches and previous-batches variables. with names ending in "-index", there are variables with names ending in "-number", "-roman", "-Roman", "-letter", and "-Letter" that are indexed from 1, "i", "I", "a", and "A", respectively. The sequence-index variable is used to number items as text is inserted. The variables like sequence-letter and sequence-roman provide for numbering using letters and Roman numerals.

Item variables defined by the in tag
Name	Description
sequence-item	The current item.
sequence-key	The key associated with the element in an items sequence. An items sequence is a sequence of value pairs that represent a mapping from a keys to values
sequence-index	The index, starting from 0, of the element within the sequence.
sequence-start	A variable that is true if the element being displayed is the first of the displayed elements, and false otherwise. This is useful when text must be inserted at the beginning of an in tag, especially if the text refers to any variables defined by the in tag.
sequence-end	A variable that is true if the element being displayed is the last of the displayed elements, and false otherwise. This is useful when text must be inserted at the end of an in tag, especially if the text refers to any variables defined by the in tag.

Also, for each of the variables listed in tables See Item variables defined by the in tag , See Batch-processing variables , and See Attributes of batch objects used when iterating over next-batches and previous-batches variables. with names ending in "-index", there are variables with names ending in "-var-xxx", where "xxx" is an element attribute name or key. This is useful when displaying previous- and next-batch information. The construct is also useful in an if tag to test whether an attribute is present, because the attribute lookup will not be extended to the full document template name space.

Summary statistics

The in tag provides variables (table See Summary statistic variables defined by the in tag ) for accessing summary statistics. Summary statistics are computed over the entire sequence, not just over items displayed.

Summary statistic variables defined by the in tag
Name	Description
total-nnn 9	The total of numeric values.
count-nnn	The total number of non-missing values.
min-nnn	The minimum of non-missing values.
max-nnn	The maximum of non-missing values.
median-nnn	The median of non-missing values.
mean-nnn	The mean of numeric values.
variance-nnn	The variance of numeric values computed with a degrees of freedom equal to the count - 1.
variance-n-nnn	The variance of numeric values computed with a degrees of freedom equal to the count.
standard-deviation-nnn	The standard deviation of numeric values computed with a degrees of freedom equal to the count - 1.
standard-deviation-n-nnn	The standard deviation of numeric values computed with a degrees of freedom equal to the count.

Batch Processing

When displaying a large number of objects, it may be impractical to display all of the data at once. While the approach used in figure See DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag. is fine for a small group of employees, it is unacceptable for browsing the employees of a large company.

For this reason, the in tag provides support for batch processing. Information is displayed in batches. Variables are provided (table See Batch-processing variables ) to aid in the construction of HTML hyper-links to other batches.

Batch-processing variables
Name	Description
sequence-query	The original query string given in a get request with the form variable named in the start attribute removed.
sequence-step-size	The batch size used.
previous-sequence	This variable will be true when the first element is displayed and when the first element displayed is not the first element in the sequence.
previous-sequence-start-index	The index, starting from 0, of the start of the batch previous to the current batch.
previous-sequence-end-index	The index, starting from 0, of the end of the batch previous to the current batch.
previous-sequence-size	The size of the batch previous to the current batch.
previous-batches	A sequence of mapping objects containing information about all of the batches prior to the batch being displayed.
next-sequence	This variable will be true when the last element is displayed and when the last element displayed is not the last element in the sequence.
next-sequence-start-index	The index, starting from 0, of the start of the batch after the current batch.
next-sequence-end-index	The index, starting from 0, of the end of the batch after the current batch.
next-sequence-size	The size of the batch after the current batch.
next-batches	A sequence of mapping objects containing information about all of the batches after the batch being displayed.

Attributes of batch objects used when iterating over *next-batches* and *previous-batches* variables.
Name	Description
batch-start-index	The index, starting from 0, of the beginning of the batch.
batch-end-index	The index, starting from 0, of the end of the batch.
batch-size	The size of the batch.

The batch-processing facilities of the in tag are quite powerful, but the various options and approaches are complex enough that it is best to look at the batch-processing features by way of an example. The example chosen here is contrived to be extremely simple to make it as easy as possible to follow what's going on. Consider a table of 36 words (figure See Table of 36 words ) We will start by using the DTML source in figure See DTML source to browse 36 words, 5 words at a time to display this data. The DTML uses an if tag to test for an empty sequence of words. The actual sequence is named w36 . Inside the if tag, there are three in tags. All three in tags include the attributes size, with the value 5, and start , with the value qs . The size attribute is used to specify a batch size. Normally, one would not choose such a small batch size, but a small batch size helps to make the presentation shorter. The start parameter is used to specify a name of a variable that holds the index of the first element of the sequence to be displayed. If the variable is not defined, then the first batch is displayed. Figure See The output of the DTML source in figure 5 as displayed in a Web browser for several batches. shows the output of the DTML as displayed on a Web browser for the first two and last two batches..

DTML source to browse 36 words, 5 words at a time
<!--#var standard_html_header--> <!--#if w36--> <!--#in w36 previous size=5 start=qs--> <a href="<!--#var document_id--><!--#var sequence-query -->qs=<!--#var previous-sequence-start-number-->"> (Previous <!--#var previous-sequence-size--> results)</a> <!--#/in--> <table border> <tr><th>WORD</th></tr> <!--#in w36 size=5 start=qs--> <tr><td><!--#var WORD--></td></tr> <!--#/in--> </table> <!--#in w36 next size=5 start=qs--> <a href="<!--#var document_id--><!--#var sequence-query -->qs=<!--#var next-sequence-start-number-->"> (Next <!--#var next-sequence-size--> results)</a> <!--#/in--> <!--#else--> Sorry, no words. <!--#/if--> <!--#var standard_html_footer-->

The output of the DTML source in figure See DTML source to browse 36 words, 5 words at a time as displayed in a Web browser for several batches.

(words 1-5)	(words 6-10)	(words 26-30)	(words 31-36)

The first of the three in tags is used to display an HTML hyper-link to a previous batch of data. The previous attribute in the in tag indicates that only previous-batch data should be displayed. Row data are not displayed. If the first batch is being displayed, then no text is inserted, as can be seen in figure 7 (words 1-5). The source in the first in tag uses four variable references. The first retrieves the document_id , which is used as a relative URL name for the document. The second variable reference, using variable sequence-query , retrieves the request query string that has been modified so that it does not include the variable named in the in tag start attribute, qs . The sequence-query value also contains punctuation, ` ? ' and ` & ' necessary so that the document_id , sequence-query , and URL-encoded value for the next batch start can be concatenated. The URL-encoded value of the next batch start is " qs= " followed by the variable,
previous-sequence-start-number . The variable previous-sequence-size provides the size of the previous batch for display in the hyper-link. Note that the previous (or next) sequence size is not necessarily equal to the batch size.

Note that the DTML source has been split over multiple lines by introducing line breaks within var tags. This is a useful way to break up long lines without causing line-breaks to be included in generated HTML.

The second in tag simply displays the rows in the batch. The third in tag is similar to the first in tag, except that a hyper link to the next, rather than the previous batch is displayed. Table See Query strings, and previous batch URL and next batch URL for the batches shown in figure 6. shows the query string, previous batch URL and next-batch URL for the example shown in figure See The output of the DTML source in figure 5 as displayed in a Web browser for several batches. .

Query strings, and previous batch URL 10 and next batch URL for the batches shown in figure See The output of the DTML source in figure 5 as displayed in a Web browser for several batches. .
Words	Query string	Previous-batch URL	Next- batch URL
1-5			r36?qs=6
6-10	qs=6	r36?qs=1	r36?qs=11
26-30	qs=26	r36?qs=21	r36?qs=31
31-36	qs=31	r36?qs=26

Orphan rows

Note that the size of the last batch is six. This is because the in tag has a feature that attempts to prevent the display of very small batches by combining them with adjacent batches. Normally, if the number of rows in a batch is less than or equal to two, then it is combined with an adjacent batch. The orphan attribute in the in tag can be used to provide an alternate setting. The value provided in the orphan attribute is the desired minimum batch size. The default setting for orphan is 3.

Overlapping batches

Normally, batches are non-overlapping. For large batch sizes, it is sometimes useful to overlap rows between batches. The overlap attribute in the in tag is used to specify how many rows to overlap between batches. The default is 0.

Showing row number and row data in previous and next batch hyper links.

The variables beginning previous-sequence-start- , previous-sequence-end- , next-sequence-start- , and next-sequence-end- and ending in index , number , roman , Roman , letter , Letter , and var-xxx , where xxx is a row attribute (or key) name can be used to label which rows begin and end previous and next batches. This is illustrated in figures See Using batch-processing variables to show previous and next batch row number using Roman and Arabic numerals. and See Using batch-processing variables to show previous-batch row number using letters and next-batch starting and ending words. , which use various batch insertion variables to label previous and next batches.

Using batch-processing variables to show previous and next batch row number using Roman and Arabic numerals.
<!--#in w36 previous size=5 start=qs--> (<!--#var previous-sequence-start-roman--> - <!--#var previous-sequence-end-roman-->) <!--#/in--> <table border><tr><th>WORD</th></tr> <!--#in w36 size=5 start=qs--> <tr><td><!--#var WORD--></td></tr> <!--#/in--> </table> <!--#in w36 next size=5 start=qs--> (<!--#var next-sequence-start-number--> - <!--#var next-sequence-end-number-->) <!--#/in-->

Using batch-processing variables to show previous-batch row number using letters and next-batch starting and ending words.
<!--#in w36 previous size=5 start=qs--> (<!--#var previous-sequence-start-letter--> - <!--#var previous-sequence-end-letter-->) <!--#/in--> <table border><tr><th>WORD</th></tr> <!--#in w36 size=5 start=qs--> <tr><td><!--#var WORD--></td></tr> <!--#/in--> </table> <!--#in w36 next size=5 start=qs--> (<!--#var next-sequence-start-var-WORD--> - <!--#var next-sequence-end-var-WORD-->) <!--#/in-->

Showing information about multiple batches

Hyper links to multiple batches can be provided using the next-batches and previous-batches variables. These variables provide access to sequences of mapping objects containing information about all previous and next batches. Figure See Use of DTML to provide links to all previous and next batches. provides examples of using previous-batches to include hyper links to previous batches showing starting and ending row numbers, and of using next-batches to show hyper-links to following batches showing starting and ending words. Note that nested in tags are used to iterate over batch information. The nested in tags must use the mapping attribute, because the items in the sequences associated with next-batches and previous-batches are mapping objects.

Use of DTML to provide links to all previous and next batches.
<!--#in w36 previous size=5 start=qs--> <!--#in previous-batches mapping--> <!--#unless sequence-start-->, <!--#/unless--> <a href="<!--#var document_id--><!--#var sequence-query -->qs=<!--#var batch-start-number-->"> <!--#var batch-start-number--> - <!--#var batch-end-number--></a> <!--#/in--> <!--#/in--> <table border><tr><th>WORD</th></tr> <!--#in w36 size=5 start=qs--> <tr><td><!--#var WORD--></td></tr> <!--#/in--> </table> <!--#in w36 next size=5 start=qs--> <!--#in next-batches mapping--> <!--#unless sequence-start-->, <!--#/unless--> <a href="<!--#var document_id--><!--#var sequence-query -->qs=<!--#var batch-start-number-->"> <!--#var batch-start-var-WORD--> - <!--#var batch-end-var-WORD--></a> <!--#/in--> <!--#/in-->

1. It is also possible to define additional syntaxes, although the mechanism for doing this is not currently documented. For example, a syntax that is similar to the syntax used by active server pages has been developed.

2. Actually, all attributes have values, but some attributes, like the capitalize attribute have defaults and the values can be omitted. Many attributes, like the capitalize attributes are flags. Their presence typically indicates that some option that is normally disabled should be enabled. There is one case in which values must be provided for these attributes, that being when the attribute is the first attribute given for a tag and would be confused as a name attribute value. For attributes like capitalize, a value of "yes", "on", or 1 is uasually provided, as in: 

3. In this context, "function" refers any "callable" object.

4. A method is like a function except that it is an attribute of an object and may use the object's data in computation.

5. The special variable, _, is an exception to this rule.

6. Python 1.4 users must use the ni module to enable packages. DocumentTemplate may also be used as a collection of modules, rather than as a package by copying all of the DocumentTemplate modules except the __init__ module to a directory in the Python path.

7. The C programming language.

8. See Batch Processing

9. nnn is the name of an attribute or key. For example, to get the mean salary in a collection of employees, mean-salary would be used.

10. These are relative URL's as generated by the DTML. The document_id for this example is r36.

Attribute name	Needs an argument?	Description
name	yes	The name of the variable to be inserted. See The name attribute
expr	yes	An expression that evaluates to the value to be inserted. See The expr attribute
fmt	yes	Specify a data format, which may be a special, custom, or C-style format. See Custom, special, C, and empty formats
null	yes	Specify a string to be inserted for null values. See Null Values
lower	no	Cause all upper-case letters to be converted to lower case
upper	no	Cause all lower-case letters to be converted to upper case.
capitalize	no	Cause the first character of the inserted value to be converted to upper case.
spacify	no	Cause underscores in the inserted value to be converted to spaces.
thousands_commas	no	Cause commas to be inserted every three digits to the left of a decimal point in values containing numbers. For example, the value, "12000 widgets" becomes "12,000 widgets".
html_quote	no	Convert characters that have special meaning in HTML to HTML character entities.
url_quote	no	Convert characters that have special meaning in URLS to HTML character entities using decimal values.
sql_quote	no	Convert single quotes to pairs of single quotes. This is needed to safely include values in Standard Query Language (SQL) strings.
newline_to_br	no	Convert new-line characters, carriage-return characters, and new-line-carriage-return character combinations to new-line characters followed by HTML break tags.
size	yes	Truncate the value to the given size. See Truncation
etc	yes	Provide a string to be added to truncated text to indicate that truncation has occurred. The default value is "...". See Truncation

Bobo Document Template Markup Language User's Guide

Contents

List of Tables

List of Figures

Bobo Document Template Markup Language User's Guide

Introduction

General Information

DTML Tag Syntax

Alternate Python String Format Syntax

Common tag attributes

The name attribute

The expr attribute

Expression Syntax

Expression examples

Variable Lookup

The special name-space variable, _

Available attributes in the special variable, _

Attributes defined by the math module.

Attributes defined by the string module

Attributes defined by the whrandom module

Access Control

The containing object that the object was accessed from,

Name lookup

Simplest-case steps for looking up names

Bobo-defined Web-request variables,

Attributes of the REQUEST variable

Attributes of the RESPONSE variable.

CGI-defined Web-request variables

Using Document Templates from Python

Document template classes

Creating document templates

Standard document template creation arguments.

Using document templates

Standard arguments for calling document templates.

Using document templates with Bobo

The var tag

var tag attributes

Custom, special, C, and empty formats

Special formats that may be used with the var tag fmt attribute

C-style specifiers for the fmt attribute

Null Values

Truncation

Conditional insertion, the if and unless tags

An if tag, with a closing /if tag,

Iterative insertion, the in tag

DTML source to create an employee phone listing

in tag attributes

DTML source to create an employee phone listing, while properly handling the case of no employees, using an in tag with an if tag.

The else tag as an intermediate tag in the in tag

DTML source to create an employee phone listing, while properly handling the case of no employees, using an else tag in an in tag.

Variables defined by the in tag

Item variables defined by the in tag

Summary statistics

Summary statistic variables defined by the in tag

Batch Processing

Batch-processing variables

Attributes of batch objects used when iterating over next-batches and previous-batches variables.

DTML source to browse 36 words, 5 words at a time

The output of the DTML source in figure See DTML source to browse 36 words, 5 words at a time as displayed in a Web browser for several batches.

Query strings, and previous batch URL 10 and next batch URL for the batches shown in figure See The output of the DTML source in figure 5 as displayed in a Web browser for several batches. .

Orphan rows

Overlapping batches

Showing row number and row data in previous and next batch hyper links.

Using batch-processing variables to show previous and next batch row number using Roman and Arabic numerals.

Using batch-processing variables to show previous-batch row number using letters and next-batch starting and ending words.

Showing information about multiple batches

Use of DTML to provide links to all previous and next batches.

Displaying objects with the with tag

Evaluating names or expressions without generating any text using the call tag

Reporting errors with the raise tag

Excluding source text with the comment tag

Index

A

B

C

D

E

F

G

H

Bobo
Document Template Markup Language
User's Guide