After more delay than I wanted, Velocimacro support is now working in
Velocity. This should be short, meant to give a brief overview. More
docs will follow. (I am sure Mr. Castura will futher add to the docs
already on the website.)
Velocimacro's are best demonstrated rather than described, at least at
this hour.
To define a Velocimacro (hereafter 'VM'), the #macro() directive was
added :
#macro( vmname arg1 arg2 )
<VM VTL code>
#end
where
1) vmname : name that will be used to call the VM, just like a directive
(#vmname)
2) arg1 arg2 : arguments to the VM. A VM can have any number of args,
but the number used at invocation must match the number specified in the
definition.
3) VM VTL code : any valid VTL code - anything you can put into a
template, you can put into a VM
and then to use, you would use it like any other VTL directive in your
template :
#vmname( arg1 arg2 )
VMs can be defined in either a 'global library', a 'local library', or
'inline' in a template. The global library and local library are
equivalent; the intention of the global library is to have a place for
useful VMs that we want to include in the Velocity distribution, whereas
the local library is for local, site-specific VMs. Inline VM
definitions are those found in regular 'user' templates.
So for a concrete example, the following is a complete template that
shows how to define a VM inline and then use it :
-- start : don't include this line (well, you can if you want to... it's
velocity!) --
## The following is a macro that takes two arguments
## a color and an array.
#macro( tablerows $color $data )
#foreach($el in $data)
<tr><td bgcolor=$color>$el</td></tr>
#end
#end
## now to use it...
#set $names = ["bob","sue","jim"]
#set $color = "blue"
<table>
#tablerows( $color $names )
</table>
-- end : don't include this line --
The output will be :
<table>
<tr><td bgcolor=blue>bob</td></tr>
<tr><td bgcolor=blue>sue</td></tr>
<tr><td bgcolor=blue>jim</td></tr>
</table>
Note : you can test this anywhere, but if you test in the test/misc
directory, you should remove the velocity.properties file. It isn't
currently correct, and interferes in an ugly way with template issues.
There is a global library defined in the default Velocity properties
called VM_global_library.vm. It is a regular template file, is found in
test/templates and when put into the template path (generally, the local
directory), will automatically add the VM 'quietnull'. quietnull is
defined as follows :
#macro( quietnull $foo)
#if($foo)$foo#end
#end
For those awake among us, this is merely a long way of doing $!foo. It
can be used as you expect
#quietnull($flargh)
and will output the value of $flargh if it has one, otherwise nothing.
It's just there as an example of how you can define a VM in the
global/local library, and just use it like a directive in any template.
More stupid VM tricks can be found in test/templates/velocimacro.vm,
part of the testbed.
The current properties that control VMs :
velocimacro.library.global : name of global VM template library. Like
any other template, must be found in the template path.
velocimacro.library.local : name of local VM template library.
velocimacro.permissions.allowInline : true/false (default true) :
determines if inline VM definitions (#macro directives) are allowed in
regular user templates
velocimacro.permissions.allowInlineToOverride : (true/false) default
false : allow inline (in-template) macro definitions to replace existing
VMs
Note : VMs *cannot* replace control directives (if, else, elseif) or PDs
(foreach, include, parse).
More docs will follow. Questions welcome and comments please...
geir
--
Geir Magnusson Jr. [EMAIL PROTECTED]
Dakota tribal wisdom: "when you discover you are riding a dead horse,
the best strategy is to dismount."
