Defining an XPath Function
A user-defined XPath function requires: (i) a name (a text string), and (ii) a definition (an XPath expression).
Additionally, you can specify one or more parameters for the function. A user-defined XPath function can also have an optional return type (specified by selecting a type from the dropdown list of the Return Type combo box). A return type is useful if you wish to check that the datatype of the returned value conforms to the selected datatype. Note that the return value is not converted to the selected datatype. If there is a type mismatch, an error is returned. If no return type is specified, no datatype check is carried out.
After a user-defined XPath function is created, it is available for use anywhere in the design. In the XSLT stylesheet, it is created as an xsl:function element that is a child of the xsl:stylesheet element, as shown in the listing below.
<xsl:function name="sps:Average" as="xs:decimal">
<xsl:param name="a" as="xs:integer"/>
<xsl:param name="b" as="xs:integer"/>
<xsl:param name="c" as="xs:integer"/>
<xsl:sequence select="avg( (\$a, \$b, \$c) )"/>
The sps:Stock function shown in the screenshot below and listed above returns the /Trades/Stock element that has a name attribute with a value that matches the content of the /Trades/Selection/Stock element. The sps:Average function listed above returns the average of three input parameter-values. The function definition uses the avg() function of XPath 2.0/3.0. The return datatype is specified to be of the xs:decimal type, which is the datatype returned by the avg() function when evaluating input values of datatype xs:integer. If the return type is specified, then the datatype of the return value is checked to see if it conforms with the specified type. If it doesn't, an error is returned.
Defining the function
To define a function, click the icon of the XPath Functions item in the Schema Tree or Design Tree. This pops up the XPath Functions dialog (screenshot above). If you wish to edit a function that has already been created, double-click its entry in the list of XPath functions. Then enter a name for the function and a definition in the Function Body pane. Parameter definitions can be entered if required (see the next two sections, Parameters and Sequences and Parameters and Nodes, for details). A return type for the function can also be specified (see above).
The most important point to bear in mind when writing the XPath expression that defines XPath function is that there is no context node for the XPath expression. If the XPath expression must locate a node then the context node for the expression can be provided in one of the following ways:
1.The XPath expression starts with the document root. The document root is specified in the first location step of the XPath expression as \$XML. For example, the XPath expression \$XML/Trades/Stock locates the first Stock child element of the /Trades element. The variable \$XML (which locates the document root of the main schema) is defined globally by StyleVision in all SPS designs.
2.The context node can be passed as a parameter. See the section Parameters and Nodes below for an explanation.
In the following cases, errors are returned:
•If a parameter is defined but is not used in the body of the definition.
•If the datatype of the value returned by the function does not match the return type defined for the function.
•If any function in the SPS contains an error, an XSLT error is generated for the whole design, even if the function containing the error is not called. Note, however, that a function can be disabled by unchecking its check box in the list of user-defined XPath functions. When disabled in the design, the function is not included in the XSLT document generated from the design. In this way, an XPath expression containing an error can be excluded from the XSLT and no XSLT error will be generated.