4 Processing Model

This chapter defines the XForms Processing Model declaratively by enumerating the various states attained by an XForms Processor and the possible state transitions that exist in each of these states. The chapter enumerates the pre-conditions and post-conditions that must be satisfied in each of these states. XForms Processors may be implemented in any manner, so long as the end results are identical to that described in this chapter.

State transitions are in general initiated by sending events to parts of the XForms tree. The XForms Processing Model consists of events in the following categories:

4.1 Events Overview

XForms processing is defined in terms of events, event handlers, and event responses. XForms uses the events system defined in [DOM2 Events][XML Events], with an event capture phase, arrival of the event at its Target, and finally the event bubbling phase.

Throughout this chapter, each reference to "form control" as a target element is a shorthand for any of the following elements: input, secret, textarea, output, upload, trigger, range, submit, select, select1, or group.

Event name Cancelable? Bubbles? Target element
4.2 Initialization Events
xforms-model-construct No Yes model
xforms-model-construct-done No Yes model
xforms-ready No Yes model
xforms-model-destruct No Yes model
4.3 Interaction Events
xforms-previous Yes No form control
xforms-next Yes No form control
xforms-focus Yes No form control
xforms-help Yes Yes form control
xforms-hint Yes Yes form control
xforms-rebuild Yes Yes model
xforms-refresh Yes Yes model
xforms-revalidate Yes Yes model
xforms-recalculate Yes Yes model
xforms-reset Yes Yes model
xforms-submit Yes Yes submission
4.4 Notification Events
DOMActivate Yes Yes form control
xforms-value-changed No Yes form control
xforms-select No Yes item or case
xforms-deselect No Yes item or case
xforms-scroll-first No Yes repeat
xforms-scroll-last No Yes repeat
xforms-insert No Yes instance
xforms-delete No Yes instance
xforms-valid No Yes form control
xforms-invalid No Yes form control
DOMFocusIn No Yes form control
DOMFocusOut No Yes form control
xforms-readonly No Yes form control
xforms-readwrite No Yes form control
xforms-required No Yes form control
xforms-optional No Yes form control
xforms-enabled No Yes form control
xforms-disabled No Yes form control
xforms-in-range No Yes form control
xforms-out-of-range No Yes form control
xforms-submit-done No Yes submission
xforms-submit-error No Yes submission
4.5 Error Indications
xforms-binding-exception No Yes any element that can contain a binding expression
xforms-link-exception No Yes model
xforms-link-error No Yes model
xforms-compute-exception No Yes model

4.2 Initialization Events

This section defines the various stages of the initialization phase. The processor begins initialization by dispatching an event xforms-model-construct to each XForms Model in the containing document. How the XForms Processor itself is requested to initialize is implementation dependent.

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 loaded. If an error occurs while attempting to access or process a remote document, processing halts with an exception (4.5.2 The xforms-link-exception Event).

  2. If an external source for the initial instance data is given, an XPath data model [7 XPath Expressions in XForms] is constructed from it; otherwise if inline initial instance data is given, that is used instead. If the external initial instance data is not well-formed XML or cannot be retrieved, processing halts with an exception (4.5.2 The xforms-link-exception Event). If neither are given, 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 initialized. [P3P 1.0]

  4. Instance data is constructed. All strings inserted into the instance data are subject to Unicode normalization. All model item properties are initialized by processing all bind elements in document order. For each bind:

    1. The attribute nodeset attached to the bind is evaluated, resulting in a set of nodes selected.

    2. For each node in the node-set, model item properties are applied according to the remaining attributes on bind: the string value of each attribute (with a name matching one of the properties defined in 6.1 Model Item Property Definitions) is copied as the local value of the model item property of the same name.

    3. If the node already contains a model item property of the same name, XForms processing for this containing document halts with an exception (4.5.1 The xforms-binding-exception Event).

  5. Perform an xforms-rebuild, xforms-recalculate, and xforms-revalidate in sequence, for this model element. (The xforms-refresh 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 binding expression is evaluated 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.

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).

