|
|
|
|
| <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="../javadoc/org/apache/velocity/tools/view/tools/ContextTool.html">ContextTool</a></li>
|
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/CookieTool.html">CookieTool</a></li>
|
| <li><a href="ImportTool.html">ImportTool</a></li>
|
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/LinkTool.html">LinkTool</a></li>
|
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/ParameterParser.html">ParameterParser</a></li>
|
| <li><a href="ViewRenderTool.html">ViewRenderTool</a></li>
|
| <li><a href="../javadoc/org/apache/velocity/tools/view/tools/ViewResourceTool.html">ViewResourceTool</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, 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 VelocityViewServlet |
| (or subclass thereof) 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 any 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 the VelocityViewServlet, 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> |
| |
| <!-- |
| Unless you plan to put your toolbox.xml and velocity.properties |
| under different folders or give them different names, then these |
| two init-params are unnecessary as of VelocityTools 1.3. The |
| VelocityViewServlet will automatically look for these files in |
| the following locations. |
| --> |
| <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> |
| </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 may be specified in web.xml, |
| but it is recommended the file be placed inside the hidden WEB-INF |
| directory of the web application and named 'velocity.properties' which |
| is where the VelocityViewServlet will look for it in the absence of |
| any location specified in the web.xml. |
| 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> by |
| default, 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 the tool has a <code>public init(Object)</code> method, |
| then the scope will also determine what data is passed to that 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 Request Paths</b></p>
|
| <p>You can specify a restriction on the request URIs for which the tool |
| will be put in the context using the <request-path> element. |
| It can be an exact request path (matching one page) or end with the |
| <code>*</code> wildard, meaning that incoming request paths need only |
| start with the provided value for the tool to be available in the context. |
| For instance:</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>catalog</key> |
| <scope>request</scope> |
| <request-path>/catalog/*</request-path> |
| <class>com.mycompany.tools.CatalogTool</class> |
| </tool></sourcecode></pre>
|
| </td></tr></table>
|
| </td></tr></table>
|
| <p>For now, this request-path filter is only valid for request scoped tools. |
| In VelocityTools 2.0, we plan to support this for session and application |
| scoped tools as well.</p>
|
| <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 have a |
| <code>public void configure(java.util.Map params)</code> method. |
| This method 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> |
| Since Tomcat 5.5 is using commons-logging as a complete |
| logging facility, we are no longer able to direct commons-logging |
| output to the servlet log by default. The result of this is that |
| our example apps can no longer contain a commons-logging.properties |
| on the classpath if we want them to work with all servlet engines. |
| </p>
|
| <p> |
| When using Tomcat 5.5+, this means that log messages |
| from our tools and tool management code are by default sent to the Tomcat |
| console, rather than the servlet log. Velocity Engine and VelocityViewServlet |
| messages will still be sent to the servlet log by default. |
| When using other servlet engines or earlier Tomcat versions |
| (e.g. Jetty or Tomcat 4.x), you must now add a commons-logging.properties |
| file at the root of the classpath that contains: |
| <code> |
| org.apache.commons.logging.Log=org.apache.velocity.tools.generic.log.LogSystemCommonsLog |
| </code> |
| if you wish to have tool and tool management log output sent to the |
| servlet log. If you are using Tomcat 5.5+, do NOT do that, as it will |
| cause an infinite loop. |
| </p>
|
| <p> |
| We plan to resolve this in future versions by removing commons-logging |
| from our code in favor of the much improved log wrappers in Velocity Engine 1.5. |
| In the meantime, commons-logging remains the most flexible solution. |
| </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>
|
