| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <html> |
| <head> |
| <title>Apache DVSL - |
| DVSL User Guide</title> |
| <style type="text/css" media="all"> |
| @import url("./css/maven-base.css"); |
| @import url("./css/maven-theme.css"); |
| @import url("./css/site.css"); |
| </style> |
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> |
| <link rel="alternate" href="http://feeds.feedburner.com/ApacheVelocitySiteNews" type="application/rss+xml" title="Apache DVSL - |
| DVSL User Guide News" /> |
| <meta name="author" content=" |
| Geir Magnusson Jr." /> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="../../../" id="bannerLeft"> |
| |
| <img src="images/velocity_project_wide.png" alt="" /> |
| |
| </a> |
| <span id="bannerRight"> |
| |
| <img src="images/dvsl.png" alt="" /> |
| |
| </span> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="xleft"> |
| |
| <a href="http://www.apache.org/">Apache</a> |
| > |
| |
| <a href="../../../">Velocity</a> |
| > |
| |
| DVSL |
| </div> |
| <div class="xright"> <a href="../../../engine/devel/">Engine</a> |
| | |
| <a href="../../../tools/devel/">Tools</a> |
| | |
| <a href="../../../anakia/devel/">Anakia</a> |
| | |
| <a href="../../../texen/devel/">Texen</a> |
| | |
| <a href="../../../docbook/">DocBook</a> |
| | |
| <a href="../../devel/">DVSL</a> |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h5>DVSL</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="index.html">General</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../download.cgi">Download</a> |
| </li> |
| </ul> |
| <h5>Documentation</h5> |
| <ul> |
| |
| <li class="none"> |
| <strong>User Guide</strong> |
| </li> |
| |
| <li class="none"> |
| <a href="ant_task_reference.html">Ant Task Reference</a> |
| </li> |
| |
| <li class="none"> |
| <a href="more-resources.html">More Resources</a> |
| </li> |
| </ul> |
| <h5>Community</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/">Wiki</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/GetInvolved">Get Involved</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../contact.html">Mailing Lists</a> |
| </li> |
| </ul> |
| <h5>Velocity Development</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/CodeStandards">Coding Standards</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/velocity/DocumentationGuidelines">Documentation Guidelines</a> |
| </li> |
| |
| <li class="none"> |
| <a href="https://issues.apache.org/jira/browse/DVSL">Issues</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../../who-we-are.html">Who we are</a> |
| </li> |
| </ul> |
| <h5>Project Documentation</h5> |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="project-info.html">Project Information</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="project-reports.html">Project Reports</a> |
| </li> |
| </ul> |
| |
| |
| |
| <a class="poweredBy" href="../../../" title="Apache Velocity" ><img class="poweredBy" alt="Apache Velocity" src="images/pbv90x30.png" /></a> |
| |
| |
| |
| <a class="poweredBy" href="../../../rss/news.rss" title="Velocity News Feed" ><img class="poweredBy" alt="Velocity News Feed" src="images/feed-icon-24x24.jpg" /></a> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| |
| |
| <a name="dvsl_user_guide"></a><div class="section"><h2>DVSL User Guide</h2> |
| |
| <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://velocity.apache.org/engine/devel/vtl-reference-guide.html" class="externalLink"> |
| 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> |
| |
| </div> |
| |
| |
| <a name="getting_started_:_building_and_using"></a><div class="section"><h2>Getting Started : Building and Using</h2> |
| |
| <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 Subversion. |
| </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://ant.apache.org" class="externalLink">Apache 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> |
| |
| <div class="source"><pre> |
| $ cd dvsl |
| $ ant jar |
| </pre></div> |
| |
| <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 command line, where you can use it to transform a single file, or as a filter. |
| The usage is : |
| </p> |
| |
| <code> |
| java org.apache.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> |
| |
| <div class="source"><pre> |
| java org.apache.dvsl.DVSL -STYLE src/stylesheets/site.dvsl -IN xdocs/index.xml > out.stuff |
| java org.apache.dvsl.DVSL -STYLE src/stylesheets/site.dvsl -OUT out.html < xdocs/index.html |
| java org.apache.dvsl.DVSL -STYLE src/stylesheets/site.dvsl < xdocs/index.xml |
| </pre></div> |
| |
| <p> |
| You can also use DVSL right from ant using the included Ant task. The Ant task supports the toolbox. |
| </p> |
| |
| <div class="source"><pre> |
| <target name="docs"> |
| |
| <taskdef name="dvsl" classname="org.apache.dvsl.DVSLTask"> |
| <classpath> |
| <pathelement location="${project.name}-${project.version}.jar"/> |
| <path refid="classpath"/> |
| </classpath> |
| </taskdef> |
| |
| <dvsl |
| basedir="${docs.src}" |
| destdir="${docs.dest}/" |
| toolboxfile="${docs.src}/toolbox.props" |
| extension=".html" |
| style="${source.home}/stylesheets/site.dvsl" |
| excludes="**/project.xml" |
| includes="**/*.xml" |
| /> |
| </target> |
| </pre></div> |
| |
| |
| |
| <p> |
| For more information on using DVSL from Ant, please see the |
| <a href="ant_task_reference.html">Ant Task Reference</a>. |
| </p> |
| |
| |
| </div> |
| |
| <a name="starting_with_examples"></a><div class="section"><h2>Starting with Examples</h2> |
| |
| <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>Simple Example</strong> |
| |
| <p> |
| To begin, we will start with a simple example. Here is a basic XML document: |
| </p> |
| |
| <div class="source"><pre> |
| |
| <?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> |
| </pre></div> |
| |
| <p> |
| A simple DVSL stylesheet to transform this into HTML might look like : |
| </p> |
| |
| <div class="source"><pre> |
| #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 |
| </pre></div> |
| |
| <p> |
| With the resulting output of |
| </p> |
| |
| <div class="source"><pre> |
| <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> |
| </pre></div> |
| |
| <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> |
| |
| <div class="source"><pre> |
| toolbox.contextname = toolbox |
| toolbox.tool.footool = Footool |
| toolbox.string.mystring = Hello there! |
| toolbox.integer.myint = 7 |
| </pre></div> |
| |
| <p> |
| Here we do a couple of things : |
| </p> |
| |
| <ol type="1"> |
| <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> |
| |
| <div class="source"><pre> |
| <dvsl |
| basedir="${docs.src}" |
| destdir="${docs.dest}/" |
| extension=".html" |
| style="${docs.src}/site.dvsl" |
| excludes="**/project.xml" |
| toolboxfile="toolbox.props" |
| includes="**/*.xml |
| /> |
| </pre></div> |
| |
| <p> |
| To use the tools, this is the stylesheet that has an example : |
| </p> |
| |
| <div class="source"><pre> |
| #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 |
| </pre></div> |
| |
| <p> |
| With an input of : |
| </p> |
| |
| <div class="source"><pre> |
| <?xml version="1.0"?> |
| |
| <document value="5"> |
| |
| Data in &lt;document&gt; node |
| |
| </document> |
| </pre></div> |
| |
| <p> |
| And with the class Footool |
| </p> |
| |
| <div class="source"><pre> |
| 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; |
| } |
| } |
| </pre></div> |
| |
| <p> |
| You get the output |
| </p> |
| |
| <div class="source"><pre> |
| 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 |
| </pre></div> |
| |
| <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> |
| |
| </div> |
| |
| <a name="the_template_api"></a><div class="section"><h2>The 'Template API'</h2> |
| |
| <p> |
| Writing templates is very simple. The basic template definition uses the directive |
| </p> |
| |
| <div class="source"><pre> |
| #match(<XPath Expression >) |
| < template content > |
| #end |
| </pre></div> |
| |
| <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> |
| |
| <div class="source"><pre> |
| <?xml version="1.0"?> |
| <document> |
| <section name="first"> |
| <p> |
| <code>foo</code> |
| </p> |
| <p> |
| <code>bar</code> |
| </p> |
| </section> |
| </document> |
| </pre></div> |
| |
| <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> |
| |
| <div class="source"><pre> |
| $node.section.children() |
| </pre></div> |
| |
| <p>As for methods, <code>$node</code> has the following API |
| for you to use : |
| </p> |
| |
| <table class="bodyTable"> |
| <tr class="a"> |
| <th >Reference</th><th >Methods</th><th >Description</th> |
| </tr> |
| <tr class="b"> |
| <td >$node</td><td ></td><td >Current node for this template match.</td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$node.name()</td><td >Element name of node - ex 'table' </td> |
| </tr> |
| <tr class="b"> |
| <td ></td><td >$node.value()</td><td >Text content of node </td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$node.attrib("name")</td><td >Returns attribute of node if appropriate. </td> |
| </tr> |
| <tr class="b"> |
| <td ></td><td >$node.selectNodes(xpathexpr)</td><td >Returns an iteratable list of nodes that satisfy the XPath expression</td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$node.selectSingleNode(xpathexpr)</td><td >Returns the first node that satisfies the XPath expression</td> |
| </tr> |
| <tr class="b"> |
| <td ></td><td >$node.get(xpathexpr)</td><td >Returns the first node that satisfies the XPath expression</td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$node.children()</td><td >Returns a List of all children of this node</td> |
| </tr> |
| <tr class="b"> |
| <td ></td> |
| <td >$node.copy()</td> |
| <td >Does a 'deep copy' of this node's subtree to the output</td> |
| </tr> |
| <tr class="a"> |
| <td ></td> |
| <td >$node.copy(List)</td> |
| <td >Does a 'deep copy' of the specified nodelist to the output.</td> |
| </tr> |
| <tr class="b"> |
| <td ></td> |
| <td >$node.valueOf(xpathexpr)</td> |
| <td >Returns the result of the specified XPath as a Object</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> |
| |
| <div class="source"><pre> |
| $attrib.name |
| </pre></div> |
| |
| <p> |
| Which would return 'first'. |
| </p> |
| |
| <p> |
| The final reference available is <code>$context</code>. This object offers the |
| following API : |
| </p> |
| |
| <table class="bodyTable"> |
| <tr class="a"> |
| <th >Reference</th><th >Methods</th><th >Description</th> |
| </tr> |
| <tr class="b"> |
| <td >$context</td><td ></td><td >Utility context.</td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$context.applyTemplates()</td><td >Applies all templates in the subtree against the ruleset.</td> |
| </tr> |
| <tr class="b"> |
| <td ></td><td >$context.applyTemplates(xpathexpr)</td> |
| <td >Applies templates to all nodes in the subtree |
| that match the given XPath expression. Ex. <code> $context.applyTemplates("*|@*") </code></td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$context.applyTemplates(Node)</td> |
| <td >Applies templates to the specified node. First match is applied.</td> |
| </tr> |
| <tr class="b"> |
| <td ></td><td >$context.applyTemplates(Node, xpathexpr)</td> |
| <td >Applies the XPath expression to the specified node, and applies |
| templates to the resulting nodeset.</td> |
| </tr> |
| <tr class="a"> |
| <td ></td><td >$context.applyTemplates(Node, xpathexpr)</td> |
| <td >Applies the XPath expression to the specified node, and applies |
| templates to the resulting nodeset.</td> |
| </tr> |
| <tr class="b"> |
| <td ></td><td >$context.getAppValue(Object key)</td> |
| <td >Returns the application value for this key. For example, Ant will |
| place the current input file name under the key "infilename".</td> |
| </tr> |
| |
| </table> |
| |
| </div> |
| |
| |
| |
| <a name="default_template_rules"></a><div class="section"><h2>Default Template Rules</h2> |
| |
| <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> |
| |
| <div class="source"><pre> |
| #match("/")$context.applyTemplates()#end |
| |
| #match("*")$context.applyTemplates()#end |
| </pre></div> |
| |
| <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> |
| |
| <div class="source"><pre> |
| #match("text()")$node.value()#end |
| |
| #match("@*")$node.value()#end |
| </pre></div> |
| |
| <p> |
| which should be there for XSLT spec compliance. If you want them, just |
| uncomment in <code>org.apache.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> |
| |
| </div> |
| |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">© |
| 2002-2007 |
| |
| The Apache Software Foundation |
| |
| |
| |
| |
| |
| |
| |
| |
| Last Published: 2007-08-13 16:24:20 |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |