1 | <html>
|
---|
2 |
|
---|
3 | <head>
|
---|
4 | <meta http-equiv="Content-Language" content="en-us">
|
---|
5 | <title>Xslt/Style Task</title>
|
---|
6 | <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
|
---|
7 | </head>
|
---|
8 |
|
---|
9 | <body>
|
---|
10 |
|
---|
11 | <h2><a name="style">Xslt/Style</a></h2>
|
---|
12 | <h3>Description</h3>
|
---|
13 | <p>Process a set of documents via XSLT.</p>
|
---|
14 | <p>This is useful for building views of XML based documentation,
|
---|
15 | or for generating code.</p>
|
---|
16 | <p><b>Note:</b> If you are using JDK 1.4 or higher, this task does not require external libraries
|
---|
17 | not supplied in the Ant distribution. Otherwise,
|
---|
18 | see <a href="../install.html#librarydependencies">Library Dependencies</a> for more information.</p>
|
---|
19 | <p>It is possible to refine the set of files that are being processed. This can be
|
---|
20 | done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
|
---|
21 | attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
|
---|
22 | have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
|
---|
23 | the files you want to have excluded. This is also done with patterns. And
|
---|
24 | finally with the <i>defaultexcludes</i> attribute, you can specify whether you
|
---|
25 | want to use default exclusions or not. See the section on <a
|
---|
26 | href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
|
---|
27 | inclusion/exclusion of files works, and how to write patterns.</p>
|
---|
28 | <p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and supports all
|
---|
29 | attributes of <code><fileset></code> (<code>dir</code> becomes <code>basedir</code>)
|
---|
30 | as well as the nested <code><include></code>, <code><exclude></code>
|
---|
31 | and <code><patternset></code> elements.</p>
|
---|
32 |
|
---|
33 | <p><b>Note</b>: Unlike other similar tasks, this task treats
|
---|
34 | directories that have been matched by the include/exclude patterns of
|
---|
35 | the implicit fileset in a special way. It will apply the stylesheets
|
---|
36 | to all files contain in them as well. Since the default include
|
---|
37 | pattern is <code>**</code> this means it will apply the stylesheet to
|
---|
38 | all files. If you specify an excludes pattern, it may still work on
|
---|
39 | the files matched by those patterns because the parent directory has
|
---|
40 | been matched. If this behavior is not what you want, set the
|
---|
41 | scanincludedirectories attribute to false.</p>
|
---|
42 |
|
---|
43 | <p>This task supports the use of a nested <code><param></code> element which is used to pass values
|
---|
44 | to an <code><xsl:param></code> declaration.</p>
|
---|
45 | <p>This task supports the use of a nested <a href="../CoreTypes/xmlcatalog.html">xmlcatalog</a>
|
---|
46 | element which is used to perform Entity and URI resolution</p>
|
---|
47 | <p><i><code><style></code> and <code><xslt></code> refer to the same Ant task and can be used interchangeably.</i></p>
|
---|
48 | <p>If you want to use Xalan-J 1 or XSL:P, you also need Ant's optional.jar</p>
|
---|
49 | <h3>Parameters</h3>
|
---|
50 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
51 | <tr>
|
---|
52 | <td valign="top"><b>Attribute</b></td>
|
---|
53 | <td valign="top"><b>Description</b></td>
|
---|
54 | <td align="center" valign="top"><b>Required</b></td>
|
---|
55 | </tr>
|
---|
56 | <tr>
|
---|
57 | <td valign="top">basedir</td>
|
---|
58 | <td valign="top">where to find the source XML file, default is the
|
---|
59 | project's basedir.</td>
|
---|
60 | <td align="center" valign="top">No</td>
|
---|
61 | </tr>
|
---|
62 | <tr>
|
---|
63 | <td valign="top">destdir</td>
|
---|
64 | <td valign="top">directory in which to store the results.</td>
|
---|
65 | <td align="center" valign="top">Yes, unless in and out have been
|
---|
66 | specified.</td>
|
---|
67 | </tr>
|
---|
68 | <tr>
|
---|
69 | <td valign="top">extension</td>
|
---|
70 | <td valign="top">desired file extension to be used for the targets. If not
|
---|
71 | specified, the default is ".html". Will be ignored if
|
---|
72 | a nested <code><mapper></code> has been specified.</td>
|
---|
73 | <td align="center" valign="top">No</td>
|
---|
74 | </tr>
|
---|
75 | <tr>
|
---|
76 | <td valign="top">style</td>
|
---|
77 | <td valign="top">name of the stylesheet to use - given either relative
|
---|
78 | to the project's basedir or as an absolute path
|
---|
79 | <em><strong>DEPRECATED</strong> - can be specified as a path relative
|
---|
80 | to the basedir attribute of this task as well</em>.
|
---|
81 | </td>
|
---|
82 | <td align="center" valign="top">Yes</td>
|
---|
83 | </tr>
|
---|
84 | <tr>
|
---|
85 | <td valign="top">classpath</td>
|
---|
86 | <td valign="top">the classpath to use when looking up the XSLT
|
---|
87 | processor.</td>
|
---|
88 | <td align="center" valign="top">No</td>
|
---|
89 | </tr>
|
---|
90 | <tr>
|
---|
91 | <td valign="top">classpathref</td>
|
---|
92 | <td valign="top">the classpath to use, given as <a
|
---|
93 | href="../using.html#references">reference</a> to a path defined elsewhere.</td>
|
---|
94 | <td align="center" valign="top">No</td>
|
---|
95 | </tr>
|
---|
96 | <tr>
|
---|
97 | <td valign="top">force</td>
|
---|
98 | <td valign="top">Recreate target files, even if they are newer
|
---|
99 | than their corresponding source files or the stylesheet.</td>
|
---|
100 | <td valign="top" align="center">No; default is false</td>
|
---|
101 | </tr>
|
---|
102 | <tr>
|
---|
103 | <td valign="top">processor</td>
|
---|
104 |
|
---|
105 | <td valign="top">name of the XSLT processor to use. Permissible values are
|
---|
106 | "trax" for a TraX compliant processor (ie JAXP interface
|
---|
107 | implementation such as Xalan 2 or Saxon),
|
---|
108 | "xslp" for the XSL:P processor, "xalan" for
|
---|
109 | the Apache XML Xalan (version 1) processor the name of an
|
---|
110 | arbitrary XSLTLiaison class. Defaults to trax, followed by xalan
|
---|
111 | and then xslp (in that order). The first one found in your class
|
---|
112 | path is the one that is used.
|
---|
113 |
|
---|
114 | <em><strong>DEPRECATED</strong> - XSL:P and xalan are deprecated and no
|
---|
115 | more supported.</em>.
|
---|
116 | </td>
|
---|
117 | <td align="center" valign="top">No</td>
|
---|
118 | </tr>
|
---|
119 | <tr>
|
---|
120 | <td valign="top">includes</td>
|
---|
121 | <td valign="top">comma- or space-separated list of patterns of files that must be included.
|
---|
122 | All files are included when omitted.</td>
|
---|
123 | <td valign="top" align="center">No</td>
|
---|
124 | </tr>
|
---|
125 | <tr>
|
---|
126 | <td valign="top">includesfile</td>
|
---|
127 | <td valign="top">the name of a file. Each line of this file is taken to be
|
---|
128 | an include pattern</td>
|
---|
129 | <td valign="top" align="center">No</td>
|
---|
130 | </tr>
|
---|
131 | <tr>
|
---|
132 | <td valign="top">excludes</td>
|
---|
133 | <td valign="top">comma- or space-separated list of patterns of files that must be excluded.
|
---|
134 | No files (except default excludes) are excluded when omitted.</td>
|
---|
135 | <td valign="top" align="center">No</td>
|
---|
136 | </tr>
|
---|
137 | <tr>
|
---|
138 | <td valign="top">excludesfile</td>
|
---|
139 | <td valign="top">the name of a file. Each line of this file is taken to be
|
---|
140 | an exclude pattern</td>
|
---|
141 | <td valign="top" align="center">No</td>
|
---|
142 | </tr>
|
---|
143 | <tr>
|
---|
144 | <td valign="top">defaultexcludes</td>
|
---|
145 | <td valign="top">indicates whether default excludes should be used or not
|
---|
146 | ("yes"/"no"). Default excludes are used when omitted.</td>
|
---|
147 | <td valign="top" align="center">No</td>
|
---|
148 | </tr>
|
---|
149 | <tr>
|
---|
150 | <td valign="top">in</td>
|
---|
151 | <td valign="top">specifies a single XML document to be styled. Should be used
|
---|
152 | with the out attribute.</td>
|
---|
153 | <td valign="top" align="center">No</td>
|
---|
154 | </tr>
|
---|
155 | <tr>
|
---|
156 | <td valign="top">out</td>
|
---|
157 | <td valign="top">specifies the output name for the styled result from the
|
---|
158 | in attribute.</td>
|
---|
159 | <td valign="top" align="center">No</td>
|
---|
160 | </tr>
|
---|
161 | <tr>
|
---|
162 | <td valign="top">scanincludeddirectories</td>
|
---|
163 | <td valign="top">If any directories are matched by the
|
---|
164 | includes/excludes patterns, try to transform all files in these
|
---|
165 | directories. Default is <code>true</code></td>
|
---|
166 | <td valign="top" align="center">No</td>
|
---|
167 | </tr>
|
---|
168 | <tr>
|
---|
169 | <td valign="top">reloadstylesheet</td>
|
---|
170 | <td valign="top">Control whether the stylesheet transformer is created
|
---|
171 | anew for every transform opertaion. If you set this to true, performance may
|
---|
172 | suffer, but you may work around a bug in certain Xalan-J versions.
|
---|
173 | Default is <code>false</code>. <em>Since Ant 1.5.2</em>.</td>
|
---|
174 | <td valign="top" align="center">No</td>
|
---|
175 | </tr>
|
---|
176 | </table>
|
---|
177 | <h3>Parameters specified as nested elements</h3>
|
---|
178 | <h4>classpath</h4>
|
---|
179 | <p>The classpath to load the processor from can be specified via a
|
---|
180 | nested <code><classpath></code>, as well - that is, a
|
---|
181 | <a href="../using.html#path">path</a>-like structure.</p>
|
---|
182 |
|
---|
183 | <h4>xmlcatalog</h4>
|
---|
184 | <p>The <a href="../CoreTypes/xmlcatalog.html">xmlcatalog</a>
|
---|
185 | element is used to perform Entity and URI resolution.</p>
|
---|
186 |
|
---|
187 | <h4>param</h4>
|
---|
188 | <p>Param is used to pass a parameter to the XSL stylesheet.</p>
|
---|
189 | <h4>Parameters</h4>
|
---|
190 | <table width="60%" border="1" cellpadding="2" cellspacing="0">
|
---|
191 | <tr>
|
---|
192 | <td valign="top"><b>Attribute</b></td>
|
---|
193 | <td valign="top"><b>Description</b></td>
|
---|
194 | <td align="center" valign="top"><b>Required</b></td>
|
---|
195 | </tr>
|
---|
196 | <tr>
|
---|
197 | <td valign="top">name</td>
|
---|
198 | <td valign="top">Name of the XSL parameter</td>
|
---|
199 | <td align="center" valign="top">Yes</td>
|
---|
200 | </tr>
|
---|
201 | <tr>
|
---|
202 | <td valign="top">expression</td>
|
---|
203 | <td valign="top">Text value to be placed into the param.<br/>
|
---|
204 | Was originally intended to be an XSL expression.</td>
|
---|
205 | <td align="center" valign="top">Yes</td>
|
---|
206 | </tr>
|
---|
207 | <tr>
|
---|
208 | <td valign="top">if</td>
|
---|
209 | <td valign="top">The param will only passed if this property is set.</td>
|
---|
210 | <td align="center" valign="top">No</td>
|
---|
211 | </tr>
|
---|
212 | <tr>
|
---|
213 | <td valign="top">unless</td>
|
---|
214 | <td valign="top">The param will only passed unless this property is set.</td>
|
---|
215 | <td align="center" valign="top">No</td>
|
---|
216 | </tr>
|
---|
217 |
|
---|
218 | </table>
|
---|
219 |
|
---|
220 | <h4>outputproperty ('trax' processors only)</h4>
|
---|
221 | <p>Used to specify how you wish the result tree to be output
|
---|
222 | as specified in the <a href="http://www.w3.org/TR/xslt#output">
|
---|
223 | XSLT specifications</a>.
|
---|
224 | <h4>Parameters</h4>
|
---|
225 | <table width="60%" border="1" cellpadding="2" cellspacing="0">
|
---|
226 | <tr>
|
---|
227 | <td valign="top"><b>Attribute</b></td>
|
---|
228 | <td valign="top"><b>Description</b></td>
|
---|
229 | <td align="center" valign="top"><b>Required</b></td>
|
---|
230 | </tr>
|
---|
231 | <tr>
|
---|
232 | <td valign="top">name</td>
|
---|
233 | <td valign="top">Name of the property</td>
|
---|
234 | <td align="center" valign="top">Yes</td>
|
---|
235 | </tr>
|
---|
236 | <tr>
|
---|
237 | <td valign="top">value</td>
|
---|
238 | <td valign="top">value of the property.</td>
|
---|
239 | <td align="center" valign="top">Yes</td>
|
---|
240 | </tr>
|
---|
241 | </table>
|
---|
242 |
|
---|
243 | <h4>factory ('trax' processors only)</h4>
|
---|
244 | Used to specify factory settings.
|
---|
245 | <h4>Parameters</h4>
|
---|
246 | <table width="60%" border="1" cellpadding="2" cellspacing="0">
|
---|
247 | <tr>
|
---|
248 | <td valign="top"><b>Attribute</b></td>
|
---|
249 | <td valign="top"><b>Description</b></td>
|
---|
250 | <td align="center" valign="top"><b>Required</b></td>
|
---|
251 | </tr>
|
---|
252 | <tr>
|
---|
253 | <td valign="top">name</td>
|
---|
254 | <td valign="top">fully qualified classname of the
|
---|
255 | transformer factory to use. For example
|
---|
256 | <tt>org.apache.xalan.processor.TransformerFactoryImpl</tt>
|
---|
257 | or <tt>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</tt>
|
---|
258 | or <tt>net.sf.saxon.TransformerFactoryImpl</tt>...
|
---|
259 | </td>
|
---|
260 | <td align="center" valign="top">No. Defaults to the JAXP lookup mechanism.</td>
|
---|
261 | </tr>
|
---|
262 | </table>
|
---|
263 | <blockquote>
|
---|
264 | <h4>attribute </h4>
|
---|
265 | <p>Used to specify settings of the processor factory.
|
---|
266 | The attribute names and values are entirely processor specific
|
---|
267 | so you must be aware of the implementation to figure them out.
|
---|
268 | Read the documentation of your processor.
|
---|
269 | For example, in Xalan 2.x:
|
---|
270 | <ul>
|
---|
271 | <li>http://xml.apache.org/xalan/features/optimize (boolean)</li>
|
---|
272 | <li>http://xml.apache.org/xalan/features/incremental (boolean)</li>
|
---|
273 | <li>...</li>
|
---|
274 | </ul>
|
---|
275 | And in Saxon 7.x:
|
---|
276 | <ul>
|
---|
277 | <li>http://saxon.sf.net/feature/allow-external-functions (boolean)</li>
|
---|
278 | <li>http://saxon.sf.net/feature/timing (boolean)</li>
|
---|
279 | <li>http://saxon.sf.net/feature/traceListener (string)</li>
|
---|
280 | <li>http://saxon.sf.net/feature/treeModel (integer)</li>
|
---|
281 | <li>http://saxon.sf.net/feature/linenumbering (integer)</li>
|
---|
282 | <li>...</li>
|
---|
283 | </ul>
|
---|
284 | <h4>Parameters</h4>
|
---|
285 | <table width="60%" border="1" cellpadding="2" cellspacing="0">
|
---|
286 | <tr>
|
---|
287 | <td valign="top"><b>Attribute</b></td>
|
---|
288 | <td valign="top"><b>Description</b></td>
|
---|
289 | <td align="center" valign="top"><b>Required</b></td>
|
---|
290 | </tr>
|
---|
291 | <tr>
|
---|
292 | <td valign="top">name</td>
|
---|
293 | <td valign="top">Name of the attribute</td>
|
---|
294 | <td align="center" valign="top">Yes</td>
|
---|
295 | </tr>
|
---|
296 | <tr>
|
---|
297 | <td valign="top">value</td>
|
---|
298 | <td valign="top">value of the attribute.</td>
|
---|
299 | <td align="center" valign="top">Yes</td>
|
---|
300 | </tr>
|
---|
301 | </table>
|
---|
302 | </blockquote>
|
---|
303 |
|
---|
304 | <h4>mapper</h4>
|
---|
305 |
|
---|
306 | <p><em>since Ant 1.6.2</em></p>
|
---|
307 |
|
---|
308 | <p>You can define filename transformations by using a nested <a
|
---|
309 | href="../CoreTypes/mapper.html">mapper</a> element. The default mapper
|
---|
310 | used by <code><xslt></code> removes the file extension from the
|
---|
311 | source file and adds the extension specified via the extension
|
---|
312 | attribute.</p>
|
---|
313 |
|
---|
314 | <h3>Examples</h3>
|
---|
315 | <blockquote>
|
---|
316 | <pre>
|
---|
317 | <style basedir="doc" destdir="build/doc"
|
---|
318 | extension=".html" style="style/apache.xsl"/></pre>
|
---|
319 | <h4>Using an xmlcatalog</h4>
|
---|
320 | <pre>
|
---|
321 | <xslt basedir="doc" destdir="build/doc"
|
---|
322 | extension=".html" style="style/apache.xsl">
|
---|
323 | <xmlcatalog refid="mycatalog"/>
|
---|
324 | </xslt>
|
---|
325 |
|
---|
326 | <xslt basedir="doc" destdir="build/doc"
|
---|
327 | extension=".html" style="style/apache.xsl">
|
---|
328 | <xmlcatalog>
|
---|
329 | <dtd
|
---|
330 | publicId="-//ArielPartners//DTD XML Article V1.0//EN"
|
---|
331 | location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
|
---|
332 | </xmlcatalog>
|
---|
333 | </xslt>
|
---|
334 | </pre>
|
---|
335 | <h4>Using XSL parameters</h4>
|
---|
336 | <pre>
|
---|
337 | <xslt basedir="doc" destdir="build/doc"
|
---|
338 | extension=".html" style="style/apache.xsl">
|
---|
339 | <param name="date" expression="07-01-2000"/>
|
---|
340 | </xslt></pre>
|
---|
341 |
|
---|
342 | <p>Then if you declare a global parameter "date" with the top-level
|
---|
343 | element <xsl:param name="date"/>, the variable
|
---|
344 | <code>$date</code> will subsequently have the value 07-01-2000.
|
---|
345 | </p>
|
---|
346 |
|
---|
347 | <h4>Using output properties</h4>
|
---|
348 | <pre>
|
---|
349 | <xslt in="doc.xml" out="build/doc/output.xml"
|
---|
350 | style="style/apache.xsl">
|
---|
351 | <outputproperty name="method" value="xml";/>
|
---|
352 | <outputproperty name="standalone" value="yes"/>
|
---|
353 | <outputproperty name="encoding" value="iso8859_1"/>
|
---|
354 | <outputproperty name="indent" value="yes"/>
|
---|
355 | </xslt>
|
---|
356 | </pre>
|
---|
357 |
|
---|
358 | <h4>Using factory settings</h4>
|
---|
359 | <pre>
|
---|
360 | <xslt in="doc.xml" out="build/doc/output.xml"
|
---|
361 | style="style/apache.xsl">
|
---|
362 | <factory name="org.apache.xalan.processor.TransformerFactoryImpl">
|
---|
363 | <attribute name="http://xml.apache.org/xalan/features/optimize" value="true"/>
|
---|
364 | </factory>
|
---|
365 | </xslt></pre>
|
---|
366 |
|
---|
367 | <h4>Using a mapper</h4>
|
---|
368 | <pre>
|
---|
369 | <xslt basedir="in" destdir="out"
|
---|
370 | style="style/apache.xsl">
|
---|
371 | <mapper type="glob" from="*.xml.en" to="*.html.en"/>
|
---|
372 | </xslt></pre>
|
---|
373 |
|
---|
374 | <hr>
|
---|
375 | <p align="center">Copyright © 2000-2005 The Apache Software Foundation. All rights
|
---|
376 | Reserved.</p>
|
---|
377 |
|
---|
378 | </body>
|
---|
379 | </html>
|
---|