Table of Contents
Directives are script elements in the Velocity Template Language that can be used to manipulate the output generated by the Velocity engine. Brief summaries of the standard VTL directives are included below. For a more detailed description, refer to the Velocity User Guide on the Apache website.
In addition to the directives provided by the Velocity engine itself, the Templates plugin includes several new directives specifically designed for use within the jEdit environment. These are also described in the sections below.
One of the most basic VTL directives is the #set
directive. It is used to assign a value to either a variable
reference or a property reference.
For example, the following are all valid #set statements:
Example 4.1. #set Directive example
#set ( $country = "Canada" ) ## string literal #set ( $anumber = 1234 ) ## number literal #set ( $myHome.country = $country ) ## variable reference #set ( $myHome.province = $country.ontario ) ## property reference #set ( $country.leader = $worldleaders.lookup($country) ) ## method reference #set ( $codes = ["us", $country.code, "uk", "de"] ) ## arraylist
Velocity allows for the optional inclusion of text through the use of the
conditional #if directive. The statement is considered
true if it is passed:
a boolean variable whose value is true
an expression which evaluates to true
an object which is not null
The following code illustrates these three cases:
Example 4.2. #if Directive example
#set ( $test = "true" ) ## boolean variable
#if ( $test )
This text is processed.
#end
#if ( $iq < $shoesize ) ## boolean expression
Dumb as a post.
#end
#set ( $testStr = "cat")
#if ( $testStr ) ## non-null object
Your pet is a $testStr.
#end
In addition, Velocty supports the logical AND (&&), OR (||) and NOT (!) operators, as well as standard relational operators such as equivalence (==), greater than (>) and less than (<). Refer to the Velocity User's Guide for more information.
The #foreach directive provides a way to loop over a
template segment once for each object in a list of objects. For example,
the following template code:
Example 4.3. #foreach Directive example
#set ( $numberList = ["one","two","three"] ) #foreach ( $number in $numberList ) ... and a $number #end
... would yield the following output when processed:
... and a one ... and a two ... and a three
The #include element can be used to import a local
file at the location where the #include directive is
encountered. The contents of the file are not parsed by the template engine.
For example:
Example 4.4. #include Directive example
## Importing a single static text file #include ( "static_text_file.txt" ); ## Importing several files #include ( "file1.txt","file2.txt","file3.txt" ); ## Referencing a file using a variable #include ( $my_filename );
The #parse directive is similar to the
#include directive, but rather than importing a
static text file, the imported file is also parsed by the template engine.
The #stop directive will halt template processing by
the template engine. This is useful for debugging during template design.
The #macro directive provides an easy method of
defining repeated segments in a template. Here's a simple example:
If we use our newly defined macro in a template like this:
#testmacro ( ) #testmacro ( ) #testmacro ( )
... we would end up with output like this:
This is a test. This is a test. This is a test.
Velocimacros can be much more complex. Consider this example macro:
Example 4.6. A more complex #macro example
#macro ( tablerows $myList )
#foreach( $listItem in $myList )
<tr><td>$listItem</td></tr>
#end
#end
This macro could then be used to set up a simple HTML table. Here's the template which makes use of the macro:
#set ( $colours = ["red","green","blue"] ) <table> #tablerows ( $colours ) </table>
... which would result in output like this:
<table>
<tr><td>red</td></tr>
<tr><td>green</td></tr>
<tr><td>blue</td></tr>
</table>