1 Apache Velocity Overview Dinagar Raghunathan by .

1

Apache Velocity Overview

Dinagar Raghunathan

by

http://www.rdinagar.com

2http://www.rdinagar.com

Agenda

• Introduction

• Architecture

• Velocity Template Language (VTL)

• References

• Directives

• Macros

• Accessing VM in JavaScript & JavaScript in VM

• how to use Velocity inside Java programs

• Sample Code

• Customized Directives

• Event Handler - Escape entities

• References


Introduction - Velocity

• Velocity is an open source templating tool developed by an international volunteer community and hosted by the Apache Software Foundation's Jakarta Project .

• Velocity is a fast and easy-to-use Java-based templating engine.

• Used in a broad range of applications, including code generation, email templating, and web applications.

• The designers can focus exclusively on the data presentation (the view), and the application programmer can focus on the application control.

• Web Macro is an open source templating system enables programmers and designers to work together while promoting the ModelViewController pattern and served as the inspiration for Apache's Velocity.


Uses of Velocity

• Web applications

Web designers can create HTML pages

• Source code generation

Velocity can be used to generate Java source code, SQL, C++.

• Automatic emails

Many applications generate automatic emails for account signup, password reminders. These mails can be created using velocity


Architecture

MVC Architecture

Model

View

Controller


Templates and Transformations

• Data Model

Contains data that has to be transformed.

• Template

Formats the data model into the output code

• Template Engine

The application that performs the transformation. It has the input data model and the template, and produces output by replacing the template internal references with real data coming from the model.

• Target The result of the transformation process.


Velocity Template Language (VTL)

• VTL is a template language using which templates are created.

• VTL has two parts

References.

Directives.

• References

Objects in the Velocity context are accessed using references from within a template. References begin with a dollar sign.


References

• There are three types of references in the VTL.• Variable.

• Property

• Methods.

• Variable

The shorthand notation of a variable consists of a leading "$" character followed by a VTL Identifier.

• Property

The shorthand notation consists of a leading $ character followed a VTL Identifier, followed by a dot character (".") and another VTL Identifier. E.g.

$customer.Address


Contd..

• Method. A method is defined in the Java code and is capable of doing something useful, like

running a calculation or arriving at a decision.e.g.

$customer.getAddress().

• Directives They are a set statements used for control and actions. The Directives in VTL are

#set() #if() #else #elseif() #end #foreach() #include() #parse() #macro()


Directives

Directive Syntax Purpose

#foreach

#foreach ($item in $collection) item is $item

#end

Iterates over a collection, array, or map.

#if/#else/ #elseif

#if ($order.total == 0) No charge#end

Conditional. Null can be checked for using #if ($obj) obj not null #end syntax.

#parse #parse("header.vm")Loads, parses, and incorporates the specified template into the generated

output.

#macro

#macro(currency $amount)${

formatter.currency($amount)

}#end

Defines a new directive and any required parameters. The result is interpreted when used later in the template. The example macro would be used as #currency($item.cost).

#include #include("disclaimer.txt") Includes the specified file, as is, into the generated output.

#set#set ($customer =

$order.customer)Assigns a value to a context object. If the context object does not exist, it is

added; otherwise, it is replaced.

#stop#if ($debug) #stop#end

Stops template processing. This is usually used for debugging purposes.


Macros

Velocity macro example

#macro( square $no )

#set($sqr =$no *$no) The square of the number is $sqr

#end

To Invoke.

#square(10)

Output:The square of the number is 100


JS in VM and VM variables to JS

• VM variables can be assigned to JavaScript Variable.• Var age = $employee.age;

• VM object reference can’t be assigned to JavaScript Variable.

• JavaScript variables cant be assigned to VM files.


How to use Velocity inside Java programs

• VelocityEngine • This class provides a separate new-able instance of the Velocity template engine.

The alternative model for use is using the Velocity class which employs the singleton model.

• Please ensure that you call one of the init() variants. This is critical for proper behavior.

• VelocityContext• General purpose implementation of the application Context interface for general

application use. This class should be used in place of the original Context class. This implementation uses a HashMap (@see java.util.HashMap ) for data storage.

• Template• This class is used for controlling all template operations. Merge operation merges

the information in the Context to the Writer object

Velocity Writer Java VM file

Output file


Sample Code - Advertisement

