Difference between revisions of "XSLT Module"
m (Text replacement - "syntaxhighlight" to "pre") |
|||
(45 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains functions and variables to perform | + | 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 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: | ||
+ | |||
+ | <pre lang="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); | ||
Line 11: | Line 16: | ||
=Conventions= | =Conventions= | ||
− | All functions 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/> |
− | |||
=Functions= | =Functions= | ||
Line 19: | Line 23: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | |{{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 | + | |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 30: | Line 34: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | |{{Code|'''xslt:version'''() as xs:string}}<br /> | + | |{{Code|'''xslt:version'''() as xs:string}}<br/> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
− | |Returns the supported XSLT version ( | + | |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/> |
|} | |} | ||
==xslt:transform== | ==xslt:transform== | ||
+ | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>xslt:transform( |
− | |- | + | $input as item(), |
+ | $stylesheet as item(), | ||
+ | $arguments as map(*)? := map { }, | ||
+ | $options as map(*)? := map { } | ||
+ | ) as node()</pre> | ||
+ | |- 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 | + | * {{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|$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) |
+ | |- valign="top" | ||
| '''Error''' | | '''Error''' | ||
− | |{{Error| | + | |{{Error|error|#Errors}} an error occurred during the transformation process. |
|} | |} | ||
Line 58: | Line 69: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>xslt:transform-text( |
− | |- | + | $input as item(), |
+ | $stylesheet as item(), | ||
+ | $arguments as map(*)? := map { }, | ||
+ | $options as map(*)? := map { } | ||
+ | ) as xs:string</pre> | ||
+ | |- 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}} 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|error|#Errors}} an error occurred during the transformation process. |
|} | |} | ||
− | == | + | ==xslt:transform-report== |
− | ''' | + | {| width='100%' |
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>xslt:transform-report( | ||
+ | $input as item(), | ||
+ | $stylesheet as item(), | ||
+ | $arguments as map(*)? := map { }, | ||
+ | $options as map(*)? := map { } | ||
+ | ) as xs:string</pre> | ||
+ | |- 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:''' | ||
− | <pre | + | <pre 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 111: | Line 128: | ||
</books> | </books> | ||
let $style := | let $style := | ||
− | <xsl:stylesheet version=' | + | <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 128: | Line 145: | ||
return xslt:transform($in, $style)</pre> | return xslt:transform($in, $style)</pre> | ||
'''Result:''' | '''Result:''' | ||
− | <pre | + | <pre lang="xml"> |
<html> | <html> | ||
<body> | <body> | ||
Line 139: | Line 156: | ||
</pre> | </pre> | ||
− | '''Example | + | '''Example 2: Textual XSL transformation''' |
'''Query:''' | '''Query:''' | ||
− | <pre | + | <pre lang='xquery'> |
+ | xslt:transform-text(<dummy/>, 'basic.xslt') | ||
+ | </pre> | ||
+ | |||
+ | '''basic.xslt''' | ||
+ | <pre lang="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:''' | ||
+ | <pre lang="xml">123</pre> | ||
+ | |||
+ | '''Example 3: XSL transformation with variable assignment''' | ||
+ | |||
+ | '''Query:''' | ||
+ | <pre 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 }) |
− | |||
− | |||
− | ) | ||
</pre> | </pre> | ||
− | '''variable. | + | '''variable.xsl''' |
− | <pre | + | <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 163: | Line 194: | ||
'''Result:''' | '''Result:''' | ||
− | <pre | + | <pre lang="xml"> |
<v>1</v> | <v>1</v> | ||
<v>1</v> | <v>1</v> | ||
+ | </pre> | ||
+ | |||
+ | '''Example 4: XSL transformation, yielding a result and info messages''' | ||
+ | |||
+ | '''Query:''' | ||
+ | <pre 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> | ||
+ | ) | ||
+ | </pre> | ||
+ | |||
+ | '''Result:''' | ||
+ | <pre lang='xquery'> | ||
+ | map { | ||
+ | "messages": ([<msg>START...</msg>], ["4 5 ...END"]), | ||
+ | "result": <xml>123</xml> | ||
+ | } | ||
</pre> | </pre> | ||
Line 173: | Line 228: | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
− | |{{Code| | + | |{{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: | + | |
− | * Updated: | + | * Added: {{Function||xslt:transform-text}} |
+ | * Updated: {{Function||xslt:transform}} returned error code | ||
;Version 7.3 | ;Version 7.3 | ||
− | |||
− | + | * Updated: $xslt:processor → {{Function||xslt:processor}}, $xslt:version → {{Function||xslt:version}} |
Latest revision as of 18: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();
Contents
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
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[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:
The semantics of
|
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
- 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