Using the DTML entity syntax
Created by AlexR.
Last modified on 1999/11/10.
This howto shows how to use the DTML entity syntax. Most information was found on the email@example.com 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 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:
and is especially handy in attributes:
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:
||Cause all upper-case letters to be converted to lower case.
||Cause all lower-case letters to be converted to upper case.
||Cause the first character of the inserted value to be converted to upper case.
||Cause underscores in the inserted value to be converted to spaces.
||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".
||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;
||Convert characters that have special meaning in URLS to HTML character entities using decimal values.
||Like url_quote but also replace blank space characters with '+'. This is needed for building query strings in some cases.
||Convert single quotes to pairs of single quotes. This is needed to safely include values in Structured Query Language (SQL) strings.
||Convert newlines and carriage-return and newline combinations to break tags.
||Get the absolute URL of the object by calling it's 'absolute_url' method, if it has one.
||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.