DTML Tag Syntax

The DTML Tag is supported by three syntaxes.1 This includes the DTML document templates, server-side includes and Python string formats. When using document templates from Python, the syntax used depends on the document template class used (or subclasses). The server-side-include new DTML syntax described here is used by the classes DocumentTemplate.HTML and DocumentTemplate.HTMLFile.

The syntax formats are shown below:

• <dtml-name>
• %(name)x
• <!--#name-->

<dtml-tag name attribute1="value1" attribute2="value2" ... >

The tag name identifies the tag type. Following the tag name, are typically one or more attributes which indicate where the tag's data is found and how that data is to be inserted. Sometimes, attribute values can be omitted and quotation marks around attribute values can be omitted if the values do not contain a space, tab, new-line character, equal sign or double quotation marks.

<dtml-var date fmt=Date>

<dtml-var name="standard_html_header">

<dtml-with subfolder>

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

Hello <dtml-var name="input_name" capitalize>!

This example uses two attributes, name and capitalize . The name attribute is used to specify a variable name. Typically, a variable name refers to data in World Wide Web (WWW) requests or properties of Zope objects, like folders. Because of the name attribute's frequent usage, there exists a shorthand version of the name attribute in which the attribute name is omitted:

Hello <dtml-var input_name capitalize>!

When using the shorthand form of the name attribute, the value is the first attribute in the tag and is not enclosed in quotation marks.

A similar shorthand notation exists for the dtml-expr attribute. The expr attribute is used to provide computational expressions, as in:

<dtml-if expr="age > 18">

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

<dtml-if "age > 18">

Like in the name attribute, the attribute value is the first attribute in the tag and is not enclosed in quotation marks.

The capitalize attribute illustrates the use of an attribute in which a value, or argument, is not defined2. The capitalize attribute indicates that the first letter of the inserted text should be capitalized. Suppose the document template source from the previous example is evaluated with the input name, " world ", then the text output would be:

Hello World!

The dtml-var tag is called a singleton tag , because it does not contain any other tags. Tags which are duplex contain bracketed text which may contain other DTML tags. Duplex tags require a matching end tag . The name of the end tag is the same as the start tag, except that it contains a " / " or an "end " prefix. End tags do not have attributes. A commonly used duplex tag is the dtml-if tag:

<dtml-if input_name>
Hello <dtml-var input_name>.
</dtml-if>

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

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

<dtml-if input_name>
Hello <dtml-var input_name>.
<dtml-else>
Have we been introduced?
<dtml-endif>

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

Intermediate tags can have attributes, as in:

<dtml-if input_name>
Hello <dtml-var input_name>.
<dtml-elif nick_name>
Hi <dtml-var nick_name>.
<dtml-else>
Have we been introduced?
</dtml-if>

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