Difference between revisions of "XSLT Module"
(13 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: |
+ | |||
+ | <syntaxhighlight lang="java"> | ||
System.setProperty( | System.setProperty( | ||
"javax.xml.transform.TransformerFactory", | "javax.xml.transform.TransformerFactory", | ||
Line 10: | Line 12: | ||
... | ... | ||
ctx.close(); | ctx.close(); | ||
− | </ | + | </syntaxhighlight> |
=Conventions= | =Conventions= | ||
Line 21: | Line 23: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''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 32: | Line 34: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''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 "3.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 /> | ||
Line 41: | Line 43: | ||
==xslt:transform== | ==xslt:transform== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| 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(), $args 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()}} | ||
− | |- | + | |- 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 /> | ||
Line 56: | Line 56: | ||
[[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|$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) | ||
− | |- | + | |- valign="top" |
| '''Error''' | | '''Error''' | ||
|{{Error|error|#Errors}} an error occurred during the transformation process. | |{{Error|error|#Errors}} an error occurred during the transformation process. | ||
Line 64: | Line 64: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{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}} | |{{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 semantics of {{Code|$params}} and {{Code|$options}} is the same as for | + | |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|error|#Errors}} an error occurred during the transformation process. | |{{Error|error|#Errors}} an error occurred during the transformation process. | ||
|} | |} | ||
− | == | + | ==xslt:transform-report== |
− | ''' | + | {| 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. | ||
+ | |} | ||
− | + | ==Examples== | |
− | |||
− | |||
− | |||
− | ''' | + | '''Example 1: XSL transformation, with XML and XSL supplied as nodes''' |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
'''Query:''' | '''Query:''' | ||
− | < | + | <syntaxhighlight lang="xquery"> |
(: Outputs the result as html. :) | (: Outputs the result as html. :) | ||
declare option output:method 'html'; | declare option output:method 'html'; | ||
− | |||
− | |||
let $in := | let $in := | ||
Line 132: | Line 128: | ||
</xsl:stylesheet> | </xsl:stylesheet> | ||
− | return xslt:transform($in, $style)</ | + | return xslt:transform($in, $style)</syntaxhighlight> |
'''Result:''' | '''Result:''' | ||
− | < | + | <syntaxhighlight lang="xml"> |
<html> | <html> | ||
<body> | <body> | ||
Line 143: | Line 139: | ||
</body> | </body> | ||
</html> | </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: | + | '''Example 3: XSL transformation with variable assignment''' |
'''Query:''' | '''Query:''' | ||
− | < | + | <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 }) | ||
− | </ | + | </syntaxhighlight> |
'''variable.xsl''' | '''variable.xsl''' | ||
− | < | + | <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 163: | Line 176: | ||
</xsl:template> | </xsl:template> | ||
</xsl:stylesheet> | </xsl:stylesheet> | ||
− | </ | + | </syntaxhighlight> |
'''Result:''' | '''Result:''' | ||
− | < | + | <syntaxhighlight lang="xml"> |
<v>1</v> | <v>1</v> | ||
<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= | =Errors= | ||
Line 176: | Line 213: | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
|{{Code|error}} | |{{Code|error}} | ||
| An error occurred during the transformation process. | | An error occurred during the transformation process. | ||
Line 182: | Line 219: | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 9.7 | ||
+ | * Added: {{Function||xslt:transform-report}} | ||
;Version 9.2 | ;Version 9.2 | ||
Line 189: | Line 229: | ||
;Version 9.0 | ;Version 9.0 | ||
− | * Updated: | + | * Updated: {{Function||xslt:transform}}, {{Function||xslt:transform-text}}: {{Code|$options}} argument added. |
* Updated: error codes updated; errors now use the module namespace | * Updated: error codes updated; errors now use the module namespace | ||
;Version 7.6 | ;Version 7.6 | ||
− | * Added: | + | * Added: {{Function||xslt:transform-text}} |
− | * Updated: | + | * Updated: {{Function||xslt:transform}} returned error code |
;Version 7.3 | ;Version 7.3 | ||
− | * Updated: $xslt:processor → | + | * Updated: $xslt:processor → {{Function||xslt:processor}}, $xslt:version → {{Function||xslt:version}} |
Revision as of 14: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>
Contents
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
XML Catalog files will be considered when resolving URIs. Variables can be bound to a stylesheet via
|
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:
The semantics of
|
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
- Added:
xslt:transform-report
- Version 9.2
- Updated: Support for XML Catalog files added.
- Version 9.0
- Updated:
xslt:transform
,xslt:transform-text
:$options
argument added. - Updated: error codes updated; errors now use the module namespace
- Version 7.6
- Added:
xslt:transform-text
- Updated:
xslt:transform
returned error code
- Version 7.3
- Updated: $xslt:processor →
xslt:processor
, $xslt:version →xslt:version