<?xml version="1.0"?>

<!--
   Copyright 2000-2004 The Apache Software Foundation

   Licensed 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>Velocity Todo</title>
  <author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
 </properties>

<body>

<section name="Todo">

<p>
This is an informal document describing what needs to
be done in the Velocity code base and the
Velocity documentation. If you need more detailed help, or have specific
questions, please send mail to the mailing list
(<a href="mailto:velocity-dev@jakarta.apache.org">velocity-dev@jakarta.apache.org</a>).
The Todo list that follows is roughly in order of importance.
</p>

</section>

<section name="The List">

    <p>
    <strong>Directive Interface</strong>
    <br/>
        Right now there is a very thin interface for directives, but
        some knowledge of JavaCC is required. The directive
        interface is not intended to be used outside core Velocity
        developers (it is not intended to be a public API), but it
        probably makes sense to shield directive creators from JavaCC.
    </p>

    <p>
    <strong>Caching</strong>
    <br/>
        It would be good to have a discussion about how objects
        in the context should be cached, how the caching
        should be specified, and who should control the
        caching: the designer, by specifying something in the template;
        the developer,
        by placing expiry times on objects placed in the context;
        or a third party, such as a content manager. For example,
        say an array consisting of a top 10 list of books is
        placed in the context. This top 10 list might be valid
        for a 24 hour period: how should that be specified? Say
        a content manager later decides this list will be valid
        for a week. Do they tell the designer, who in turn changes
        the template, or could we provide a mechanism that would
        allow a content manager to change the default expiry time
        for that particular context object with the aid of a webapp
        of some sort? The groundwork has be laid for a flexible
        caching system in Velocity, but this discussion would be
        one of usage and policy.
    </p>

    <p>
    <strong>UML Overview</strong>
    <br/>
        It would great to include a set of comprehensive
        UML diagrams that describe Velocity. This would
        allow new developers to get up to speed quickly.
    </p>

    <p>
    <strong>Velocity Profiling</strong>
    <br/>
        If someone is handy with one of the standard profilers,
        it would be great to start hunting for bottlenecks. No
        serious optimization has been started. But in conjuction
        with the presence of a JUnit test suite, optimization
        changes could be made with confidence. It would be nice
        to have a configuration of a setup for a common profiler
        so that anyone who wanted to do some profiling could do
        so in a consistent manner.
    </p>

    <p>
    <strong>Syntax Dumper</strong>
    <br/>
        Right now there is a primitive syntax dumper in the Velocity
        code base, and it could be improved. This tool is very helpful
        in debugging, and it is also good for creating directives.
        It basically has a simple dump method that is used for all
        the AST node types. It would be good to tailor dump methods
        for particular AST node types so that the structure produced
        is a little clearer.
    </p>

    <p>
    <strong>Syntax Checker</strong>
    <br/>
        It would be good to have a standard syntax checker, something
        that would find all syntax errors and report them to the
        designer in some intelligible format. This tool could be
        hooked into various designer tools like DreamWeaver.
    </p>

    <p>
    <strong>Compiler</strong>
    <br/>
        It would be great to have a template compiler. There is a great
        utility called JavaClass that provides a very clean and simple way
        to create class files, and there is also some byte code generating
        code present in the DynamicJava package that could be utilized.
    </p>

    <p>
    <strong>IDE Integration</strong>
    <br/>
        How could Velocity be integrated into standard IDEs like
        JBuilder and VisualAge?
    </p>

    <p>
    <strong>Scripting Language Integration</strong>
    <br/>
        This is something that has been discussed on the Turbine
        list. Allowing Context building classes to be written
        in JPython, Rhino or other scripting languages would
        dramatically improve development time and might allow technically
        proficient web designers who are familiar JavaScript to create
        an entire servlet solution with Velocity. As most of these
        scripting solutions provide a compiler, performance would still
        remain at an acceptable level.
    </p>

</section>

</body>
</document>
