JeeWiz Architect's Guide


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 8. Templates and Velocity Features

8.4 #return

JeeWiz provides a 'return' feature (as the #return directive). This can be used in a template, macro or method script to

stop the processing of the script immediately
return a value, rather than the rendered output of the script.

In summary, this works very similarly to the return statement in languages like Java.

8.4.1	Syntax
8.4.2	Operation
8.4.3	Returning A Value

8.4.1 Syntax

#return can be used with 0 or 1 arguments, e.g.:

#return()
#return( true )

The parentheses are required to invoke the #return functionality.

The parameter passed to the 1-parameter version of #return can be any legal Velocity expression. Note that, currently, a macro invocation (e.g. #mymacro(arg)) is not a legal Velocity expression. This restriction is simply the result of the Velocity syntax. In other words, you cannot write return statements like

#return( #mymacro( "a" "b" ) )

Examples of legal Velocity expressions are

true
false
$object
$object.methodThatReturnsAnObject()
1
2 > 1
2 > $logLevel
(2 > $logLevel)

8.4.2 Operation

Both the 0- and 1-argument version of #return directive stop processing of the current script immediately (after evaluation of the argument in the 1-argument case). This aspect of the #return feature can be useful for avoiding multiple nested #if's that reach to the end of the script. So instead of:

#if( $condition1 )
    ...
#else
    #if( $condition2 )
        ...
    #end
#end

you can write

#if( $condition1 )
    ...
    #return()
#end
#if( $condition2 )
    ...
    #return()
#end

This of course becomes more useful the more conditional cases there are.

8.4.3 Returning A Value

The #return directive is used in a script - a template, method or macro. The default operation of a script is to output text, and this is still what happens if #return() without an argument is used. When #return is used with an argument:

any existing output from the script is discarded
the argument is evaluated as an expression in the context of the script
the expression is returned, without at this point converting it to the string representation.

Of course, if the invocation of the script was not in an expression (which must be the case for a #macro or a template/pattern included via #parse) then the normal action of converting the expression to its string representation is performed. When the invocation of the script is part of a Velocity expression - which is only possible if the script is a JeeWiz method - then the returned value is substituted for the invoking expression.

This means it is possible to return 'true', 'false', numbers, expressions and objects from a method. For example, the method

#method( giveMeATrue )
    #return( true )  ## e.g. #return( $n > 1 ) is also possible
#end

can be used in an expression:

#if( $nc.giveMeATrue() )
    ...
#end