After all form controls have been initialized, 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 Interaction Events

4.3.1 The xforms-next and xforms-previous Events

Dispatched in response to: user request to navigate to the next or previous form control.

Target: form control

Bubbles: No

Cancelable: Yes

Context Info: None

The default action for these events results in the following: Navigation according to the default navigation order. For example, on a keyboard interface, "tab" might generate an xforms-next event, while "shift+tab" might generate an xforms-previous event.

Navigation is determined on a containing document-wide basis. The host language is responsible for defining overall navigation order. The following describes a possible technique based on a navindex attribute, using individual form controls as a navigation unit: The <group>, <repeat>, and <switch> structures also serve as navigation units, but instead of providing a single navigation point, they create a local navigation context for child form controls (and possibly other substructures). The navigation sequence is determined as follows:

  1. Form controls that have a navindex specified and assign a positive value to it are navigated first.

    1. Outermost form controls are navigated in increasing order of the navindex value. Values need not be sequential nor must they begin with any particular value. Form controls that have identical navindex values are to be navigated in document order.

    2. Ancestor form controls (<group>, <repeat>, and <switch>) establish a local navigation sequence. All form controls within a local sequence are navigated, in increasing order of the navindex value, before any outside the local sequence are navigated. Form controls that have identical navindex values are navigated in document order.

  2. Those form controls that do not specify navindex or supply a value of "0" are navigated next. These form controls are navigated in document order.

  3. Those form controls that are disabled, hidden, or not relevant are assigned a relative order in the overall sequence but do not participate as navigable controls.

  4. The navigation sequence past the last form control (or before the first) is undefined. XForms Processors may cycle back to the first/last control, remove focus from the form, or other possibilities.

4.3.2 The xforms-focus Event

Dispatched in response to: set focus to a form control.

Target: form control

Bubbles: No

Cancelable: Yes

Context Info: None

The default action for these events results in the following:

Focus is given to the target form control if the form control is able to accept focus. Setting focus to a repeating structure sets the focus to the repeat item represented by the repeat index.

4.3.3 The xforms-help and xforms-hint Events

Dispatched in response to: a user request for help or hint information.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for these events results in the following: If the form control has help/hint elements supplied, these are used to construct a message that is displayed to the user. Otherwise, user agents may provide default help or hint messages, but are not required to.

4.3.4 The xforms-refresh Event

Dispatched in response to: a request to update all form controls 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:

  1. All UI bindings should be reevaluated as necessary.

  2. A node can be changed by confirmed user input to a form control, by xforms-recalculate (section 4.3.6) or by the setvalue (section 10.1.9) action. If the value of an instance data node was changed, then the node must be marked for dispatching the xforms-value-changed event.

  3. If the xforms-value-changed event is marked for dispatching, then all of the appropriate model item property notification events must also be marked for dispatching (xforms-optional or xforms-required, xforms-readwrite or xforms-readonly, and xforms-enabled or xforms-disabled).

  4. For each form control, each notification event that is marked for dispatching on the bound node must be dispatched (xforms-value-changed, xforms-valid, xforms-invalid, xforms-optional, xforms-required, xforms-readwrite, xforms-readonly, and xforms-enabled, xforms-disabled). The notification events xforms-out-of-range or xforms-in-range must also be dispatched as appropriate. This specification does not specify an ordering for the events.

  5. The user interface reflects the state of the model, which means that all forms controls reflect for their corresponding bound instance data:

    • its current value

    • its validity

    • whether it is required, readonly or relevant.

4.3.5 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

An instance node is valid if and only if the following conditions hold:

  • the constraint model item property is true

  • the node satisfies any applicable XML schema definitions (including those associated by the type model item property)

Note:

A node that satifies the above conditions is valid even if it is required but empty.

The default action for this event results in the following:

All instance data nodes in all instance elements in the model are checked for validity according to the above definition. If the validity of a node changes, then the node is marked for dispatching the appropriate notification event (xforms-valid or xforms-invalid) to bound form controls during xforms-refresh as follows:

  • If the node changes from invalid to valid, then the node is marked for dispatching the xforms-valid event.

  • If the node changes from valid to invalid, then the node is marked for dispatching the xforms-invalid event.

4.3.6 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-revalidate and 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.

  • 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.

  • 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.

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.4 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.

Note:

Authors should not refer to the current node's value in calculate expressions because the effect is not well-defined. Other model item properties, such as required or readonly, however, are well-defined in the presence of self-references.

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

  1. An XForms Processor should not recalculate computes that are not computationally dependent on one or more of the elements in L.

  2. An XForms Processor should 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.4 The xforms-compute-exception Event).

D Recalculation Sequence Algorithm describes one possible method for achieving the desired recalculation behavior.

4.3.7 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:

The default action for this event is that the computational dependency data structures are rebuilt, then the change list L is set to contain references to all instance nodes that have an associated computational expression such that a full recalculate is performed the next time the xforms-recalculate event is dispatched to the model.

4.3.8 The xforms-reset Event

Dispatched in response to: a user request to reset the model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for this event results in the following:

The instance data is reset to the tree structure and values it had immediately after having processed the xforms-ready event. Then, the events xforms-rebuild, xforms-recalculate, xforms-revalidate and xforms-refresh are dispatched to the model element in sequence.

4.3.9 The xforms-submit Event

See chapter 11 Submit.

4.4 Notification Events

4.4.1 The DOMActivate Event

Dispatched in response to: the "default action request" for a form control, for instance pressing a button or hitting enter.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

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

4.4.2 The xforms-value-changed Event

Dispatched in response to: a change to an instance data node bound to a form control.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event due to a change.

Note:

For incremental processing, this specification does not define how often XForms Processors fire these events. Implementations are expected to optimize processing (for instance not flashing the entire screen for each character entered, etc.).

Note:

The change to the instance data associated with this event happens before the event is dispatched.

4.4.3 The xforms-select and xforms-deselect Events

Dispatched in response to: an item in a select, select1, or switch becoming selected or deselected.

Target: item or itemset or case

Bubbles: Yes

Cancelable: No

Context Info: None

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

4.4.4 The xforms-scroll-first and xforms-scroll-last Events

Dispatched in response to: a setindex action attempting to set an index outside the range of a repeat.

Target: repeat

Bubbles: Yes

Cancelable: No

Context Info: None

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

4.4.5 The xforms-insert and xforms-delete Events

Dispatched in response to: A event handler invoking an XForms Action insert or delete, successfully adding or deleting a repeat item..

Target: instance

Bubbles: Yes

Cancelable: No

Context Info: Path expression used for insert/delete (xsd:string).

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

4.4.6 The xforms-valid Event

Dispatched in response to: an instance data node either changing and being or becoming valid.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.5 The xforms-revalidate Event.

4.4.7 The xforms-invalid Event

Dispatched in response to: an instance data node either changing and being or becoming invalid.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.5 The xforms-revalidate Event.

4.4.8 The DOMFocusIn Event

Dispatched in response to: a form control receiving focus.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

4.4.9 The DOMFocusOut Event

Dispatched in response to: a form control losing focus.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

4.4.10 The xforms-readonly Event

Dispatched in response to: an instance data node either changing and being or becoming readonly.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.

4.4.11 The xforms-readwrite Event

Dispatched in response to: an instance data node either changing and being or becoming read-write.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.

4.4.12 The xforms-required Event

Dispatched in response to: an instance data node either changing and being or becoming required.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.

4.4.13 The xforms-optional Event

Dispatched in response to: an instance data node either changing and being or becoming optional.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.

4.4.14 The xforms-enabled Event

Dispatched in response to: an instance data node either changing and being or becoming enabled.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.

4.4.15 The xforms-disabled Event

Dispatched in response to: an instance data node either changing and being or becoming disabled.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.

4.4.16 The xforms-in-range Event