public static void main(String args[]) throws Exception {VelocityEngine ve=new

VelocityEngine();ve.init();

ArrayList list=new ArrayList();

Map mp=new HashMap();mp.put("name",“Perfume");mp.put("price","Rs 100");list.add(mp);

mp=new HashMap();mp.put("name",“Biscuit");mp.put("price","Rs 10");list.add(mp);

// Setting up Velocity Context VelocityContext vc=new

VelocityContext();vc.put(“prodList",list);

Template t=ve.getTemplate("Products.vm");

StringWriter sw=new StringWriter();

t.merge(vc,sw);System.out.println(sw.toString());

}MyVelocityWriter.java


Template - Advertisement

There are $prodList.size() Products for Sale!

We are proud to offer these products

at these amazing prices. This month only,

choose from:

#foreach($prod in $prodList)

$prod.name for only $prod.price

#end

Call Immediately!

sampleVelocityFile.vm


Output

There are 2 Products for Sale!

We are proud to offer these products

at these amazing prices. This month only,

choose from:

Perfume for only Rs 100

Biscuit for only Rs 10

Call Immediately!

sampleVelocity.html


Example - Mail Template

$Date

Dear $Contact.FirstName $Contact.LastName,

Thank you for your recent purchase of $Order.ProductName. The cost of the item was $Order.TotalCost #if($Order.Tax > 0) including a tax of $Order.TaxRate%#end.

Sincerely,Biggest and Best Book Merchants, Inc.

November 17, 2004

Dear Jennifer Glass,

Thank you for your recent purchase of Alice in Wonderland, Annotated Edition. The cost of the item was $29.95.

Sincerely,Biggest and Best Book Merchants, Inc.

Order

Contact

Date


Controlling Velocity Template Generation with a Custom Directive

• Consider – can the problem you are trying to solve be done more simply with a Tool or VelocityMacro?

• If not, Velocity allows you to code your own custom directives by doing the following:• Create a class that extends

org.apache.velocity.runtime.directive.Directive

• Add the following to velocity.propertiesuserdirective = yourdirectiveclass

• Review the directives in the velocity source code for good examples. For example, review org.apache.velocity.runtime.directive.ForEach


Custom Directive Example: Generate Endnotes

#endNotesAll in the golden afternoon (*1:In these prefatory verses Carroll recalls that "golden afternoon" in 1862 when he and his friend the Reverend Robinson Duckworth (then a fellow of Trinity College, Oxford, later canon of Westminster) took the three charming Liddell sisters on a rowing expedition up the Thames. *) Full leisurely we glide;For both our oars, with little skill, By little arms are plied,While little hands make vain pretence Our wanderings to guide.(* 2:Note how this stanza puns three times with the word "little." "Liddle" was pronounced to rhyme with "fiddle." *)#end

Usage:

All in the golden afternoon Full leisurely we glide;For both our oars, with little skill, By little arms are plied,While little hands make vain pretence Our wanderings to guide.

NOTES1: In these prefatory verses Carroll recalls that "golden afternoon" in 1862 when he and his friend the Reverend Robinson Duckworth (then a fellow of Trinity College, Oxford, later canon of Westminster) took the three charming Liddell sisters on a rowing expedition up the Thames.

2:Note how this stanza puns three times with the word "little." "Liddle" was pronounced to rhyme with "fiddle."

Results:


Custom Directive Example: Code Excerpt – Main Class

public class MyVelocityWriterDirective {

public static void main(String argv[]) throws Exception {

VelocityEngine velocityEngine = new VelocityEngine();

// load properties from classpath

Properties properties = new Properties();

InputStream inputStream = MyVelocityWriterDirective.class.getResourceAsStream("velocity.properties");

properties.load(inputStream);

inputStream.close();

velocityEngine.init(properties);

// configure the context

Context context = new VelocityContext();

// process the template

Template template = velocityEngine.getTemplate("input1.vm");

FileWriter writer = new FileWriter("output.txt");

template.merge(context, writer);

writer.close();

}

}MyVelocityWriterDirective.java


Custom Directive Example: Code Excerpt – Directive Class

public class EndNoteDirective extends Directive {

public String getName() { return "endNotes"; }

public int getType() { return BLOCK; }

public boolean render(InternalContextAdapter context, java.io.Writer writer,Node node)

throws ResourceNotFoundException,ParseErrorException,MethodInvocationException

{

// first, parse the entire block and retrieve the content

StringWriter internalwriter = new StringWriter();

// the node's children are the arguments and the body.

// here there should be only one child, since there are no arguments

node.jjtGetChild(0).render(context, internalwriter);

String sourcecontent = internalwriter.toString();

internalwriter.close();

// missing code creates new "finalcontent" based on "sourcecontent"

writer.write(finalcontent.toString());

return true;

}

}

EndNoteDirective.java


Custom Directive Example: Configuration

velocity.properties Input1.vm

## Load templates from classpath

resource.loader = class

class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader

## Specify the user directive

userdirective=com.jlamp.directive.EndNoteDirective

• Demo

Output.txt


Adding an Event Handler

• Velocity provides a mechanism to intercept and modify parsing operation.

• Currently, three event handlers available:• ReferenceInsertionEventHandler: Modify the text that gets inserted

from a reference (e.g. $date)• NullSetEventHandler: Prevents logging of null #set operations• MethodExceptionEventHandler: Intercept a method thrown by a tool

in the context.

• Event handlers are instantiated for each page that is parsed, and are "attached" to the context before the template is merged:EventCartridge ec = new EventCartridge(); ec.addEventHandler(new CustomReferenceInsertionHandler());ec.attachToContext( context );

// now merge the template


Event Handler Example: Escape XML Entities (excerpt)

MyVelocityWriterEvent.java CustomReferenceInsertionHandler.java

/**

* Escape all XML Entities in the reference insertion. Specifically, the following

* conversions are performed:

* <DL>

* <DT>&</DT><DD>&</DD>

* <DT><</DT><DD><</DD>

* <DT>></DT><DD>></DD>

* <DT>"</DT><DD>"</DD>

* </DL>

*/

public class EscapeXMLEntities implements ReferenceInsertionEventHandler {

/**

* Escape the XML entities for all inserted references.

*/

public Object referenceInsert(String reference, Object value) {

String val = value.toString();

return escapeText(val);

}

}

• DemosampleVelocity.html


References

• http://jakarta.apache.org/velocity/

• http://wiki.apache.org/jakarta-velocity/HackingVelocity


Thank You

1 Apache Velocity Overview Dinagar Raghunathan by .

Documents

Transcript of 1 Apache Velocity Overview Dinagar Raghunathan by .