| <html> | |
| <head> | |
| <title>Velocity - VelocityView</title> | |
| <meta name="author" value="Gabriel Sidler"/> | |
| <meta name="email" value="sidler@apache.org" /> | |
| <meta name="author" value="Geir Magnusson Jr."/> | |
| <meta name="email" value="geirm@apache.org" /> | |
| <meta name="author" value="Nathan Bubna"/> | |
| <meta name="email" value="nbubna@apache.org" /> | |
| </head> | |
| <body bgcolor="#ffffff" text="#000000" link="#525D76" | |
| alink="#525D76" vlink="#525D76"> | |
| <table border="0" width="100%" cellspacing="4"> | |
| <tr><td colspan="2"> | |
| <a href="http://jakarta.apache.org/"> | |
| <img src="http://jakarta.apache.org/images/jakarta-logo.gif" | |
| align="left" alt="The Jakarta Project" border="0"/> | |
| </a> | |
| <a href="index.html"> | |
| <img src="../images/velocityview.png" align="right" alt="< Tools - View >" border="0"/> | |
| </a> | |
| </td></tr> | |
| <tr> | |
| <td colspan="2"> | |
| <hr noshade="" size="1"/> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td width="20%" valign="top" nowrap="true"> | |
| <p><strong><a href="../index.html">Velocity Tools</a></strong></p> | |
| <p> | |
| <strong>VelocityView</strong> | |
| </p> | |
| <ul> | |
| <li><a href="index.html">Overview</a></li> | |
| <li><a href="../index.html#Download">Download</a></li> | |
| <li><a href="index.html#Installation">Installation</a></li> | |
| <li><a href="index.html#VelocityLayoutServlet">LayoutServlet</a></li> | |
| <li><a href="index.html#Examples">Examples</a></li> | |
| <li><a href="../javadoc/index.html">Javadoc</a></li> | |
| </ul> | |
| <p> | |
| <strong>VelocityView Tools</strong> | |
| </p> | |
| <ul> | |
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/AbstractPagerTool.html">AbstractPagerTool</a></li> | |
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/AbstractSearchTool.html">AbstractSearchTool</a></li> | |
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/BrowserSnifferTool.html">BrowserSnifferTool</a></li> | |
| <li><a href="CookieTool.html">CookieTool</a></li> | |
| <li><a href="ImportTool.html">ImportTool</a></li> | |
| <li><a href="LinkTool.html">LinkTool</a></li> | |
| <li><a href="ParameterParser.html">ParameterParser</a></li> | |
| <li><a href="ViewRenderTool.html">ViewRenderTool</a></li> | |
| </ul> | |
| <p> | |
| <strong>Other Subprojects</strong> | |
| </p> | |
| <ul> | |
| <li><a href="../generic/">GenericTools</a></li> | |
| <li><a href="../struts/">VelocityStruts</a></li> | |
| </ul> | |
| <p> | |
| </p> | |
| </td> | |
| <!-- RIGHT SIDE MAIN BODY --> | |
| <td colspan="1" valign="top" align="left"> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#525D76"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Overview"> | |
| <strong>Overview</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>VelocityView provides support for rapidly and cleanly building web applications | |
| using Velocity templates as the view layer. The project is designed with the | |
| <a href="http://jakarta.apache.org/turbine/further-reading/pullmodel.html">Pull-MVC Model</a> | |
| in mind and works well in conjunction with web application frameworks that act | |
| as the controller (e.g. <a href="../struts/index.html">Struts</a>), but can be used | |
| quite effectively on its own for those creating simpler applications. | |
| </p> | |
| <p>Key features:</p> | |
| <ul> | |
| <li><b><a href="../javadoc/org/apache/velocity/tools/view/servlet/VelocityViewServlet.html">VelocityViewServlet</a> | |
| class</b> - standalone servlet that renders Velocity | |
| templates. Invoked directly from web clients requests, or via servlet | |
| forwarding similar to how JSP files are rendered by JSPServlet.</li> | |
| <li>The HttpServletRequest, HttpSession, ServletContext, | |
| and their attributes are automatically available in your templates.</li> | |
| <li>Tools can also be made available to your templates, through a | |
| <strong>toolbox</strong> configuration file.</li> | |
| <li>A number of useful, extendable tools for developing web applications are | |
| already provided for your convenience.</li> | |
| <li>Logging can be directed to the log infrastructure of the Web application. | |
| (default is the logging facility provided by the Servlet API).</li> | |
| </ul> | |
| <p>Using VelocityViewServlet, it becomes possible to write web applications that | |
| are independent of a particular view technology. This opens a straightforward | |
| migration path between JSP pages and Velocity templates as the view layer | |
| technology in web applications.</p> | |
| <p>A typical application use-case is to provide the view rendering layer for | |
| a servlet-based web application framework. The | |
| <a href="../struts/">VelocityStruts</a> subproject | |
| uses the approach to bring Velocity templates to the Struts application framework.</p> | |
| </td> | |
| </tr> | |
| </table> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#525D76"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Installation"> | |
| <strong>Installation</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>The VelocityViewServlet needs to be installed into your servlet container | |
| so it can handle all request for *.vm (velocity template) files. There are | |
| only two additional configuration files necessary, and they are shown in | |
| detail below.</p> | |
| <br clear="all"/> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#828DA6"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Servlet Setup"> | |
| <strong>Servlet Setup</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>The servlet configuration (<strong>web.xml</strong>) must be | |
| modified to include a reference to the special Velocity-based | |
| servlet which will perform the rendering. All *.vm files are | |
| mapped to this servlet which will populate the 'context' with | |
| Request, Session, and Application scopes plus additional tools | |
| specified in the <strong>toolbox.xml</strong> file. The servlet | |
| will use this contextual information and the Velocity Engine to | |
| render the template file. </p> | |
| <br clear="all"/> | |
| <p><strong>Note:</strong> Additional functionality can be achieved | |
| through subclassing this servlet, and will be discussed further in | |
| the VelocityLayoutServlet below. </p> | |
| <p><b>web.xml</b></p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode><!-- Define Velocity template compiler --> | |
| <servlet> | |
| <servlet-name>velocity</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> | |
| <!-- Map *.vm files to Velocity --> | |
| <servlet-mapping> | |
| <servlet-name>velocity</servlet-name> | |
| <url-pattern>*.vm</url-pattern> | |
| </servlet-mapping></sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| </td> | |
| </tr> | |
| </table> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#828DA6"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Velocity Configuration"> | |
| <strong>Velocity Configuration</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>Velocity configuration is <strong>optional</strong>, and for | |
| most applications the defaults will work fine. The | |
| <strong>velocity.properties</strong> file contains settings that | |
| affect logging, encoding, and macro settings.</p> | |
| <p>The default configuration specifies the location of a 'global' | |
| Velocimacro template. This file can contain macros which will be | |
| made available to all templates.</p> | |
| <p>The location of the configuration file is specified in web.xml, | |
| and it is recommended the file be placed inside the hidden WEB-INF | |
| directory of the web application. An example configuration | |
| file is included with the distribution.</p> | |
| <p>Please see the | |
| <a href="http://jakarta.apache.org/velocity/user-guide.html">Velocity User's Guide</a> | |
| for more information on Velocity configuration.</p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode> 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</sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| <br clear="all"/> | |
| </td> | |
| </tr> | |
| </table> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#828DA6"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Toolbox Configuration"> | |
| <strong>Toolbox Configuration</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>The toolbox file, <strong>WEB-INF/toolbox.xml</strong> in our | |
| example, maps names of our choosing to the classes that they will | |
| represent. It's easier than that sounds.</p> | |
| <p>Think about asking our friend Jon to grab us a 'wrench' from a | |
| real toolbox. Jon just needs to know which wrench we want (metric, | |
| pipe, crescent etc,). He doesn't need to know what the wrench does | |
| nor what we are planning to do with it.</p> | |
| <p>The Velocity Toolbox works the same way, we must only specify | |
| which tool to assign to a name, and then the Velocity engine takes | |
| care of the rest by making any public method available to the | |
| template. For example, from the definitions below, the template | |
| could call $wrench.getSize() or $wrench.size .</p> | |
| <p><b>PipeWrench.java</b></p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode>public class PipeWrench { | |
| public String getSize() { | |
| return "Large Pipe Wrench!"; | |
| } | |
| } </sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| <p><b>toolbox.xml</b></p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode><?xml version="1.0"?> | |
| <toolbox> | |
| <tool> | |
| <key>wrench</key> | |
| <scope>application</scope> | |
| <class>PipeWrench</class> | |
| </tool> | |
| </toolbox></sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| <br clear="all"/> | |
| <p><b>Tool Scopes</b></p> | |
| <p>The toolbox support built into the VelocityViewServlet also provides | |
| support for specifying the scope of your tool with regards to the | |
| servlet environment. Tools may be placed within the <i>request</i>, | |
| <i>session</i>, or <i>application</i> scopes of your web app.</p> | |
| <p>The scope that you set for your tool will determine both its | |
| lifecycle and, if it implements the | |
| <a href="../javadoc/org/apache/velocity/tools/view/tools/ViewTool.html">ViewTool</a> | |
| interface, then the scope will also determine what data is passed to the | |
| <code>init(Object)</code> method:</p> | |
| <ul> | |
| <li><i>application</i> scoped tools will be instantiated only once and then | |
| reused for each request. Due to this, it is <em>strongly</em> encouraged | |
| that your application scoped tools be completely threadsafe. The MathTool | |
| in the <a href="../generic/">GenericTools</a> section is a good example of tool meant to be application | |
| scoped. If an application scoped tool implements ViewTool, then the | |
| javax.servlet.ServletContext for the webapp will be passed to its | |
| <code>init(Object)</code> method after it is instantiated.</li> | |
| <li><i>session</i> scoped tools are instantiated once per unique session and | |
| are then reused for every request associated with that particular session. If | |
| a session scoped tool implements ViewTool, then its <code>init(Object)</code> | |
| method will be passed the | |
| <a href="../javadoc/org/apache/velocity/tools/view/context/ViewContext.html">ViewContext</a> | |
| of the request during which the session was created.</li> | |
| <li><i>request</i> is the default scope. If no scope is specified for a | |
| <tool> in your toolbox.xml, then it will be automatically set as | |
| <i>request</i> scope. Tools with this scope are instantiated for every | |
| servlet request fed to the VelocityViewServlet. If a request scoped tool | |
| implements ViewTool, then its <code>init(Object)</code> method will be | |
| passed the current ViewContext.</li> | |
| </ul> | |
| <p>You can specify the scope of your tools by adding a <scope> | |
| element to your toolbox.xml entries like this:</p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode><tool> | |
| <key>math</key> | |
| <scope>application</scope> | |
| <class>org.apache.velocity.tools.generic.MathTool</class> | |
| </tool></sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| <br clear="all"/> | |
| <p><b>Tool Parameters</b></p> | |
| <p>The toolbox support built into the VelocityViewServlet also provides | |
| support for passing configuration parameters to tools that implement | |
| the <a href="../javadoc/org/apache/velocity/tools/view/tools/Configurable.html">Configurable</a> | |
| interface. This interface consists of only a | |
| <code>void configure(java.util.Map params)</code> method which will only be called | |
| if parameters have been specified for the tool.</p> | |
| <p>You can specify parameters for your tools by adding a <parameter> | |
| element to your toolbox.xml entries like this:</p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode><tool> | |
| <key>math</key> | |
| <scope>application</scope> | |
| <class>com.foo.tools.MyTool</class> | |
| <parameter name="my.parameter.name" value="my.parameter.value"/> | |
| </tool></sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| <br clear="all"/> | |
| <p><b>Toolbox Data</b></p> | |
| <p>In addition to specifiying arbitrary Java classes as <b>tools</b> | |
| to be automatically available to your templates, the toolbox support | |
| also includes the ability to specify arbitrary strings, booleans, and | |
| numbers to be automatically available in your templates. The format | |
| is as follows:</p> | |
| <table width="100%" cellpadding="1" cellspacing="0" border="0"><tr><td bgcolor="#000000"> | |
| <table width="100%" cellpadding="5" cellspacing="0" border="0"><tr><td bgcolor="#FFFFFF"> | |
| <pre><sourcecode><?xml version="1.0"?> | |
| <toolbox> | |
| <data type="number"> | |
| <key>app_version</key> | |
| <value>0.9</value> | |
| </data> | |
| <data type="string"> | |
| <key>app_name</key> | |
| <value>Jon's Tool Shop</value> | |
| </data> | |
| <data type="boolean"> | |
| <key>debug</key> | |
| <value>true</value> | |
| </data> | |
| </toolbox></sourcecode></pre> | |
| </td></tr></table> | |
| </td></tr></table> | |
| <p>As with your tools, your data will be exposed to your templates | |
| under the specified key (e.g. $app_version, $app_name, $debug).</p> | |
| <br clear="all"/> | |
| </td> | |
| </tr> | |
| </table> | |
| </td> | |
| </tr> | |
| </table> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#525D76"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="VelocityLayoutServlet"> | |
| <strong>VelocityLayoutServlet</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>One derivative of the VelocityViewServlet is the | |
| <a href="layoutservlet.html"><strong>VelocityLayoutServlet</strong></a>. | |
| 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.</p> | |
| <p>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.</p> | |
| <p>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.</p> | |
| <p>Detailed documentation here: <a href="layoutservlet.html">VelocityLayoutServlet</a>.</p> | |
| <br clear="all"/> | |
| </td> | |
| </tr> | |
| </table> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#525D76"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Examples"> | |
| <strong>Examples</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>A simple application example has been included to demonstrate the use | |
| of the VelocityViewServlet with automatically loaded view tools.</p> | |
| <p>To run the examples you need Tomcat 4.x, Tomcat 5.0.x, Tomcat 5.5.x, | |
| or a compatible servlet runner.</p> | |
| <p>The build process automatically generates a ready-to-deploy <b>simple.war</b> | |
| archive file located in the examples subdirectory. Deploy (i.e. copy) this | |
| simple.war file to the webapps directory of your servlet runner and restart. | |
| Now point a web browser at the following url:</p> | |
| <p><b>http://<your_server>:<port>/simple/</b></p> | |
| <br clear="all"/> | |
| </td> | |
| </tr> | |
| </table> | |
| <table border="0" cellspacing="0" cellpadding="2" width="100%"> | |
| <tr> | |
| <td colspan="2" bgcolor="#525D76"> | |
| <font color="#ffffff" face="arial,helvetica.sanserif"> | |
| <a name="Known Issues"> | |
| <strong>Known Issues</strong></a></font> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td NOWRAP> </td> | |
| <td> | |
| <p>None!</p> | |
| <br clear="all"/> | |
| </td> | |
| </tr> | |
| </table> | |
| </td> | |
| </tr> | |
| <!-- FOOTER SEPARATOR --> | |
| <tr> | |
| <td colspan="2"> | |
| <hr noshade="" size="1"/> | |
| </td> | |
| </tr> | |
| <!-- PAGE FOOTER --> | |
| <tr><td colspan="2"> | |
| <div align="center"><font color="#525D76" size="-1"><em> | |
| Copyright © 1999-2003, Apache Software Foundation | |
| </em></font></div> | |
| </td></tr> | |
| </table> | |
| </body> | |
| </html> |