Raible's Wiki

Raible Designs
Wiki Home
News
Recent Changes

AppFuse

Homepage
  - Korean
  - Chinese
  - Italian
  - Japanese

QuickStart Guide
  - Chinese
  - French
  - German
  - Italian
  - Korean
  - Portuguese
  - Spanish
  - Japanese

User Guide
  - Korean
  - Chinese

Tutorials
  - Chinese
  - German
  - Italian
  - Korean
  - Portuguese
  - Spanish

FAQ
  - Korean

Latest Downloads

Other Applications

Struts Resume
Security Example
Struts Menu

Set your name in
UserPreferences

Edit this page


Referenced by
AppFuseSupport
Articles
Articles_cn
Articles_de
Articles_pt
Articles_zh




JSPWiki v2.2.33

[RSS]


Hide Menu

AppFuseVelocity


Part I: Integrating Velocity into AppFuse - A HowTo for adding the Velocity Templating engine to AppFuse applications for rendering views.

About this Tutorial

This tutorial will show you how to modify the Ant build script to include Velocity into the build cycle for AppFuse.

Table of Contents

  • [1] Download the prerequisite packages
  • [2] Add the packages to AppFuse's lib structure
  • [3] Modify the build script to include the packages
  • [4] Add the ViewServlet definition
  • [5] Configure the Toolbox and Velocity Engine
  • [6] Modify an ActionForward to send to Velocity
  • [7] Build your Velocity Templates

Download the prerequistie packages [#1]

First we need to get our hands on the VelocityTools packages. These are available from the Jakarta Apache Project.

Personally I used Velocity-Tools-1.0-bin, from here.

Add the packages to AppFuse's lib structure [#2]

The main distribution comes with all sorts of other things, including sample applications, that we don't need. We will extract the precompiled JARs (or make them if you were brave and got a source distribution). The ones we're interested in are the ones that start "velocity-". All of the other dependencies are already in AppFuse.

We now need to add this to the the lib folder in your AppFuse source tree. Create a directory lib/velocity-tools-1.0.

Now add the following to lib.properties

#
# Velocity View Tools - http://jakarta.apache.org/velocity/tools/
#
velocity.version		= 1.0
velocity.dir=${lib.dir}/velocity-tools-${velocity.version}

Modify the build script to include these packages [#3]

Now that AppFuse is aware of the new libraries, we need to include them in the build process. Those of you scared of ant build scripts look away now.

We must modify the package-web target, to add the following to the lib directives for the war task:

<lib dir="${velocity.dir}">
    <include name="*.jar" />
</lib>
So the full war task definition becomes thus:

    <war
            basedir="${webapp.target}" 
            destfile="${webapp.dist}/${webapp.war}"
            webxml="${build.dir}/web/WEB-INF/web.xml"
            excludes="**/web.xml,**/hibernate.properties,**/web-test.xml,
                      **/mail.properties,**/cactus.properties"
            compress="true">
            
            <classes dir="${build.dir}/web/classes"/>
            
            <lib file="${dist.dir}/${webapp.name}-common.jar" />     
            <lib file="${dist.dir}/${webapp.name}-ejb.jar" />
            
            <webinf dir="${struts.dir}" includes="*.xml"/>
            <lib dir="${struts.dir}" includes="*.jar"/>
            <lib dir="${jstl.dir}/lib">
                <include name="jstl.jar"/>
                <include name="standard.jar"/>
            </lib>
            <lib file="${log4j.jar}"/>      
            <lib file="${strutsmenu.jar}"/>
            <lib file="${displaytag.jar}"/>
            <lib file="${hibernate.jar}"/>
            <lib dir="${hibernate.dir}/lib">
                <include name="odmg.jar" />
                <include name="dom4j.jar" />
                <include name="cglib*.jar" />
                <include name="ehcache.jar" />
                <include name="oscache*.jar" />
            </lib>
            <lib file="${statetag.jar}"/> 
            <lib file="${countrytag.jar}"/>
            <lib file="${clickstream.jar}"/>
            <lib dir="${velocity.dir}">
            	<include name="*.jar" />
            </lib>
    </war>

Add the ViewServlet definition [#4]

We know need to make webdoclet generate the appropriate entries for the VelocityViewServlet in web.xml.

Open metadata/web/servlets.xml and add the following:

    <servlet>
    	<servlet-name>velocity-view</servlet-name>
    	<servlet-class>org.apache.velocity.tools.view.servlet.VelocityViewServlet</servlet-class>
    	<init-param>
    		<param-name>org.apache.velocity.toolbox</param-name>
    		<param-value>/WEB-INF/toolbox.xml</param-value>
    	</init-param>
    	<init-param>
    		<param-name>org.apache.velocity.properties</param-name>
    		<param-value>/WEB-INF/velocity.properties</param-value>
    	</init-param>
    	<load-on-startup>10</load-on-startup>
    </servlet>

Now we must setup the mappings: Open metadata/web/servlet-mappings.xml and add:

    <servlet-mapping>
    	<servlet-name>velocity-view</servlet-name>
    	<url-pattern>*.jst</url-pattern>
    </servlet-mapping>
The pattern can be anything you like. Velocity usually uses .vm, but I used .jst for Java Server Templates.

Configure the Toolbox and VelocityEngine

With me so far? Good, the last step is easy. We need to create two files in the web/WEB-INF directory to configure Velocity. More information about configuring Velocity can be found on their site.

First is the velocity.properties:

  velocimacro.library = /WEB-INF/VM_global_library.vm
  velocimacro.permissions.allow.inline = true
  velocimacro.permissions.allow.inline.to.replace.global = false
  velocimacro.permissions.allow.inline.local.scope = false  
  velocimacro.context.localscope = false
Very simple, the only thing you may wish to change is velocimacro.library to match where you wish to put your global macros file.

Last is toolbox.xml (this configures the Struts tools):

<?xml version="1.0"?>

<toolbox> <tool> <key>link</key> <scope>request</scope> <class>org.apache.velocity.tools.struts.StrutsLinkTool</class> </tool> <tool> <key>msg</key> <scope>request</scope> <class>org.apache.velocity.tools.struts.MessageTool</class> </tool> <tool> <key>errors</key> <scope>request</scope> <class>org.apache.velocity.tools.struts.ErrorsTool</class> </tool> <tool> <key>form</key> <scope>request</scope> <class>org.apache.velocity.tools.struts.FormTool</class> </tool> </toolbox>

Modify and ActionForward to point to Velocity [#6]

Change your XDoclet @struts.action-forwards to be something like the following:
* @struts.action-forward name="edit"
   path="/path/to/template/.[vm/jst/whatever]"

The above tools will contain all the struts resources you'll need. They're embedded in the context as $key, for example $link, $errors, $form and so on.

Build your Velocity Templates [#7]

See the User Guide for Velocity for help with VTL.

This tutorial was written by Cameron Gray - thanks Cameron!



Go to top   Edit this page   More info...   Attach file...
This page last changed on 06-Nov-2006 13:52:58 MST by MattRaible.