Z Object Publishing Environment

Search | Download | Documentation | Resources | Members




Join Zope.org
Log in

 Zope Exits

Zope Newbies

How-To: Using the DTML entity syntax

Version 0.1

This howto shows how to use the DTML entity syntax. Most information was found on the zope@zope.org 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:


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:


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)



You can get the verbatim, unformatted variable value:


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

You can also combine several attributes:


Here we get all caps html-quoted text.

Privacy policy       Printable Page       Feedback to this page's author      Feedback about Zope.org