<?xml version="1.0"?>

<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>

    <properties>
        <title>VelocityTools Project</title>
        <author email="geirm@apache.org">Geir Magnusson Jr.</author>
        <author email="sidler@apache.org">Gabriel Sidler</author>
        <projectfile>xdocs/menu.xml</projectfile>
    </properties>

    <body>
    <section name="Overview">
        <p>
        VelocityTools is a collection of Velocity subprojects with a common goal
        of creating tools and infrastructure for building both web and non-web
        applications using the Velocity template engine.
        </p>

        <subsection name="GenericTools" >
            <p><a href="generic/">GenericTools</a> is a group of reuseable and
            documented tools that can be added to a Velocity context. A
            <b>tool</b> is simply a class which can perform various tasks when
            made available to the Velocity engine. Most tools are optimized for use
            with an automatically managed toolbox (see VelocityViewServlet).</p>
            <br clear="all" />
        </subsection>

        <subsection name="VelocityView" >
            <p><a href="view/">VelocityView</a>
            contains a standalone servlet (VelocityViewServlet) which can render
            templates for web applications. </p>
            <p> Also included is a Toolbox Manager which can automatically make
            &quot;view tools&quot; and data available to the templates. Any class
            with public methods can be used as a tool in the template.
            </p>
            <p>
            <a href="view/layoutservlet.html">VelocityLayoutServlet</a> is an
            extension of the basic VelocityViewServlet that can render screen
            content into common layout templates.</p>
            <br clear="all" />
        </subsection>

        <subsection name="VelocityStruts" >
            <p><a href="struts/">VelocityStruts</a> is a set of tools for using the
            Velocity template engine as the view layer for a web application built upon the
            <a href="http://struts.apache.org/">Apache Struts</a> framework.</p>
            <p>This work leverages the <strong>VelocityViewServlet</strong> and
            additional tools which make it easy to integrate the Velocity with
            Struts. Several example hybrid applications are included.</p>
            <br clear="all" />
        </subsection>

        <subsection name="Example Applications">
            <p>Several example applications are currently available, including
            one to demonstrate the use of Velocity as a view technology for Struts.
            The example utilizes both Velocity and JSP files for the view in parallel
            so that they can be compared easily. Also, resources bundle usage for
            language localization is demonstrated there. Other examples include a demonstration
            of the use of the VelocityLayoutServlet and a minimal "simple" application.</p>
            <br clear="all" />
        </subsection>

        <subsection name="Documentation">
          <p>
            Emphasis <s>is</s> was being put on providing tool documentation that
            is suitable for template designers. To achive this goal, a documentation
            format has been defined that captures all information relevant to the
            template designer. It is being supplied in addition to the customary
            Javadoc. This should help to achieve what we always claim for Velocity:
            "Decouple the work of template designers from the work of software
            developers". Look at the Struts
            <a href="struts/MessageTool.html">MessageTool</a>
            for a good example of the new documentation format.
          </p>
          <p>
            <b>Update:</b>
            While we value the look and readability of this format, we are presently
            drifting away from the use of it. The primary reason for this is that the
            developers have found it difficult to maintain (i.e. no one
            has been motivated enough to put in the extra work).  If you feel this
            documentation format is valuable and wish to help us create and maintain
            it for the various individual tools, please see
            <a href="#Wanna help?">below</a>
            for more details on getting involved.  Meanwhile, we'll be putting effort
            into improving javadoc for individual tools and overview documents for
            the sub-projects.
          </p>
        </subsection>
        <br clear="all"/>
    </section>

    <section name="Download">
        <p><strong>Releases</strong></p>
        <p>
          The latest versions are available for
          <a href="http://velocity.apache.org/download.cgi">download</a>
          in source or binary form.
        </p>

        <br clear="all"/>
    </section>

    <section name="Subversion Repository">
        <p>All VelocityTools project code is maintained in the
        Subversion repository <a href="http://svn.apache.org/repos/asf/velocity/tools/">
        http://svn.apache.org/repos/asf/velocity/tools/</a>.</p>

        <p>Web Browser: <a href="http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/">
        http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/</a></p>

        <p>Subversion Client: <a href="http://www.apache.org/dev/version-control.html">http://www.apache.org/dev/version-control.html</a>.
        </p>
        <br clear="all"/>
    </section>

    <section name="Wanna help?">
        <p>We encourage interested developers to evaluate the project
        and send feedback to the velocity-user or velocity-dev mailing list.</p>
        <p>Those interested in furthering the development of this project are
        especially welcome to jump in and help out.  Patches can be sent to the
        mailing list or attached to a
        <a href="http://issues.apache.org/jira/browse/VELTOOLS">JIRA</a>
        issue.  The <a href="http://wiki.apache.org/velocity/VelocityTools">Wiki</a>
        can also be a good place to discuss and develop ideas.</p>

        <p>A few good places to get started include:
          <ul>
            <li>Documentation (patches for the site or additions to the Wiki)</li>
            <li>Improving the example apps</li>
            <li>Contributing to the <a href="http://wiki.apache.org/elocity/VelocimacroLibrary">VelocimacroLibrary</a></li>
          </ul>
        Other project goals and proposals can be found in the project
        <a href="http://svn.apache.org/viewcvs.cgi/velocity/tools/trunk/STATUS?view=markup">STATUS</a>
        file.</p>
    </section>
 </body>

</document>
