11.1.1 Design Rationale

The Reference Processing Model set out in this chapter will:

• Be simple enough to implement across a wide range of devices, including resource-constrained handhelds and appliances.

• Define a predictive processing model with enough detail for implementors to create interoperable software.

• Define a well-ordered system for calculations and dependencies independent of processor speed or threading.

• Provide a unified addressing scheme for binding expressions, independent of how the structure of the instance data is defined.

• Be simple enough for the existing base of HTML authors to quickly get up to speed.

• Be compatible (to the extent reasonably possible) with existing form processing.

11.4.1 Initialization/Resume

The following describes the initialization process for XForms. Initialization must occur before any other processing. For each xform element in the containing document, in document order, the following processing occurs:

1. An xforms-construct event is fired; this is the place for authors to handle any initialization tasks.

2. Instance data is constructed (11.4.2 Instance Data Construction).

3. An xforms-initialize event is fired. A handler for this event could perform form initialization tasks such as a database lookup.

4. A recalculation (11.4.5 Recalculation Algorithm) takes place.

5. A UI refresh (11.4.6 UI Refresh Algorithm) takes place.

11.4.2 Instance Data Construction

The following steps describe how the instance data associated with each xform element is constructed. Of the following options, the first applicable option is chosen. Only one of the following applies:

1. If an instance element is present and contains non-whitespace child nodes, the contents of the instance element are copied into the instance data tree, based on the infoset mappings defined in the XPath [XPath 1.0]data model.

2. If an instance element is present and contains a reference to non-local initial instance data, it is retrieved by traversing the link to it, then copied into the instance data as described above. A remote instance that is unretrievable for any reason is ignored, in which case an XForms Processor may issue a warning.

3. If an instance element is not present, then a default instance data configuration is produced, according to the following rules:

   1. Each form control bound to the xform element currently being processed is visited in document order. Each form control's binding expression is evaluated.

   2. If the instance data item result of evaluating the binding expression doesn't already exist, it is created, and if the use-nil property is true, populated with a nil value (an xsi:nil="true" attribute). Note that only elements can hold nil values. The form control receives a default blank value. The algorithm for creating instance data items is as follows: For each location step in the canonical binding expression, from left to right, where no matching node exists in the instance data, a new node is inserted.

      Issue (creating-instance-nodes):

      The algorithm for creating instance nodes is under discussion, with one possibility being ignoring the path information, using only the local name, in a flat list.

4. If none of the above options are fulfilled, this is an error condition, and the XForms Processor must stop processing with an error message.

11.4.3 Navigation Sequence Algorithm

Navigation is determined on a containing document-wide basis. The navigation sequence is determined as follows:

1. Those form controls that support navindex and assign a positive value to it are navigated first. Navigation proceeds from the form control with the lowest navindex value to the form control with the highest value. Values need not be sequential nor must they begin with any particular value. form controls that have identical navindex values should be 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 on a non relevant subtree are assigned a relative order in the overall sequence but do not participate as navigable controls.

4. The navigation sequence past the 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.4.4 Interactivity

XForms provides similar processing to the HTML onChange event. As users indicate completion of a form control by navigating away the following occurs:

1. If the display value has changed since the user last navigated to the form control, an xforms-value-changing event is fired. If the display value hasn't changed, processing for this event ends.

   1. Any listener may prevent default processing (one option under consideration provides a <stopevent/> action), which will end event processing immediately after the Capture and Bubbling phases. Alternatively, a listener may perform a custom translation from display value to canonical value. Any listener may have side-effects that modify any instance data item, in which case the modified instance data items must be marked "dirty".

   2. Default processing is to convert the display value of the form control to the canonical value as specified in the Datatypes chapter. Default processing should automatically take into account regional settings (if any), such as decimal character symbol, date formats, etc.

2. If the immediate-revalidate property is true, all validations (11.4.7 Revalidation Algorithm) bound to the form control are run. Note that validation is performed against the canonical value, not the display value.

   1. If any validation fails, the user must be notified, and may not be allowed to navigate away from the control. The invalid entry in the form control should be preserved. The associated instance data item is left unchanged, thereby ending processing for this event.

3. The instance data item is updated with the new value, and marked "dirty".

