| Table of Contents | Prev | Next | Bottom |
Note:
This chapter has undergone significant revision since last publication. The diff-marked version of this chapter does not include indications of changes, due to the large amount of new material.
This chapter defines the XForms processing model declaratively, i.e., describing the various states attained by an XForms processor, and the possible state transitions that exist with respect to each of these states. In defining these states and state transitions, this 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.
The XForms processing model consists of the following three phases:
initialization
User interaction
Submission
Each of these phases is further subdivided as explained in detail in subsequent sections of this chapter. State transitions in the processing model occur when specific events are received, and the event handler that processes the event determines the new state.
Thus, XForms processing is defined in terms of events, event handlers, and event responses. XForms uses the events system defined in [DOM2 Events], with a event Capture phase, arrival of the event at its Target, and finally the event Bubbling Phase.
| Event name | Cancelable? | Bubbles? | Target element |
|---|---|---|---|
| 11.2 Initialization Events | |||
| modelConstruct | No | No | model
|
| modelInitialize | No | No | model
|
| initializeDone | No | No | model
|
| UIInitialize | No | No | model
|
| formControlInitialize | No | No | model
|
| 11.3 Interaction Events | |||
| previous | Yes | Yes | form control |
| next | Yes | Yes | form control |
| focus | Yes | Yes | form control |
| blur | Yes | Yes | form control |
| activate | Yes | Yes | form control |
| valueChanging | Yes | Yes | form control |
| valueChanged | Yes | Yes | form control |
| scrollFirst | Yes | Yes | repeat
|
| scrollLast | Yes | Yes | repeat
|
| insert | No | Yes | instance |
| delete | Yes | Yes | instance |
| select | Yes | Yes | form control or switch |
| deselect | Yes | Yes | form control or switch |
| help | Yes | Yes | form control |
| hint | Yes | Yes | form control |
| alert | Yes | Yes | form control |
| valid | No | Yes | form control |
| invalid | No | Yes | form control |
| refresh | Yes | Yes | model
|
| revalidate | Yes | Yes | form control or model |
| recalculate | Yes | Yes | model
|
| reset | Yes | Yes | model
|
| 11.4 XForms Submit | |||
| submit | Yes | Yes | submitInfo
|
| 11.5 Error Indications | |||
| schemaConstraintsError | No | Yes | model |
| traversalError | No | Yes | model |
| invalidDatatypeError | No | Yes | model |
Note:
Events editorial whiteboard:
If the submit event targets submitInfo (which seems reasonable), we should allow XForms Actions as children of <submitInfo>.
Did we get rid of destruct? I couldn't find a reference either way.
This section defines the various stages of the
initialization phase.The processing application begins
initialization by dispatching an event xforms:modelConstruct to each XForms Model in the containing document.
Dispatched in response to: XForms Processor initialization.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
Schema is loaded, if any.
An XPath data model is constructed from the instance data, according to the following rules:
From an external source
If there is no reference to an external instance, from an inline instance
Note:
If neither of these are supplied, the instance is constructed from the user interface, during user interface construction.
Following this, an xforms:modelInitialize event is dispatched to element model.
Dispatched in response to: completion of xforms:modelConstruct processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
The instance data has been structurally validated against the Schema, if any. If structural validation fails, all XForms processing for this containing document halts.
If applicable, P3P has been initialized. [P3P 1.0]
The instance data has been constructed.
The xforms:initializeDone event is dispatched to the model element after initialization
of that model element is completed but before rendering of the UI has
started.
After all XForms Models are initialized, the host must dispatch an
xforms:UIInitialize event to each model element.
Dispatched in response to: xforms:modelInitialize processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
Dispatched in response to: XForms Processor user interface initialization.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
The host processor traverses the containing document, and for each form control, dispatches a xforms:formControlInitialize event to the form control.
Dispatched in response to: xforms:UIInitialize processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
If the referenced model contains doesn't have instance data, it is created by following the rules for default instance data.
@@@text here on default XForms Model construction.
Dispatched in response to: any change in the instance data.
Target: instance data node
Bubbles: Yes
Cancelable: No
Context Info: varies
In implementations that support the DOM, standard DOM mutation events should be dispatched to the changing target nodes whenever the instance data changes. Note that script, using the method getInstanceDocument() and a tree-walk, is required to associate event handlers with the instance data.
Dispatched in response to: user request to navigate to the next or previous form control.
Target: form control
Bubbles: Yes
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" would typically generate an xforms:next event, while "shift+tab" would generate an xforms:previous event.
Navigation is determined on a containing document-wide basis. The
basic unit of navigation is the form control. 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:
Those navigation units that support navIndex and assign a positive value to it are navigated first.
Outermost navigation units are navigated in increasing order
of the navIndex value. Values need not be sequential nor must they begin with any
particular value. Navigation units that have identical navIndex values are be navigated in document order.
Ancestor navigation units establish a local navigation
sequence. All navigation units within a local sequence are navigated, in
increasing order of the navIndex value, before any outside the local sequence are navigated. Navigation
units that have identical navIndex values are navigated in document order.
Those form controls that do not supply 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: a form control gaining or losing focus through any means.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for these events results in the following: None; notification events only.
| Editorial note | |
Do these events apply also to group,
switch, and repeat?
|
|
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.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Certain form controls allow 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). Interactive temporary values such as this are expressly allowed to be "invalid", that is outside the permissible value space. This is because incomplete data may be present while the user is entering transitional values.
Example: A partially entered credit card value of "3" is not valid because it doesn't (yet) have enough characters. This is permitted temporarily, as long as the user remains on the form control. XForms Full Processors would update/refresh on every character. XForms Basic Processors would typically only update/refresh on the final value.
Default processing for this event results in the following:
If the partial value meets all validity constraints, it is reflected in the instance data. If not, the instance data remains as it was before processing this event.
Event recalculate has been dispatched to element model.
Event refresh has been dispatched to element model.
Implementations that choose to implement valueChanging are expected optimize processing (for instance not flashing the entire
screen for each character entered, etc.).
Note:
XForms Basic processors are not required to generate or respond to these events.
Dispatched in response to: a change to an instance data node bound to a form control, 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:
The value from the form control is reflected in the instance data.
Event revalidate has been dispatched to element model.
Event recalculate has been dispatched to element model.
Event refresh has been dispatched to element model.
Dispatched in response to: a repeat view is 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 repeat view is scrolled past the end 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: No
Context Info: Path expression used for insert/delete.
Default processing for these events results in the following: None; notification event only.
Dispatched in response to: an item in a selectOne,
selectMany, or switch becoming selected or deselected.
Target: form control or switch
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 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: None; notification event only. User agents may provide default help or hint messages.
Dispatched in response to: a form control failing validation.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: An error message displayed, informing the user of the action needed to make the form control valid.
Dispatched in response to: a form control becoming valid with respect to the bound instance data.
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 becoming invalid with respect to the bound instance data.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following:
Event alert is dispatched to the the form control.
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 will reflect the state of the model. This means:
All form controls show the current value corresponding to the bound instance data.
All form controls show the validity state of the corresponding bound instance data.
Any form control associated with a model item property
relevant evaluating to false is disabled/hidden/etc.
Dispatched in response to: a request to revalidate one or all form controls associated with a particular XForms Model.
Target: model or a form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
Revalidation may occur targeted to a context form control. The default handling for this event must satisfy the following conditions:
The bound instance data node is checked against any bound Schema Constraints. If any fail, the context form control is considered invalid.
The bound instance data node is checked against any bound XForms Constraints. If any fail, the context form control is considered invalid.
If the context form control is invalid, the XForms Processor must
dispatch event invalid to the context form control. Otherwise, event valid must be dispatched to the form control.
When element model is targeted by this event, the above is
applied to every form control in document order.
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:
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.
D Recalculation Sequence Algorithm describes one possible method for achieving the desired recalculation behavior.
Dispatched in response to: a user request to reset the instance data.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
All of the instance data is selected for resetting.
New instance data for the selected instance data is prepared,
based on the instance element associated with the current
model element, according to the rules for initialization above.
The selected instance data is replaced with the new instance data.
Form filling experience ends with submitting the form, or perhaps starting over. The XForms processing for these events are covered here. The following sections describe how the instance data is prepared for submission.
Dispatched in response to: a user request to submit the instance data.
Target: submitInfo
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
A node from the instance data is selected, based on the attribute
ref on element submitInfo. This node and all child nodes,
are considered for the remainder of the submit process.
All selected instance data is revalidated. Any invalid instance data stops submit processing.
Selected instance data is serialized according to one of the
processes defined below, as indicated by element submitInfo attributes
mediaType and mediaTypeExtension. Nodes that have an
associated relevant constraints that evaluates to false are not serialized.
Instance data is delivered over the network using the network
protocol indicated by element submitInfo attribute
method.
Note:
The HTTP "get" protocol is deprecated for use in form submission. Form authors should use "post" for greater compatibility.
The response returned from the submission is applied as follows:
if element submitInfo attribute replace has the value of
"all", the entire containing document is replaced. If the attribute
value is "instance", the response is parsed as XML and the internal instance data is
replaced with the result, using the same processing as remote instance data
retrieved through xlink:href, and the xforms:initialize event is dispatched to element model. Behaviors of other possible values for attribute replace
are not defined in this specification.
Under no circumstances may more than a single concurrent submit process be under way for a particular XForms Model.
This format is selected by the string application/x-www-form-urlencoded in element submitInfo attribute mediaType.
Note:
This serialization format is deprecated, and will be removed in a future version of the XForms specification. For greater compatibility with XML and non-western characters, form authors should choose a different serialization format.
This format is intended to facilitate the integration of XForms into HTML forms processing environments, and represents an extension of the [XHTML 1.0] form content type of the same name with extensions to expresses the hierarchical nature of instance data.
This format is not suitable for the persistence of binary content. Therefore, it is recommended that XForms capable of containing binary content use either the multipart/form-data (11.4.3 multipart/form-data) or text/xml (11.4.4 text/xml) formats.
Issue (issue-urlencoding-mods):
Modifications to urlencoding process
The urlencoding technique given here does not exactly match how legacy implementations produce urlencoded data. (In particular, we are adding contextual information with slashes and multiple location-steps) Will this approach interfere with legacy implementations?
Under discussion is the intent to have the data be UTF8 encoded; however, this is dependent upon IETF developments. Would UTF8 meet the needs of the forms community?
Instance data is urlencoded with the following rules:
Each element node is visited in document order. If the element contains only a single node, it is selected for inclusion. Note that attribute information is not preserved.
Elements selected for inclusion are encoded as "EltName=value;", where "=" and ";" are literal characters, "EltName" represents the element local name, and "value" represents the contents of the text node. Note that contextual path information is not preserved, nor are namespace prefixes, and multiple elements might have the same name.
All such encodings are concatenated, maintaining document order. The resulting string is urlencoded, as in HTML processing.
Example:
FirstName=Roland;
This format consists of simple name-value pairs.
<PersonName title="Mr"> <FirstName>Roland</FirstName> </PersonName>
Here is the instance data for the above example. Note that very little of the data is preserved. Authors desiring greater data integrity should select a different serialization format.
This format is selected by the string multipart/form-data in element submitInfo attribute mediaType.
This format is intended to facilitate the integration of XForms into HTML forms processing environments, and represents an extension of the [XHTML 1.0] form content type of the same name that expresses the hierarchical nature of instance data. Unlike the application/x-www-form-urlencoded (11.4.2 application/x-www-form-urlencoded) format, this format is suitable for the persistence of binary content.
This format follows the rules of all multipart MIME data streams for form data as outlined in [RFC 2388], with the "name" of each part being the canonical binding expression that references the selected instance data node.
Example:
Content-Type: multipart/form-data; boundary=AaB03x --AaB03x Content-Disposition: form-data; name="/PersonName/@title" Mr --AaB03x Content-Disposition: form-data; name="/PersonName/FirstName" Roland --AaB03x ...Possibly more data... --AaB03x-
This format consists of sets of a canonical binding expression paired with a value.
<PersonName title="Mr"> <FirstName>Roland</FirstName> </PersonName>
Here is the instance data for the above example.
This format is selected by the string text/xml in element submitInfo attribute mediaType.
This format permits the expression of the instance data as XML that is straightforward to process with off-the-shelf XML processing tools. In addition, this format is suitable for the persistence of binary content.
The steps for building this persistence format is as follows:
An XML document is produced following
the rules of the XML output method defined in XPath [XSLT]
section 16 and 16.1, using the values supplied as attributes of the
submitInfo element.
Instance data nodes with values of the types xsd:base64Binary and xsd:hexBinary are specifically allowed, and are included in the serialized data according to the rules defined in [XML Schema part 2]
Dispatched in response to: instance data becoming schema-invalid.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only. Default error handling may be used.
Dispatched in response to: a failure in link traversal of an xlink:href attribute value.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: The URI that failed to load.
Default processing for this event results in the following: None; notification event only. Default error handling may be used.
Dispatched in response to: an invalid parameter passed to an XForms function.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None; notification event only. Default error handling may be used.
| Table of Contents | Top |