Section 9.4. Transforming XML Using XSLT

9.4. Transforming XML Using XSLT

The xslt task, also called the style task (the two names are interchangeable in Ant), can process a set of documents via XSLT. This is handy for building nicely formatted views of XML-based documentation in other formats like HTML, or for generating code. How do you use this task to perform XSLT transformations? Example 9-5 shows a build file that puts it to work, transforming style.xml into style.html, using style.xsl.

Example 9-5. Using the xslt/style task ch09/xslt/build.xml

<?xml version="1.0" encoding="UTF-8" ?>  <project default="main" >      <target name="main">          <xslt basedir="." destdir="." extension=".html" includes="style.xml"              style="style.xsl"/>     </target>  </project>

Here's style.xml, the XML document to transform, which holds data about three U.S. states:

<?xml version="1.0" encoding ="UTF-8"?> <states>     <state>         <name>California</name>         <population units="people">33871648</population><!--2000 census-->         <capital>Sacramento</capital>         <bird>Quail</bird>         <flower>Golden Poppy</flower>         <area units="square miles">155959</area>     </state>     <state>         <name>Massachusetts</name>         <population units="people">6349097</population><!--2000 census-->         <capital>Boston</capital>         <bird>Chickadee</bird>         <flower>Mayflower</flower>         <area units="square miles">7840</area>     </state>     <state>         <name>New York</name>         <population units="people">18976457</population><!--2000 census-->         <capital>Albany</capital>         <bird>Bluebird</bird>         <flower>Rose</flower>         <area units="square miles">47214</area>     </state> </states>

In this example, the names of the states are extracted and used to create an HTML document with style.xsl:

<?xml version="1.0" encoding="UTF-8"?>  <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">     <xsl:template match="states">         <HTML>             <BODY>                 <xsl:apply-templates/>             </BODY>         </HTML>     </xsl:template>        <xsl:template match="state">         <P>             <xsl:value-of select="name"/>          </P>     </xsl:template>    </xsl:stylesheet>

Here's the resulting HTML document:

<HTML>     <BODY>              <P>California</P>              <P>Massachusetts</P>              <P>New York</P>     </BODY> </HTML>

The attributes of this task appear in Table 9-6.

If you are using JDK 1.4 or higher, this task doesn't require external libraries. If you're using an earlier JDK, you'll need Xalan from http://xml.apache.org/xalan-j/index.html (or another XSLT processor), and Ant's optional.jar.

Table 9-6. The xslt/style task's attributes
Attribute	Description	Required	Default
`basedir`	Specifies the directory to search for the source XML file.	No	${basedir}
`classpath`	Specifies the classpath to use when searching for the XSLT processor.	No
`classpathref`	Specifies the classpath to use, given as a reference.	No
`defaultexcludes`	Specifies if you want to use default excludes or not. Set to `yes`/`no`.	No	Default excludes are used.
`destdir`	Specifies the directory in which you want to store the results.	Yes, unless `in` and `out` have been specified.
`excludes`	Specifies the patterns matching files to exclude, as a comma- or space-separated list.	No
`excludesfile`	Specifies the name of a file where each line is a pattern matching files to exclude.	No
`extension`	Specifies the file extension to be used for the output files.	No	"`.html`"
`force`	Forces creation of the output files.	No	`false`
`in`	Specifies a single XML document to be transformed. This attribute should be used with the `out` attribute.	No
`includes`	Specifies the patterns matching files to include, as a comma- or space-separated list.	No
`includesfile`	Specifies the name of a file where each line is a pattern matching files to include.	No
`out`	Specifies the output name for the transformed result (specified with the `in` attribute).	No
`processor`	Specifies the name of the XSLT processor to use. Possible values: `trax` for a TraX compliant processor, `xslp` for the XSL:P processor (note that this value has been deprecated, however), `xalan` for the Apache XML Xalan processor (Version 1this value has been deprecated), or the name of an arbitrary XSLTLiaison class. The first one found in your class path is the one that is used.	No	Defaults to `trax`, followed by `xalan` and then `xslp` (in that order).
`reloadstylesheet`	Specifies if the transformer is freshly created for every transformation. Originally introduced to handle a bug in some Xalan-J versions.	No	`false`
`scanincludeddirectories`	Specifies you want to transform files found in any directories specified by the `include` patterns.	No	`TRue`
`style`	Specifies the name of the stylesheet to use for the transformation.	Yes

This task forms an implicit fileset and so supports all attributes of fileset (dir becomes basedir) as well as the nested include, exclude, and patternset elements. You can use nested classpath elements to load the XSLT processor, nested xmlcatalog elements (see Table 9-3) for entity and URI resolution, and attribute elements (see Table 9-4) to specify settings of the processor factory (the attribute names and values are processor specific). The xslt/style task supports the use of nested param elements, whose attributes appear in Table 9-7, to pass values to xsl:param declarations in stylesheets.

Table 9-7. The param element's attributes
Attribute	Description	Required
`name`	Specifies the name of an XSLT parameter you want set	Yes
`expression`	Specifies the text value to be stored in the parameter	Yes
`if`	Specifies you want to pass the parameter only if this property is set	No
`unless`	Specifies you want to pass the parameter only if this property is not set	No

You can use outputproperty elements, whose attributes appear in Table 9-8, with a TraX processor to specify how the result tree should be output.

Table 9-8. The outputproperty element's attributes
Attribute	Description	Required
`name`	Specifies the name of the property to set	Yes
`value`	Specifies the new value of the property	Yes

TraX processors can accept factory elements to specify factory settings. These elements can contain one attribute, name, which specifies the fully qualified classname of the transformer factory to use.

9.4. Transforming XML Using XSLT

Example 9-5. Using the xslt/style task ch09/xslt/build.xml

Table 9-6. The xslt/style task's attributes

Table 9-7. The param element's attributes

Table 9-8. The outputproperty element's attributes