PLEAC

I found nice project that tries to create ebooks (html pages). These ebooks are copy of Perl Cookbook but using different programming languates:

http://pleac.sourceforge.net/

Apache Velocity

Velocity consists of two main parts, Template and Context. Where template holds html, xml etc. and references, directives etc. Context holds the data.

Using Strig as template:

Context ctx = new VelocityContext();
ctx.put("user", "Admin user");

StringWriter writer = new StringWriter();
/* used as the template name for log messages in case of error */
String logTag = "template name";
String templateString = "<div>$user</div>";

Velocity.evaluate(ctx, writer, logTag, templateString);
System.out.println(writer.getBuffer());

Using Velocity Template

RuntimeServices runtimeServices = RuntimeSingleton.getRuntimeServices();
Template template = new Template();
template.setRuntimeServices(runtimeServices);

StringReader reader = new StringReader("<div>$user</div>");
SimpleNode node = runtimeServices.parse(reader, "template name");
template.setData(node);
template.initDocument();

// ... create context and writer

template.merge(context, writer);

Merge method (template.merge(context, writer)) calls render method on its data (template.setData(node)), which is instance of SimpleNode.

SimpleNode then calls merge method on every child it has (SimpleNode or subclass of SimpleNode). Every part of the template (text, references, directives etc.) are represented as SimpleNode (or its subclass).

Knowing this we can for example count number of references (instances of ASTReference) in the template:

SimpleNode simpleNode = (SimpleNode) template.getData();

for (int x = 0; x < simpleNode.jjtGetNumChildren(); x++) {
    if (simpleNode.jjtGetChild(x) instanceof ASTReference) {
        ASTReference astRef = (ASTReference) simpleNode.jjtGetChild(x);
        // root reference without $, so '$user.name' becomes 'user'
        System.out.println(astRef.getRootString());
        // literal reference, so '$user.name' is '$user.name'
        System.out.println(astRef.literal());
    }
}

Loading resource from classpath

The following code loads resource (in this case spring macro).

StringBuilder springMacro = new StringBuilder();
ClasspathResourceLoader resourceLoader = new ClasspathResourceLoader();
Scanner sc = new Scanner(resourceLoader.getResourceStream(
        "org/springframework/web/servlet/view/velocity/spring.vm"));
while(sc.hasNextLine()) {
    springMacro.append(sc.nextLine());
}

System.out.println(springMacro.toString());

This is needed only when using spring macro (spring.vm), so it has requestContext reference (needed for binding - #springBind(...))

VelocityContext context = new VelocityContext();
// request is instance of HttpServletRequest and mav is instance of ModelAndView
context.put("springMacroRequestContext", new RequestContext(request, mav.getModel()));

Using Velocity Tools

With standalone velocity, you can configure tools (tools.xml) this way:

ToolManager manager = new ToolManager();
/* path to tools.xml */
manager.configure("/path/to/my/configuration.xml");
Context context = manager.createContext();
myVelocityEngine.evaluate(context, myOutputWriter, 
        "This is a $text.test", "Test template");

Links:

Developer guide:
http://velocity.apache.org/engine/devel/developer-guide.html

User guide:
http://velocity.apache.org/engine/releases/velocity-1.6.4/user-guide.html

API:
http://velocity.apache.org/engine/releases/velocity-1.6.4/apidocs/index.html