This page details the setup of Velosurf in a Webapp powered by Velocity Tools 1.4 or Velocity Tools 2.0. For other environments, you should refer to the FAQ or the mailing-list.

You should be familiar with Velocity and the concept of Webapp to easily understand the following.

Building the Velosurf archive

The last release is included at the root of the archive directory, but if you want to re-build the library, you need to have ant installed.

Then, the ./build/build.xml file contains the following ant targets:

Configuring the toolbox

First, you need to set up the Velocity toolbox in your Webapp. Please refer to VelovityView Tools 1.4 installation or to VelocityView 2.0+ installation.

Then, you have to set up the Velosurf tools by means of the /WEB-INF/toolbox.xml (for 1.4):

<?xml version="1.0"?>
<toolbox> <!-- toolbox file for Velocity View 1.4 -->

  <!-- ...other tools... -->

  <!-- http query parameters tool:
         You can either use
         or velosurf.web.HttpQueryTool, which inherits the former to add a generic
         setter - in clear, if using VelocityTools 1.4 or prior, you have to use
         the Velosurf version if you want to be able to add values to the tool
         like with #set($'bar').-->


  <!-- database -->

    <-- uncomment the next line tu use a custom model file -->
    <--<param name='config' value='./WEB-INF/mymodel.xml'/>-->


Or /WEB-INF/tools.xml (for 2.0+):

<?xml version="1.0"?>
  <tools> <!-- toolbox file for Velocity View 2.0+ -->

  <!-- ... other toolboxes ... -->

    <toolbox scope="request"/> <!-- or other scopes, see below -->
      <!-- ... other tools ... -->
      <tool key="db" class="velosurf.web.VelosurfTool"/> <!-- add «config="/WEB-INF/mymodel.xml"» for a custom model file -->



Alternatively, the name of the configuration file can also be specified in the velosurf.config servlet context parameter (this latter method must be chosen when using Velosurf authentication or localization filters that rely on the database since the toolbox is not yet initialized at the time the filters are initialized). In that case, you'll have to put the following declaration in /WEB-INF/web.xml:

<context-param> <param-name>velosurf.config</param-name> <param-value>/WEB-INF/db.xml</param-value> </context-param>

Configuring the Velosurf model

By default, the database will be reverse engineered and each table becomes an entity, each column an attribute, and each foreign key will produce two attributes (see the paragraph about foreign keys in the User Guide).

You can thus start with the minimal configuration, which only specifies the database connection parameters (don't forget to specify the schema if you use one):

<?xml version="1.0"?>
<database user='login' password='password' url='database_url' schema='the_schema'>

You can then check your installation with a very simple template that displays a few values taken from the database.

Next, please refer to the User Guide and the Configuration Reference to tune your model file.

The model file supports the XML XInclude mechanism, which lets you split a big model into many files.