DVSL (Declarative Velocity Style Language) is a tool modeled after XSLT and is intended for general XML transformations. DVSL steals two of the best features of XSLT:

• It uses a declarative syntax like XSLT.
• Document control and selection is based on XPath.

DVSL's template language is Velocity, so conventional Velocity syntax is used to get and set data, to perform looping and flow control, etc. Anything that you can normally do in a Velocity template can be done in DVSL templates.

Before you use DVSL, you must get the source and build the tool. Currently, there is no release, so you must either get a nightly snapshot, or download directly from CVS.

Building DVSL is very simple. All dependency jars that are required are included in the distribution. However, we do require that Jakarta Ant is installed.

Once ant is installed, you simply need to change to the project root directory and invoke ant with the 'jar' target :

This will build the dvsl jar in the project root directory.

While DVSL is also a tool that can be integrated into your applications, DVSL is able to be used without any programming.

The first way is via command line, where you can use it to transform a single file, or as a filter. The usage is :

Note that the stylesheet is the only required element, and the input and output then default to stdin and stdout. By adding the appropriate stuff in your classpath (that would be all the jars in the project lib directory ), you can use it :

You can also use DVSL right from ant using the included Ant task. The Ant task supports the toolbox.

A few examples are provided with the current distribution, in the examples directory in the distribution, and the examples that follow were originally taken from there.

To begin, we will start with a simple example. Here is a basic XML document:

A simple DVSL stylesheet to transform this into HTML might look like :

$node.copy($node.children())

With the resulting output of

Hello from section foo

Hello from section bar

This can be found in examples/simple and is example1.xml and example1.dvsl.

A more interesting example involves specifying and using tools. We'll give an example and explain the toolbox later on.

A simple toolbox example is included, in examples/toolbox. First, you must define the tools and values in a properties file

Here we do a couple of things :

1. toolbox.contextname = toolbox : defines 'toolbox' as the name we will use in the template to access the tools.
2. toolbox.tool.footool = Footool : defines that an instance of the class 'Footool' will be placed in the context under the key 'footool'.
3. toolbox.string.mystring = Hello there! : defines that a java.lang.String "Hello there!" will be placed in the context under the key 'mystring'
4. toolbox.integer.myint = 7 : defines that a java.lang.Integer will be placed in the context under the key 'myint'.

You specify the toolbox in the <dvsl> task in the ant script as such :

To use the tools, this is the stylesheet that has an example :

With an input of :

And with the class Footool

You get the output

This can be found in examples/toolbox.

Also, the examples/velocitydocs example shows how to grab and use the HTMLEscape class from the Velocity jar as a tool to do escaping.

Writing templates is very simple. The basic template definition uses the directive

This directive declares that when a node matches the <XPath Expression > then the body of the directive is to be rendered to the ouput. In the body, you would place any static content you wish to go to the output, and also get data from the XML document you are working in.

Future plans include a #name() directive, and optional arguments to the #match() and #name() directives to support modes and namsepaces.

During processing, when a match occurs and a template is invoked, a few objects are placed in the Context for you to access. These elements are read-only and cannot be modified via #set().

The most important is the current Node, which is accessible via the reference $node. The $node is the current node that matched the template XPath expression (or name).

You can use the $node object two ways. First, you can use the Velocity property formalism to access child nodes in the document tree rooted at the current node. So with a document such as :

you could use references like

     $node.section.p.code
  

to access elements and atributes in the subtree, assuming that $node was the 'document' element. Further, you can of course call methods on the sub-elements :

As for methods, $node has the following API for you to use :

The next node-specific reference is $attrib. This corresponds to a collection of the current nodes attributes (if appropriate - for example, an attribute doesn't itself have attributes) which you can use to quickly get the values using Velocity's property reference formalism. So with the example above, if you matched the 'section' node you could find the value of the 'name' attribute via

Which would return 'first'.

The final reference available is $context. This object offers the following API :

DVSL has default patterns to drive the transformation engine just like XSLT does. These patterns currently are modeled after the XSLT default behavior. DVLS differs in that it will offer you the abillity to override the default patterns w/o having to change your stylesheet. The patterns are :

These patterns are registered in the matching engine first, so any patterns specified in the stylesheet will override these definitions.

What this means for the user is that DVSL will automatically start with the root of the document (in the XSL sense, the the 'properly formed document sense') and try to match each element that it finds. Because it has a default rule for elements ("*") it will appply templates to all nodes in each element that it finds. Further it will print out the value of each text ndoes, and each attribute node.

These rules are copied from the XSLT spec. There are two more rules that have been commented out :

which should be there for XSLT spec compliance. If you want them, just uncomment in org.apache.tools.dvsl.resource.defaultroot.dvsl and rebuild the jar.

They are currently left out as they don't seem to be desireable, and it doesn't appear that xalan respects the rules either.