Two syntaxes are currently supported1 by 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 syntax described here is used by the classes DocumentTemplate.HTML and DocumentTemplate.HTMLFile. Zope Document objects use the server-side-include syntax. 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 by DTML to indicate text substitution is based on the use of DTML tags. A DTML tag is of the form:
<!--#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.
The most common tag is the 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 <!--#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 short-hand version of the name attribute in which the attribute name is omitted:
Hello <!--#var input_name capitalize-->!
When using the short-hand form of the name attribute, the value is the first attribute in the tag and is not enclosed in quotation marks.
A similar short-hand notation exists 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:
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:
The var tag is called an empty tag , because it does not contain any other tags. Tags which are non-empty contain bracketed text which may contain other DTML tags. Non-empty 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 non-empty tag is the if tag:
<!--#if input_name-->
Hello <!--#var input_name-->.
<!--#/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 if tag can use an intermediate else tag, as in:
<!--#if input_name-->
Hello <!--#var input_name-->.
<!--#else-->
Have we been introduced?
<!--#endif-->
Note that in this case, the alternate prefix of the end tag is used.
Intermediate tags can have attributes, as in:
<!--#if input_name-->
Hello <!--#var input_name-->.
<!--#elif nick_name-->
Hi <!--#var nick_name-->.
<!--#else-->
Have we been introduced?
<!--#/if-->
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 or spaces may be placed between the pound character (#), the tag name, attributes or the end of a tag. For example, the following are all valid tags:
<!--#
var x--> <!--#var y -->
<!--#var some_really_long_name
--><!--#var and_another_rather_long_one
-->