Main Page » XQuery » Functions » XSLT Functions

XSLT Functions

This module contains functions and variables to perform XSL transformations. The standard function fn:transform uses the same processors.

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();
The functions of this module are always invoked via the JAXP interface. If Saxon is available, fn:transform addresses it via its s9api interface instead, which gives access to all entry points, options and delivery formats of the specification. Currently, xslt:transform-report requires Saxon 10 or later to return results.

Conventions

All functions and errors are in the http://basex.org/modules/xslt namespace, to which the xslt prefix is statically bound.

Functions

xslt:processor

Signature
xslt:processor() as xs:string
SummaryReturns 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

Signature
xslt:version() as xs:string
SummaryReturns 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

Signature
xslt:transform(  $input       as item(),  $stylesheet  as item(),  $arguments   as map(*)?  := {},  $options     as map(*)?  := {}) as document-node()create
SummaryTransforms the document specified by $input, using the XSLT template specified by $stylesheet, and returns the result as a document 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:
optiondefaultdescription
cachefalse() Cache XSLT transformer; speeds up repeated transformations, but increases memory consumption.
Errors
errorAn error occurred during the transformation process.

xslt:transform-text

Signature
xslt:transform-text(  $input       as item(),  $stylesheet  as item(),  $arguments   as map(*)?  := {},  $options     as map(*)?  := {}) as xs:stringcreate
SummaryTransforms the document specified by $input, using the XSLT template specified by $stylesheet, and returns the result as string. The semantics of $arguments and $options is the same as for xslt:transform.
Errors
errorAn error occurred during the transformation process.

xslt:transform-report

Signature
xslt:transform-report(  $input       as item(),  $stylesheet  as item(),  $arguments   as map(*)?  := {},  $options     as map(*)?  := {}) as map(*)create
SummaryTransforms 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 nodes, or (if the result cannot be converted to XML) an item of type xs:untypedAtomic.
  • messages: Requires Saxon 10 or later: 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.
  • error (optional): An error string, which would be raised as an error by the other functions of this module.

The semantics of $arguments and $options is the same as for xslt:transform.

xslt:init

Signature
xslt:init() as empty-sequence()create
SummaryDiscards the cached XSLT transformers.

Examples

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='1.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'>
• <b><xsl:apply-templates select='title'/></b>: <xsl:value-of select='author'/> 
          </xsl:for-each>
        </body>
      </html>
    </xsl:template>
  </xsl:stylesheet>
return xslt:transform($in, $style)
Result: 
<!DOCTYPE HTML><html><body>
• <b>XSLT Programmer’s Reference</b>: Michael H. Kay
• <b>XSLT</b>: Doug Tidwell</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, { "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>

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: 
{
  "messages": ([<msg>START...</msg>], ["4 5 ...END"]),
  "result": <xml>123</xml>
}

Errors

CodeDescription
errorAn error occurred during the transformation process.

Changelog

Version 11.0
  • Added: xslt:init to discard cached XSLT transformers.
Version 9.7Version 9.2
  • Updated: Support for XML Catalog files added.
Version 9.0Version 7.6Version 7.3
⚡Generated with XQuery
 
XSLT Functions