Introduction

Apache Velocity is a well-known template engine in the Java world. It can be used to produce text output from a program by writing templates containing variables and then bind values to these variables to produce concrete output. Velocity has its quirks, but is generally quite usable and fast.

Of course you can use Velocity directly from Scala without a wrapper library. But there are a few things that are improved by using a small wrapper library, especially for the case where the templates are small.

Features

Shorter syntax for Context creation

Rendering of a Velocity template requires that you create a Context object, which basically behaves like a map from template variable name to the value of that variable. The Scala Velocity Wrapper adds a conversion from a Scala Map to a Velocity Context. Furthermore, it adds additional merge methods that take an association variable argument list like the Scala map factory method (see examples below).

Support for Scala Iterables

Velocity supports iteration in its template language (#foreach). Because Velocity does not know about the collection types of Scala, it cannot iterate over Scala collections by itself. The Scala Velocity Wrapper adds an Iterable adapter when converting from Scala maps to Velocity Context, such that iteration works for Scala collections.

Simpler construction of Templates from Strings ("Template Literals")

For short templates that do not have to be externally edited it is convenient to specify the template directly in program code. Unfortunately Velocity supports such "Template literals" only using an evaluate function that does not allow to store the compiled representation of the template. In other words, your program has no control over the lifetime of the compiled template. Creation of compiled templates from Strings is not very well supported in Velocity.

The Scala Velocity Wrapper provides a conversion from String to Template that greatly simplifies writing short Velocity templates directly within Scala code.

Unclutter the Velocity API

For simple use cases Velocity's API is too large. Often you encounter implementation artifacts that are not really helpful for getting things done. The Scala Velocity Template allows a really simple approach to Velocity and uses its own stripped down interface to the Velocity templating. No logging configuration, no event support, no resource management. Just template rendering. When you need to use the other features, you can switch to the original Velocity APIs, later.

Usage Examples

The following example shows the above features in a few lines of code and will make things clearer than all of the text above.

// 1 //
import eu.kneissl.scala.velocity.Conversions._


// 2 //
assert ("Hello ${yourname}. My name is ${myname}".merge('yourname->"Guest", 
                                                        'myname->"Martin") 
  == "Hello Guest. My name is Martin"

// 3 //
assert ("#foreach( $i in $is )$i#end".merge('is->(1 to 3)) 
  == "123")


// 4 //
val template: Template = "Hello ${yourname}. My name is ${myname}"
people foreach { person => println(template.merge('yourname->person.name, 'myname->"Martin") }

(1) Import the contents of module Conversions to get the implicit conversion from Map to Context and from String to Template.

(2) You can use the merge method on pimped Strings to have them interpreted as Velocity templates and expand them binding values in a concise syntax. If you don't like the use of Symbols as keys, you can also use Strings.

(3) This example binds a scala collection to template variable "is". The collection can be iterated by Velocity.

(4) You can store Templates as objects and use them without recompilation. This is similar to the typical usage of regular expressions. If you use them more than once, you typically create a named value for the compiled object and use it again and again.

All the examples above use the merge method that takes a variable argument list of associations and returns a String. There are overloaded merge methods that work with Map or Context and there are ones that write output to a java.io.Writer.

License

The Scala Velocity Wrapper is licensed under the Apache Software License, Version 2.0.