| Table of Contents | Prev | Next | Bottom |
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:
Initialization
Interaction
Notification
Error Conditions
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 |
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.
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:
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).
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).
If applicable, P3P initialized. [P3P 1.0]
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:
The attribute nodeset attached to the bind is evaluated, resulting in a set of nodes selected.
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.
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).
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.
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:
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:
For the first reference to an instance a default instance is created by following the rules described below.
A root instanceData element is created.
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).
For the second and subsequent references to an instance which was automatically created the following processing is performed:
If a matching instance data node is found, the user interface control will be connected to that element.
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.
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.
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.
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:
Form controls that have a navindex specified and assign a positive value to it are navigated first.
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.
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.
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.
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.
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.
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.
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.
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:
All UI bindings should be reevaluated as necessary.
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.
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).
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.
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.
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.
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.
An XForms Processor should not recalculate computes that are not computationally dependent on one or more of the elements in L.
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.
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.)
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.
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.
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.
See chapter 11 Submit.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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].
input, secret, textarea, range, or upload ControlsWhen 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.
select or select1 ControlsWhen a selection is interactively changed, and the form control has the "incremental="true" setting, the event sequence is described at 4.6.6 Sequence: Selection Without Value Change, which may be followed immediately by the sequence described at 4.6.7 Sequence: Value Change.
When a selection is interactively changed, and the form control does not have the "incremental="true" setting, the event sequence is described at 4.6.6 Sequence: Selection Without Value Change.
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.
trigger ControlsActivating the form control causes the event sequence defined at 4.6.8 Sequence: Activating a Trigger.
submit ControlsActivating the form control causes the event sequence defined at 4.6.8 Sequence: Activating a Trigger, followed immediately by the event sequence defined at 4.6.9 Sequence: Submission.
xforms-recalculate
xforms-revalidate
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).
Perform further deferred updates as necessary
| Table of Contents | Top |