Difference between revisions of "XSLT Module"
(40 intermediate revisions by 2 users 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 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: |
+ | |||
+ | <syntaxhighlight 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); | ||
... | ... | ||
ctx.close(); | ctx.close(); | ||
− | </ | + | </syntaxhighlight> |
=Conventions= | =Conventions= | ||
− | All functions in this module are assigned to the | + | 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 20: | Line 22: | ||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
− | | width=' | + | | width='120' | '''Signatures''' |
|{{Code|'''xslt:processor'''() as xs:string}}<br /> | |{{Code|'''xslt:processor'''() as xs:string}}<br /> | ||
|- | |- | ||
Line 31: | Line 33: | ||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
− | | width=' | + | | width='120' | '''Signatures''' |
|{{Code|'''xslt:version'''() as xs:string}}<br /> | |{{Code|'''xslt:version'''() as xs:string}}<br /> | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the supported XSLT version (currently: "1.0" or " | + | |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%' | ||
|- | |- | ||
− | | width=' | + | | 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()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Transforms the document specified by {{Code|$input}}, using the XSLT template specified by {{Code|$stylesheet}}, and returns the result as | + | |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. | ||
− | The {{Code|$ | + | [[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) |
− | + | |- | |
− | + | | '''Error''' | |
− | + | |{{Error|error|#Errors}} an error occurred during the transformation process. | |
− | + | |} | |
− | </xslt: | + | |
− | </ | + | ==xslt:transform-text== |
− | * as map | + | |
− | + | {| width='100%' | |
− | + | |- | |
− | </ | + | | 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}} | |
+ | |- | ||
+ | | '''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 [[#xslt:transform|xslt:transform]].<br /> | ||
+ | |- | ||
+ | | '''Error''' | ||
+ | |{{Error|error|#Errors}} an error occurred during the transformation process. | ||
|} | |} | ||
Line 69: | Line 78: | ||
'''Query:''' | '''Query:''' | ||
− | < | + | <syntaxhighlight lang="xquery"> |
− | xslt:transform(<dummy/>, 'basic.xslt') | + | xslt:transform-text(<dummy/>, 'basic.xslt') |
− | </ | + | </syntaxhighlight> |
'''basic.xslt''' | '''basic.xslt''' | ||
− | < | + | <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="/"> | + | <xsl:template match="/">123</xsl:template> |
− | |||
− | |||
</xsl:stylesheet> | </xsl:stylesheet> | ||
− | </ | + | </syntaxhighlight> |
'''Result:''' | '''Result:''' | ||
− | < | + | <syntaxhighlight lang="xml">123</syntaxhighlight> |
'''Example 2: XSLT transformation of an input document''' | '''Example 2: XSLT transformation of an input document''' | ||
'''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'; | ||
Line 108: | Line 115: | ||
</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 123: | Line 130: | ||
</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 134: | Line 141: | ||
</body> | </body> | ||
</html> | </html> | ||
− | </ | + | </syntaxhighlight> |
'''Example 3: Assigning a variable to an XSLT stylesheet''' | '''Example 3: Assigning a variable to an XSLT stylesheet''' | ||
'''Query:''' | '''Query:''' | ||
− | < | + | <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 }) |
− | + | </syntaxhighlight> | |
− | |||
− | ) | ||
− | </ | ||
− | '''variable. | + | '''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 157: | Line 161: | ||
</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> |
=Errors= | =Errors= | ||
− | {| | + | {| class="wikitable" width="100%" |
− | ! width=" | + | ! width="110"|Code |
− | + | |Description | |
|- | |- | ||
− | |{{Code| | + | |{{Code|error}} |
− | | An error occurred during the transformation. | + | | An error occurred during the transformation process. |
|} | |} | ||
=Changelog= | =Changelog= | ||
− | ;Version 7. | + | ;Version 9.2 |
− | * Updated: returned error code | + | |
+ | * Updated: Support for XML Catalog files added. | ||
+ | |||
+ | ;Version 9.0 | ||
+ | |||
+ | * Updated: [[#xslt:transform|xslt:transform]], [[#xslt:transform-text|xslt:transform-text]]: {{Code|$options}} argument added. | ||
+ | * Updated: error codes updated; errors now use the module namespace | ||
+ | |||
+ | ;Version 7.6 | ||
+ | |||
+ | * Added: [[#xslt:transform-text|xslt:transform-text]] | ||
+ | * Updated: [[#xslt:transform|xslt:transform]] returned error code | ||
;Version 7.3 | ;Version 7.3 | ||
+ | |||
* Updated: $xslt:processor → [[#xslt:processor|xslt:processor]], $xslt:version → [[#xslt:version|xslt:version]] | * Updated: $xslt:processor → [[#xslt:processor|xslt:processor]], $xslt:version → [[#xslt:version|xslt:version]] | ||
− | |||
− |
Revision as of 13: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>
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.
|
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
- 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