var: Inserts a variable

The var tags allows you insert variables into DTML output.

Syntax

var tag syntax:

      <dtml-var Variable|expr="Expression">

The var tag is a singleton tag. The var tag finds a variable by searching the DTML namespace which usually consists of current object, the current object's containers, and finally the web request. If the variable is found, it is inserted into the DTML output. If not found, Zope raises an error.

var tag entity syntax:

      &dtml-variableName;

Entity syntax is a short cut which inserts and HTML quotes the variable. It is useful when inserting variables into HTML tags.

var tag entity syntax with attributes:

      &dtml.attribute1[.attribute2]...-variableName;

To a limited degree you may specify attributes with the entity syntax. You may include zero or more attributes delimited by periods. You cannot provide arguments for attributes using the entity syntax. If you provide zero or more attributes, then the variable is not automatically HTML quoted. Thus you can avoid HTML quoting with this syntax, &dtml.-variableName;.

Attributes

html_quote
Convert characters that have special meaning in HTML to HTML character entities.
missing=string
Specify a default value in case Zope cannot find the variable.
fmt=string
Format a variable. Zope provides a few built-in formats including C-style format strings. For more information on C-style format strings see the Python Library Reference If the format string is not a built-in format, then it is assumed to be a method of the object, and it called.
whole-dollars
Formats the variable as dollars.
dollars-and-cents
Formats the variable as dollars and cents.
collection-length
The length of the variable, assuming it is a sequence.
structured-text
Formats the variable as Structured Text. For more information on Structured Text see Structured Text How-To on the Zope.org web site.
null=string
A default value to use if the variable is None.
lower
Converts upper-case letters to lower case.
upper
Converts lower-case letters to upper case.
capitalize
Capitalizes the first character of the inserted word.
spacify
Changes underscores in the inserted value to spaces.
thousands_commas
Inserts commas every three digits to the left of a decimal point in values containing numbers for example 12000 becomes 12,000.
url
Inserts the URL of the object, by calling its absolute_url method.
url_quote
Converts characters that have special meaning in URLs to HTML character entities.
url_quote_plus
URL quotes character, like url_quote but also converts spaces to plus signs.
url_unquote
Converts HTML %xx escapes into their single character values (ie: undoes the effects of url_quote).
url_unquote_plus
Like url_unquote, but also replaces + characters with spaces (ie: undoes the effects of url_quote_plus).
sql_quote
Converts single quotes to pairs of single quotes. This is needed to safely include values in SQL strings.
newline_to_br
Convert newlines (including carriage returns) to HTML break tags.
size=arg
Truncates the variable at the given length (Note: if a space occurs in the second half of the truncated string, then the string is further truncated to the right-most space).
etc=arg
Specifies a string to add to the end of a string which has been truncated (by setting the size attribute listed above). By default, this is ...

Examples

Inserting a simple variable into a document:

      <dtml-var standard_html_header>

Truncation:

      <dtml-var colors size=10 etc=", etc.">

will produce the following output if colors is the string 'red yellow green':

      red yellow, etc.

C-style string formatting:

      <dtml-var expr="23432.2323" fmt="%.2f">

renders to:

      23432.23

Inserting a variable, link, inside an HTML A tag with the entity syntax:

      <a href="&dtml-link;">Link</a>

Inserting a link to a document doc, using entity syntax with attributes:

      <a href="&dtml.url-doc;"><dtml-var doc fmt="title_or_id"></a>

This creates an HTML link to an object using its URL and title. This example calls the object's absolute_url method for the URL (using the url attribute) and its title_or_id method for the title.