FreeMarker vs. Velocity

Disclaimer: This page is OLD, and had to be reviewed. Thus no links points to it from our homepage anymore...

Velocity is a simpler, more lightweight tool. Thus, it does not address many tasks that FreeMarker does, and its template language is less powerful in general, but it is simpler.

However, we think that for most applications, working with FreeMarker is simpler than working with Velocity, since with Velocity you have to find custom tools and find various other workarounds to solve typical template authoring tasks again and again, and you end up losing much more time in the long run than you have won on the quick starting. Also, the result of solving something with tools and workarounds is most probably not as terse or efficient as the solution in the engine core. Furthermore, according to Velocity list archives, the workaround often means extensive direct usage of Java object methods in the Velocity template (this violates the idea of simple, non-programmer HTML-designer friendly templates) or the movement of presentation tasks into the controller code (this violates the MVC idea). And, after all, if you use FreeMarker only for what Velocity can do out-of-the-box, it is as simple as Velocity.

An advantage of Velocity over FreeMarker is that Velocity has wider third party support and a much larger user community. However, you might need less support for FreeMarker because instead of creating and discussing workarounds you might often be able to simply use FreeMarker standard features. And in case you have difficulties there are of course active web forums and mailing lists. Moreover, since with FreeMarker you can use Model-2 frameworks as Struts and any JSP tag libraries out-of-the-box, perhaps third-party support is not a that big problem if you are in the servlet segment. Also, more and more servlet frameworks adapt FreeMarker as their view layer, next to JSP and Velocity.

There are other parameters that should be considered when you compare tools, like code quality and documentation quality. But of course, we as the authors of the product should not say anything about this. It is up to the users to judge.

Feature comparison sheet

Here's a quick, non-comprehensive listing of things you can do with FreeMarker out of the box, and which you can not do with Velocity (or, you can but only with nontrivial workarounds). This list is originally based on a comparison with Velocity 1.2. Contact us for change suggestions.

Number and date support

• You can perform arithmetic calculations and comparisons on arbitrary number types, including the arbitrary-precision types, not just integers.
• You can compare and display (format) date/time values.

Internationalization:

• You can format numbers locale-sensitively, based on a variety of built-in and custom number-formatting patterns.
• You can format dates locale- and timezone-sensitively, based on variety of built-in and custom date-formatting patterns.
• Identifiers (variable names) can contain non-English letters like accented letters, Arabic letters, Chinese letters, etc.

Loop handling:

• You can break out of loops.
• You can access control variables of outer loops from bodies of inner loops.
• You can test whether you are in the last iteration of the loop.

Array handling on the template language level:

• You can access array elements, both primitive and non-primitive by index using the familiar [i] syntax.
• You can query the length of an array.

Macros:

• Macro invocations can pass parameters either by position or by name.
• Macro parameters can have default values which are effective when the parameter is omitted on invocation.
• Macro invocations can have a nested body (<@myMacro>body</@myMacro>) that can be called by the macro for processing.
• Macros are plain variables, so you can select the macro to execute based on an expression, or pass a macro to another macro as parameter.
• Invoke a macro that is defined later in the template.
• Local variables in macros, and recursive invocation of macros. In Velocity it is now possible with the currently (Feb. 2005) not officially documented #local function.

Name-spaces:

• You can use multiple name-spaces for variables. This is invaluable when you build "macro libraries", because you can prevent name collisions with application specific variables or with variables of other macro libraries.

Java-independent string, list, and map manipulations with built-in functions/operators:

• You can turn a string upper-, lower-, or title-case, turn upper-/lowercase only the first letter, convert (escape) the string to HTML, XML, or RTF, extract substrings, split strings, query string length, find/replace substring, ...etc.
• Access elements of lists by index, extract sublists, concatenate lists, query size of a lists, sort lists.
• Access map elements by variable key, check if the map is empty, obtain the key or value list.

Expose typos and other mistakes in template:

• When you try to access an undefined variable, FreeMarker will not accept that silently. You can configure FreeMarker to stop template rendering with an error message, or skip the wrong part. In either case, FreeMarker will log the problem, so it does not remain hidden.
• FreeMarker will throw an exception if you mistype a directive name, and will not print the statement silently to the output (unless you use the now deprecated non-strict syntax).

Advanced rendering control:

• You can enclose a block of template in a set of tags that will cause it to apply HTML escaping or XML escaping (or any other transformation you can express as a FreeMarker expression for that matter) on all interpolations (${foo}) in the block.
• FreeMarker has transforms, which are blocks of template that when rendered, go through a transforming filter. Built-in transforms include whitespace compressor, HTML and XML escaper. Best of all, you can implement your own transformers as well (i.e. if you generate Java source code, you can write a Java code pretty-printer transform and insert it into the template). Naturally, transforms can be nested.
• You can explicitly flush the output writer with a built-in flush-directive.
• You can stop the rendering with a built-in stop-directive.

Literals:

• Beside the usual string, number, and boolean literals you can define list and map literals as well inside templates.
• There is a support for all Java string literal escapes: \b, \t, \n, \f, \r, \", \', \\, also we support \xXXXX to specify characters with their UNICODE code.

Advanced white-space removal:

• FreeMarker consistently removes white-space (spaces, tabs and line-break) from lines that contain non-outputting FreeMarker tags only, thus eliminates most annoying, obviously superfluous white-space.
• There are directives to explicitly trim lines from needless white-space, just for the extreme cases, when white-space is a real problem.

Integration with other technologies:

• You can use JSP custom tag libraries in templates.
• You can work directly on Python objects.

Powerful XML transformation capabilities:

• As of version 2.3, FreeMarker has powerful new XML transformation capabilities that make it a viable replacement for XSLT. Though there have been some attempts to make Velocity more capable in this domain (i.e. DVSL) Velocity is not really competitive in this regard. In our view, it never will be unless certain improvements to the core engine are made, such as support for macro libraries mapped to namespaces, and local variables in macros.
• See here for a more detailed comparison of FreeMarker and XSLT.

Advanced template metaprogramming:

• You can capture the output of an arbitrary part of the template into a context variable.
• You can interpret arbitrary context variable as if it were a template definition.
• You can imagine what can you do when you combine the two...