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. The XForms Model is initialized.

4. All binding expressions are evaluated. If any fail to conform to the binding expression constraints, an exception is thrown.

5. An xforms-initialize event is fired. A handler for this event could perform form initialization tasks that require other parts of XForms to be previously initialized.

6. A recalculation (11.4.5 Recalculation Sequence Algorithm) takes place.

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

1. 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 results in an xforms-exception, which if unhandled, resutls in a fatal error..

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

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 node 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 nodes 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 basic unit of navigation is the form control. The <group>, <repeat>, <switch> and <component> structures also serve as navigation units, but instead of providing a navigation point 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 non relevant 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 propagate="stop" attribute), 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 node, in which case the modified instance data nodes 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 revalidations (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 node is left unchanged, thereby ending processing for this event.

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

4. If the immediate-recalculate property is true, a recalculate (11.4.5 Recalculation Sequence 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 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.

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. XForms Basic 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 revalidations on the form control are successful, the instance data node is updated, and marked "dirty". If any validations fail (indicating a transitional value) all form controls bound to the same instance data node 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 Sequence 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 Sequence Algorithm

XForms Processors are free (and encouraged) to skip or optimize any steps in this algorithm, as long as the end result is the same. The XForms recalculation algorithm considers model items and model item properties to be vertices in a directed graph. Edges between the vertices represent computational dependencies between vertices.

Following is the default handling for a recalculate action:

1. A master dependency directed graph is created. Details below at 11.4.5.1 Details on Creating the Master Dependency Directed Graph.

2. To provide consistent behavior, implementations must reduce the number of vertices to be processed by computing a pertinent dependency subgraph consisting only of vertices and edges that are reachable from nodes that require recomputation. Details on this are available at 11.4.5.2 Details on Creating the Pertinent Dependency Subgraph. Note that on a first recomputation (such as on form load), the pertinent dependency subgraph will be the same as the master dependency directed graph.

3. A topological sort is performed on the vertices of the pertinent dependency subgraph, resulting in an order of evaluation in which each vertex is evaluated only after those vertices on which it depends and before all vertices which depend on it. Details below at 11.4.5.3 Details on Computing Individual Vertices.

4. The recalculate action completes.

// Use depth-first search to explore master digraph subtrees rooted at
// each changed vertex. A 'visited' flag is used to stop exploration
// at the boundaries of previously explored subtrees (because subtrees
// can overlap in directed graphs).

for each vertex r in Lc
	if r is not visited
	{
		Push the pair (NIL, r) onto a stack
		while the stack is not empty
		{
			(v, w) = pop dependency pair from stack
			if w is not visited
			{
				Set the visited flag of w to true
				Create a vertex wS in S to represent w
				Set the index of w equal to the array location of wS
				Set the index of wS equal to the array location of w
				Set the XMLNode of wS equal to the XMLNode of w
				For each dependency node x of w
					Push the pair (w, x) onto the stack
			}
			else Obtain wS from index of w
			
			if v is not NIL
			{
				Obtain vS from index of v
				Add dependency node for wS to vS
				Increment inDegree of wS
			}
		}
	}

// Now clear the visited flags set in the loop above
	
for each vertex vS in S
{
	Obtain v from index of vS
	Assign false to the visited flag of v
}

11.4.6 UI Refresh Algorithm

Following is the default handling for a refresh action:

1. For purposes of UI refresh, the instance data as it exists at the beginning of processing the refresh action 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 node is not "dirty", processing for that particular form control completes.

   1. Otherwise, if the instance data node 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 node is checked against any bound XForms Datatype constraining facets. If any fail, the context form control is considered invalid.

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

3. If a isValid 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 a submitInstance action, the following takes place:

1. Event listeners may prevent default processing of the submit request. Otherwise, default handling as described below occurs, following a successful xforms-submit event notification:

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 binding attributes are 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. If the withResponse value is "replace":

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

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

11.5.2 Reset

In response to a resetInstance action, the following takes place, following a successful xforms-reset event notification:

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 binding attributes are 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 selected by the string "urlencoded" in the encType attribute of xform:submitInfo.

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 selected by the string "form-data" in the encType attribute of xform:submitInfo.

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

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

11.6.3 text/xml

This format is selected by the string "xml" in the encType attribute of xform:submitInfo.

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. 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, following the rules of the XML output method defined in XPath [XPath 1.0] section 16 and 16.1, using the values supplied as attributes of the xform:submitInfo element..

2. If the selected content of the instance data corresponds to a multiply-rooted data structure (such as a general parsed entity), an the above serialization takes place, after which the serialized instance data is inserted as child elements of the unqualified element <Body>, which is in turn inserted as a child of the unqualified element <Envelope>.

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.

11.7.3 Conforming XForms Processors

All XForms Processors must support the required portions of the specifications normatively listed as references (C References).

XForms Basic Processors must implement all required features labeled as Basic.

XForms Full Processors must implement all required features.

11.7.4 Conforming XForms Containing Documents

All XForms Containing Documents must conform to the required portions of the specifications normatively listed as references (C References). XForms elements are typically inserted into a containing document in multiple places. The root element for each individual fragment must be xform, a form control, or one of group, switch, repeat, component, defComponent. Individual XForms fragments must be schema-valid against the Schema for XForms (A Schema for XForms).

All XForms Basic Containing Documents must conform to all required portions of this specification marked as Basic, and additionally not include any features not specifically marked as Basic.

All XForms Full Containing Documents must conform to all required portions of this specification.

11.7.5 Conforming XForms Generators

XForms Basic Generators must create conforming XForms Basic documents.

XForms Full Generators must create conforming XForms Basic and XForms Full documents, depending on the author's choice.