Velocity or FreeMarker?

Two open source Java-based template engines compared

Page 2 of 3

What can I do with a template engine?

Many applications that create output do so based on a certain template, though it might be known under another name, such as "report design" or "master page." Because a generic template engine is capable of creating any type of text document, the range of usage scenarios is wide. Template engines are most popularly used for creating HTML, in some variant or another, as the view in an MVC architecture.

Creating a document always involves merging data and a template. The template is static, the data is dynamic. After processing the data and the template the template engine produces an output document. Based on the instructions in the template all or some of the data provided will be part of the output. Usually, you will provide the data to the template engine in the form of a collection or container, such as a HashMap. Most template engines provide special classes for this, commonly named context or model. FreeMarker provides a SimpleHash class (among others), Velocity offers a VelocityContext class for feeding data to the template engine.

Types of output

Creating other types of text documents besides HTML is easy, but you must take care with some of these formats. For instance, it can be tricky to create RTF documents in Velocity because the ${} notation has special meanings in RTF docs and Velocity, respectively. Subsequently, you have to escape the processing instructions recognized by the document format in the right way in order to avoid nasty surprises in the final document. Generally speaking, RTF is a hard format to use. The only editors that seem to completely understand this format are full-blown word processors like Microsoft Word.

Other file formats, such as ODF, are easier to deal with. Any file format consisting of plain text is easily generated using a template engine. As a general rule you might say that the closer a format is to plain text, the easier it is to create it with a template engine. XML is one example of a format that is very basic, with no real formatting or embedded processing instructions. As such it is an ideal candidate to generate with a template engine.

Basic operations

Now that you have an idea of what you can do with a template engine, let's take a look at some of the basic operations involved. A Velocity template for generating the mandatory "Hello World!" output might look like this:

Hello, ${engineName} world!

If you supply Velocity with the value for the engineName token, Velocity will replace the token in the template with that value and write the result of the merge to the output.

A template engine can do much more than straightforward token replacement, however. Looping, for instance:

#foreach($engineName in $engineNames) 
  Hello, ${engineName} world!

This code will produce a document that contains a line for every engineName that is present in the engineNames collection.

You can also do conditional processing with template engines:

#if ($engineName = "Velocity")
  Hello, $engineName world!
  Hello, other world! 

This code will produce output only if the engineName is Velocity.

Including other content in a template is also a basic operation, as shown here:

Hello $engineName world!

Next we'll take a closer look at two of the most popular template engines.

| 1 2 3 Page 2