Chapter 25 adds and uses XSLT extension functions

Custom error handling

When an error occurs, the XSLT processor (Xalan or Saxon) executes the error() method of the current error handler, sending a message as a parameter to the method. Similarly, when a fatal error or Warning occurs, the XSLT processor executes the datalError() or Warning() methods as needed.

For all three methods, the default behavior is to write the message to the current device.

To customize error handling, do the following:

• forXalanorSaxonProcessor, in the creation%XML.XSLT.ErrorHandlerThe subclass. In this subclass, implement as neededError(),FatealError()andWarning()Methods.

Each of these methods takes a single parameter, a string containing a message sent by the XSLT processor.

These methods do not return values.

• To use this error handler when compiling the stylesheet, create an instance of the subclass and use it in the parameter list when compiling the stylesheet.
• To use this error handler when performing AN XSLT transformation, create an instance of a subclass and use theTransformUse it in the argument list of the method.

Specifies the parameters used by the stylesheet

To specify the parameters used by the stylesheet, do the following:

1. create%ArrayOfDataTypesThe instance of.
2. Of this instanceSetAt()Method adds parameters and their values to this instance. forSetAt(), specify the first parameter as the parameter value and the second parameter as the parameter name.

Add as many parameters as you need.

    Set tParameters=##class(%ArrayOfDataTypes%).New(a)Set tSC=tParameters.SetAt(1."myparameter")
    Set tSC=tParameters.SetAt(2."anotherparameter")
Copy the code

3. Use this instance asTransformmethodspParmsParameters.

Instead of using %ArrayOfDataType, you can use an IRIS multidimensional array, which can have any number of nodes with the following structure and values:

Add and use XSLT extension functions

XSLT extension functions can be created in InterSystems IRIS and then used in a stylesheet, as follows:

• forXSLT2.0(SaxonProcessor), you can use namespacescom.intersystems.xsltgateway.XSLTGatewayIn theevaluateFunction or namespacehttp://extension-functions.intersystems.comIn theevaluatefunction
• forXSLT1.0(XalanProcessor), can only be in the namespacehttp://extension-functions.intersystems.comThe use ofevaluatefunction

By default (for example), the latter function reverses the character it receives. However, the default behavior is usually not used because some other behavior is implemented. To simulate multiple individual functions, you need to pass a selector as the first argument and implement a switch that uses that value to select 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:

1. forXalanorSaxonProcessor, in the creation%XML.XSLT.CallbackHandlerThe subclass. In this subclass, implement as neededevaluate()Methods. See the next section.
2. In the style sheet, declareevaluateThe namespace to which the function belongs and used as neededevaluateFunction. See the next section.
3. When performing the XSLT transformation, create an instance of the subclass and use theTransformUse it in the argument list of the method. See “Performing XSLT Transformations.”

Implement the evaluate() method

Internally, code calling 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 with the following structure:

This method has only one return value. The return value can be:

• Scalar variables (such as strings or numbers).
• Stream objects. This allows you to return extremely long strings that exceed the string length limit. Streams must be wrapped in a new window%XML.XSLT.StreamAdapterIn the example, enable the XSLT processor to read the stream. Here are some examples:

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

}
Copy the code

Use calculations in stylesheets

To use XSLT extension functions in XSLT, you must declare the namespace of the extension function in the XSLT stylesheet. For InterSystems the evaluate function, this namespace is http://extension-functions.intersystems.com or com. InterSystems. Xsltgateway. Xsltgateway, As mentioned earlier.

The following example shows a stylesheet that uses EVALUATE:

      

<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>
Copy the code

Use ISC: Compute cache

XSLT2.0 gateway caches the EVALUATE function calls in the ISC: evaluate cache. The default maximum size of the cache is 1000 items, but the size can be set to a different value. In addition, you can clear the cache, dump the cache, and prepopulate the cache from the %List. Use the following format:

• Total number of cached entries
• For each entry:

1. Evaluate the total number of parameters
2. All evaluation parameters
3. Calculated value

The cache also includes a filter list of cacheable function names. Please note the following:

• Function names can be added or removed from the filter list.
• The list of filters can be cleared.
• The list of filters can be overridden by setting a Boolean value that will cache eachevaluateThe call.

Adding a function name to the filter list does not limit the size of the evaluation cache. You can make any number of calls to the same function, but with different arguments and return values. Each combination of function name and parameter is a separate entry in the evaluation cache.

You can use the methods in % xml.xslt2. Transformer to manipulate the evaluation cache.

Use the XSL transformation wizard

Studio provides a wizard to perform XSLT transformations, which is useful when you want to quickly test stylesheets or customize XSLT extension functions. To use this architecture wizard, do the following:

1. Tools > Add-Ins > XSLT Schema Wizard.
2. Specify the following required details:

• For XML files, select Browse to select the XML file to convert.
• For the XSL file, choose Browse to select the XSL style sheet to use.
• For rendering as, select text or XML to control how the transformation is displayed.

3. If already created for use in this transformation%XML.XSLT.CallbackHandlerSubclass, specify the following details:

• For the first drop-down list in the XSLT Helper Class, select a namespace.
• For the second drop-down list in the XSLT Helper Class, select this Class.

4. Select Finish.

The converted file is displayed at the bottom of the dialog box. You can copy and paste from this area.

5. To close this dialog box, select Cancel.