XForms 1.1

1.5.1 Model and Instance

The model element now must support a version attribute to help authors bridge the transition between XForms 1.0 to XForms 1.1.

The instance element now has a resource attribute that allows instance data to be obtained from a URI only if the instance does not already contain data. By contrast, the src attribute overrides the inline content in an instance. The resource attribute is more useful in systems that must support save and reload of XForms-based documents.

1.5.2 Enhanced Submissions

The submission element offers many new features that allow significantly improved data communications capabilities for XForms, including:

• Access to SOAP-based web services, RESTful services, ATOM-based services, and non-XML services

• Improved control over submission processing and serialization

• Ability to control the submission URI and headers with instance data

• Targetted instance data replacement capabilities

The submission element now has a resource attribute and resource child element that allow the instance data to dynamically control the submission URI. As a result, the action attribute is deprecated, though still supported in XForms 1.1.

In XForms 1.0, submissions were already more capable than AJAX, based on the ability to automatically update a form with results from HTTP and HTTPS services, including RSS feeds. In XForms 1.1, the method attribute now supports delete as well as any other QName. The method child element also allows the method to be dynamically controlled by instance data. Submission headers can now be added, and even dynamically controlled by instance data, using the header child element. These features complete the capabilities needed for ATOM and RESTful services. XForms 1.1 also offers special submission header behavior through the mediatype attribute to allow communications with SOAP 1.1 and 1.2 web services.

The submission element now supports attributes relevant and validate, which allow form authors to turn off instance data relevance pruning and validity checking. This allows submission to be used to save and reload unfinished data on a server or the local file system.

The submission element now supports the target attribute, which allows partial instance replacement by identifying a node to be replaced with the submission result. The replace attribute also now supports a text setting, which allows the content of the target node, rather than the target node itself, to be replaced with a non-XML (text) submission result.

The submission element now also supports the xforms-submit-serialize event, which allows the form author to provide a custom serialization, such as plain text or the full XForms document, as the submission data. The serialization attribute also provides increased control over the submission data serialization, including the setting none, which allows submission to be used for simple URI activation.

The xforms-submit-done and xforms-submit-error events now have event context information available that provide more information about both successful and failed submissions, such as the response headers of successful submissions and the reason code for failed submissions.

Finally, over a dozen new examples have been added to illustrate submission usage.

1.5.3 Datatypes and Model Item Properties

XForms 1.1 now offers email and card-number datatypes so form authors can easily validate email address and credit card number input values.

To further simplify authoring, XForms 1.1 now also provides its own definitions of the XML Schema datatypes, except the XForms versions permit the empty string. Allowing empty string means that input like an age or a birthdate can be collected without being required input for validity (an empty string is not in the lexical space of XML schema datatypes like xsd:positiveInteger and xsd:date). If an input is required, the form author can still use the XForms versions of the datatypes in combination with the required model item property. The XForms datatypes also aid authoring by allowing type definitions to omit namespace qualification, e.g. type="date" rather than type="xsd:date", if the default namespace of the model is set to XForms.

The readonly model item property was defined to be an inviolate property of the data model. This means it cannot be violated by anything outside of the model item property system, including not just form controls but also XForms actions and instance data access from the DOM interface.

1.5.4 Functions and XPath Expressions

XForms 1.1 now contains many new functions that can be used in calculate and other XPath expressions to enable numerous features, including:

• basic date math and working with local dates and times: local-date(), local-dateTime(), days-to-date(), seconds-to-dateTime(), and adjust-dateTime-to-timezone()

• working with tabular data and parallel lists: current(), choose() and context()

• basic security capabilities: digest(), hmac(), and random()

• improved numeric and string processing: power(), is-card-number(), and compare()

• search across instances of a model: two parameter id() function

• access to context information added to many XForms events: event()

The specification now provides a better classification of binding expression types as well as a more rigorous definition for dynamic dependencies. These definitions ensure that XPath expressions in form controls and actions which use the index() are automatically re-evaluated when appropriate.

Due to the addition of the choose() function, the if() function is still supported but deprecated as futureproofing against the conflict with the if keyword in XPath 2.0.

1.5.5 User Interface

The behavioral description common to all form controls has been improved to indicate default layout styling and rendering requirements for required data.

The output form control has been improved to render non-text mediatypes, particularly images, obtained from instance data.

An example was added to show the use of a DOMActivate handler on an input to automatically initiate a submission once a user enters and commits input, such as a search query.

The processing model and implementation requirements on selection controls were elaborated upon to ensure consistency of behavior between selection data expressed as textual lists versus element lists.

The ability to create wizard-like interfaces with dynamically available form controls has been improved. Details are in the description of improvements to actions.

The specification provides more rigorous definitions and classifications of form controls, which have been applied throughout the specification to ensure proper support of varied features related to form controls, such as events, applicability of model item properties, and focusability.

The XForms repeat has been made more powerful and flexible. The specification now provides rigorous definitions and processing model descriptions for repeated content, including creation, destruction, IDREF resolution and event flow between repeated content and the containing content (which may itself be repeated). The repeat is now capable of operating over any nodeset, not just an homogeneous collection. A formal processing model for repeat index handling has been defined.

1.5.6 Actions and Events

The insert and delete actions have been converted from specialized actions associated with repeat to generalized data insertion and deletion operations. An entire appendix of 15 examples was added to illustrate this additional capability in detail.

All XForms actions, as well as sets of actions, can be executed conditionally or iteratively. Combined with the generalized insert and delete, this means that the information processing power of XForms 1.1 is Turing-complete.

The dispatch action now allows the event name and target to be specified by instance data. A new attribute, delay, has also been added to allow an event to be scheduled for dispatch at a later time. Since the event handler for the event can schedule same event for later dispatch, it is possible in XForms 1.1 to create background daemon tasks.

The setfocus and toggle have been improved to help with creating wizard interfaces and handling dynamically available content. The control to focus and the case to select can now be specified by instance data. These actions have also been improved relative to the recalculation processing model. They now perform deferred updates before their regular processing to ensure the user interface is automatically refreshed.

As part of the improvement to repeat index management, the setindex action now behaves more like setvalue, which means it now sets the flags for automatic recalculation, revalidation and user interface refresh. As well, this action now als performs deferred updates before its regular processing to ensure the user interface is up to date.

Finally, the setvalue action has been improved due to the addition of the context() function. Now it is possible to express the value attribute in terms of the same context node used to evaluate the single node binding. This improves the ability to use setvalue inside of a repeat to set values of instance nodes that are outside of the repeat nodeset based on values that are within the repeat nodeset.

3.2.1 Common Attributes

The Common Attribute Collection applies to every element in the XForms namespace.

anyAttribute

Foreign attributes are allowed on all XForms elements.

id

The optional id attribute of type xsd:ID assigns an identity to the containing element.

3.2.2 Linking Attributes

The host language may permit a Linking Attributes Collection to be applied to XForms elements as an alternate means of obtaining content related to the element. An example is the src attribute from [XHTML 1.0]. The schedule by which link traversal occurs is defined by the host language. If the link traversal fails, the host language may dispatch xforms-link-exception or xforms-link-error to the model associated with the in-scope evaluation context node of the element that bears the Linking Attributes Collection for the failed link.

3.2.3 Single-Node Binding Attributes

The following attributes can be used to define a binding between an XForms element such as a form control or an action and an instance data node defined by an XPath expression.

ref

Binding expression interpreted as XPath. This attribute has no meaning when a bind attribute is present.

model

Optional XForms Model selector. Specifies the ID of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when a bind attribute is present. Rules for determining the context XForms Model are located at 7.2 Evaluation Context.

bind

Reference to a bind element.

In this specification, when an XForms element is declared to have a Single-Node Binding, then the Single-Node Binding is required unless the element explicitly states that it is optional.

In some cases, an XForms element may allow a Single-Node Binding, but one or more attributes in the Single-Node Binding attribute group are inappropriate for that XForms element. In such cases, the exact attributes are listed for the XForms element, but those attributes still express a Single-Node Binding if they appear in the element. For example, the submission element forbids the model attribute because the model is defined to be the one containing the submission, so the attributes ref and bind are listed for submission rather than referring to the Single-Node Binding attribute group, but if a ref or bind attribute is used on a submission, it does express a Single-Node Binding.

When the Single-Node Binding is required, one of ref or bind is required. When bind is used, the node is determined by the referenced bind. See 4.7.2 References to Elements within a bind Element for details on selecting an identified bind that is iterated by one or more containing bind elements. When ref is used, the node is determined by evaluating the XPath expression with the evaluation context described in Section 7.2 Evaluation Context.

First-node rule: When a Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set, based on document order, is used.

It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model attribute IDREF value that refers to an ID not on a model element, or a bind attribute IDREF value that refers to an ID not on a bind element.

3.2.4 Node-Set Binding Attributes

The following attributes define a binding between an XForms element such as a form control or an action and a node-set defined by the XPath expression.

nodeset

Binding expression interpreted as XPath. This attribute has no meaning when a bind attribute is present.

model

Optional XForms Model selector. Specifies the ID of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when a bind attribute is present. Rules for determining the context XForms Model are located at 7.2 Evaluation Context.

bind

Reference to a bind element.

In this specification, when an XForms element is declared to have a Node-Set Binding, then the Node-Set Binding is required unless the element explicitly states that it is optional.

In some cases, an XForms element may allow a Node-Set Binding, but one or more attributes in the Node-Set Binding attribute group are inappropriate for that XForms element. In such cases, the exact attributes are listed for the XForms element, but those attributes still express a Node-Set Binding if they appear in the element. For example, the bind element only allows the nodeset attribute. The model and bind attributes are not allowed on a bind element, but if the nodeset attribute appears on a bind element, it does express a Node-Set Binding.

When the Node-Set Binding is required, one of nodeset or bind is required. When bind is used, the node-set is determined by the referenced bind. See 4.7.2 References to Elements within a bind Element for details on selecting an identified bind that is iterated by one or more containing bind elements. When nodeset is used, the node-set is determined by evaluating the XPath expression with the evaluation context described in Section 7.2 Evaluation Context.

It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model attribute IDREF value that refers to an ID not on a model element, or a bind attribute IDREF value that refers to an ID not on a bind element.

3.2.5 Model Item Property Attributes

This collection contains one attribute for each model item property, with an attribute name exactly matching the name of the model item property, as defined in 6.1 Model Item Property Definitions.

3.3.1 The model Element

This element represents a form definition and is used as a container for elements that define the XForms Model. No restriction is placed on how many model elements may exist within a containing document.

Common Attributes: Common, Events

Attributes from XML Events are allowed on this element to facilitate creating observers. This element is not an XForms Action.

Special Attributes:

functions

Optional space-separated list of XPath extension functions (represented by QNames) required by this XForms Model. Guidance on the use of this attribute is at 7.12 Extension Functions.

schema

Optional list of xsd:anyURI links to XML Schema documents outside this model element. The XForms Processor must process all Schemas listed in this attribute. Within each XForms Model, there is a limit of one Schema per namespace declaration, including inline and linked Schemas.

The schema definitions for a namespace are determined to be applicable to instance nodes based on an instance schema validation episode initialized to lax processing. When an element lacks a schema declaration, the XML Schema specification defines the recursive checking of children and attributes as optional. For this specification, this recursive checking is required. Schema processing for a node with matching schema declarations is governed by its content processing definition, which is strict by default.

Note:

The schema list may include URI fragments referring to elements located outside the current model elsewhere in the containing document; e.g. "#myschema". xs:schema elements located inside the current model need not be listed.

version

Optional attribute with a default value of empty string and legal values defined by the datatype xforms:versionList. Examples are "1.0" and "1.0 1.1". If one or more versions are indicated by this attribute on the default model, then an XForms Processor must support at least one of the listed language versions of XForms. Otherwise, the XForms Processor must terminate processing after dispatching the event xforms-version-exception to the default model. If the XForms Processor supports more than one language version indicated by the version setting on the default model or if the version setting on the default model is empty string (whether specified or by default), then the XForms Processor may execute the XForms content using any language conformance level available to it. If any non-default model has a version setting that is incompatible with the language version selected by the XForms Processor, then the XForms Processor must terminate processing after dispatching the event xforms-version-exception to the default model.

Examples:

<model id="Person" schema="MySchema.xsd">
  <instance resource="http://example.com/cgi-bin/get-instance" />
  ...
</model>

<model>
  <message level="modal" ev:event="xforms-version-exception" ref="event('errorinformation')"/>
  ...
</model>
...
<model id="m2" version="1.1">
  ...
</model>

<model version="1.0 1.1">
  ...
</model>
...
<model id="m2">
  ...
</model>

3.3.2 The instance Element

This optional element contains or references initial instance data.

Common Attributes: Common

Special Attributes:

src

Optional link to externally defined initial instance data. If the link traversal fails, it is treated as an exception (4.5.4 The xforms-link-exception Event).

resource

Optional link to externally defined initial instance data. If the link is traversed and the traversal fails, it is treated as an exception (4.5.4 The xforms-link-exception Event).

If the src attribute is given, then it takes precedence over inline content and the resource attribute, and the XML data for the instance is obtained from the link. If the src attribute is omitted, then the data for the instance is obtained from inline content if it is given or the resource attribute otherwise. If both the resource attribute and inline content are provided, the inline content takes precedence.

If the initial instance data is given by a link (from src or resource), then the instance data is formed by creating an XPath data model of the linked resource. If the link cannot be traversed, then processing halts after dispatching an xforms-link-exception with a resource-uri of the link that failed.

If the initial instance data is given by inline content, then instance data is obtained by first creating a detached copy of the inline content (including namespaces inherited from the enveloping ancestors), then creating an XPath data model over the detached copy. The detached copy must consist of content that would be well-formed XML if it existed in a separate document. Note that this restricts the element content of instance to a single child element.

If creation of the XPath data model for the instance data fails due to an XML error, then processing halts after dispatching an xforms-link-exception with a resource-uri indicating either the URI for an external instance, a fragment identifier URI reference (including the leading # mark) for an identified internal instance, or empty string for an unidentified internal instance. This exception could happen, for example, if the content had no top-level element or more than one top-level element, neither of which is permitted by the grammar of XML.

3.3.3 The submission Element

Details about the submission element and its processing are described in 11 The XForms Submission Module.

3.3.4 The bind Element

Element bind selects a node-set from the instance data with either a model binding expression in the nodeset attribute or the default of the in-scope evaluation context node. Other attributes on element bind encode model item properties to be applied to each node in the node-set. When bind has an attribute of type xsd:ID, the bind then associates that identifier with the selected node-set.

Common Attributes: Common, Model Item Properties (Optional)

Special Attributes:

nodeset

An optional attribute containing a model binding expression that selects the set of nodes on which this bind operates. If the attribute is omitted, the default is the in-scope evaluation context node.

See 6 Model Item Properties for details on model item properties.

See 7.2 Evaluation Context for details on how the evaluation context is determined for each attribute of the bind element.

3.4.1 The extension Element

Optional element extension is a container for application-specific extension elements from any namespace other than the XForms namespace. This specification does not define the processing of this element.

Common Attributes: Common

For example, RDF metadata could be attached to an individual form control as follows:

<input ref="dataset/user/email" id="email-input">
  <label>Enter your email address</label>
  <extension>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="#email-input">
        <my:addressBook>personal</my:addressBook>
      </rdf:Description>
    </rdf:RDF>
  </extension>
</input>

4.2.1 The xforms-model-construct Event

Dispatched to each XForms model by the XForms processor.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following:

1. All XML Schemas are loaded. If an error occurs while attempting to access or process a remote document, processing halts with an exception (4.5.4 The xforms-link-exception Event).

2. For each instance element, an XPath data model [7 XPath Expressions in XForms] is constructed from it as described in Section 3.3.2 The instance Element. If there are no instance elements, the data model is not constructed in this phase, but during user interface construction (4.2.2 The xforms-model-construct-done Event).

3. If applicable, P3P initialization occurs. [P3P 1.0]

4. Perform the behaviors of xforms-rebuild, xforms-recalculate, and xforms-revalidate in sequence on this model element without dispatching events to invoke the behaviors. The notification event markings for these operations are discarded, and the xforms-refresh behavior is not performed since the user interface has not yet been initialized.

After all XForms Models have been initialized, an xforms-model-construct-done event is dispatched to each model element.

4.2.2 The xforms-model-construct-done Event

Dispatched after the completion of xforms-model-construct processing.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event happens once, no matter how many XForms Models are present in the containing document, and results in the following, for each form control:

Processing can proceed in one of two different ways depending on whether an instance in a model exists when the first form control is processed.

If the instance referenced on the form control existed when the first form control was processed:

1. The single node binding expression is evaluated, if it exists on the form control, to ensure that it points to a node that exists. If this is not the case then the form control should behave in the same manner as if it had bound to a model item with the relevant model item property resolved to false.

2. Otherwise, the user interface for the form control is created and initialized.

If the instance referenced on the form control did not exist when the first form control for the same instance was processed:

1. For the first reference to an instance a default instance is created by following the rules described below.

   1. A root instanceData element is created.

   2. An instance data element node will be created using the binding expression from the user interface control as the name. If the name is not a valid QName, processing halts with an exception (4.5.1 The xforms-binding-exception Event).

2. For the second and subsequent references to an instance which was automatically created the following processing is performed:

   1. If a matching instance data node is found, the user interface control will be connected to that element.

   2. If a matching instance data node is not found, an instance data node will be created using the binding expression from the user interface control as the name. If the name is not a valid QName, processing halts with an exception (4.5.1 The xforms-binding-exception Event).

The above steps comprise the default processing of xforms-model-construct-done.

After all form controls have been initialized and all xforms-model-construct-done events have been processed, an xforms-ready event is dispatched to each model element.

4.2.3 The xforms-ready Event

Dispatched as part of xforms-model-construct-done processing.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

4.2.4 The xforms-model-destruct Event

Dispatched by the processor to advise of imminent shutdown of the XForms Processor, which can occur from user action, or from the load XForms Action, or as a result of form submission.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

4.3.1 The xforms-rebuild Event

Dispatched in response to: a request to rebuild the internal data structures that track computational dependencies within a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for this event results in the following:

All model item properties are initialized by processing all bind elements in document order. For each bind:

1. If the attribute nodeset is attached to the bind, it is evaluated to select an XPath node-set. Otherwise, if the bind does not have a nodeset attribute, then the selected XPath node-set consists of the in-scope evaluation context.

2. For each node in the selected XPath node-set, model item properties are applied according to the remaining attributes on the bind element (for details on the model item properties, see 6 Model Item Properties). If a node already contains a model item property of the same name due to the processing of prior bind elements, then XForms processing for the containing document halts with an exception (4.5.1 The xforms-binding-exception Event).

3. For each node in the selected XPath node-set, any child bind elements are recursively processed as described in the three points of this list.

After initial processing of the bind elements, the computational dependency data structures are rebuilt, and then the change list L is set to contain references to all instance nodes that have an associated computational expression so that a full recalculation is performed the next time the behavior of xforms-recalculate is invoked.

4.3.2 The xforms-recalculate Event

Dispatched in response to: a request to recalculate all calculations associated with a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for this event results in the following:

The values of all instance data items match their associated 'calculate' constraints, if any. All model item properties that can contain computed expressions are resolved. In addition to contributing further node value changes that will cause xforms-value-changed notifications in xforms-refresh, the model item properties that change are marked to help xforms-refresh to determine the notification events to dispatch.

• If the required model item property changes, then either the xforms-required event must be marked for dispatch if required is true or the xforms-optional event must be marked for dispatch if required is false. Marking one of these events for dispatch unmarks the other.

• If the readonly model item property changes, then either the xforms-readonly event must be marked for dispatch if readonly is true or the xforms-readwrite event must be marked for dispatch if readonly is false. Marking one of these events for dispatch unmarks the other.

• If the relevant model item property changes, then either the xforms-enabled event must be marked for dispatch if relevant is true or the xforms-disabled event must be marked for dispatch if relevant is false. Marking one of these events for dispatch unmarks the other.

An XPath expression is bound either to the value or to a model item property (e.g., required, relevant) of one or more instance nodes. The combination of an XPath expression with a single instance node's value or model item property is considered as a single computational unit, a compute, for the purposes of recalculation.

When it is time to recalculate a model item property, the XPath expression is evaluated. The evaluation context is determined from the model binding expression that applied the model item property, as defined for computed expressions in 7.2 Evaluation Context. The XPath expression may reference or refer to another instance node, in which case the value of the instance node is referenced. Each referenced instance node has as dependents those computes which directly refer to the instance node. References to the current node's value in calculate expressions are explicitly ignored, i.e., if an expression associated with a compute refers to the instance node associated with the compute, then the instance node does not take itself as a dependent. A compute is computationally dependent on an instance node (whose value may or may not be computed) if there is a path of dependents leading from the instance node through zero or more other instance nodes to the compute. A compute is part of a circular dependency if it is computationally dependent on itself.

When a recalculation event begins, there will be a list L of one or more instance nodes whose values may have been changed, e.g., by user input being propagated to the instance or by a setvalue action.

1. An XForms Processor must recalculate computes for nodes in L, if any, and nodes that are computationally dependent on nodes in L.

2. An XForms Processor must perform only a single recalculation of each compute that is computationally dependent on one or more of the elements in L.

3. An XForms Processor must recalculate a compute C after recalculating all computes of instance nodes on which C is computationally dependent. (Equivalently, an XForms Processor must recalculate a compute C before recalculating any compute that is computationally dependent on the instance node associated with C.)

4. Finally, if a compute is part of a circular dependency and also computationally dependent on an element in L, then an XForms processor must report an exception (4.5.2 The xforms-compute-exception Event).

C Recalculation Sequence Algorithm describes one possible method for achieving the required recalculation behavior.

4.3.3 The xforms-revalidate Event

Dispatched in response to: a request to revalidate a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None</p