<?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>Using XML</title>
        <projectfile>xdocs/project.xml</projectfile>
        <subprojectfile>xdocs/config.project.xml</subprojectfile>
    </properties>

    <body>

    <section name="Configuration using XML">
        <p>
            Providing an xml format configuration file is still the standard, 
            but unlike VelocityTools 1.x, it is no longer necessary at all, 
            thanks to the introduction of default configurations.  The default 
            configurations for <a href="generic.html">
            GenericTools</a>, <a href="view.html">
            VelocityView</a> and <a href="struts.html">
            VelocityStruts</a> are all defined via XML.
        </p>

        <p>
            Here's a somewhat thorough example:
        </p>
        
        <sourcecode>
&lt;tools&gt;
    &lt;toolbox scope="request" xhtml="true"&gt;
        &lt;tool key="toytool" class="ToyTool" restrictTo="index.vm"/&gt;
        &lt;tool key="custom" class="org.mine.CustomTool" randomProperty="whatever"/&gt;
    &lt;/toolbox&gt;

    &lt;toolbox scope="session"&gt;
        &lt;property name="create-session" value="true" type="boolean"/&gt;
        &lt;tool key="map" class="java.util.HashMap"/&gt;
    &lt;/toolbox&gt;

    &lt;toolbox scope="application"&gt;
        &lt;tool class="org.apache.velocity.tools.generic.DateTool"/&gt;
    &lt;/toolbox&gt;

    &lt;data type="number" key="version" value="1.1"/&gt;
    &lt;data key="startdate" value="Mon Sep 17 10:08:03 PDT 2007" class="java.util.Date" 
             converter="org.apache.commons.beanutils.locale.converters.DateLocaleConverter"/&gt;
    &lt;data type="boolean" key="isSimple" value="true"/&gt;
    &lt;data key="foo" value="this is foo."/&gt;
    &lt;data key="bar"&gt;this is bar.&lt;/data&gt;
    &lt;data type="list" key="dataKeys" value="version,date,isSimple,foo,bar,dataKeys,switches"/&gt;
    &lt;data type="list.boolean" key="switches" value="true,false,false,true"/&gt;
&lt;/tools&gt;
        </sourcecode>
        
        <p>
            For those upgrading from VelocityTools 1.x, you will notice that 
            the format has changed rather drastically.  Not to worry, the old 
            format is still supported, though it has been deprecated and does 
            not offer as many features as the new one.  We strongly recommend 
            you upgrade to the new format.
        </p>

    </section>

    </body>

</document>
