1*6626518dSAndrew VuongTitle: Apache Velocity Engine 2*6626518dSAndrew Vuong 3*6626518dSAndrew Vuong# Apache Velocity 4*6626518dSAndrew Vuong 5*6626518dSAndrew VuongWelcome to Apache Velocity Engine! Apache Velocity is a general purpose 6*6626518dSAndrew Vuongtemplate engine written in Java. For more information about Velocity, 7*6626518dSAndrew Vuongplease look at the HTML documentation on the [Velocity web site](http://velocity.apache.org/index.html). 8*6626518dSAndrew Vuong 9*6626518dSAndrew VuongHere's a description of the top level directories: 10*6626518dSAndrew Vuong 11*6626518dSAndrew Vuong velocity-engine-core/ The Velocity Engine core module 12*6626518dSAndrew Vuong velocity-engine-examples/ Several simple examples 13*6626518dSAndrew Vuong velocity-engine-scripting/ JSR-223 implementation for Velocity scripting 14*6626518dSAndrew Vuong spring-velocity-support Velocity Engine factory bean for Spring framework 15*6626518dSAndrew Vuong src/ Source for parent modules, mainly changelog 16*6626518dSAndrew Vuong 17*6626518dSAndrew Vuong## REQUIREMENTS 18*6626518dSAndrew Vuong 19*6626518dSAndrew VuongApache Velocity 2.2 will run with any Java runtime engine v1.8 or greater. 20*6626518dSAndrew Vuong 21*6626518dSAndrew VuongBuilding from source requires Java development kit v1.8 or greater and Maven 3 (3.0.5+). 22*6626518dSAndrew Vuong 23*6626518dSAndrew VuongAt compile time, Maven should fetch all engine needed dependencies, which are: 24*6626518dSAndrew Vuong 25*6626518dSAndrew Vuong* commons-lang v3.9 26*6626518dSAndrew Vuong* slf4j-api v1.7.30 27*6626518dSAndrew Vuong 28*6626518dSAndrew Vuongplus the following ones, needed for the integrated tests: 29*6626518dSAndrew Vuong 30*6626518dSAndrew Vuong* slf4j-simple v1.7.30 31*6626518dSAndrew Vuong* junit v4.13 32*6626518dSAndrew Vuong* hsqldb v2.5.0 33*6626518dSAndrew Vuong* commons-io 2.8.0 34*6626518dSAndrew Vuong 35*6626518dSAndrew VuongAt runtime, Velocity only needs: 36*6626518dSAndrew Vuong 37*6626518dSAndrew Vuong* commons-lang v3.9+ 38*6626518dSAndrew Vuong* slf4j-api and an slf4j binding, v1.7.30+ 39*6626518dSAndrew Vuong 40*6626518dSAndrew Vuong## BUILDING APACHE VELOCITY 41*6626518dSAndrew Vuong 42*6626518dSAndrew VuongIn order to use the latest version of Apache Velocity, you may want to 43*6626518dSAndrew Vuongbuild it. 44*6626518dSAndrew Vuong 45*6626518dSAndrew VuongBuilding is easy. All components necessary to build are included or 46*6626518dSAndrew Vuongget downloaded from the internet during the build, except for the Java 47*6626518dSAndrew Vuong SDK and the Maven build tool. You can find details online on [how to build 48*6626518dSAndrew VuongVelocity](http://velocity.apache.org/engine/devel/build.html). 49*6626518dSAndrew Vuong 50*6626518dSAndrew Vuong*IMPORTANT* As the Apache Velocity build process wants to download a 51*6626518dSAndrew Vuongnumber of jars from the internet, you must be online when you are 52*6626518dSAndrew Vuongbuilding for the first time. 53*6626518dSAndrew Vuong 54*6626518dSAndrew VuongTo build Velocity's jar, just run maven using the command: 55*6626518dSAndrew Vuong 56*6626518dSAndrew Vuong mvn 57*6626518dSAndrew Vuong 58*6626518dSAndrew VuongThis will create a target/ directory containing the Velocity .jar 59*6626518dSAndrew Vuongfile in each sub-module directory. 60*6626518dSAndrew Vuong 61*6626518dSAndrew VuongBe sure to update your classpath to include Velocity's .jar 62*6626518dSAndrew Vuongfile, or when using a modern servlet container, put it in the 63*6626518dSAndrew VuongWEB-INF/lib directory. 64*6626518dSAndrew Vuong 65*6626518dSAndrew Vuong## CUSTOMIZING THE PARSER 66*6626518dSAndrew Vuong 67*6626518dSAndrew VuongSince 2.2, it's possible to [build a custom parser](http://velocity.apache.org/engine/2.2/developer-guide.html#customizing-the-vtl-parser), to change some of the characters used by in the VTL syntax: `*`, `@`, `$` and `#`. 68*6626518dSAndrew Vuong 69*6626518dSAndrew VuongLet's say you want to merge some templatized jQuery code full of `$` characters, you can for instance build you own parser which will use the `§` character as references prefix instead of `$`. 70*6626518dSAndrew Vuong 71*6626518dSAndrew Vuong## TRYING THE EXAMPLES 72*6626518dSAndrew Vuong 73*6626518dSAndrew VuongAfter building Velocity, you can also build the examples that are 74*6626518dSAndrew Vuongincluded with the Velocity distribution. These examples show how to 75*6626518dSAndrew Vuonguse Velocity in your Java applications. 76*6626518dSAndrew Vuong 77*6626518dSAndrew VuongFor more information, please see the [examples README](velocity-engine-examples) in the `velocity-engine-examples` directory. 78*6626518dSAndrew Vuong 79*6626518dSAndrew Vuong___ 80*6626518dSAndrew Vuong 81*6626518dSAndrew Vuong- The Apache Velocity Team 82*6626518dSAndrew Vuong 83