Mentawai Web Framework

Velocity Support

To use Velocity with Mentawai, first you have to place the velocity jar file inside your application's /WEB-INF/lib directory. You can use the file velocity-dep-1.4.jar that comes with Mentawai inside its /lib directory.

Then all you have to do is install the org.mentawai.velocity.VelocityServletFilter in your web application. Notice that this is a servlet filter, not a Mentawai filter. A servlet filter can intercept and alter the contents of a page before it is sent to the web browser.

To install the VelocityServletFilter in your web application include the following lines in your web.xml file:

<!-- Define the velocity filter -->
<filter>
    <filter-name>VelocityFilter</filter-name>
    <filter-class>
        org.mentawai.velocity.VelocityServletFilter
    </filter-class>
</filter>

<!-- Map the filter to a file extension -->
<filter-mapping>
    <filter-name>VelocityFilter</filter-name>
    <url-pattern>*.vm</url-pattern>
    <dispatcher>REQUEST</dispatcher> 
    <dispatcher>FORWARD</dispatcher>    
    <dispatcher>INCLUDE</dispatcher>    
    <dispatcher>ERROR</dispatcher>    
</filter-mapping>
    

Above we are indicating that our filter should be applied to all files with the .vm extension. Notice that you can also specify in what situations the filter should be applied through the <dispatcher> tag.

  • REQUEST: When the file is accessed directly by the web browser. (Ex: Redirect consequence)
  • FORWARD: When the file is accessed through a servlet forward. (Ex: Forward consequence)
  • INCLUDE: When the file is accessed through a jsp include. (Ex: <jsp:include>)
  • ERROR: When the file is an error page. (Ex: <%@ page isErrorPage="true" %>)
That's it! You can start using Velocity with Mentawai!


What about the Mentawai tags?

Good question! How can you use all those handy Mentawai tags for i18n, authentication, html forms, output display, etc. with Velocity? Don't despair. With Mentawai you can call any jsp taglib from inside your velocity template! Include the following lines in your web.xml file to make your velocity template also behave like a jsp page:

<servlet>
    <servlet-name>tags-for-vm</servlet-name>
    <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
    <load-on-startup>3</load-on-startup>  
</servlet>

<servlet-mapping>
    <servlet-name>tags-for-vm</servlet-name>
    <url-pattern>*.vm</url-pattern>    
</servlet-mapping>
    

Try the template below and see for yourself that it works:

<%@ taglib uri="/WEB-INF/lib/mentawai.jar" prefix="mtw" %>
<!-- example of a hello.vm file -->
<html>
<body>
<!-- mentawai tag -->
<h3>Hello <mtw:out value="username" /> from Mentawai!</h3>
<!-- now velocity -->
<h3>Hello $username with Velocity!</h3>
<!-- do something crazy with velocity -->
#set( $criteria = ["name", "address"] )

#foreach( $criterion in $criteria )
    <h1>$criterion</h1>
#end
</body>
</html>
    

Just be aware that the JSP is processed first and then the velocity template is processed.


Just a little bit of velocity in my JSP

Ok! If you don't want to take a velocity approach, using only *.vm templates, you can still use velocity inside your JSPs through the Mentawai <mtw:velocity> tag.

Check the example below:

<!-- example of a hello.jsp file -->
<%@ taglib uri="/WEB-INF/lib/mentawai.jar" prefix="mtw" %>
<html>
<body>
<!-- mentawai tag -->
<h3>Hello <mtw:out value="username" /> from Mentawai!</h3>
<!-- now velocity -->
<mtw:velocity>
<h3>Hello $username with Velocity!</h3>
<!-- do something crazy with velocity -->
#set( $criteria = ["name", "address"] )

#foreach( $criterion in $criteria )
    <h1>$criterion</h1>
#end
</mtw:velocity>
</body>
</html>
    

Whatever approach you choose, just be careful not to produce a real mess with a crazy mixture of velocity and jsp. ;-)