web analytics

XSLT Extensions: Extension Elements and Extension Functions

Options

codeling 1602 - 6666
@2017-09-19 10:54:17

There are three categories of elements that can be in an XSLT stylesheet:

  • Elements from the XSLT namespace that tell the processor how to transform the source tree into the result tree.
  • Literal result elements of any namespace you like that get added to the result tree just as they are shown in the stylesheet.
  • Extension elements: customized instruction elements that can be used along with the instructions from the XSLT namespace.

Elements from the XSLT namespace fall into two categories:

  • top-level elements, which are children of the xsl:stylesheet element with general instructions about handling the source document,
  • and the children of the xsl:template elements known as instructions, which give specific instructions about nodes to add to the result tree.

Extension elements cannot be top-level elements; they are always new instructions.

It's an important part of an XSLT processor's job to recognize all the elements in a stylesheet from the XSLT namespace and to carry out their instructions. If literal result elements can be from any namespace, letting you add elements from the HTML, XLink, or any other namespace to the result tree, how does a processor know which elements are extension elements? Because the stylesheet must explicitly list which namespaces are to be treated as extension element namespaces in the extension-element-prefixes attribute.

For example, In the following stylesheet, the http://icl.com/saxon namespace is declared as a namespace with a prefix of "saxon", and this "saxon" namespace prefix is included in the value of the xsl:stylesheet element's extension-element-prefixes attribute, wich means all the elements in the http://icl.com/saxon namespace are to be treated as extension elements.



<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     xmlns:saxon="http://icl.com/saxon"

     extension-element-prefixes="saxon"

     version="1.0">

<xsl:output method="xml" omit-xml-declaration="yes"/>

....  

</xsl:stylesheet>
@2017-09-19 10:57:51

If an XSLT processor doesn't implement a particular extension element, it must look for an xsl:fallback child of that element and add its contents to the result tree. In the following revision of the stylesheet above, the xsl:fallback element has no contents to add to the result tree, but instead sends an xsl:message text string to wherever such strings go for the processor in question. (The xsl:message element sends a text message somewhere other than the result tree -- for example, to a command line window -- and is useful for debugging and status messages. Not all XSLT processors support it fully.)



<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     xmlns:saxon="http://icl.com/saxon"

     extension-element-prefixes="saxon"  

     version="1.0">

  <xsl:output method="xml" omit-xml-declaration="yes"/>



  <xsl:variable name="color" 

       saxon:assignable="yes">red</xsl:variable>


  <xsl:template match="/">

    <saxon:assign name="color">blue<xsl:fallback>

        <xsl:message>This XSLT processor doesn't support saxon:assign.

        </xsl:message></xsl:fallback></saxon:assign>

    The color variable has the following value:

    <xsl:value-of select="$color"/>

  </xsl:template>

</xsl:stylesheet>

When run with the Saxon processor, this creates the same result as the earlier Saxon run. No xsl:message text appears at the command line because the saxon:assign element enclosing the xsl:fallback element executed successfully. When run with the Xalan Java parser, however, the stylesheet creates the same result as with the earlier Xalan run and sends the following message to the command line window:

This XSLT processor doesn't support saxon:assign. 
@2017-09-19 10:58:36

While the xsl:fallback element gives you a way to handle the failure of an extension element, the boolean element-available() function gives you a way to check whether the extension element is supported before even trying to execute it.

The following revision of the stylesheet above has an xsl:choose element that uses this function to test whether the saxon:assign element is supported. If so, the saxon:assign element inside the xsl:when element gets evaluated; if not, the message "This XSLT processor doesn't support saxon:assign" gets sent wherever that XSLT processor sends such messages.



<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

     xmlns:saxon="http://icl.com/saxon"

     extension-element-prefixes="saxon"  

     version="1.0">

<xsl:output method="xml" omit-xml-declaration="yes"/>

  <xsl:variable name="color" 

       saxon:assignable="yes">red</xsl:variable>

  <xsl:template match="/">

    <xsl:choose>

      <xsl:when test="element-available('saxon:assign')">

        <saxon:assign name="color">blue</saxon:assign>

      </xsl:when>

      <xsl:otherwise>

        <xsl:message>This XSLT processor doesn't support saxon:assign.

        </xsl:message>

      </xsl:otherwise>

    </xsl:choose>

    The color variable has the following value:

    <xsl:value-of select="$color"/>

  </xsl:template>

</xsl:stylesheet>

The results, when run with Saxon and then Xalan Java, are the same as with the previous version of the stylesheet: with Saxon, the result tells us that the color variable was successfully set to "blue", and no extra messages appear in the command prompt window; when run with Xalan Java, the result tells us that the color variable remains at the original setting of "red" and the xsl:message element sends the message about the lack of support for saxon:assign to the command prompt window.

@2017-09-19 11:13:47

Using Built-in Extension Functions

An XSLT processor can add additional functions to the selection required of it by the XSLT and XPath specifications. To use one of these extension functions, you only have to declare the namespace and then reference that namespace when calling the function. (When using extension elements, you need the extension-element-prefixes attribute to tell the processor that extension elements from certain namespaces will be used in the stylesheet, but there's no need for this when using extension functions.)

The stylesheet also uses the function-available() function that must be supported by all XSLT processors to check whether the extension function is available for use by the stylesheet.

Comments

You must Sign In to comment on this topic.


© 2024 Digcode.com