VelocityView includes all of the GenericTools and adds infrastructure and specialized tools for using Velocity in the view layer of web applications (Java EE projects). This includes the VelocityViewServlet or VelocityLayoutServlet for processing Velocity template requests and the VelocityViewTag for embedding Velocity in JSP.
The VelocityView object forms the core of the VelocityView infrastructure. In particular, it serves as the base class for the following:
The VelocityViewServlet class is a standalone servlet that renders Velocity templates. It can be invoked directly from web client's requests, or via servlet forwarding similar to how JSP files are rendered by JSPServlet.
Detailed documentation is here.
One derivative of the VelocityViewServlet is the VelocityLayoutServlet. This servlet performs a simplified 'two-pass render' in order to apply a shared, common layout to all of the web pages in an application.
The Struts "template" tag library does something similar, but requires a separate file to define which 'layout' file to use and which .jsp files to render into that layout. The VelocityLayoutServlet takes a simpler approach. It first renders the primary template being called (example: showDetails.vm) into a content holder variable (ex. $screen_content). Next, the servlet loads a 'layout' file. It uses the existing data, including any additional variables set or changed by the first template, to render a the layout template.
The VelocityLayoutServlet also allows you to specify an 'error' template to be displayed when an exception is thrown during the processing of a requested template. This allows you to provide a customized error screen for a more user-friendly application.
Detailed documentation is here.
These are in addition to those provided by GenericTools
A simple application example has been included to demonstrate the use of the VelocityViewServlet with automatically loaded view tools.
To run the examples you need Tomcat 4+ or a compatible servlet runner.
The 'ant examples' target of the build process automatically generates ready-to-deploy simple.war and showcase.war archive files located in the examples subdirectory of the distribution. Deploy (i.e. copy) one or both of these war files to the webapps directory of your servlet runner and restart. Now point a web browser at the following urls:
You can also use the embedded servlet runner to start and stop the showcase webapp on localhost's 8081 port using the start.showcase.webapp and stop.showcase.webapp ant targets.
Since Tomcat 5.5 used commons-logging as a complete logging facility and the Struts example directs commons-logging output to the servlet log via LogChuteCommonsLog, you will get an infinite loop if you try to run the Struts example on Tomcat 5.5. To fix this, upgrade to Tomcat 6.x or delete the commons-logging.properties file from the Struts example's classpath root.
You may, of course, experience the same thing if you are running your web application on Tomcat 5.5 and decide to use LogChuteCommonsLog for commons-logging and stick with the ServletLogChute (the default) for Velocity(Tools) logging. You will have to change one of these two settings or else upgrade your servlet engine.