Apache Velocity Engine Documentation

Apache Velocity is a general-purpose template engine written in Java. The repository is organized into several functional modules:

• velocity-engine-core/: The core engine module.
• velocity-engine-examples/: Simple usage examples for Java applications.
• velocity-engine-scripting/: A JSR-223 implementation for using Velocity as a scripting language.
• spring-velocity-support: A Velocity Engine factory bean designed for modern Spring (6.x/7.x) running on Java 17.
• spring5-velocity-support: A Velocity Engine factory bean for legacy Spring 5.x running on Java 8.

You can build a custom parser to change the characters used by the Velocity Template Language (VTL) syntax. This is useful when your templates contain characters that conflict with default VTL delimiters like *, @, $ or # (for example, when embedding jQuery code that uses $).

For detailed implementation instructions, refer to the Velocity Developer Guide.

Use the spring-velocity-support module to integrate Apache Velocity into modern Spring applications. This module is Jakarta-based and requires Java 17+. It is compatible with both Spring 6.x and Spring 7.x because it relies on stable spring-core, spring-beans, and spring-context APIs.

If you are working on a legacy project using Spring 5.x on Java 8, do not use this module; instead, use the spring5-velocity-support module.

<bean id="velocityEngine"
    class="org.apache.velocity.spring.VelocityEngineFactoryBean">
    <property name="velocityProperties">
        <props>
            <prop key="resource.loaders">classpath</prop>
            <prop key="resource.loader.classpath.class">
                org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
            </prop>
        </props>
    </property>
</bean>

To use Apache Velocity within a Spring 5.x application (running on Java 8), configure the org.apache.velocity.spring.VelocityEngineFactoryBean as a bean in your Spring XML configuration. This allows you to define engine properties, such as resource loaders, directly within the bean definition.

Note: This module is intended for legacy Spring 5.x environments. For modern Spring (6.x/7.x) on Java 17, use the spring-velocity-support module instead.

<bean id="velocityEngine"
    class="org.apache.velocity.spring.VelocityEngineFactoryBean">
    <property name="velocityProperties">
        <props>
            <prop key="resource.loaders">classpath</prop>
            <prop key="resource.loader.classpath.class">
                org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
            </prop>
        </props>
    </property>
</bean>

After downloading or building the ${project.build.finalName}-pkg.zip package, unzip it and navigate to the ${project.build.finalName} directory.

Note for Windows users: The provided .sh shell scripts are designed for Linux or BSD. To run them on Windows, you must create batch files that construct the classpath using the JAR files in the lib/ directory and then invoke java on the target main class with the required arguments.

To set up the Velocity engine within a Spring application context, define a bean of type org.apache.velocity.spring.VelocityEngineFactoryBean. You can pass custom Velocity configuration properties via the velocityProperties property using a standard Spring <props> element.

For example, to configure the ClasspathResourceLoader, set resource.loaders to classpath and specify the loader class using resource.loader.classpath.class.

<bean id="velocityEngine"
    class="org.apache.velocity.spring.VelocityEngineFactoryBean">
    <property name="velocityProperties">
        <props>
            <prop key="resource.loaders">classpath</prop>
            <prop key="resource.loader.classpath.class">
                org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
            </prop>
        </props>
    </property>
</bean>

This is an advanced example demonstrating Velocity's event handling features. This is recommended for users who have already mastered the basics of Velocity.

./event_example.sh

This example shows how to use Velocity in a standalone program specifically utilizing the org.apache.velocity.util.Velocity utility class, which provides convenient methods for application developers.

./example2.sh

This example demonstrates how to use the Velocity Template Engine within a standalone Java program. It uses a provided template file named example.vm.

./example1.sh