11 Processing Model

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:

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.

11.1 Events Overview

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.

11.2 Initialization Events

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.

11.2.1 xforms:modelConstruct

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:

  1. Schema is loaded, if any.

  2. An XPath data model is constructed from the instance data, according to the following rules:

    1. From an external source

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

  3. Following this, an xforms:modelInitialize event is dispatched to element model.

11.2.2 xforms:modelInitialize

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:

  1. The instance data has been structurally validated against the Schema, if any. If structural validation fails, all XForms processing for this containing document halts.

  2. If applicable, P3P has been initialized. [P3P 1.0]

  3. The instance data has been constructed.

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

  5. After all XForms Models are initialized, the host must dispatch an xforms:UIInitialize event to each model element.

11.2.3 xforms:initializeDone

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:

11.2.4 xforms:UIInitialize

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.

11.2.5 xforms:formControlInitialize

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.

11.3 Interaction Events

11.3.1 DOM Mutation Events

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.

11.3.2 xforms:next and xforms:previous

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:

  1. Those navigation units that support navIndex and assign a positive value to it are navigated first.

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

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

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

  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.

11.3.3 xforms:focus and xforms:blur

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?

11.3.4 xforms:activate

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.

11.3.5 xforms:valueChanging

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:

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

  2. Event recalculate has been dispatched to element model.

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

11.3.6 xforms:valueChanged

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:

  1. The value from the form control is reflected in the instance data.

  2. Event revalidate has been dispatched to element model.

  3. Event recalculate has been dispatched to element model.

  4. Event refresh has been dispatched to element model.

11.3.7 xforms:scrollFirst

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.

11.3.8 xforms:scrollLast

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.

11.3.9 xforms:insert and xforms:delete

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.

11.3.10 xforms:select and xforms:deselect

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.

11.3.11 xforms:help and xforms:hint

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.

11.3.12 xforms:alert

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.

11.3.13 xforms: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.

11.3.14 xforms:invalid

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.

11.3.15 xforms:refresh

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.

11.3.16 xforms:revalidate

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:

  1. The bound instance data node is checked against any bound Schema Constraints. If any fail, the context form control is considered invalid.

  2. The bound instance data node is checked against any bound XForms Constraints. If any fail, the context form control is considered invalid.

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

11.3.17 xforms:recalculate

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.

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

  2. An XForms processor must perform 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.

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

11.3.18 xforms:reset

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:

  1. All of the instance data is selected for resetting.

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

  3. The selected instance data is replaced with the new instance data.

11.4 XForms Submit

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.

11.4.1 xforms:submit

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:

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

  2. All selected instance data is revalidated. Any invalid instance data stops submit processing.

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

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

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

11.4.2 application/x-www-form-urlencoded

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?

Issue (issue-utf8-encoding):

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:

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

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

  3. All such encodings are concatenated, maintaining document order. The resulting string is urlencoded, as in HTML processing.

Example:

Example: application/x-www-form-urlencoded
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.

11.4.3 multipart/form-data

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:

Example: multipart/form-data
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.

11.4.4 text/xml

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:

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

11.4.4.1 Binary Content

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]

Issue (issue-instance-metadata):

Where a value within the instance data represents binary content, can we store meta-information with an xform:mediaType attribute reflecting the appropriate content type (e.g., "image/jpg")?

11.5 Error Indications

11.5.1 xforms:schemaConstraintsError

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.

11.5.2 xforms:traversalError

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.

11.5.3 xforms:invalidDatatypeError

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.