previous   next   contents

10 Processing Model and Conformance


Contents

This chapter is normative.

10.1 Introduction

The XForms Reference Processing Model is a normative explanation of the components, predictive behavior, and mechanisms of XForms Processors. It is not intended to constrain implementations. XForms Processors may be implemented in any manner, so long as the end results are identical to that described in this chapter.

This chapter uses the terms may, must, and should (when rendered as in this paragraph) in accord with RFC 2119.

[Editor's Feedback Request 10.1.processing: This chapter is still at an early phase and may contain errors or omissions. Feedback on this chapter is especially appreciated.]

Design Rationale

The Reference Processing Model set out in this chapter will:

10.2 XForms Properties

For each <xform> element, the XForms Processor maintains a set of properties, as described here.

version (readonly) is defined as the string "1.0" for XForms 1.0

conformance-level (readonly) strings are TBD

locale (readonly) strings are TBD, as is the process for determining the locale

timezone (readonly) strings are signed integers representing the number of minutes offset from GMT

immediate-refresh (read-write) controls whether changes in the instance data are immediately updated in the UI

immediate-revalidate (read-write) controls whether changes in the instance data immediately trigger a validation

immedate-recalculate (read-write) controls whether changes in the instance data immediately trigger a recalculation

use-nulls (read-write) controls whether XML Schema Instance nulls are placed in the instance data

The Working Group is currently discussing the syntax for accessing these properties from the Dynamic Constraints Language.

10.3 Events

XForms uses an events system as defined in [DOM2 Events], with a Capture phase, arrival at the Event Target, and then a Bubbling Phase.

Events fall into different groupings. One class of events indicates that some processing is about to happen. That processing may be halted by the event handler:

Another class of events indicates that some processing has already happened or is in progress. Such processing can not be halted by the event hander:

Finally, certain events are used by the author or the XForms Processor to cause processing to happen:

Unless otherwise noted, the target node for all events is the <xform> element. When a containing document has multiple <xform> elements, the binding is used to determine which <xform> element is used.

The Working Group is considering syntax proposals for event handlers, mainly based on [XHTML Events].

10.4 Virtual Instance Data

For each containing document, an XForms Processor must behave as if it internally maintains a set of instance data, called virtual instance data. In this document, this is represented as a virtual <instance> element, which contains and maintains all instance data associated with an <xform> element.

It is not allowed for elements in the virtual instance data to be in the XForms namespace (for example if the XML data to be submitted itself consisted of XForms elements).

Representation of virtual instance data 
<instance>
  ... instance data goes here ...
</instance>
This is an example of virtual instance data as used by the XForms Reference Processing Model.

[Editor's Feedback Request 10.4.dom: Should virtual instance data be mapped to the DOM of the containing document, or should it exist in a separate document space?]

[Editor's Feedback Request 10.4.access: From the DOM, should virtual instance data be read-only or read-write? What are possible security implications here?]

Additionally, for purposes of the Reference Processing Model, virtual instance data keeps track of which instance data items (whether elements, attributes, complex types, etc.) are "dirty", or in need of update.

10.5 XForms Processing

10.5.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. If the <model> element contains a reference to a non-local XForms Model, it is retrieved by traversing the link to it. An XForms Model that is unretrievable for any reason must be regarded as a fatal error, preventing the form from being filled.
  3. If the <instance> element contains a reference to non-local instance data, it is retrieved by traversing the link to it. Instance data that is unretrievable for any reason is ignored, in which case an XForms Processor may issue a warning.
  4. If the <xform> element currently being processed 1) contains no <instance> child, and 2) contains no <model> child, the following processing occurs:
    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-nulls property is true, populated with a null value (in whatever representation Schema finalizes upon). Note that the way Schema specifies things, only elements can hold null 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, left to right, where no matching node exists in the virtual instance data, a new node is inserted.
  5. An xforms-resume event is fired.
  6. A recalculation takes place.
  7. A UI refresh takes place.

10.5.2 Navigation Sequence Algorithm

Navigation is determined on a 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.

10.5.3 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 preventDefault() method), 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 parts 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 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 occurs to perform any defined calculations.
  5. If the immediate-refresh property is true, a refresh 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 xforms-interactive-value-changing events.
    1. Event listeners may prevent default processing.
    2. Otherwise, default handling is as follows: The current form control is revalidated. 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 occurs to perform any defined calculations.
    4. If the immediate-refresh property is true, a refresh occurs to update any form controls that might be dependent on this newly changed value.

