15.3 WebMacro Directives

Java Servlet Programming, 2nd Edition > 15. WebMacro > 15.3 WebMacro Directives

< BACK

CONTINUE >

Directives are WebMacro statements that perform some operation, conditionally include text, or repeat a block within a template. The list of available directives is maintained in the WebMacro.properties file as the Directives property. Directives all begin with a # character. Some directives operate on a block, and such blocks can be demarcated with curly braces, { and }, or with #begin and #end keywords. The keywords aren't as convenient to type as curly braces but cause less trouble with included JavaScript.

There are seven commonly used default directives. As with context tools, you can write your own directives to supplement the defaults, although with directives it's not as common. Let's look at the seven defaults.

15.3.1 #if

#if (condition) { ... } #else { ... }

The #if directive, alone or in conjunction with the #else directive, can be used to conditionally include text. The text is included if the condition is true and not included if the condition is false. A condition is considered true if it has a non-null value other than the Boolean false. The #if condition can make use of the familiar Boolean operators &&, ||, and !, as well as parentheses to specify ordering. Objects can be compared as part of the condition using the == and != operators, which actually invoke the .equals( ) method to do the comparison. No operators exist for less-than or greater-than comparisons, because objects are not required to be comparable in this manner. The MathTool includes such comparisons for use with integers.

#if ($Customer.owesMoney() && $Customer.Name != "Jason") {   Pay up, or else! } #else {   Welcome! }

15.3.2 #set

#set $property = value

The #set directive assigns a value to the given variable or variable property. The property must be successfully located using the WebMacro reflection logic and must be publicly settable in some manner. If no such variable is in scope, a new variable is created and assigned the given value. Variables are implicitly assigned either a String or Integer type. A String type is the default unless the value can be parsed as an Integer and is not surrounded by double quotes. For convenience, Integer values can be converted to String values as necessary. Arrays can also be set using square brackets. Use a backslash to escape a dollar sign:

#set $num1 = 4 #set $num2 = 7 #set $price = "90" #set $invoice = "You owe \$$price" #set $quote = "$num1 score and $num2 years ago..." #set $all = [ $num1, $num2, $quote ]  ## array syntax

15.3.3 #foreach

#foreach $thing in $list { ... }

The #foreach directive iterates through a list, including its output block once for each element in the list. Each time through the loop the variable $thing takes on the value of the next term in the $list. The list can be an array declared from within WebMacro or a Java object that satisfies one of the following conditions (searched for via reflection in this order):

The object itself is an array.
The object itself is an Iterator.
The object itself is an Enumeration.
The object has an Iterator iterator( ) method.
The object has an Enumeration elements( ) method.

The following code prints the client's preferred locales (if any):

#set $array = $Request.Locales <UL> #foreach $item in $array {   <LI>$item } </UL>

15.3.4 #parse

 #parse file

The #parse directive includes the contents of the target file at the location of the directive and parses it as though it were part of the current template. This provides a convenient mechanism to include template code that's common between template files. The file can be specified as an absolute path or as a relative path located within the TemplatePath:

#set $title = "Page title" #parse "header.wm"  ## The $title variable is visible in header.wm

15.3.5 #include

#include url

The #include directive includes the contents of the target URL at the location of the directive but does not attempt to parse its contents. This provides an easy mechanism to include JavaScript and other things whose syntax might conflict with WebMacro. If the URL has no protocol, file: is assumed:

#include "http://webmacro.org/CREDITS"  ## Raw text include

15.3.6 #param

#param $name = value

The #param directive specifies values within the template that can be examined by the servlet calling the template. They provide a way for the template author to pass information to the backend Java programmer that may be used to determine what kind of information to put into the context:

#param $author = "Susan Kelley" #param $require = [ "user", "document", "session" ]

The servlet can retrieve the value by calling Object getParam(String) on the Template object. The method returns a String or Integer if there's one value and an Object[] containing String and/or Integer objects if the value is a list:

String author = (String) tmpl.getParam("author"); Object[] require = (Object[]) tmpl.getParam("require");

15.3.7 #use

#use 'parser' #begin   ... #end

Finally, the #use directive allows a block of template text (denoted by the #begin and #end markers) to be parsed by an alternate parser. This feature allows enhancement or even wholesale replacement of the WebMacro syntax. Generally it's not used for nearly such grandiose endeavors, however. Its two most common uses are to literally include a block of text (using the text parser) or to remove a block of text (using the null parser):

#use 'text' #begin   All text here is included raw   ## Comments too since the comment format is a parser issue #end #use 'null' #begin   Text here can be considered to be "commented out" #end

The WebMacro.properties file maintains the list of available default parsers in the Parsers property.^[3]

^[3] The pluggable parser mechanism may be replaced by targeted directives. For example, #use 'text' may be replaced by #text, and #use 'null' may be replaced by #comment.

< BACK

CONTINUE >