Dispatched in response to: the value of an instance data node has changed such that the value can now be represented by the form control.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched whenever the value of an instance data node that was not possible to represent given the constraints specified on a form control has changed such that the value can now be represented by the form control.

4.4.17 The xforms-out-of-range Event

Dispatched in response to: the value of an instance data node has changed such that the value can not be represented by the form control.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

This event is dispatched whenever the value of an instance data node can not be represented given the constraints specified on a form control.

4.4.18 The xforms-submit-done Event

Dispatched in response to: completion of submit processing, including processing any returned document.

Target: submission

Bubbles: Yes

Cancelable: No

Context Info: None

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

4.4.19 The xforms-submit-error Event

Dispatched as an indication of: a failure of the submit process, as defined at 11 Submit

Target: submission

Bubbles: Yes

Cancelable: No

Context Info: The submit method URI that failed (xsd:anyURI)

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

4.5 Error Indications

Error indications happen as a result of unusual conditions in the XForms Processor. Some of these are "fatal" errors, which halt processing, and bear the suffix "exception". Others are simply for notification, and bear the suffix "error". For all events in this section, it is permissible for the XForms Processor to perform some kind of default handling, for example logging error messages to a file.

4.5.1 The xforms-binding-exception Event

Dispatched as an indication of: an illegal binding expression, or a model attribute that fails to point to the ID of a model element, or a bind attribute that fails to point to the ID of a bind element, or a submission attribute that fails to point to the ID of a submission element, or an instance attribute on the submission element that fails to point to an instance element in the same model element as the submission..

Target: any element that can contain a binding expression

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: Fatal error.

4.5.2 The xforms-link-exception Event

Dispatched as an indication of: a failure in link traversal of a linking attribute.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: The URI that failed to load (xsd:anyURI)

The default action for this event results in the following: Fatal error.

4.5.3 The xforms-link-error Event

Dispatched as an indication of: a failure in link traversal of a linking attribute, in a situation not critical to form processing.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: The URI that failed to load (xsd:anyURI)

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

4.5.4 The xforms-compute-exception Event

Dispatched as an indication of: an error occurring during XPath evaluation.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: Implementation-specific error string.

The default action for this event results in the following: Fatal error.

4.6 Event Sequencing

The previous sections describe processing associated with individual events. This section gives the overall sequence of related events that must occur in several common situations. In the following lists, events that may be fired more than once are prefixed with [n].

4.6.1 For input, secret, textarea, range, or upload Controls

  • When the form control is interactively changed, and has the "incremental="true" setting, the event sequence described at 4.6.7 Sequence: Value Change may be initiated at implementation dependent intervals.

  • When the form control is interactively changed and does not have the "incremental=true" setting, no events are required to be dispatched, and thus no order is defined.

  • When focus changes from the form control and the value has changed, the event sequence is as described at 4.6.7 Sequence: Value Change.

4.6.2 For output Controls

  • No event sequences are defined.

4.6.3 For select or select1 Controls

4.6.4 For trigger Controls

4.6.5 For submit Controls

4.6.6 Sequence: Selection Without Value Change

  1. xforms-deselect

  2. xforms-select

4.6.7 Sequence: Value Change

  1. xforms-recalculate

  2. xforms-revalidate

  3. xforms-refresh performs reevaluation of UI binding expressions then dispatches these events according to value changes, model item property changes and validity changes:

    • [n] xforms-value-changed

    • [n] xforms-valid or xforms-invalid

    • [n] xforms-enabled or xforms-disabled

    • [n] xforms-optional or xforms-required

    • [n] xforms-readonly or xforms-readwrite

    • [n] xforms-out-of-range or xforms-in-range

    (The order in which these events are dispatched is not defined).

  4. Perform further deferred updates as necessary

4.6.8 Sequence: Activating a Trigger

  1. DOMActivate

4.6.9 Sequence: Submission

  1. xforms-submit

  2. xforms-submit-done or xforms-submit-error