Velocity @ Google Summer of Code 2007

Macro Improvements

Proposal

Velocity is a template engine written in Java. A very important feature of the velocity template language (VTL) is the ability to define Velocimacros. Velocimacros enable template writers to easily re-use the code. However, the current macro implementation requires some improvements and fixes. A common use of Velocimacros would be to define them in separate files and include them with the #parse directive. The other way to include macros defined in separate files would be the Java API.However, both methods are not supported in the current implementation. Another problem with Velocimacros is the recursive calls. When a Velocimacro calls itself recursively without meeting stopping conditions, the current implementation does not work properly. One way to solve this problem is to introduce a maximum recursion depth for Velocimacros. If the Velocimacros can be overloaded with different arguments it will be very user friendly. This allows more freedom in writing Velocimacros. This is another improvement to be made. This project will mainly focus on restructuring and adding new features to the existing Velocity macro handling code, to solve the above issues. This process inevitably involves dependencies to the other aspects of Velocity as well. So the project requires a good in depth understanding of the overall Velocity structure.


Suggestions on where to work

(I added +++ signs after each item to denote how hard I think a given item is. + == easy, ++++ = very hard)

  ## Optional parameters:

  #macro myOptionalMacro($arg1, $arg2=100, $arg3="bar")
    ... do something with $arg1, $arg2, $arg3
  #end

  #myOptionalMacro("foo") ## $arg1 = "foo", $arg2 = 100, $arg3 = "bar"
  #myOptionalMacro("foo", "baz") ## $arg1 = "foo", $arg2 = "baz", $arg3 = "bar"

  ## named parameters

  #macro myNamedMacro($arg1, $arg2, $arg3)
    ... do something with $arg1, $arg2, $arg3
  #end

  #set ($foo = "bar")
  #myNamedMacro($arg2=100, $arg3="", $arg1=$foo)
    --> $arg1 is $foo, $arg2 is an integer value 100, $arg3 is an empty String