Installation

This page details the setup of Velosurf in a Webapp powered by the velocity-tools toolbox. For other environments, you should refer to the FAQ.

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:

jar: builds ./velosurf-x.y.jar
download: downloads dependency jars in the ./lib directory
javadoc: builds the javadocs in ./docs/api
tarball: builds the distribution tarball velosurf-x.y.tgz
test: runs all the test cases.
clean: cleans all temporary files.
clean-all: cleans all temporary files and deletes all dependency jars.

Configuring the toolbox

First, you need to set up the Velocity toolbox in your Webapp. This involves:

copying needed archives from ./lib to /WEB-INF/lib
adding a reference to the toolbox in the context-parameters of the Webapp deployment descriptor (web.xml):

<context-param>
  <param-name>org.apache.velocity.toolbox</param-name>
  <param-value>/WEB-INF/toolbox.xml</param-value>
</context-param>

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

<?xml version="1.0"?>
<toolbox>

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

  <tool>
    <key>query</key>
    <scope>request</scope>
    <class>velosurf.web.HttpQueryTool</class>
  </tool>

  <!-- database -->

  <tool>
    <key>db</key>
    <scope>request</scope>
    <class>velosurf.tools.VelosurfTool</class>
    <-- uncomment the next comment if you want to specify a configuration file which is not one
           of the default values (./WEB-INF/model.xml or ./WEB-INF/velosurf.xml) -->
    <--<param name='config' value='./WEB-INF/mymodel.xml'/>-->
  </tool>

</toolbox>

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 Velosurf

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'>
</database>

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 use of Velosurf.