Module
zope.documenttemplate.dt_var

Variable insertion parameters

When inserting variables, parameters may be specified to control how the data will be formatted. In HTML source, the fmt parameter is used to specify a C-style or custom format to be used when inserting an object. In EPFS source, the fmt parameter is only used for custom formats, a C-style format is specified after the closing parenthesis.

Custom formats

A custom format is used when outputing user-defined objects. The value of a custom format is a method name to be invoked on the object being inserted. The method should return an object that, when converted to a string, yields the desired text. For example, the HTML source:

          <!--#var date fmt=DayOfWeek-->

Inserts the result of calling the method DayOfWeek of the object bound to the variable date, with no arguments.

In addition to object methods, serveral additional custom formats are available:

whole-dollars
Show a numeric value with a dollar symbol.
dollars-and-cents
Show a numeric value with a dollar symbol and two decimal places.
collection-length
Get the length of a collection of objects.

Note that when using the EPFS source format, both a C-style and a custom format may be provided. In this case, the C-Style format is applied to the result of calling the custom formatting method.

Null values and missing variables

In some applications, and especially in database applications, data variables may alternate between "good" and "null" or "missing" values. A format that is used for good values may be inappropriate for null values. For this reason, the null parameter can be used to specify text to be used for null values. Null values are defined as values that:

For example, when showing a monitary value retrieved from a database that is either a number or a missing value, the following variable insertion might be used:

           <dtml-var cost fmt="$%.2d" null='n/a'>

Missing values are providing for variables which are not present in the name space, rather than raising an NameError, you could do this:

and in this case, if cost was missing, it would be set to 0. In the case where you want to deal with both at the same time, you can use 'default':

In this case, it would use '' if the value was null or if the variable was missing.

String manipulation

A number of special attributes are provided to transform the value after formatting has been applied. These parameters are supplied without arguments.

lower
cause all upper-case letters to be converted to lower case.
upper
cause all upper-case letters to be converted to lower 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.
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 Standard 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.

Truncation

The attributes size and etc can be used to truncate long strings. If the size attribute is specified, the string to be inserted is truncated at the given length. If a space occurs in the second half of the truncated string, then the string is further truncated to the right-most space. After truncation, the value given for the etc attribute is added to the string. If the etc attribute is not provided, then ... is used. For example, if the value of spam is "blah blah blah blah", then the tag <!--#var spam size=10--> inserts "blah blah ...".

Evaluating expressions without rendering results

A call tag is provided for evaluating named objects or expressions without rendering the result.