Difference between revisions of "XSLT Module"

From BaseX Documentation
Jump to navigation Jump to search
(42 intermediate revisions by 2 users 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 or 10 of the [https://www.saxonica.com/ Saxon XSLT Processor] is found in the class path (see [[Startup#Distributions|Distributions]] for more details). A custom transformer can be specified by assigning a class to the system property {{Code|javax.xml.transform.TransformerFactory}}, e.g. directly in Java:
 +
 
 +
<syntaxhighlight lang="java">
 +
System.setProperty(
 +
  "javax.xml.transform.TransformerFactory",
 +
  "org.custom.xslt.TransformerFactoryImpl");
  
<pre class="brush:java">
 
System.setProperty("javax.xml.transform.TransformerFactory", "org.custom.xslt.TransformerFactoryImpl");
 
 
Context ctx = new Context();
 
Context ctx = new Context();
 
String result = new XQuery("xslt:transform('...', '...')").execute(ctx);
 
String result = new XQuery("xslt:transform('...', '...')").execute(ctx);
 
...
 
...
 
ctx.close();
 
ctx.close();
</pre>
+
</syntaxhighlight>
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://basex.org/modules/xslt}} 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/>
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
Line 19: Line 23:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Code|'''xslt:processor'''() as xs:string}}<br />
 
|{{Code|'''xslt:processor'''() as xs:string}}<br />
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''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").<br />
 
|Returns the name of the applied XSLT processor, or the path to a custom implementation (currently: "Java", "Saxon EE", "Saxon PE", or  "Saxon HE").<br />
Line 30: Line 34:
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
 
|{{Code|'''xslt:version'''() as xs:string}}<br />
 
|{{Code|'''xslt:version'''() as xs:string}}<br />
|-
+
|- valign="top"
 
| '''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==
 +
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='90' | '''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 item()|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()}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Transforms the document specified by {{Code|$input}}, using the XSLT template specified by {{Code|$stylesheet}}, and returns the result as node. {{Code|$input}} and {{Code|$stylesheet}} can be specified as<br />
 
|Transforms the document specified by {{Code|$input}}, using the XSLT template specified by {{Code|$stylesheet}}, and returns the result as node. {{Code|$input}} and {{Code|$stylesheet}} can be specified as<br />
* {{Code|xs:string}}, containing the path to the document,
+
* {{Code|xs:string}}, containing the stylesheet URI,
 
