Difference between revisions of "XSLT Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "syntaxhighlight" to "pre")
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
This [[Module Library|XQuery Module]] contains functions and variables to perform XSL transformations.
 
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:
+
By default, this module uses Java’s XSLT 1.0 Xalan implementation to transform documents. XSLT 3.0 is used if the [https://www.saxonica.com/ Saxon XSLT Processor] is found in the class path (e.g. by placing the library files in the [[Startup#Full Distributions|{{Code|lib/custom}} directory]]). A specific transformer can be specified by assigning a classpath to the system property {{Code|javax.xml.transform.TransformerFactory}} with the [https://docs.oracle.com/en/java/javase/11/tools/java.html -D flag] on the command line, or directly in Java:
  
<syntaxhighlight lang="java">
+
<pre lang="java">
 
System.setProperty(
 
System.setProperty(
 
   "javax.xml.transform.TransformerFactory",
 
   "javax.xml.transform.TransformerFactory",
Line 12: Line 12:
 
...
 
...
 
ctx.close();
 
ctx.close();
</syntaxhighlight>
+
</pre>
  
 
=Conventions=
 
=Conventions=
Line 24: Line 24:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Code|'''xslt:processor'''() as xs:string}}<br />
+
|{{Code|'''xslt:processor'''() as xs:string}}<br/>
 
|- valign="top"
 
|- 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 ("Java", "Saxon EE", "Saxon PE", "Saxon HE"). If a system property was assigned that points to an existing implementation other than Saxon, the classpath is returned instead.<br/>
 
|}
 
|}
  
Line 35: Line 35:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Code|'''xslt:version'''() as xs:string}}<br />
+
|{{Code|'''xslt:version'''() as xs:string}}<br/>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
|Returns the supported XSLT version (currently: "1.0" or "3.0"). "Unknown" is returned if a custom implementation was chosen.<br />
+
|Returns the supported XSLT version ("1.0", "3.0"). An empty string is returned if a classpath in the system property points to an existing implementation other than Saxon.<br/>
 
|}
 
|}
  
Line 46: Line 46:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{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()}}
+
|<pre>xslt:transform(
 +
  $input       as item(),
 +
  $stylesheet as item(),
 +
  $arguments  as map(*)? := map { },
 +
  $options    as map(*)? := map { }
 +
) as node()</pre>
 
|- valign="top"
 
|- 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 stylesheet URI,
 
