| 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.
| Event name | Cancelable? | Bubbles? | Target element |
|---|---|---|---|
| 4.2 Initialization Events | |||
| xforms-model-construct | No | No | model |
| xforms-model-initialize | No | No | model |
| xforms-initialize-done | No | No | model |
| xforms-ui-initialize | No | No | model |
| xforms-form-control-initialize | No | No | form control |
| xforms-model-destruct | No | No | 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-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 | |||
| xforms-activate | Yes | Yes | form control |
| xforms-value-changing | Yes | Yes | form control |
| xforms-value-changed | Yes | Yes | form control |
| xforms-select | Yes | Yes | item or
case |
| xforms-deselect | Yes | Yes | item or
case |
| xforms-scroll-first | Yes | Yes | repeat |
| xforms-scroll-last | Yes | Yes | repeat |
| xforms-insert | Yes | Yes | instance |
| xforms-delete | Yes | Yes | instance |
| xforms-valid | No | Yes | form control |
| xforms-invalid | No | Yes | form control |
| DOMFocusIn | No | No | form control |
| DOMFocusOut | No | No | 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-submit-done | No | Yes | submission |
| xforms-submit-error | No | Yes | model |
| 4.5 Error Indications | |||
| xforms-bind-exception | No | Yes | model |
| 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.
Dispatched by the containing document processor to bootstrap XForms Processor initialization.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
All XML Schemas loaded. If an error occurs while attempting to access 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 neither are given, the data model is not constructed in this phase, but during user interface construction (4.2.5 The xforms-form-control-initialize Event).
Following this, an xforms-model-initialize event is
dispatched to element model.
Dispatched at the conclusion of
xforms-model-construct processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
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).
The xforms-initialize-done event is dispatched to
the model element after initialization of that model
element is completed but before rendering of the UI has
started.
The events xforms-rebuild,
xforms-recalculate, and xforms-revalidate
are dispatched to the model element in sequence. (The
xforms-refresh event is not dispatched since the user
interface has not yet been initialized).
After all XForms Models are initialized, (which includes
completely processing xforms-rebuild,
xforms-recalculate, and
xforms-revalidate) an
xforms-ui-initialize event is dispatched to each
model element.
Dispatched as part of xforms-model-initialize
processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched as part of xforms-model-initialize
processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
The processor traverses the containing document, and for each
form control bound to the XForms Model being processed, dispatches
a xforms-form-control-initialize event to the form
control.
Dispatched as part of xforms-ui-initialize
processing.
Target: form control
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
Processing can proceed in one of two different ways depending on
whether an instance in a model exists
when the first xforms-form-control-initialize event is
processed.
If the instance referenced on the form control
existed when the first xforms-form-control-initialize
event 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
xforms-form-control-initialize event for a form
control that referenced 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).
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
Default processing 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 basic unit of navigation is the form control, through an
attribute named navindex. 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
Default processing for these events results in the following:
focus is given to the target form control.
Dispatched in response to: a user request for help or hint information.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing 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
Default processing for this event results in the following: 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
Default processing for this event results in the following:
The default handling for this event must satisfy the following conditions:
All instance data nodes in all instance elements in
the model are checked against any specified XML
Schema.
All instance data nodes in all instance elements in
the model are checked against any bound model item
properties which define constraints on the value, i.e.
required, constraint, minOccurs, maxOccurs (6 Model Item Properties).
The appropriate xforms-valid or
xforms-invalid events are dispatched to all form
controls that are bound to instance data nodes in the model. (See
4.4.7 The xforms-valid
Event and 4.4.8 The
xforms-invalid Event).
Note:
Prior to completion of the xforms-ui-initialize
event handler, there are no form controls bound to instance data,
so xforms-valid and xforms-invalid events
are not dispatched.
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
Default processing 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.
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 compute, the XPath expression is evaluated in the context of the instance node whose value or model item property is associated with the compute. 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. Self-references 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 have been changed, e.g., by user input being propagated to the instance.
An XForms processor must not recalculate computes that are not computationally dependent on one or more of the elements in L.
An XForms processor must perform 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).
Issue (recalculation-strictness):
The Working Group requests implementation feedback on whether bullets 1 and 2 above, forbidding certain computational redundancies, are necessary for conformance to XForms 1.0.
Resolution:
None recorded.
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
Default processing for this event results in the following:
The default processing 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
Default processing 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-initialize-done 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
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: an interactive change to an instance data node bound to a form control that has the attribute 'incremental' set to 'true'.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None; notification event only.
Setting the value of attribute incremental to
true on a form control enables interactive response
without finalizing on a value. Examples of this include edit boxes
(users can type various characters before navigating away) and
slider controls (users can be continuously adjusting the value
before releasing at a certain value).
Note:
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: a confirmed change to an instance data node bound to a form control, such as when the user navigates away from the form control.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None; notification event only.
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 case
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: a repeat view being scrolled past the beginning of the repeat items.
Target: repeat
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing 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.
Target: instance
Bubbles: Yes
Cancelable: Yes
Context Info: Path expression used for insert/delete (xsd:string).
Default processing for these events results in the following: None; notification event only.
Dispatched in response to: an instance data node being valid at
the conclusion of xforms-revalidate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: an instance data node being invalid
at the conclusion of xforms-revalidate processing and
to which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: a form control receiving focus.
Target: form control
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: a form control losing focus.
Target: form control
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: the readonly property on
an instance data node evaluating to true at the
conclusion of xforms-recalculate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: the readonly property on
an instance data node evaluating to false at the
conclusion of xforms-recalculate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: the required property on
an instance data node evaluating to true at the
conclusion of xforms-recalculate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: the required property on
an instance data node evaluating to false at the
conclusion of xforms-recalculate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: the relevant property on
an instance data node evaluating to true at the
conclusion of xforms-recalculate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: the relevant property on
an instance data node evaluating to false at the
conclusion of xforms-recalculate processing and to
which the target form control is bound.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only.
Dispatched in response to: completion of submit processing, including processing any returned document.
Target: submission
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing 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: model
Bubbles: Yes
Cancelable: No
Context Info: The submit method URI that failed (xsd:anyURI)
Default processing 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.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing 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)
Default processing 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)
Default processing for this event results in the following: None; notification event only.
| Table of Contents | Top |