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.
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
dollars-and-cents
collection-length
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.
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:
None
or
are false and yield an empty string when converted to
a string.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.
A number of special attributes are provided to transform the value after formatting has been applied. These parameters are supplied without arguments.
lower
upper
capitalize
spacify
thousands_commas
html_quote
url_quote
url_quote_plus
+
. This is needed for building
query strings in some cases.sql_quote
newline_to_br
url
absolute_url
method, if it has one. 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 ..."
.
A call
tag is provided for evaluating named objects or expressions
without rendering the result.