* {{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.
[[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:
+
[[Catalog Resolver|XML Catalog files]] will be considered when resolving URIs. Variables can be bound to a stylesheet via {{Code|$arguments}} (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)
 
|- valign="top"
 
|- valign="top"
Line 65: Line 70:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{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}}
+
|<pre>xslt:transform-text(
 +
  $input       as item(),
 +
  $stylesheet as item(),
 +
  $arguments  as map(*)? := map { },
 +
  $options    as map(*)? := map { }
 +
) as xs:string</pre>
 
|- valign="top"
 
|- 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 semantics of {{Code|$params}} and {{Code|$options}} is the same as for {{Function||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"
 
|- valign="top"
 
| '''Error'''
 
| '''Error'''
Line 79: Line 89:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{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}}
+
|<pre>xslt:transform-report(
 +
  $input       as item(),
 +
  $stylesheet as item(),
 +
  $arguments  as map(*)? := map { },
 +
  $options    as map(*)? := map { }
 +
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
Line 86: Line 101:
 
* {{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|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}}.
 
* {{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.
+
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.
 
* {{Code|error}} (optional): An error string, which would be raised as an error by the other functions of this module.
 
|}
 
|}
Line 95: Line 110:
  
 
'''Query:'''
 
'''Query:'''
<syntaxhighlight lang="xquery">
+
<pre lang='xquery'>
 
(: Outputs the result as html. :)
 
(: Outputs the result as html. :)
 
declare option output:method 'html';
 
declare option output:method 'html';
Line 128: Line 143:
 
   </xsl:stylesheet>
 
   </xsl:stylesheet>
  
return xslt:transform($in, $style)</syntaxhighlight>
+
return xslt:transform($in, $style)</pre>
 
'''Result:'''
 
'''Result:'''
<syntaxhighlight lang="xml">
+
<pre lang="xml">
 
<html>
 
<html>
 
   <body>
 
   <body>
Line 139: Line 154:
 
   </body>
 
   </body>
 
</html>
 
</html>
</syntaxhighlight>
+
</pre>
  
 
'''Example 2: Textual XSL transformation'''
 
'''Example 2: Textual XSL transformation'''
  
 
'''Query:'''
 
'''Query:'''
<syntaxhighlight lang="xquery">
+
<pre lang='xquery'>
 
xslt:transform-text(<dummy/>, 'basic.xslt')
 
xslt:transform-text(<dummy/>, 'basic.xslt')
</syntaxhighlight>
+
</pre>
  
 
'''basic.xslt'''
 
'''basic.xslt'''
<syntaxhighlight lang="xml">
+
<pre 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>
</syntaxhighlight>
+
</pre>
  
 
'''Result:'''
 
'''Result:'''
<syntaxhighlight lang="xml">123</syntaxhighlight>
+
<pre lang="xml">123</pre>
  
 
'''Example 3: XSL transformation with variable assignment'''
 
'''Example 3: XSL transformation with variable assignment'''
  
 
'''Query:'''
 
'''Query:'''
<syntaxhighlight lang="xquery">
+
<pre 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 })
</syntaxhighlight>
+
</pre>
  
 
'''variable.xsl'''
 
'''variable.xsl'''
<syntaxhighlight lang="xslt">
+
<pre 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 176: Line 191:
 
     </xsl:template>
 
     </xsl:template>
 
</xsl:stylesheet>
 
</xsl:stylesheet>
</syntaxhighlight>
+
</pre>
  
 
'''Result:'''
 
'''Result:'''
<syntaxhighlight lang="xml">
+
<pre lang="xml">
 
<v>1</v>
 
<v>1</v>
 
<v>1</v>
 
<v>1</v>
</syntaxhighlight>
+
</pre>
  
 
'''Example 4: XSL transformation, yielding a result and info messages'''
 
'''Example 4: XSL transformation, yielding a result and info messages'''
  
 
'''Query:'''
 
'''Query:'''
<syntaxhighlight lang="xquery">
+
<pre lang='xquery'>
 
xslt:transform-report(
 
xslt:transform-report(
 
   <_/>,
 
   <_/>,
Line 198: Line 213:
 
   </xsl:transform>
 
   </xsl:transform>
 
)
 
)
</syntaxhighlight>
+
</pre>
  
 
'''Result:'''
 
'''Result:'''
<syntaxhighlight lang="xquery">
+
<pre lang='xquery'>
 
map {
 
map {
 
   "messages": ([<msg>START...</msg>], ["4 5 ...END"]),
 
   "messages": ([<msg>START...</msg>], ["4 5 ...END"]),
 
   "result": <xml>123</xml>
 
   "result": <xml>123</xml>
 
}
 
}
</syntaxhighlight>
+
</pre>
  
 
=Errors=
 
=Errors=

Latest revision as of 17:38, 1 December 2023

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 is used if the Saxon XSLT Processor is found in the class path (e.g. by placing the library files in the lib/custom directory). A specific transformer can be specified by assigning a classpath to the system property javax.xml.transform.TransformerFactory with the -D flag on the command line, or directly in 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();

Conventions[edit]

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[edit]

xslt:processor[edit]

Signature xslt:processor() as xs:string
Summary Returns the name of the applied XSLT processor ("Java", "Saxon EE", "Saxon PE", "Saxon HE"). If a system property was assigned that points to an existing implementation other than Saxon, the classpath is returned instead.

xslt:version[edit]

Signature xslt:version() as xs:string
Summary Returns the supported XSLT version ("1.0", "3.0"). An empty string is returned if a classpath in the system property points to an existing implementation other than Saxon.

xslt:transform[edit]

Signature
xslt:transform(
  $input       as item(),
  $stylesheet  as item(),
  $arguments   as map(*)?  := map { },
  $options     as map(*)?  := 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 $arguments (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[edit]

Signature
xslt:transform-text(
  $input       as item(),
  $stylesheet  as item(),
  $arguments   as map(*)?  := map { },
  $options     as map(*)?  := 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[edit]

Signature
xslt:transform-report(
  $input       as item(),
  $stylesheet  as item(),
  $arguments   as map(*)?  := map { },
  $options     as map(*)?  := 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[edit]

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

Query:

(: 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>
    <div>
      <xsl:for-each select='books/book'>
      • <b><xsl:apply-templates select='title'/></b>: <xsl:value-of select='author'/><br/>
      </xsl:for-each>
    </div>
  </body>
</html>
    </xsl:template>
  </xsl:stylesheet>

return xslt:transform($in, $style)

Result:

<html>
  <body>
    <div>
      • <b>XSLT Programmer’s Reference</b>: Michael H. Kay<br>
      • <b>XSLT</b>: Doug Tidwell<br>
    </div>
  </body>
</html>

Example 2: Textual XSL transformation

Query:

xslt:transform-text(<dummy/>, 'basic.xslt')

basic.xslt

<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
  <xsl:template match="/">123</xsl:template>
</xsl:stylesheet>

Result:

123

Example 3: XSL transformation with variable assignment

Query:

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

variable.xsl

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

Result:

<v>1</v>
<v>1</v>

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

Query:

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

Result:

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

Errors[edit]

Code Description
error An error occurred during the transformation process.

Changelog[edit]

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