Difference between revisions of "XSLT Module"

From BaseX Documentation
Jump to navigation Jump to search
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains functions and variables to perform XSLT transformations. By default, this module uses Java’s XSLT 1.0 Xalan implementation to transform documents. XSLT 2.0 is used instead if Version 9.x of the [http://www.saxonica.com/ Saxon XSLT Processor] ({{Code|saxon9he.jar}}, {{Code|saxon9pe.jar}}, {{Code|saxon9ee.jar}}) is found in the classpath. A custom transformer can be specified by overwriting the system property {{Code|javax.xml.transform.TransformerFactory}}, as shown in the following Java example:
+
This [[Module Library|XQuery Module]] contains functions and variables to perform XSL transformations. By default, this module uses Java’s XSLT 1.0 Xalan implementation to transform documents. XSLT 3.0 will be enabled if Version 9.x of the [https://www.saxonica.com/ Saxon XSLT Processor] ({{Code|saxon9he.jar}}, {{Code|saxon9pe.jar}}, {{Code|saxon9ee.jar}}) is found in the classpath (see [[Startup#Distributions|Distributions]] for more details. A custom transformer can be specified by overwriting the system property {{Code|javax.xml.transform.TransformerFactory}}, as shown in the following Java example:
  
<pre class="brush:java">
+
<syntaxhighlight lang="java">
 
System.setProperty(
 
System.setProperty(
 
   "javax.xml.transform.TransformerFactory",
 
   "javax.xml.transform.TransformerFactory",
Line 10: Line 10:
 
...
 
...
 
ctx.close();
 
ctx.close();
</pre>
+
</syntaxhighlight>
  
 
=Conventions=
 
=Conventions=
 
{{Mark|Updated with Version 9.0:}}
 
  
 
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/xslt</nowiki></code> namespace, which is statically bound to the {{Code|xslt}} prefix.<br/>
 
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/xslt</nowiki></code> namespace, which is statically bound to the {{Code|xslt}} prefix.<br/>
Line 39: Line 37:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the supported XSLT version (currently: "1.0" or "2.0"). "Unknown" is returned if a custom implementation was chosen.<br />
+
|Returns the supported XSLT version (currently: "1.0" or "3.0"). "Unknown" is returned if a custom implementation was chosen.<br />
 
|}
 
|}
  
 
==xslt:transform==
 
==xslt:transform==
 
{{Mark|Updated with Version 9.0:}} {{Code|$options}} argument added.
 
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|xslt:transform|$input as item(), $stylesheet as item()|node()}}<br />{{Func|xslt:transform|$input as item(), $stylesheet as item(), $params as map(*)?|node()}}<br />{{Func|xslt:transform|$input as item(), $stylesheet as item(), $params as map(*)?, $options as map(*)?|node()}}
+
|{{Func|xslt:transform|$input as item(), $stylesheet as item()|node()}}<br />{{Func|xslt:transform|$input as item(), $stylesheet as item(), $params as map(*)?|node()}}<br />{{Func|xslt:transform|$input as item(), $stylesheet as item(), $args as map(*)?, $options as map(*)?|node()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 56: Line 52:
 
* {{Code|xs:string}}, containing the document in its string representation, or
 
* {{Code|xs:string}}, containing the document in its string representation, or
 
* {{Code|node()}}, containing the document itself.
 
* {{Code|node()}}, containing the document itself.
The {{Code|$params}} argument can be used to bind variables to a stylesheet. Only strings are supported when using Saxon (XSLT 2.0). The following {{Code|$options}} are available:
+
[[Catalog Resolver|XML Catalog files]] will be considered when resolving URIs. Variables can be bound to a stylesheet via {{Code|$args}} (only strings are supported when using XSLT 3.0 and Saxon). The following {{Code|$options}} are available:
 
* {{Code|cache}}: cache XSLT transformer (speeds up repeated transformations, but increases memory consumption)
 
* {{Code|cache}}: cache XSLT transformer (speeds up repeated transformations, but increases memory consumption)
 
|-
 
|-
Line 64: Line 60:
  
 
==xslt:transform-text==
 
==xslt:transform-text==
 
{{Mark|Updated with Version 9.0:}} {{Code|$options}} argument added.
 
  
 
{| width='100%'
 
{| width='100%'
Line 84: Line 78:
  
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
xslt:transform-text(<dummy/>, 'basic.xslt')
 
xslt:transform-text(<dummy/>, 'basic.xslt')
</pre>
+
</syntaxhighlight>
  
 
'''basic.xslt'''
 
'''basic.xslt'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 
   <xsl:template match="/">123</xsl:template>
 
   <xsl:template match="/">123</xsl:template>
 
</xsl:stylesheet>
 
</xsl:stylesheet>
</pre>
+
</syntaxhighlight>
  
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">123</pre>
+
<syntaxhighlight lang="xml">123</syntaxhighlight>
  
 
'''Example 2: XSLT transformation of an input document'''
 
'''Example 2: XSLT transformation of an input document'''
  
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
(: Outputs the result as html. :)
 
(: Outputs the result as html. :)
 
declare option output:method 'html';
 
declare option output:method 'html';
Line 121: Line 115:
 
   </books>
 
   </books>
 
let $style :=
 
let $style :=
   <xsl:stylesheet version='2.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
+
   <xsl:stylesheet version='3.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 
   <xsl:output method='xml'/>
 
   <xsl:output method='xml'/>
 
     <xsl:template match="/">
 
     <xsl:template match="/">
Line 136: Line 130:
 
   </xsl:stylesheet>
 
   </xsl:stylesheet>
  
return xslt:transform($in, $style)</pre>
+
return xslt:transform($in, $style)</syntaxhighlight>
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<html>
 
<html>
 
   <body>
 
   <body>
Line 147: Line 141:
 
   </body>
 
   </body>
 
</html>
 
</html>
</pre>
+
</syntaxhighlight>
  
 
'''Example 3: Assigning a variable to an XSLT stylesheet'''
 
'''Example 3: Assigning a variable to an XSLT stylesheet'''
  
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
let $in := <dummy/>
 
let $in := <dummy/>
 
let $style := doc('variable.xsl')
 
let $style := doc('variable.xsl')
 
return xslt:transform($in, $style, map { "v": 1 })
 
return xslt:transform($in, $style, map { "v": 1 })
</pre>
+
</syntaxhighlight>
  
 
'''variable.xsl'''
 
'''variable.xsl'''
<pre class="brush:xslt">
+
<syntaxhighlight lang="xslt">
 
<xsl:stylesheet version='1.0'
 
<xsl:stylesheet version='1.0'
 
     xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 
     xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
Line 167: Line 161:
 
     </xsl:template>
 
     </xsl:template>
 
</xsl:stylesheet>
 
</xsl:stylesheet>
</pre>
+
</syntaxhighlight>
  
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<v>1</v>
 
<v>1</v>
 
<v>1</v>
 
<v>1</v>
</pre>
+
</syntaxhighlight>
  
 
=Errors=
 
=Errors=
 
{{Mark|Updated with Version 9.0:}}
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 188: Line 180:
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.2
 +
 +
* Updated: Support for XML Catalog files added.
  
 
;Version 9.0
 
;Version 9.0

Revision as of 12:12, 2 July 2020

This XQuery Module contains functions and variables to perform XSL transformations. By default, this module uses Java’s XSLT 1.0 Xalan implementation to transform documents. XSLT 3.0 will be enabled if Version 9.x of the Saxon XSLT Processor (saxon9he.jar, saxon9pe.jar, saxon9ee.jar) is found in the classpath (see Distributions for more details. A custom transformer can be specified by overwriting the system property javax.xml.transform.TransformerFactory, as shown in the following Java example:

<syntaxhighlight lang="java"> System.setProperty(

 "javax.xml.transform.TransformerFactory",
 "org.custom.xslt.TransformerFactoryImpl");

Context ctx = new Context(); String result = new XQuery("xslt:transform('...', '...')").execute(ctx); ... ctx.close(); </syntaxhighlight>

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/xslt namespace, which is statically bound to the xslt prefix.

Functions

xslt:processor

Signatures xslt:processor() as xs:string
Summary Returns the name of the applied XSLT processor, or the path to a custom implementation (currently: "Java", "Saxon EE", "Saxon PE", or "Saxon HE").

xslt:version

Signatures xslt:version() as xs:string
Summary Returns the supported XSLT version (currently: "1.0" or "3.0"). "Unknown" is returned if a custom implementation was chosen.

xslt:transform

Signatures xslt:transform($input as item(), $stylesheet as item()) as node()
xslt:transform($input as item(), $stylesheet as item(), $params as map(*)?) as node()
xslt:transform($input as item(), $stylesheet as item(), $args as map(*)?, $options as map(*)?) as node()
Summary Transforms the document specified by $input, using the XSLT template specified by $stylesheet, and returns the result as node. $input and $stylesheet can be specified as
  • xs:string, containing the stylesheet URI,
  • xs:string, containing the document in its string representation, or
  • node(), containing the document itself.

XML Catalog files will be considered when resolving URIs. Variables can be bound to a stylesheet via $args (only strings are supported when using XSLT 3.0 and Saxon). The following $options are available:

  • cache: cache XSLT transformer (speeds up repeated transformations, but increases memory consumption)
Error error: an error occurred during the transformation process.

xslt:transform-text

Signatures xslt:transform-text($input as item(), $stylesheet as item()) as xs:string
xslt:transform-text($input as item(), $stylesheet as item(), $params as map(*)?) as xs:string
xslt:transform-text($input as item(), $stylesheet as item(), $params as map(*)?, $options as map(*)?) as xs:string
Summary Transforms the document specified by $input, using the XSLT template specified by $stylesheet, and returns the result as string. The semantics of $params and $options is the same as for xslt:transform.
Error error: an error occurred during the transformation process.

Examples

Example 1: Basic XSL transformation with dummy document and without parameters

Query: <syntaxhighlight lang="xquery"> xslt:transform-text(<dummy/>, 'basic.xslt') </syntaxhighlight>

basic.xslt <syntaxhighlight lang="xml"> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>

 <xsl:template match="/">123</xsl:template>

</xsl:stylesheet> </syntaxhighlight>

Result: <syntaxhighlight lang="xml">123</syntaxhighlight>

Example 2: XSLT transformation of an input document

Query: <syntaxhighlight lang="xquery"> (: Outputs the result as html. :) declare option output:method 'html'; (: Turn whitespace chopping off. :) declare option db:chop 'no';

let $in :=

 <books>
   <book>
     <title>XSLT Programmer’s Reference</title> 
     <author>Michael H. Kay</author> 
   </book>
   <book>
     <title>XSLT</title> 
     <author>Doug Tidwell</author> 
     <author>Simon St. Laurent</author>
     <author>Robert Romano</author>
   </book>
 </books>

let $style :=

 <xsl:stylesheet version='3.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 <xsl:output method='xml'/>
   <xsl:template match="/">

<html>

 <body>
     <xsl:for-each select='books/book'>
     • <xsl:apply-templates select='title'/>: <xsl:value-of select='author'/>
</xsl:for-each>
 </body>

</html>

   </xsl:template>
 </xsl:stylesheet>

return xslt:transform($in, $style)</syntaxhighlight> Result: <syntaxhighlight lang="xml"> <html>

 <body>
XSLT Programmer’s Reference: Michael H. Kay
XSLT: Doug Tidwell
 </body>

</html> </syntaxhighlight>

Example 3: Assigning a variable to an XSLT stylesheet

Query: <syntaxhighlight lang="xquery"> let $in := <dummy/> let $style := doc('variable.xsl') return xslt:transform($in, $style, map { "v": 1 }) </syntaxhighlight>

variable.xsl <syntaxhighlight lang="xslt"> <xsl:stylesheet version='1.0'

   xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 <xsl:param name='v'/>
   <xsl:template match='/'>
     <v><xsl:value-of select='$v'/></v>
   </xsl:template>

</xsl:stylesheet> </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> <v>1</v> <v>1</v> </syntaxhighlight>

Errors

Code Description
error An error occurred during the transformation process.

Changelog

Version 9.2
  • Updated: Support for XML Catalog files added.
Version 9.0
Version 7.6
Version 7.3