| The BSLTemplate takes an HTML document with embedded "BSL"
markup tags in it and evaluates those special tags to produce a
standard HTML document.
BSL stands for Brazil Scripting Language. BSL can be used to substitute
data from the request properties into the resultant document. However,
rather than simple property substitution as is provided by the
PropsTemplate, this class provides the ability to iterate
over and choose amongst the values substituted with a set of simple
flow-control constructs.
BSL uses the following special tags as its language constructs:
This template recursively evalutes the bodies/clauses of the BSL commands,
meaning that they may contain nested BSL and/or other tags defined by
other templates.
The following configuration parameter is used to initialize this
template.
- debug
- If this configuration parameter is present, this class replaces
the BSL tags with comments, so the user can keep track of where
the dynamically generated content is coming from by examining the
comments in the resultant HTML document. By default, the BSL tags
are completely eliminated from the HTML document rather than changed
into comments.
<foreach> TAG
The <foreach> tag repeatedly evaluates its body a
selected number of times. Each time the body is evaluated, the provided
named property is set to the next word in the provided list of words.
The body is terminated by the </foreach> tag.
This tag is especially useful for dynamically producing lists and tables.
<foreach name=var list="value1 value2 ..." [delim=x]>
<property var>
</foreach>
Iterate over the set of values "value1 value2 ...". The named
property var is assigned each value in turn. If the optional
parameter delim is specified, its value is used as
the list delimeter. By default, whitespace is used.
<foreach name=var property=property [delim=x]>
<property var>
</foreach>
Iterate over the values in the other property. The value
of the other property is broken up using the StringTokenizer
and each piece is assigned to the named property var in turn.
If the optional
parameter delim is specified, its value is used as
the list delimeter. By default, whitespace is used.
<foreach name=var property=property [delim=x]>
<property var>
</foreach>
Iterate over the values in the other property. The value
of the other property is broken up using the StringTokenizer
and each piece is assigned to the named property var in turn.
<foreach name=var glob=pattern>
<property var.name>
<property var.value>
<property var.name.1>
<property var.name.2>
</foreach>
Iterate over all the properties whose name matches the
sunlabs.brazil.util.Glob glob pattern. In turn, the
following properties are set:
var.name is the name of the property.
var.value is the value of the property.
var.name.1, var.name.2, ... are
the substrings matching the wildcard characters in the pattern, if any.
<foreach name=var glob=pattern>
<property var.name>
<property var.value>
<property var.name.1>
<property var.name.2>
</foreach>
Iterate over all the properties whose name matches the
sunlabs.brazil.util.Glob glob pattern. In turn, the
following properties are set:
var.name is the name of the property.
var.value is the value of the property.
var.name.1, var.name.2, ... are
the substrings matching the wildcard characters in the pattern, if any.
<foreach name=var match=pattern>
<property var.name>
<property var.value>
<property var.name.0>
<property var.name.1>
<property var.name.2>
</foreach>
Iterate over all the properties whose name matches the
sunlabs.brazil.util.regexp.Regexp regular expression pattern. In turn, the following properties are set:
var.name is the name of the property.
var.value is the value of the property.
var.name.0 is the substring that matched the whole
pattern.
var.name.1, var.name.2, ... are
the substrings matching the parenthesized subexpressions, if any.
Sorting using foreach
The <foreach> tag contains an (experimantal) feature to
change the order of iteration. This facility is intended for
common sorting operations. For general purpose manipulation of
the iteration order, the order should be defined either in another
handler, or by using the
sunlabs.brazil.tcl.TclServerTemplate <server> directive.
The three additional parameters used to control sorting are:
- reverse
- The list of items is iterated in the reverse order.
- numeric
- When used in conjunction with the
sort parameter, it
causes the sort keys to be interpreted as numbers (or zero if the
key is an invalid number).
- sort[=key]
- The items to be iterated over are sorted. If no key is supplied, the
items are sorted by the property name. If a key is supplied, its
value is used as the sort key for the iteration. For this to be
meaningful, the key should contain one or more variable substitutions
(e.g. ${...}, see *
sunlabs.brazil.util.Format.getPropertygetProperty ). Before iteration commences, the value for the key is
computed for each item to be iterated over, by performing all of the
'${...}' substitutions in key for each value, then sorting the
items by the result.
<if> TAG
The <if> tag evaluates one of its clauses dependant upon
the value of the provided named property(ies). The other clauses are not
evaluated and do not appear in the resultant HTML document.
The general format of the <if> tag is as follows:
<if ...condition...>
...clause...
<elseif ...condition...>
...clause...
<else>
...clause...
</if>
The <elseif> and <else> tags are
optional, and multiple <elseif> tags may be present.
Following are the formats of the "...condition...":
-
<if var>
- Test if the value of property var is set and is not "",
"false", "no", "off", or the number 0.
-
<if name=var>
- Same as above.
-
<if name=var value=string>
- Test if the value of property var is equal to the
given string.
-
<if name=var glob=pattern>
- Test if the value of property var matches the given
sunlabs.brazil.util.Glob glob pattern.
-
<if name=var match=pattern>
- Test if the value of property var matches the given
sunlabs.brazil.util.regexp.Regexp regular expression pattern.
Anytime a variable name is specified, variable substitution as
described in
sunlabs.brazil.util.Format.getProperty may be used.
See Also: a sample HTML page that contains some BSL
See Also: markup |
