XSLTForms/The transform function

Description
The  function is an XSLTForms extension to the standard XForms function library. Public discussions suggest that it's based on proposals for a similar function to be included in XForms 2.0, but work seems to have stalled in 2011. There seems to be no  function in the current draft of the XPath Expressions Module, and not currently active specification of a separate module for the   function.

Syntax / Signature
The  function applies an external XSLT stylesheet to a node set. In current versions of XSLTForms (since 2014 or so), it takes a series of three or more arguments:


 * The first argument is a node to be transformed (e.g.  or just   or  ).
 * The second argument is either
 * the URI of an XSLT stylesheet, as a string (e.g. ), or
 * a string representation of an XSLT stylesheet.
 * The third argument is  if the second argument is an XSLT stylesheet in string form,   if the second argument is the URI of an XSLT stylesheet.
 * The fourth, sixth, eighth, ... arguments, if present, are names of XSLT stylesheet parameters.
 * The fifth, seventh, ninth, ... arguments, if present, are values for those parameters.

Note: Earlier versions of the function took only two arguments:  the node to be transformed, and the URI of an XSLT stylesheet.

The  function returns a string. This will seem implausible to many XSLT users, so it needs to be stressed: the  function returns a string.


 * If the XSLT output method is, the returned value is the string (wrapped, in almost all browsers under almost all circumstances, in some browser-dependent XML element).
 * If the XSLT output method is, the returned value is the serialized form of the XML document produced.  Under most circumstances, looking at it will show the angle brackets and ampersands escaped as   and  .  If the returned value is injected into the XHTML document, however, the results are formatted like normal HTML.

(And the  output method?)

Formatting data in read-only form
One use for  is to format XML instance data into appropriately styled HTML for convenient read/only display by the browser. For example:

Showing XML source
Another use for  is to pretty-print XML instance data for convenient read/only display of the XML source by the browser. For example:

This example assumes a pretty-printing stylesheet which produces output with newlines and suitable indentation. This is not necessary in principle (one could use  instead), but useful in practice, since otherwise some browsers display the entire XML document on one very long line of output.

Updating an instance
Since  returns a string, the following attempt to generate a new document instance for further processing by XForms will fail:  instead of replacing instance   with the output of the transformation, it will replace the content of   with the serialized string form of the transformation result.

If the instance contained a normal SVG document to start with, then after the trigger shown is fired, it will consist of an SVG element containing an XML-escaped SVG document as a single text-node:

One workaround for this problem is to use the experimental action  with   or   attributes, to replace either the content of the node or the node itself:

Another workaround is to submit the string to a script on the server which echoes it back as XML. (See the example in the discussion of the  action.)

Known problems and issues
In Safari, and in older versions of Chrome (through version 30 and possibly later), the transformation may fail if the stylesheet whose URI is given in the second argument to  contains an   instruction. The symptom is an error alert saying. (It's likely that this problem will also arise if the stylesheet contains an  instruction, but that has not been verified.)  This problem does not arise in Firefox, Opera, or newer versions of Chrome (from version 49 and possibly earlier).

Workaround: remove the , so that the stylesheet is a free-standing object without dependencies on other stylesheets.

Further information
Some further information can be gleaned from a a set of transform test cases which illustrate a variety of different ways to call the function and show what it produces in each case.