Adding and Using XSLT Extension Functions

You can create XSLT extension functions in InterSystems IRIS and then use them within your stylesheet, as follows:

For XSLT 2.0 (the Saxon processor), you can use the evaluate function in the namespace com.intersystems.xsltgateway.XSLTGateway or the evaluate function in the namespace http://extension-functions.intersystems.com
For XSLT 1.0 (the Xalan processor), you can only use the evaluate function in the namespace http://extension-functions.intersystems.com

By default (and as an example), the latter function reverses the characters that it receives. Typically, however, the default behavior is not used, because you implement some other behavior. To simulate multiple separate functions, you pass a selector as the first argument and implement a switch that uses that value to choose the processing to perform.

Internally, the evaluate function is implemented as a method (evaluate()) in the XSLT callback handler.

To add and use XSLT extension functions, do the following:

For either the Xalan or the Saxon processor, create a subclass of %XML.XSLT.CallbackHandlerOpens in a new tab. In this subclass, implement the evaluate() method as needed. See the following subsection.
In the style sheet, declare the namespace to which the evaluate function belongs and use the evaluate function as needed. See the following subsection.
When performing an XSLT transform, create an instance of your subclass and use it in the argument list of the transform method you use. See Performing an XSLT Transform.

Implementing the evaluate() Method

Internally, the code that calls the XSLT processor can pass any number of positional arguments to the evaluate() method of the current callback handler, which receives them as an array that has the following structure:

Node	Value
Args	Number of arguments
Args(index)	Value of the argument in the position index

The method has a single return value. The return value can be either:

A scalar variable (such as a string or number).
A stream object. This allows you to return an extremely long string, one that exceeds the string length limit. The stream has to be wrapped in an instance of %XML.XSLT.StreamAdapterOpens in a new tab which enables the XSLT processor to read the stream. The following shows a partial example:
```
Method evaluate(Args...) As %String
{
 //create stream
 ///...

 // create instance of %XML.XSLT.StreamAdapter to
 // contain the stream
 Set return=##class(%XML.XSLT.StreamAdapter).%New(tStream)

 Quit return

}
```

Using evaluate in a Stylesheet

To use XSLT extension functions in an XSLT, you must declare the namespace of the extension functions in the XSLT stylesheet. For the InterSystems evaluate function, this namespace is http://extension-functions.intersystems.com or com.intersystems.xsltgateway.XSLTGateway, as discussed previously.

The following example shows a style sheet that uses evaluate:

<?xml version="1.0"?>

<xsl:stylesheet 
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" 
xmlns:isc="http://extension-functions.intersystems.com">

  <xsl:output method="xml" indent="yes"/>
 
  <xsl:template match="//@* | //node()">
    <xsl:copy>
      <xsl:apply-templates select="@*"/>
      <xsl:apply-templates select="node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="/s1/s2/s3">
  <xsl:apply-templates select="@*"/>
  <xsl:choose>
  <xsl:when test="function-available('isc:evaluate')">
  <xsl:copy>
  <xsl:value-of select="isc:evaluate(.)" disable-output-escaping="yes"/>
  </xsl:copy>
  </xsl:when>
  <xsl:otherwise>
  <xsl:value-of select="."/>
  </xsl:otherwise>
  </xsl:choose>
  </xsl:template> 

</xsl:stylesheet>

For a closer look at this example, see the source code for the Example3() method of %XML.XSLT.TransformerOpens in a new tab.

Working with the isc:evaluate Cache

The XSLT 2.0 gateway caches evaluate function calls in the isc:evaluate cache. The default maximum size of the cache is 1000 items, but you can set the size to a different value. Also, you can clear the cache, you can dump the cache, and you can pre-populate the cache from a %ListOpens in a new tab with the following format:

Total number of cache entries
For each entry:
1. Total number of evaluate arguments
2. All evaluate arguments
3. Evaluate value

The cache also includes a filter list of function names that can be cached. Note the following:

Function names can be added to or removed from the filter list.
The filter list can be cleared.
The filter list can be overridden by setting a boolean that will cache every evaluate call.

Adding a function name to the filter list does not limit the size of the evaluate cache. There may be any number of calls to the same function, but with different arguments and return values. Each combination of function name and arguments is a separate entry in the evaluate cache.

You can use methods from the %XML.XSLT2.TransformerOpens in a new tab class to manipulate the evaluate cache. For details, see the class reference.

Using the XSL Transform Wizard

Specifying Parameters for Use by the Stylesheet