Velocity: using the #macro command

At some point in developing with Velocity, you may be tempted to use the #macro command. This command is the feature closest resembling a function or method in a programming languages. A macro may use local and global variables but it doesn't have a local context. A macro definition, once cached, can be called from any other Velocity file in your application. A velocity macro doesn't return a value. It was designed to only write values directly to the output string, usually the screen.

When should I use a macro?

To avoid code repetition or make your code more readable, it is often useful to define a macro. However, most of the time this can also be achieved with a #define or #parse command. The macro command is different in that it available globally and may use local variables. Also, the #macro command is more concise. Note: to be honest, a #parse command is also available globally.

Return values with a macro

But you just said macros do not return values! Yes, I did however macros can create or manipulate existing global variables. So these global variables can be used to "return" a result, although it is not technically a return value. Here's an example.

#macro(addNumbers $a, $b)
 #set($result = $a + $b)
#end

Note that all variables in a macro are global except those defined in the macro definition as its parameters. So $a and $b are local and $result is global. So if this macro is calles #addNumbers(1,2), the value of $result will be 3.

Local variables, global context

It is important to understand that the macro is only local with respect to it's parameter variables. Any other variable is a global variable and will either already have a value or get one.

Macro library and library cache

There are two ways a macro can be defined, in the velocity macro file or in any other velocity file. The velocity macro file is a specific file called macros.vm. It should be found in the root directory of your application. The macros defined in this file are read into the macro library cache when you application is first started.

Macros may also defined in files other than the macros.vm file. However, these macros are not automatically read. They will only become available when the file or files in which they are defined are executed. Once this is done, the macro will be part of the macro library cache just like the macros in a macros.vm file.

Once in this library, the macros cannot be changed anymore. Only a restart of the Velocity interpreter will flush the macro library. This happens automatically when you alter files in the application's resource files. However there are situations where you need to refresh the macro library manually. For example if you do not develop using the resource files or you have just uploaded a new file containing macros using ftp. Just go to the Application Panel and click on the 'Refresh macros' option 

Off course, developing a macro and having to click 'refresh macros' all the time may be a bit time-consuming. You can solve this easily by moving the "body" code of the macro into a separate file and use #parse inside your macro to execute it. Since only the parse command is cached, changes in the file WILL be picked up! When finished you can replace the parse with the final code.