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 SetTemplate
, 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:
<if>
<foreach>
<abort>
<break>
<continue>
<extract>
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>
tag evaluates one of its clauses dependant upon the value of the provided conditions. 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 [not] condition> clause <elseif [not] condition> clause <else> clause </if>The
<elseif>
and <else>
tags are optional, and multiple <elseif>
tags may be present. <elseif>
may also be spelled <elif>
or <else if>
. The optional parameter not
reverses the sense of the specified condition. Following are the formats of the condition:
<if name=var>
<if name=var value=string>
<if name=pattern any>
<if name=var glob=pattern>
<if name=var match=pattern>
if the attribute nocase
is present, then a case insensitive match is performed.
<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="chars"]> <get var> body </foreach>Iterate over the set of values "value1 value2 ...". The named property var is assigned each value in turn.
If the optional parameter delim
specifies, the delimiter for splitting the list into elements.
delim
is a single character, then that character is used as the delimiter. delim
is not specified or is the empty string "", the delimiter is whitespace. <foreach name=var property=property [delim="chars"]> <get var> body </foreach>Iterate over the values in the other property. The value of the other property is broken into elements and each element is assigned to the named property var in turn. This form is equivalent to
<foreach name=var list=${property}>
. If the optional parameter delim
is specified, the characters are delimiters for splitting the list into elements using the StringTokenizer
rules. If delim
is not specified or is the empty string "", the delimiter is whitespace.
<foreach name=var glob=pattern> <get var.name> <get var.value> <get var.name.1> <get var.name.2> body </foreach>Iterate over all the properties whose name matches the {@link sunlabs.brazil.util.Glob glob} pattern. In turn, thefollowing 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> <get var.name> <get var.value> <get var.name.0> <get var.name.1> <get var.name.2> body </foreach>Iterate over all the properties whose name matches the {@link 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. NOTE: In the current implementation, when there are large numbers of property values, using glob
is (potentially) much more efficient than match
for locating names.
<foreach>
. if the attribute nocase
is present, then a case insensitive match is performed.
foreach
The four additional parameters used to control sorting are:
reverse
sort[=key]
<foreach name=id property=employee.ids sort="${employee.${id}.last}, ${employee.${id}.first}">This option can be tricky to use correctly. The following example will not sort employees by last name:
1. <foreach name=id property=employee.ids sort="employee.${id}.last">Why? Because another level of ${...} needs to be inserted in the sort key:
2. <foreach name=id property=employee.ids sort="${employee.${id}.last}">Example (1) will just sort the literal strings "employee.1234.last", "employee.5678.last", etc. while example (2) will do the correct thing and sort the values "Stevens" and "Johnson". Remember that BSL sorts based on exactly what you pass it and does not know that the provided string should be treated as another variable itself.
numeric
sort
parameter, it causes the items to be interpreted as numbers (or zero if the item doesn't look like a number).
nocase
sort
parameter, it causes the items to be sorted in a case-insensitive fashion. Note that when used with "glob=..."
or "match=..."
, it does NOT cause the glob or regular expression to be case insensitive. It causes the results of the glob or regexp to be sorted in a case-insensitive fashion. There is currently no way to specify a case-insensitive glob or regular expression.
<abort>
tag terminates processing of the current HTML page at the point it is evaluated. All HTML on the page after the <abort>
tag is discarded, and the HTML processed up to that point is returned. This tag can be placed anywhere on a page, including within a <foreach>
or <if>
construct. The following is an example usage of this tag:
<foreach name=x list="0 1 2 3"> <if name=x value=3> <abort> </if> <get name=x> </foreach> TestingThis example produces the output:
0 1 2
<break>
tag terminates processing within a <foreach>
construct. The processing of HTML continues immediately after the </foreach>
. This tag can only be used inside of a <foreach>
tag. The following is an example usage of this tag:
<foreach name=x list="0 1 2 3"> <if name=x value=3> <break> </if> <get name=x> </foreach> TestingThis example produces the output:
0 1 2 Testing
<continue>
tag continues processing at the top of a <foreach>
construct. This skips any HTML after the <continue>
tag and before the </foreach>
. This tag can only be used inside of a <foreach>
tag. The following is an example usage of this tag:
<foreach name=x list="0 1 2 3"> <if name=x value=2> <continue> </if> <get name=x> </foreach> TestingThis example produces the output:
0 1 3 Testing
<extract>
tag permits portions of a property's value to be extracted into additional properties, based on either glob or regular expression patterns. The extract tag takes the following tag parameters: name=var
prepend=base
glob=pattern
base.1
, base.2
, ... are the substrings that matched the wildcard characters in the pattern.
match=pattern
base.0
is the substring that matched the whole pattern. base.1
, base.2
, ... are the substrings that matched the parenthesized subexpressions in pattern, if any. If the attribute all
is present, then all matches and submatches are extracted into properties. The properties base.0
, base.1
, etc., are set to the 1st matched expression, the 2nd matched expression, etc. The properties base.0.0
, base.0.1
... are set to the sub-matches of the first full match, and so forth. If any matches are found the following additional properties are set:
basematches
basesubmatches
. basematchelist
. replace=substitution
map
glob
or match
must be specified. In addition, the property base.matches
is set to a value indicating the number of matches and submatches stored. This property can be examined and compared with 0
to determine if the <extract>
tag matched at all. If there was no match, the numbered properties base.N
are not set or changed from their previous value.
Any time a boolean parameter (XXX) is allowed (nocase, not, numeric, or reverse) it is considered false if it takes any of the forms: XXX=0, XXX=no, XXX=false XXX="". If it takes the forms XXX or XXX="anything else", the value is true.
see a sample HTML page that contains some BSL markup. @see SetTemplate
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|