Using the DTML entity syntax

Created by . Last modified on 2003/08/05.

Version 0.1

This howto shows how to use the DTML entity syntax. Most information was found on the [email protected] list and in the Zope distribution readme files. I also included data from Phil Harris and Martijn Pieters. Feel free to send me your feedback.

Version History

• Version 0.1 - 10th November 1999 - First draft

Introducing the DTML entity syntax

The entity notation is an alternate syntax for the <dtml-var> tag. It is available since Zope 2.0. Here is a text snippet from the ZopeDir\doc\CHANGES.txt file for the 2.0.1 distribution (in a slightly adapted form) that explains it all:

Zope 2.0 introduces a new HTML DTML syntax that, among other things, allows simple 'var' tags to be entered using the entity-reference syntax, as in:

<input name=myVar value="&dtml-myVar;">

The entity reference syntax is mainly intended for use when a var tag is used to insert text into an HTML tag. In these cases, the text needs to be html-quoted. For this reason, use of the entity reference syntax now implies html quoting. For example, the DTML snippet above is equivalent to:

<input name=myVar value="<dtml-var myVar html_quote>">

...

You can also use an entity-reference syntax for the var tag as an alternative to the tag syntax. For example:

&dtml-foo;

is equivalent to:

<dtml-var foo>

and is especially handy in attributes:

<A HREF="&dtml-foo;">

Differences with the standard syntax

The &dtml-myVar; syntax is intended for use within HTML tag attributes, and as such will insert the variable HTML-quoted. This means that characters that have a special meaning in HTML (such as <, >, or &) will be replaced by the corresponding entities. So if you include &dtml-standard_html_header; in a page you'll find your header HTML source in the browser, instead of rendered HTML.

Features added in the Zope 2.1 release

In the new version 2.1, the syntax has been extended. You can then specify var tag options, which influence the formatting (most of these options could already be used with the <dtml-var myVar> syntax in the previous release). Use this syntax:

&dtml.attribute-myVar;

where myVar is a variable name (or an objet name, eg. a folder name) and attribute is one of the following options:

Attribute Name	Description
lower	Cause all upper-case letters to be converted to lower case.
upper	Cause all lower-case letters to be converted to upper case.
capitalize	Cause the first character of the inserted value to be converted to upper case.
spacify	Cause underscores in the inserted value to be converted to spaces.
thousands_commas	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	Convert characters that have special meaning in HTML to HTML character entities. However, the &dtml-myVar; syntax is already html-quoted. Thus &dtml-myVar; is the same as &dtml.html_quote-myVar;
url_quote	Convert characters that have special meaning in URLS to HTML character entities using decimal values.
url_quote_plus	Like url_quote but also replace blank space characters with '+'. This is needed for building query strings in some cases.
sql_quote	Convert single quotes to pairs of single quotes. This is needed to safely include values in Structured Query Language (SQL) strings.
newline_to_br	Convert newlines and carriage-return and newline combinations to break tags.
url	Get the absolute URL of the object by calling it's 'absolute_url' method, if it has one.
missing	Allows an undefined variable to render to ''. If you don't specify this option, using a missing variable will cause an error.

(This information comes straight from the ZopeDir\lib\python\DocumentTemplate\DT_Var.py file in the 2.1 Zope distribution)

Examples:

&dtml.html_quote-myVar;
&dtml.url_quote-myVar;
&dtml.upper-myVar;
&dtml.url-myVar;
&dtml.missing-myVar;

You can get the verbatim, unformatted variable value:

&dtml.-myVar;

Thus &dtml.-myVar; is the equivalent of <dtml-var myVar>.

You can also combine several attributes:

&dtml.html_quote.upper-myVar;

Here we get all caps html-quoted text.