Typical 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.).

10.5.4 Recalculate 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.

10.5.5 UI Refresh Algorithm

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

  1. For purposes of UI refresh, the virtual 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 XForms Model chapter.
  4. For each form control, the binding expression is evaluated. If the virtual 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 virtual innate 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 virtual instance data are cleared.

Editor's Note: Still to be addressed is the processing when a datatype facet or model item property are changed--what gets marked "dirty"?; what gets recalculated?; what gets revalidated?; what gets refreshed?

10.5.6 Revalidate 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.

10.6 Submit, Suspend and Reset

The form filling experience ends with submitting the form, saving it for later, or starting over. The XForms processing for these events are covered here.

The following sections describe how to instance data is prepared for submission.

10.6.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. Any invalid values must be reported to the user and submit processing must not continue.
  3. A subset or all of the virtual instance data is selected based on the binding expression used to invoke the submit request.
    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 packaged according to one of the processes defined below.
  5. Instance data is delivered over the network using the XForms Submit Protocol.

10.6.2 Suspend

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

  1. Event listeners may prevent default processing of the suspend request. Otherwise, default handling as described below occurs.
  2. No form control revalidation occurs.
  3. A subset or all of the virtual instance data is selected based on the binding expression used to invoke the suspend request.
    1. If the instance data selection results in an empty node-set, the suspend must be aborted and suspend processing must not continue.
  4. Instance data is packaged using one of the persistence formats described below, possibly including a TBD flag that says this isn't final data.
  5. Instance data is persisted either locally or remotely in a manner that is TBD.

10.6.3 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 virtual instance data is selected based on the binding expression used to invoke the suspend request.
    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 according to the rules for initialization above.
  4. The selected instance data is replaced with the new instance data.

10.6.4 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 that 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 or text/xml formats.

[Editor's Feedback Request 10.6.4.urlencoding: 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 urlencoding parsers?]

[Editor's Feedback Request 10.6.4.utf8: 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?]

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 virtual instance data, iterate over the content of the instance 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:

application/x-www-form-urlencoded 
/PersonName/@title=Mr&/PersonName/FirstName=Roland

This format consists of sets of a canonical binding expression paired with a value.
Corresponding Instance Data 
<PersonName title="Mr">
  <FirstName>Roland</FirstName>
</PersonName>

Here is the instance data for the above example.

10.6.5 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 format, this format is suitable for the persistence of binary content.

This format follows the rules of all multipart MIME data streams as outlined in [RFC 2045]. Each part is expected to contain:

  1. A "Content-Disposition" header whose value is "form-data".
  2. A name attribute specifying the canonical binding expression of the corresponding value from the instance data. Names originally encoded in non-ASCII character encoding schemes may be encoded using the method outlined in [RFC 2045].

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.
Corresponding Instance Data 
<PersonName title="Mr">
  <FirstName>Roland</FirstName>
</PersonName>

Here is the instance data for the above example.

Binary Content

Each part may be encoded and the "Content-Transfer-Encoding" header supplied if the value of that part does not conform to the default (7 bit) encoding.

Where a value within the instance data represents binary content, the value should be identified by the appropriate content type (e.g., "application/octet-stream"). If multiple values of binary content are to be returned as the result of a single model item, they should be returned as "multipart/mixed" embedded within the "multipart/form-data".

The XForms Processor may wish to supply a file name for each value of binary content. The file name may be specified with the "filename" parameter of the 'Content-Disposition: form-data' header, or in the case of multiple values of binary content, in a 'Content-Disposition: file' header of the subpart. If the file name of the client's operating system is not in US-ASCII, the file name might be approximated or encoded using the method of [RFC 2045]. This is convenient for those cases where, for example, the uploaded files might contain references to each other (e.g., a TeX file and its ".sty" auxiliary style description).

10.6.6 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. Serialize, into the XML document the entire content of the virtual instance data <instance> node.

Binary Content

Handling of binary content will likely be based on the ongoing work in the XML Protocol Working Group.

[Editor's Feedback Request 10.6.5.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")?]

10.7 Conformance

XForms have been designed for use among a wide variety of XForms Processors, of varying size and resource constraints. Because of this, multiple conformance levels are being discussed. This chapter will be updated in the future with more details.

previous   next   contents