4. If the immediate-recalculate property is true, a recalculate (11.4.5 Recalculation Algorithm) occurs to perform any defined calculations.

5. If the immediate-refresh property is true, a refresh (11.4.6 UI Refresh Algorithm) occurs to update any form controls that might be dependent on this newly changed value.

Certain form controls allow interactive response without finalizing on a value. Examples of this include edit boxes (users can type various characters before "tabbing out") 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 currency value of "U" is not valid because it doesn't (yet) have 3 characters. This is permitted temporarily, as long as the user remains on the form control. XForms Processors with sufficient processing resources would typically update/refresh on every character. Resource-constrained XForms Processors would typically only update/refresh on the final value.

1. Any time the display value of a form control changes (such as through character or cut/paste activities), even without indication that this is a final value, an xforms-interactive-value-changing event is fired. Resource-constrained XForms Processor implementations may choose to ignore all such events.

   1. Event listeners may prevent default processing.

   2. Otherwise, default handling is as follows: The current form control is revalidated (11.4.7 Revalidation Algorithm). This is for internal purposes only, and happens regardless of the immediate-revalidate setting. If all validations on the form control are successful, the instance data item is updated, and marked "dirty". If any validations fail (indicating a transitional value) all form controls bound to the same instance data item may be directly updated with the display value. Otherwise, the following occurs:

   3. If the immediate-recalculate property is true, a recalculation (11.4.5 Recalculation Algorithm) occurs to perform any defined calculations.

   4. If the immediate-refresh property is true, a refresh (11.4.6 UI Refresh Algorithm) occurs to update any form controls that might be dependent on this newly changed value.

Implementations that choose to respond xforms-interactive-value-changing are expected optimize processing (for instance not flashing the entire screen for each character entered, etc.).

11.4.5 Recalculation Algorithm

XForms Processors are free (and encouraged) to skip or change any steps in this algorithm, as long as the end result is the same. Each form control may have a model item property priority value, which is the main factor in determining calculation order.

Following is the default handling for an xforms-recalculate event:

1. Each model item with a bound calculate model item property is visited in calculation order, which is defined as follows:

   1. Those model items that are bound to a priority and assign a positive integer to it are computed first. Computation proceeds from the model item with the lowest bound priority to the model item with the highest bound priority. Values need not be sequential nor must they begin with any particular value. Model items with the same bound priority value are computed in document order.

   2. Those model items not bound to a priority or bound to one with the value "0" are computed next. These model items are computed in document order.

2. For each model item, the expression in the calculate model item property is evaluated. Any instance data item changes as a result of this are marked with a "dirty" flag.

3. The instance data item bound to the model item is updated with the result of the calculate expression, and the "dirty" flag is set.

11.4.6 UI Refresh Algorithm

Following is the default handling for an xforms-refresh event:

1. For purposes of UI refresh, the instance data as it exists at the beginning of processing the xforms-refresh event is used.

2. Each form control is visited in refresh order, which is defined as follows:

   1. Those form controls that have a given or computed navigation sequence value are visited first, in the navigation sequence.

   2. Those form controls outside the navigation sequence are visited next. These form controls are visited in document order.

3. For each form control, the relevant constraint is evaluated, which might result in the form control being disabled/hidden/etc. as specified in the chapter 5 The XForms Model.

4. For each form control, the binding expression is evaluated. If the instance data indicates that the instance data item is not "dirty", processing for that particular form control completes.

   1. Otherwise, if the instance data item is "dirty", an xforms-instance-changed event is fired.

   2. Listeners to the xforms-instance-changed event are free to compute a new display value.

   3. Listeners to the xforms-instance-changed event are prohibited from directly updating any form controls present.

   4. Listeners to the xforms-instance-changed event are prohibited from altering any portion of the instance data. To attempt to do so results in an xforms-exception being fired.

   5. Listeners may prevent the default processing of the xforms-instance-changed event.

   6. Default processing is to convert the canonical value into a display value, taking into account regional settings (if any) such as decimal separator character, etc.

5. The form control is updated with the display value.

6. After all form controls have been updated, all "dirty" flags in the instance data are cleared.

11.4.7 Revalidation Algorithm

Revalildation always occurs within the scope of a context form control. Following is the revalidation process:

1. The bound instance data item is checked against any bound XForms Datatype constraining facets. If any fail, the context form control is considered invalid.

2. The bound instance data item is checked against any bound Schema Datatype constraining facets. If any fail, the context form control is considered invalid.

3. If a validate model item property is bound to the context form control, the expression within is evaluated. If it evaluates to false, the context form control is considered invalid.

4. If the context form control is invalid, the XForms Processor must notify the user. The XForms Processor may combine messages before presentation to the user.

11.5.1 Submit

In response to an xforms-submit event, the following takes place:

1. Event listeners may prevent default processing of the submit request. Otherwise, default handling as described below occurs.

2. Every form control is revalidated (11.4.7 Revalidation Algorithm). Any invalid values must be reported to the user and submit processing must not continue.

3. A subset or all of the instance data is selected based on the binding expression used to invoke the submit request. The selected nodes and all children are selected for serialization as submitted data. If no ref attribute is specified, all nodes in the instance data are selected by default.

   1. If the instance data selection results in an empty node-set, the submit must be aborted and submit processing must not continue.

4. Instance data is serialized according to one of the processes defined below.

5. Instance data is delivered over the network as an HTTP POST.

6. Upon successful delivery of the submit data, an xforms-destruct event is fired and form processing shuts down.

7. The response page sent by the server replaces the current containing document.

11.5.2 Reset

In response to an xforms-reset event, the following takes place:

1. Event listeners may prevent default processing of the reset request. Otherwise, default handling as described below occurs.

2. A subset or all of the instance data is selected based on the binding expression used to invoke the suspend request. The selected nodes and all children are selected for resetting. If no ref attribute is specified, all nodes in the instance data are selected by default.

   1. If the instance data selection results in an empty node-set, the reset has no effect.

3. New instance data for the selected instance data is prepared, based on the instance element associated with the current xform element, according to the rules for initialization above.

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

11.6.1 application/x-www-form-urlencoded

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.6.2 multipart/form-data) or text/xml (11.6.3 text/xml) formats.

The steps for building this persistence format is as follows:

1. Prepare a new UTF-8 encoded string buffer to hold the persisted instance data.

2. Beginning with the root element of the instance data, iterate over the selected content of the instance data in document order and build an ordered set of strings by performing the following steps:

   1. For each element with an attribute, append to the set a string of the format "path=value" where path is the canonical binding expression that refers to each attribute, and value is the character content of each attribute (urlencoded if necessary).

   2. For each element enclosing character content, append to the set a string of the format "path=value" where path is the canonical binding expression that refers to the element, and value is the character content of the element (urlencoded if necessary).

   3. For each element enclosing element content, continue the iteration.

3. Append the strings from the ordered set together, delimiting the strings with an ampersand '&' character, and place the result of the append into the UTF-8 encoded string buffer.

Example:

/PersonName/@title=Mr&/PersonName/FirstName=Roland

<PersonName title="Mr">
  <FirstName>Roland</FirstName>
</PersonName>

11.6.2 multipart/form-data

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.6.1 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 item.

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-

<PersonName title="Mr">
  <FirstName>Roland</FirstName>
</PersonName>

11.6.3 text/xml

This format permits the expression of the instance data as an XML-based format 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. Prepare a new empty XML document to hold the persisted instance data.

2. If the selected content of the instance data corresponds to a singly-rooted data structure, serialize, into the XML document the entire content of the selected instance data, beginning at the root node.

3. If the selected content of the instance data corresponds to a multiply-rooted data structure (such as a general parsed entity), an unqualified root element of <Envelope>, with an unqualified element <Body> is inserted into the XML document, and the selected instance data serialized into the content of the <Body> element.

11.7.1 XForms Basic

This conformance level will be suitable for devices with limited computing power, such as mobile phones, handheld computers, and appliances. This conformance level will depend on a subset of XML Schema, and will not include any resource-intensive features. Implementations of XForms Basic should return "basic" for the conformance-level property.

11.7.2 XForms Full

This conformance level will be suitable for more powerful forms processing, such as might be found on a standard desktop browser or a server. Implementations of XForms Full should return "full" for the conformance-level property.

Additional details will be provided in future revisions of this chapter.