User Guide

Installation

Download velocity2js

Download the velocity2js jar file from sourceforge.net.

Install velocity2js

Just extract the downloaded zip archive.

Usage

Use from command line

java -jar Velocity2Js.jar -d <template-dir> <output-dir> [<resource-file>]
<template-dir> = directory where template are located (sub-dirs will be processed too)
<output-dir> = directory where the generated js file (vel2js.js) will saved
[<resource-file>] = optional name of resource bundle, used for internationalization (eg: ../template/mybundle)
or
java -jar Velocity2Js.jar -f <base-dir> <input-file> <output-file> [<resource-file>]

Ant Task

Add following lines to your ant file: 

<taskdef name="vel2js" classname="at.riemers.velocity2js.velocity.Velocity2JsTask" 
         classpath="<velocity2js-dir>/Velocity2Js.jar;
                    <velocity2js-dir>/velocity-1.5.jar; 
	            <velocity2js-dir>/lib/commons-collections-3.1.jar; 
	            <velocity2js-dir>/lib/commons-lang-2.1.jar; 
                    <velocity2js-dir>/lib/commons-logging.jar; 
                    <velocity2js-dir>/lib/commons-logging.jar; 
	            <velocity2js-dir>/velocity-1.5/lib/log4j-1.2.12.jar;"/>
    

<vel2js templateDir="<template-source-dir>" 
           javascriptDir="<javascript-output-dir>" 
           [javascriptName="<javascript-file>"] 
           [resource="<resource-file>"] >        
		   
        <fileset dir="<template-source-dir>" casesensitive="yes">
            <include name="**/*.vm"/>    
        </fileset>              
</vel2js>

This ant task will compile all templates specified by the fileset and create one or more JavaScript file called 

vel2js_<locale>.js

 in the 

<javascript-output-dir>
.

<template-dir> = directory where templates are located

It is used for function naming convention.
eg: Templates are located in "/templates";
<template-dir>="."
All JS functions will be prefixed with "templates".

If <template-dir>="templates", the JS functions are not prefixed.

<javascript-output-dir> = directory where the generated js files (vel2js_<locale>.js) will be saved

<javascript-file> = File name of the output JavaScript files. <javascript-file>_<locale>.js

Fileset

Use ant's fileset to specify which templates should be compiled. More information about filesets at http://ant.apache.org/manual/CoreTypes/fileset.html.

[<resource-file>] = optional name of resource bundle, used for internationalization

To use velocity2js's internationalization support, you must specify a resource bundle.
eg: ../template/mybundle, means the resource bundle "mybundle" is located in directory "../templates".
The bundle consists of one or more files named mybundle_*.properties
eg: mybundle_en.properties, mybundle_de.properties,...

Writing Template

Please have a look at Apache Velocity - User Guide

Following Directives are implemented yet:

Not implemented:


If you notice any incompatibility with Apache Velocity, please post a comment in the velocity2js Forum

Internationalization (I18N)

To use velocity2js's internationalization support, you must specify a resource bundle. A resource bundle consists of one or more Properties files. For each language one Properties file is needed. The files have to be named <bundle-name>_<language-code>.properties. Velocity2js will generate one JavaScript file per language.

The structuce of the Properties file is quite simple.
<property-name>=<property-value>

eg:
mybundle_en.properties
firstname=Firstname
lastname=Lastname
catalog.header=CATALOG

mybundle_de.properties
firstname=Vorname
lastname=Nachname
catalog.header=KATALOG

Use I18N in Velocity Templates

If you have defined and specifyed your resource bundle, you can make use of it as showed below:
$I18N.<property-name>
eg: $I18N.firstname

Using the generated JavaScript functions

Include the JavaScript files vel2jstools.js and the generated vel2js.js in your web site. 

<script type="text/javascript" src="vel2jstools.js" ></script>
<script type="text/javascript" src="vel2js.js" ></script>

Call JavaScript function: 

var context = { world: { name : 'WORLD' }, 
			greetings: [ { language : 'English', text: 'Hi' },
						 { language : 'German', text: 'Hallo' },
						 { language : 'Swedish', text: 'Hey' },
						 { language : 'Spanish', text: 'Ola' }
						] }
 // typically the context will be received via JSON						
var html = v2js_helloworld(context);
yourDiv.innerHTML = html;