* {{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, which can either be specified<br />
+
[[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:
* as children of an {{Code|<xslt:parameters/>}} element; e.g.:
+
* {{Code|cache}}: cache XSLT transformer (speeds up repeated transformations, but increases memory consumption)
<pre class="brush:xml">
+
|- valign="top"
<xslt:parameters>
 
  <xslt:key1 value='value1'/>
 
  ...
 
</xslt:parameters>
 
</pre>
 
* or as map, which contains all key/value pairs:
 
<pre class="brush:xquery">
 
map { "key1" := "value1", ... }
 
</pre>
 
Note that only strings are supported when using Saxon (XSLT 2.0).
 
|-
 
 
| '''Error'''
 
| '''Error'''
|{{Error|BXSL0001|#Errors}} an error occurred during the transformation process.
+
|{{Error|error|#Errors}} an error occurred during the transformation process.
 
|}
 
|}
  
 
==xslt:transform-text==
 
==xslt:transform-text==
 
{{Mark|Introduced with Version 7.6}}
 
  
 
{| width='100%'
 
{| width='100%'
|-
+
|- valign="top"
| width='90' | '''Signatures'''
+
| width='120' | '''Signatures'''
|{{Func|xslt:transform-text|$input as item(), $stylesheet as item()|node()}}<br />{{Func|xslt:transform-text|$input as item(), $stylesheet as item(), $params as item()|node()}}
+
|{{Func|xslt:transform-text|$input as item(), $stylesheet as item()|xs:string}}<br />{{Func|xslt:transform-text|$input as item(), $stylesheet as item(), $params as map(*)?|xs:string}}<br />{{Func|xslt:transform-text|$input as item(), $stylesheet as item(), $params as map(*)?, $options as map(*)?|xs:string}}
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Transforms the document specified by {{Code|$input}}, using the XSLT template specified by {{Code|$stylesheet}}, and returns the result as string. The parameters have the same meaning as described for [[#xslt:transform|xslt:transform]].<br />
+
|Transforms the document specified by {{Code|$input}}, using the XSLT template specified by {{Code|$stylesheet}}, and returns the result as string. The semantics of {{Code|$params}} and {{Code|$options}} is the same as for {{Function||xslt:transform}}.<br />
|-
+
|- valign="top"
 
| '''Error'''
 
| '''Error'''
|{{Error|BXSL0001|#Errors}} an error occurred during the transformation process.
+
|{{Error|error|#Errors}} an error occurred during the transformation process.
 
|}
 
|}
  
==Examples==
+
==xslt:transform-report==
  
'''Example 1: Basic XSL transformation with dummy document and without parameters'''
+
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signatures'''
 +
|{{Func|xslt:transform-report|$input as item(), $stylesheet as item()|xs:string}}<br />{{Func|xslt:transform-report|$input as item(), $stylesheet as item(), $params as map(*)?|xs:string}}<br />{{Func|xslt:transform-report|$input as item(), $stylesheet as item(), $params as map(*)?, $options as map(*)?|xs:string}}
 +
|- valign="top"
 +
| '''Summary'''
 +
|Transforms the document specified by {{Code|$input}}, using the XSLT template specified by {{Code|$stylesheet}}, and returns a map with the following keys:
 +
* {{Code|result}}: The transformation result: One or more document nodes, or (if the result cannot be converted to XML) an item of type {{Code|xs:untypedAtomic}}.
 +
* {{Code|messages}}: Informational output generated by {{Code|xsl:message}} elements: A sequence of arrays. The arrays consist of XML elements, or (for those messages that cannot be converted to XML) items of type {{Code|xs:untypedAtomic}}.
 +
The semantics of {{Code|$params}} and {{Code|$options}} is the same as for {{Function||xslt:transform}}.<br />For the moment, messages can only be returned with recent versions of Saxon.
 +
* {{Code|error}} (optional): An error string, which would be raised as an error by the other functions of this module.
 +
|}
  
'''Query:'''
+
==Examples==
<pre class="brush:xquery">
 
xslt:transform-text(<dummy/>, 'basic.xslt')
 
</pre>
 
 
 
'''basic.xslt'''
 
<pre class="brush:xml">
 
<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 
  <xsl:template match="/">123</xsl:template>
 
</xsl:stylesheet>
 
</pre>
 
  
'''Result:'''
+
'''Example 1: XSL transformation, with XML and XSL supplied as nodes'''
<pre class="brush:xml">123</pre>
 
 
 
'''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';
(: Turn whitespace chopping off. :)
 
declare option db:chop 'no';
 
  
 
let $in :=
 
let $in :=
Line 125: Line 113:
 
   </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 140: Line 128:
 
   </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 151: Line 139:
 
   </body>
 
   </body>
 
</html>
 
</html>
</pre>
+
</syntaxhighlight>
 +
 
 +
'''Example 2: Textual XSL transformation'''
 +
 
 +
'''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>
  
'''Example 3: Assigning a variable to an XSLT stylesheet'''
+
'''Result:'''
 +
<syntaxhighlight lang="xml">123</syntaxhighlight>
 +
 
 +
'''Example 3: XSL transformation with variable assignment'''
  
 
'''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 (
+
return xslt:transform($in, $style, map { "v": 1 })
  xslt:transform($in, $style, <xslt:parameters><xslt:v>1</xslt:v></xslt:parameters>),
+
</syntaxhighlight>
  xslt:transform($in, $style, map { "v" := 1 })
 
)
 
</pre>
 
  
'''variable.xslt'''
+
'''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 174: Line 176:
 
     </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>
 +
 
 +
'''Example 4: XSL transformation, yielding a result and info messages'''
 +
 
 +
'''Query:'''
 +
<syntaxhighlight lang="xquery">
 +
xslt:transform-report(
 +
  <_/>,
 +
  <xsl:transform version='2.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
 +
    <xsl:template match='/'>
 +
      <xsl:message><msg>START...</msg></xsl:message>
 +
      <xml>123</xml>
 +
      <xsl:message select='4, 5, "...END"'/>
 +
    </xsl:template>
 +
  </xsl:transform>
 +
)
 +
</syntaxhighlight>
 +
 
 +
'''Result:'''
 +
<syntaxhighlight lang="xquery">
 +
map {
 +
  "messages": ([<msg>START...</msg>], ["4 5 ...END"]),
 +
  "result": <xml>123</xml>
 +
}
 +
</syntaxhighlight>
  
 
=Errors=
 
=Errors=
  
{| width='100%' class="wikitable" width="100%"
+
{| class="wikitable" width="100%"
! width="5%"|Code
+
! width="110"|Code
! width="95%"|Description
+
|Description
|-
+
|- valign="top"
|{{Code|BXSL0001}}
+
|{{Code|error}}
 
| An error occurred during the transformation process.
 
| An error occurred during the transformation process.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.7
 +
* Added: {{Function||xslt:transform-report}}
 +
 +
;Version 9.2
 +
 +
* Updated: Support for XML Catalog files added.
 +
 +
;Version 9.0
 +
 +
* Updated: {{Function||xslt:transform}}, {{Function||xslt:transform-text}}: {{Code|$options}} argument added.
 +
* Updated: error codes updated; errors now use the module namespace
  
 
;Version 7.6
 
;Version 7.6
* Added: [[#xslt:transform-text|xslt:transform-text]]
+
 
* Updated: [[#xslt:transform|xslt:transform]] returned error code
+
* Added: {{Function||xslt:transform-text}}
 +
* Updated: {{Function||xslt:transform}} returned error code
  
 
;Version 7.3
 
;Version 7.3
* Updated: $xslt:processor → [[#xslt:processor|xslt:processor]], $xslt:version → [[#xslt:version|xslt:version]]
 
  
[[Category:XQuery]]
+
* Updated: $xslt:processor → {{Function||xslt:processor}}, $xslt:version → {{Function||xslt:version}}

Revision as of 13:20, 20 July 2022

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 or 10 of the Saxon XSLT Processor is found in the class path (see Distributions for more details). A custom transformer can be specified by assigning a class to the system property javax.xml.transform.TransformerFactory, e.g. directly in Java:

<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.

xslt:transform-report

Signatures xslt:transform-report($input as item(), $stylesheet as item()) as xs:string
xslt:transform-report($input as item(), $stylesheet as item(), $params as map(*)?) as xs:string
xslt:transform-report($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 a map with the following keys:
  • result: The transformation result: One or more document nodes, or (if the result cannot be converted to XML) an item of type xs:untypedAtomic.
  • messages: Informational output generated by xsl:message elements: A sequence of arrays. The arrays consist of XML elements, or (for those messages that cannot be converted to XML) items of type xs:untypedAtomic.

The semantics of $params and $options is the same as for xslt:transform.
For the moment, messages can only be returned with recent versions of Saxon.

  • error (optional): An error string, which would be raised as an error by the other functions of this module.

Examples

Example 1: XSL transformation, with XML and XSL supplied as nodes

Query: <syntaxhighlight lang="xquery"> (: Outputs the result as html. :) declare option output:method 'html';

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 2: Textual XSL transformation

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 3: XSL transformation with variable assignment

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>

Example 4: XSL transformation, yielding a result and info messages

Query: <syntaxhighlight lang="xquery"> xslt:transform-report(

 <_/>,
 <xsl:transform version='2.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
   <xsl:template match='/'>
     <xsl:message><msg>START...</msg></xsl:message>
     <xml>123</xml>
     <xsl:message select='4, 5, "...END"'/>
   </xsl:template>
 </xsl:transform>

) </syntaxhighlight>

Result: <syntaxhighlight lang="xquery"> map {

 "messages": ([<msg>START...</msg>], ["4 5 ...END"]),
 "result": <xml>123</xml>

} </syntaxhighlight>

Errors

Code Description
error An error occurred during the transformation process.

Changelog

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