The XForms Transform Module

From W3C XForms Group Wiki (Public)

The process of transforming an XForms instance is not unlike submitting an instance in that the transform, like the web application, has a URI and, when applied to the instance, they both have the ability to 'transform' the instance data. In addition, the transform can takes parameters in a similar way to the submission which uses the HTTP headers. They both have a 'source' document (the instance) and they have a result/response target.

The transformation Element

The transformation element represents declarative instructions on what to transform, and how.

Common Attributes: Common

Special Attributes:

resource
Attribute indicating the transformation's URI for transforming instance data. This attribute is not author-optional unless the transformation URI is provided by the resource element, which can dynamically specify the URI based on instance data. Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended.
ref
Author-optional selector binding expression enabling transformation of a portion of the instance data. The selected node, and all descendants, are selected for transformation. The default value is "/".
bind
Author-optional reference to a bind element. When present, the binding reference on this attribute is used in preference to any binding reference from the ref attribute.
version
Author-optional attribute specifying the version of the transform. The default is "1.0".
replace
Author-optional attribute specifying how the information returned after transformation should be applied. In the absence of this attribute, "instance" is assumed. The legal values are "instance" and "text".
instance
Author-optional attribute specifying the instance to replace when the replace attribute value is "instance". When the attribute is absent, then the default is the instance that contains the data to be transformed.
targetref
Author-optional attribute containing an XPath expression that indicates the target node for data replacement. The in-scope evaluation context of the transformation element is used to evaluate the expression. If replace is "instance", then the target node is replaced by the transformation result. If replace is "text", then the content of the target node is replaced by the transformation result. For other values of the replace attribute, this attribute is ignored. By default, the target node is the document element of the instance indicated by the instance attribute.


XSLT 2.0 Transform Specific Attributes:

initial-mode
Author-optional attribute for XSLT 2.0 transformations that defines the initial transformation mode when invoking the transformation and defaults to "#default".
template-name
Author-optional attribute for XSLT 2.0 transformations that defines an XSLT transform template to be called upon invoking the transformation.


Transformation Events

Unless an error is caught by, for example, a try/catch expression around the calling function, the default error handler(s) will be those defined within the transform function:

Reporting a Transform Termination Event that was triggered by an xsl:message terminate="yes" from within the transform

<transformation id="tx" ref="instance('data')" resource="my-stylesheet.xsl" instance="view">
  <message ev:event="xforms-transform-termination">The transform was terminated from within the stylesheet.</message>
</transformation>

Note: Should a transform event's context be the with respect to where the transform is invoked or where it is defined?


The xforms-transform Event

Target: transformation

Bubbles: ?

Cancelable: ?

Context Info: ?

The xforms-transform-done Event

Target transformation

Bubbles: ?

Cancelable: ?

Context Info: ?

The xforms-transform-error Event

Target: transformation

Bubbles: ?

Cancelable: ?

Context Info:

Property Type Value
error-type string One of the following: load-error, validation-error, parse-error, resource-error, transform-termination, transform-error
resource-uri string The transform resource URI that failed (xsd:anyURI)
message string The error message returned by the transformation engine.


Reporting a Transformation Error

<transformation id="tx" ref="instance('data')" resource="my-stylesheet.xsl" instance="view">
  <message ev:event="xforms-transform-error">A transform error (<output value="event('error-type')"/>) occurred.</message>
</transformation>

The Transformation Resource

The transformation resource is the URI for the transformation. It is of type xsd:anyURI.

The transform can be retrieved and loaded into an XForms instance element. In which case, the instance can be identified by use of a specific XForms URI scheme xforms:// where the ID of the instance data node that holds the transform as can be seen in the following example:

<transformation id="tx" ref="instance('data')" resource="xforms://transform" instance="view"/>

<instance id="transform">
  <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    ...
  </xsl:transform>
</instance>

The alternative would be to use a fragment identifier (with respect to the previous example: #transform) that is to be resolved within the context of the form.

NOTE: This does raise the question as to whether the fragment identifier should be constrained to the XForms model that contains it or to the entire parent document. If it is constrained to the model that it is declared within then it will not be possible to separate the XSLT transforms (for example) from the model that contains the instance data that they are applied to.

The resource element provides the transform's URI, overriding the resource attribute. If a transform has more than one resource child element, the first resource element child must be selected for use. Individually, the resource element and the resource attribute are not required. However, one of them is mandatory as there is no default transform resource.

The resource Element

The resource element allows the URI used for a transformation to be dynamically calculated based on instance data.

Common Attributes: None

Special Attributes:

value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the URI, the result of the expression is processed as if by call to the XPath string function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The URI to be used by the transformation can be specified with either the value attribute or the string content of the resource element. If both are specified, then the value attribute takes precedence. If the transform does not have a resource child element, then the transform URI is obtained from the resource attribute.

Example:

The param Element

The param element can be used to contribute information to the transformation. The transformation element can contain zero or more param child elements.

Common Attributes: None

Special Attributes: None

Content: (name, value) | (value, name)

The value of a parameter will be taken as a nodeset and it is up to the implementation as to whether it applies a single node binding or the complete nodeset.


The name Element

When the name element appears as a child of element param, it is used to specify the name of a parameter to be provided to the transform.

Common Attributes: None

Special Attributes:

value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the parameter name, the result of the expression is processed as if by call to the XPath string function. An empty string is used if the XPath evaluation fails.

The parameter name may be given by the string content of the name element, or by the result of the value attribute. If both are given, the result from the value attribute takes precedence. If the resulting name is the empty string, then the entry is considered to be void, and it is not supplied to the transform.

The value Element

When the value element appears as a child of element param, it is used to specify the value component of a parameter to be supplied to the transform.

Common Attributes: None

Special Attributes:

value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the parameter value, the result of the expression is processed as if by call to the XPath string function. An empty string is used if the XPath evaluation fails.

The parameter value may be given by the string content of the value element, or by the result of the value attribute. If both are given, the result from the value attribute takes precedence.

Evaluation context of Resource and Param Elements

In the case of a transform definition that uses either the param or resource elements with a value attribute, the evaluation context for the XPath expression they contain will be the place they are defined (the parent model). This will prevent the transform from being able to read instance data from within, for example, a repeat. Perhaps the transform function that references the transform declaration will be able to override, locally, the evaluation context?


Examples

<transformation id="tx" ref="instance('data')" resource="my-stylesheet.xsl" instance="view"/>

Like the submission, the transformation would be invoked by reference to its ID.