geirm 01/12/18 12:43:48
Added: xdocs index.xml license.xml more-resources.xml
project.xml toolbox.props users-guide.xml
Log:
initial docs set - wanted to cut apart the index.xml that was posted
first to the whiteboard
Revision Changes Path
1.1 jakarta-velocity-dvsl/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>DVSL</title>
<author email="[EMAIL PROTECTED]">Geir Magnusson Jr.</author>
</properties>
<body>
<section name="DVSL : Declarative XML Processing without the Tears">
<p>
DVSL (Declarative Velocity Style Language) is a tool modeled after
XSLT and is intended for general XML transformations. The key
differences are that it
incorporates easy access to Java objects and allows you to use
the Velocity template language and it's features for expresing the
transformation templates.
</p>
<strong> Similarities to XSLT</strong>
<p>
DVSL steals two of the best features of XSLT:
</p>
<ul>
<li>
It uses a declarative syntax like XSLT.
</li>
<li>
Document control and selection is based on XPath.
</li>
</ul>
<strong>Differences From XSLT</strong>
<p>
DVSL differs from XSLT in a few ways
</p>
<ul>
<li>
DVSL's template language is Velocity, so conventional Velocity syntax is
used to get and set data, to perform looping and flow control, etc. All
features of VTL are available.
</li>
<li>
Because DVSL is based on Velocity, it offers a very tight binding to
Java objects. This means that it's easy to access other data sources
from within the DVSL stylesheet, using conventional method call syntax,
allowing you to integrate, collect, and
transform with and to outside data like databases, calculation libraries, etc
</li>
<li>
DVSL also allows the creation of 'dynamic stylesheets' -
ones whose matching rules can be altered
as a group. (see examples)
</li>
</ul>
</section>
<section name="Current Status">
<p>
The current status is best described as 'post experiemental', where the
basic test of styling it's own documentation (this that you are
now reading)
without resorting to ugly hacks and kludges
has been passed.
</p>
<p>
The code is still very primitive (and downright embarassing in places...),
and the object model (from the template POV) is still crystalizing, and
no performance work has been done.
</p>
</section>
<section name="Nightly Snapshots">
<p>
Nightly snapshots of CVS will soon be available.
</p>
</section>
<section name="CVS Access">
<p>
Access to the DVSL CVS repository is available :
</p>
<ul>
<li><a href="http://cvs.apache.org/viewcvs/jakarta-velocity-dvsl/";>Online</a>
via ViewCVS in your browser.
</li>
<li>
Using a <a href="http://jakarta.apache.org/getinvolved/cvsindex.html";>cvs
client</a>
</li>
</ul>
</section>
</body>
</document>
1.1 jakarta-velocity-dvsl/xdocs/license.xml
Index: license.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Apache Software License</title>
<author email="[EMAIL PROTECTED]">
Velocity Documentation Team</author>
</properties>
<body>
<section name="Apache Software License">
<source test=""><![CDATA[
/*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowledgement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgement may appear in the software itself,
* if and wherever such third-party acknowledgements normally appear.
*
* 4. The names "The Jakarta Project", "Velocity", "DVSL" and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact [EMAIL PROTECTED]
*
* 5. Products derived from this software may not be called "Apache",
* "Velocity" nor may "Apache" appear in their names without prior
* written permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
]]></source>
</section>
</body>
</document>
1.1 jakarta-velocity-dvsl/xdocs/more-resources.xml
Index: more-resources.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Apache Software License</title>
<author email="[EMAIL PROTECTED]">
DVSL Documentation Team</author>
</properties>
<body>
<section name="More Information">
<p>
For a good basic tutorial on XPAth, see
<a href="http://www.zvon.org/xxl/XPathTutorial/General/examples.html";>
this site</a> at <a href="http://www.zevon.org";>Zevon.org</a>
</p>
</section>
</body>
</document>
1.1 jakarta-velocity-dvsl/xdocs/project.xml
Index: project.xml
===================================================================
<?xml version="1.0"?>
<project>
<title>DVSL</title>
<logo href="/images/logo.gif"> < :) /></logo>
<body>
<menu name="Velocity">
<item name="Velocity Home"
href="http://jakarta.apache.org/velocity/"/>
</menu>
<menu name="About">
<item name="DVSL Home" href="/index.html"/>
<item name="Getting Started" href="/users-guide.html#Getting Started
: Building and Using"/>
<item name="License" href="/license.html"/>
</menu>
<menu name="Documentation">
<item name="Users Guide" href="/users-guide.html"/>
<item name="More Resources" href="/more-resources.html"/>
</menu>
<menu name="Community">
<item name="Get Involved"
href="http://jakarta.apache.org/site/getinvolved.html"/>
<item name="CVS Repository"
href="http://jakarta.apache.org/site/cvsindex.html"/>
<item name="Mailing List"
href="http://jakarta.apache.org/site/mail.html"/>
</menu>
</body>
</project>
1.1 jakarta-velocity-dvsl/xdocs/toolbox.props
Index: toolbox.props
===================================================================
toolbox.contextname = toolbox
toolbox.tool.htmlescape = org.apache.velocity.anakia.Escape
1.1 jakarta-velocity-dvsl/xdocs/users-guide.xml
Index: users-guide.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>DVSL User Guide</title>
<author email="[EMAIL PROTECTED]">Geir Magnusson Jr.</author>
</properties>
<body>
<section name="DVSL Users Guide">
<p>
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:
</p>
<ul>
<li>
It uses a declarative syntax like XSLT.
</li>
<li>
Document control and selection is based on XPath.
</li>
</ul>
<p>
DVSL's template language is <a href="http://jakarta.apache.org/velocity/";>
Velocity</a>, 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.
</p>
</section>
<section name="Getting Started : Building and Using">
<strong>Where to Get DVSL</strong>
<p>
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.
</p>
<strong>How to Build</strong>
<p>
Building DVSL is very simple. All dependency jars that are required
are included in the distribution. However, we do require that
<a href="http://jakarta.apache.org/ant/";>Jakarta Ant</a> is installed.
</p>
<p>
Once ant is installed, you simply need to change to the project
root directory and invoke ant with the 'jar' target :
</p>
<source>
$ cd jakarta-velocity-dvsl
$ ant jar
</source>
<p>
This will build the dvsl jar in the project root directory.
</p>
<strong>Using DVSL</strong>
<p>
While DVSL is also a tool that can be integrated into your applications,
DVSL is able to be used without any programming.
</p>
<p>
The first way is via commandline, where you can use it to transform a single
file, or as a filter.
The usage is :
</p>
<code>
java org.apache.tools.dvsl.DVSL -STYLE <i>stylesheet</i> [-IN <i>infile</i>]
[-OUT <i>outfile</i> ]
</code>
<p>
Note that the stylesheet is the only required element, and the input and output
then default to
<code>stdin</code> and <code>stdout</code>.
By adding the appropriate stuff in your classpath (that would be all the jars in
the project
<code>lib</code> directory ), you can use it :
</p>
<source>
<![CDATA[
java org.apache.tools.dvsl.DVSL -STYLE src/stylesheets/site.dvsl -IN
xdocs/index.xml > out.stuff
java org.apache.tools.dvsl.DVSL -STYLE src/stylesheets/site.dvsl -OUT out.html <
xdocs/index.html
java org.apache.tools.dvsl.DVSL -STYLE src/stylesheets/site.dvsl <
xdocs/index.xml
]]>
</source>
<p>
You can also use DVSL right from ant using the included Ant task. The Ant task
supports the toolbox.
</p>
<source>
<![CDATA[
<target name="docs">
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
<classpath>
<pathelement location="${project.name}-${project.version}.jar"/>
<path refid="classpath"/>
</classpath>
</taskdef>
<dvsl
basedir="${docs.src}"
destdir="${docs.dest}/"
toolbox="${docs.src}/toolbox.props"
extension=".html"
style="${source.home}/stylesheets/site.dvsl"
excludes="**/project.xml"
includes="**/*.xml"
/>
</target>
]]>
</source>
</section>
<section name="Starting with Examples">
<p>
A few examples are provided with the current distribution, in the
<code>examples</code>
directory in the distribution, and the examples that follow were originally taken
from there.
</p>
<strong>Simmple Example</strong>
<p>
To begin, we will start with a simple example. Here is a basic XML document
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<document>
<section name="foo">
<p>
Hello from section foo
</p>
</section>
<section name="bar">
<p>
Hello from section bar
</p>
</section>
</document>
]]></source>
<p>
A simple DVSL stylesheet to transform this into HTML might look like :
</p>
<source><![CDATA[
#match("document")
<html>
<body>
$context.applyTemplates()
</body>
</html>
#end
#match("section")
<hr>
<b>Section:</b> $attrib.name
$context.applyTemplates("p")
#end
#match("p")
<blockquote>
$node.copy( $node.children() )
</blockquote>
#end
]]></source>
<p>
With the resulting output of
</p>
<source><![CDATA[
<html>
<body>
<hr>
<b>Section:</b> foo
<blockquote>
Hello from section foo
</blockquote>
<hr>
<b>Section:</b> bar
<blockquote>
Hello from section bar
</blockquote>
</body>
</html>
]]></source>
<p>
This can be found in examples/simple and is example1.xml and example1.dvsl.
</p>
<strong>Now Add Some External Tools</strong>
<p>
A more interesting example involves specifying and using tools. We'll give an
example and explain the toolbox later on.
</p>
<p>
A simple toolbox example is included, in examples/toolbox. First, you must
define the tools and values in a properties file
</p>
<source>
toolbox.contextname = toolbox
toolbox.tool.footool = Footool
toolbox.string.mystring = Hello there!
toolbox.integer.myint = 7
</source>
<p>
Here we do a couple of things :
</p>
<ol>
<li>
<code>toolbox.contextname = toolbox</code> :
defines 'toolbox' as the name we will use in the template
to access the tools.
</li>
<li>
<code>toolbox.tool.footool = Footool</code> : defines that an instance
of the class 'Footool' will be placed in the context under the key 'footool'.
</li>
<li>
<code>toolbox.string.mystring = Hello there!</code> : defines that a
<code>java.lang.String</code>
"Hello there!" will be placed in the context under the key 'mystring'
</li>
<li>
<code>toolbox.integer.myint = 7</code> : defines that a
<code>java.lang.Integer</code> will be placed in the context under the
key 'myint'.
</li>
</ol>
<p>
You specify the toolbox in the <dvsl> task in the ant script as
such :
</p>
<source><![CDATA[
<dvsl
basedir="${docs.src}"
destdir="${docs.dest}/"
extension=".html"
style="${docs.src}/site.dvsl"
excludes="**/project.xml"
toolbox="toolbox.props"
includes="**/*.xml"
/>
]]></source>
<p>
To use the tools, this is the stylesheet that has an example :
</p>
<source><![CDATA[
#match("document")
Hello from the document node.
From the toolbox :
Method : $context.toolbox.footool.getFoo()
String : $context.toolbox.mystring
Int : $context.toolbox.myint
#foreach( $data in $context.toolbox.footool.getList() )
Item $velocityCount : $data
#end
#end
]]></source>
<p>
With an input of :
</p>
<source><![CDATA[
<?xml version="1.0"?>
<document value="5">
Data in <document> node
</document>
]]></source>
<p>
And with the class Footool
</p>
<source><![CDATA[
import java.util.List;
public class Footool
{
public String getFoo()
{
return "Hello from Foo!";
}
public List getList()
{
List list = new java.util.ArrayList();
list.add( "red" );
list.add( "blue" );
list.add( "green" );
return list;
}
}
]]></source>
<p>
You get the output
</p>
<source><![CDATA[
Hello from the document node.
From the toolbox :
Method : Hello from Foo!
String : Hello there!
Int : 7
Item 1 : red
Item 2 : blue
Item 3 : green
]]></source>
<p>
This can be found in <code>examples/toolbox</code>.
</p>
<p>
Also, the <code>examples/velocitydocs</code> example shows how to grab
and use the HTMLEscape class from the Velocity jar as a tool to do
escaping.
</p>
</section>
<section name="The 'Template API'">
<p>
Writing templates is very simple. The basic template definition uses the directive
</p>
<source>
#match( <XPath Expression > )
< template content >
#end
</source>
<p>
This directive declares that when a node matches the <code><XPath Expression
></code>
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.
</p>
<p>
<i>Future plans include a #name() directive, and optional arguments to the #match()
and #name() directives to support modes and namsepaces.</i>
</p>
<strong>The Node API</strong>
<p>
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().
</p>
<p>
The most important is the current Node, which is accessible via the reference
<code>$node</code>. The <code>$node</code> is the current node that matched
the template XPath expression (or name).
</p>
<p>
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 :
</p>
<source><![CDATA[
<?xml version="1.0"?>
<document>
<section name="first">
<p>
<code>foo</code>
</p>
<p>
<code>bar</code>
</p>
</section>
</document>
]]></source>
<p>
you could use references like
</p>
<pre>
$node.section.p.code
</pre>
<p>
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 :
</p>
<pre>
$node.section.children()
</pre>
<p>As for methods, <code>$node</code> has the following API
for you to use :
</p>
<table>
<tr>
<th>Reference</th><th>Methods</th><th>Description</th>
</tr>
<tr>
<td>$node</td><td></td><td>Current node for this template match.</td>
</tr>
<tr>
<td></td><td>$node.name()</td><td>Element name of node - ex 'table' </td>
</tr>
<tr>
<td></td><td>$node.value()</td><td>Text content of node </td>
</tr>
<tr>
<td></td><td>$node.attrib("name")</td><td>Returns attribute of node if
appropriate. </td>
</tr>
<tr>
<td></td><td>$node.selectNodes( xpath )</td><td>Returns an iteratable list of
nodes that satisfy the XPath expression</td>
</tr>
<tr>
<td></td><td>$node.selectSingleNode( xpath )</td><td>Returns the first node that
satisfies the XPath expression</td>
</tr>
<tr>
<td></td><td>$node.get( xpath )</td><td>Returns the first node that satisfies
the XPath expression</td>
</tr>
<tr>
<td></td><td>$node.children()</td><td>Returns a List of all children of this
node</td>
</tr>
<tr>
<td></td><td>$node.copy()</td><td>Does a 'deep copy' of this node's subtree to
the output</td>
</tr>
<tr>
<td></td><td>$node.copy( List )</td><td>Does a 'deep copy' of the specified
nodelist to the output.</td>
</tr>
</table>
<p>
The next node-specific reference is <code>$attrib</code>. 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
</p>
<pre>
$attrib.name
</pre>
<p>
Which would return 'first'.
</p>
<p>
The final reference available is <code>$context</code>. This object offers the
following API :
</p>
<table>
<tr>
<th>Reference</th><th>Methods</th><th>Description</th>
</tr>
<tr>
<td>$context</td><td></td><td>Utility context.</td>
</tr>
<tr>
<td></td><td>$context.applyTemplates()</td><td>Applies all templates in the
subtree against the ruleset.</td>
</tr>
<tr>
<td></td><td>$context.applyTemplates( XPath )</td>
<td>Applies templates to all nodes in the subtree
that match the given XPath expression. Ex. <code> $context.applyTemplates(
"*|@*" ) </code></td>
</tr>
<tr>
<td></td><td>$context.applyTemplates( Node )</td>
<td>Applies templates to the specified node. First match is applied.</td>
</tr>
<tr>
<td></td><td>$context.applyTemplates( Node, XPath )</td>
<td>Applies the XPath expression to the specified node, and applies
templates to the resulting nodeset.</td>
</tr>
<tr>
<td></td><td>$context.applyTemplates( Node, XPath )</td>
<td>Applies the XPath expression to the specified node, and applies
templates to the resulting nodeset.</td>
</tr>
</table>
</section>
<section name="Default Template Rules">
<p>
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 :
</p>
<source><![CDATA[
#match( "/" )$context.applyTemplates()#end
#match("*")$context.applyTemplates()#end
]]></source>
<p>
These patterns are registered in the matching engine first, so any
patterns specified in the stylesheet will override these definitions.
</p>
<p>
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.
</p>
<p>
These rules are copied from the XSLT spec. There are two more rules
that have been commented out :
</p>
<source><![CDATA[
#match("text()")$node.value()#end
#match("@*")$node.value()#end
]]></source>
<p>
which should be there for XSLT spec compliance. If you want them, just
uncomment in <code>org.apache.tools.dvsl.resource.defaultroot.dvsl</code>
and rebuild the jar.
</p>
<p>
They are currently left out as they don't seem to be desireable, and it
doesn't appear that xalan respects the rules either.
</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
