<?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>Overview</title>
        <projectfile>xdocs/project.xml</projectfile>
    </properties>

    <body>

    <section name="Overview">
        <p>
            A Velocity "tool" is just a POJO (plain old java object) that is 
            "useful" in a template and is not meant to be rendered in the 
            output.  In other words, a "tool" (in Velocity-speak) is meant 
            to be used but not seen themselves (e.g. for formatting dates 
            or numbers, url building, etc).
        </p>

        <p>
            The VelocityTools project is, first of all, a collection of such 
            useful Java classes, as well as infrastructure to easily, 
            automatically and transparently make these tools available to your 
            Velocity templates.  Other aims of the project include providing 
            easy integration of Velocity into the view-layer of your web 
            applications (via the 
            <a href="view.tag.html">VelocityViewTag</a> and 
            <a href="view.servlet.html">VelocityViewServlet</a>) 
            and integration with Struts 1.x applications.
        </p>

        <p>
            In recognition of these varying aims, the VelocityTools project is 
            divided into three parts: <a href="generic.html">GenericTools</a>, 
            <a href="view.html">VelocityView</a> and <a href="struts.html">
            VelocityStruts</a>. Each of these parts builds on the previous one 
            and has its own JAR distribution.
        </p>

        <subsection name="GenericTools">
            <p>
                <a href="generic.html">GenericTools</a> is the set of classes 
                that provide basic infrastructure for using tools in standard 
                Java SE Velocity projects, as well as a set of tools for use 
                in generic Velocity templates.  Perenial favorites here are 
                the DateTool, NumberTool and RenderTool, though there are many 
                others available as well.
            </p>
        </subsection>

        <subsection name="VelocityView">
            <p>
                <a href="view.html">VelocityView</a> includes all of the 
                <a href="generic.html">GenericTools</a> structure and 
                specialized tools for using Velocity in the view layer of web 
                applications (Java EE projects). This includes the 
                <a href="view.servlet.html">VelocityViewServlet</a> or 
                <a href="view.layoutservlet.html">VelocityLayoutServlet</a>
                for processing Velocity template requests and the 
                <a href="view.tag.html">VelocityViewTag</a> for 
                embedding Velocity in JSP. Popular tools here are the LinkTool
                and the ParameterTool.
            </p>
        </subsection>

        <subsection name="VelocityStruts">
            <p>
                <a href="struts.html">VelocityStruts</a> includes both 
                <a href="view.html">VelocityView</a> and <a href="generic.html">
                GenericTools</a> and adds tools for use in Struts 1.x 
                applications.  These tools match the functions of the key 
                Struts taglibs and provide access to Struts resources, messages, 
                tiles, validation functions and more.
            </p>
        </subsection>

        <p>
            It is worth noting that these tools, being POJOs (though some 
            require a little configuration) are generally useful and may be 
            used within your java classes or even other template languages, 
            though you may need to instantiate and configure them manually (not 
            difficult) to do so.  VelocityTools 2 has been designed with this 
            in mind.  Ask on the user mailing list if you have questions about 
            using VelocityTools without Velocity.
        </p>

    </section>

    <section name="Why 2.0?">
        <p>
            Those already familiar with VelocityTools 1.x may be curious about 
            the goals and motivations behind developing VelocityTools 2. 
            In planning and developing the 2.0 release, there were three main 
            goals:
        </p>
        <ul>
            <li>
                Transparent, on-demand tool instantiation (aka lazy loading 
                for tools) - This allows you to have many tools available 
                (even ones that are expensive to instantiate), but not waste 
                time instantiating or initializing/configuring those you don't 
                use for every request.
            </li>

            <li>
                More accessible, reusable infrastructure - This allows easier 
                access to tools outside of your templates and provides better 
                means to integrate VelocityTools support into other web 
                frameworks or even other view technologies 
                (e.g. VelocityViewTag).
            </li>

            <li>
                Simpler, more flexible toolbox 
                <a href="config.html">configuration</a> - Now you can 
                configure via a 
                <a href="config.properties.html">properties file</a>, 
                <a href="config.java.html">plain java</a>, or really 
                whatever you want (though perhaps with a bit more work).  No 
                <a href="config.xml.html">XML</a> required anymore; though,
                if you do use it, it's now a lot better than it was.
            </li>
        </ul>

        <p>
            These things could not have been accomplished without rewriting 
            most of the core infrastructure and configuration code.  At the 
            same time, we wanted to make it easy for people to upgrade from 
            the 1.x series.  This led to the decision to aim for complete 
            backwards compatibility.  Granted much has been deprecated and 
            those who directly used or extended the 1.x infrastructure will 
            have to update their code in just a few releases, but for the time 
            being they should be able to use 2.0 in their applications with 
            few problems. Those who merely used the old toolbox.xml format or 
            the old tools directly will be immediately able to take advantage 
            of the new infrastructure without even updating their 
            configuration, though eventually even the old toolbox.xml format 
            may be retired.  Don't cry.  You'll like the 
            <a href="config.xml.html">new one</a> better once 
            you get to know it!  It can do much more with much less typing.
        </p>

    </section>

    <section name="Subversion Repository">
        <p>
            All VelocityTools project code is maintained in the Subversion 
            repository which can be reached in a number of ways. The most 
            direct method of accessing the repository is through a 
            web browser, but to effectively work on the code, a 
            <a href="http://svn.tigris.org/links.html#clients">Subversion
            client</a> is required.
        </p>

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

    </section>

    <section name="Helping Out">
        <subsection name="Communication">
            <p>
            Feedback about the project, whether positive or gently critical,
            is always helpful to those working on the project.  Such feedback
            may be sent to either the user@velocity.apache.org or 
            dev@velocity.apache.org 
            <a href="http://velocity.apache.org/contact.html">mailing lists</a>.
            </p>
            <p>
            Another great way to help is to simply participate in conversations
            on the mailing list.  On the user list, you can help answer questions
            that other users have. This frees the developers to focus on
            development more than user support.  On the dev list, you can
            participate in design discussions and release votes to help
            maintain the high quality of the releases and direct the future
            directions of the project.
            </p>
        </subsection>
        <subsection name="Contribution">
            <p>
            Those interested in furthering the development of this 
            project have an open invitation to jump in and help out.
            We welcome your contributions!
            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:</p>
            <ul>
                <li>Documentation (patches for the site or additions to 
                the Wiki)</li>
                <li>Improving the example apps</li>
                <li>Working on unresolved tasks in
                    <a href="http://issues.apache.org/jira/browse/VELTOOLS">JIRA</a></li>
                <li>Contributing to the 
                    <a href="http://wiki.apache.org/velocity/VelocimacroLibrary">VelocimacroLibrary</a></li>
            </ul>
            <p>
            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>
        </subsection>
        <subsection name="Code">
            <p>
            When contributing code, it helps <strong>immensely</strong> if you follow
            through with the things on this checklist, especially the coding conventions.
            Keeping our code style consistent, our codebase stays easy to read and easy
            to patch.  Adding javadoc (and examples therein) simplifies the documentation
            process and reduces confusion about the purpose of various methods and classes.
            Tests make sure that things work as expected, especially as development continues
            down the road.  Of course, contributions that don't follow the checklist will
            be considered and often accepted, but you can expect the project committers
            to be slower and less enthusiastic in doing so. :)
            </p>
            <p><b>Checklist for Code Contributions</b>:</p>
            <ul>
                <li><a href="http://wiki.apache.org/velocity/CodeStandards">Velocity coding conventions</a></li>
                <li>Javadoc included (the more detailed the better)</li>
                <li>Examples included (in JavaDoc or as stand-alone template example)</li>
                <li>Tests included (not required but <b>GREATLY</b> appreciated)</li>
            </ul>
        </subsection>

    </section>

    </body>
                                                                               
</document>
