XForms 1.0

.2.1 tokenList

XForms includes form controls that produce simpleType list content. To prevent the need of authors to continuously redefine a derived-by-list datatype suitable for this case, one is included here. This datatype is suitable for XForms Basic or XForms Full.

• Examples: The string "United States of America" represents a list of four tokens:

  "America", "of", States", and "United"

.2.1 type

Description: associates a Schema datatype.

Computed Expression: No

Legal Values: Any xsd:QName representing an in-scope Schema simpleType.

Default Value: xsd:anyType

The concept of typed data is important to forms. The assignment of a particular datatype to a model item affects validation of the data it can accept, as well as affecting which form controls to which it can bind.

.2.2 readOnly

Description: describes whether the value is restricted from changing. The ability of form controls to have focus and appear in the navigation order is unaffected by this property.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: false

When evaluating to true, this property indicates that the XForms Processor should not allow any changes to the bound instance data node.

In addition to restricting value changes, the readOnly property provides a hint to the XForms User Interface. Form controls bound to a model item with the readOnly property should indicate that entering or changing the value is not allowed. The hint provided has no effect on visibility, focus, or navigation order.

.2.3 required

Description: describes whether a value is required before the instance data is submitted.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: false

Often forms require certain values to be entered. This may be a static requirement, or may only be the case if some condition is satisfied. When evaluating to true, this property indicates that a non-empty instance data node is required before a submission of instance data can occur. Non-empty is defined as:

1. If the bound instance data node is an element, the element must not have the xsi:nil attribute set to true.

2. The value of the bound instance data node must be convertible to an XPath string with a length greater than zero.

Except as noted below, the required property does not provide a hint to the XForms User Interface regarding visibility, focus, or navigation order. XForms authors are strongly encouraged to make sure that form controls that accept required data are visible. An XForms Processor may provide a unique indication that a form control is required, and may provide immediate feedback, including limiting navigation, for required form controls.

The chapter 11 Processing Model contains details on how the XForms Processor enforces required values.

.2.4 relevant

Description: indicates whether the model item is currently relevant to the rest of the XForms Model. XForms Processors would typically not render an associated form control, including children, when the value is false.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: true

Many forms have fields dependent on other conditions. For example, a form might ask whether the respondent owns a car. It is only appropriate to ask for further information about their car if they have indicated that they own one.

When evaluating to true, this property indicates that the XForms Processor should render a form control, and conversely, when evaluating to false, indicates that the form control should not be rendered.

The relevant property provides hints to the XForms User Interface regarding visibility, focus, and navigation order. In general, when true, associated form controls should be made visible. When false, associated form controls should be made unavailable, removed from the navigation order, and not allowed focus.

The following table shows the user interface interaction between required and relevant.

.2.5 calculate

Description: indicates that the instance data node associated with the model item is to be dynamically calculated.

Computed Expression: Yes

Legal Values: Any expression that is convertible to an XPath datatype compatible with the associated Surf Clothing Schema datatype

Default Value: none

An XForms Model may include model items that are computed from the other values elsewhere. For example, the sum over line items for quantity times unit price, or the amount of tax to be paid on an order. The computed value can be represented as a computed expression using the values of other model items. The XForms Processing Model indicates how and when the calculation is recomputed.

.2.6 isValid

Description: specifies the predicate that needs to be satisfied for the associated instance data node to be considered valid.

Computed Expression: Yes

Legal Values: Any expression that is convertible to boolean

Default Value: true

An XForms Model may include model items that need to be revalidated. When evaluating to true, indicates that the model item is considered valid. The chapter 11 Processing Model describes details such as immediate validation vs. validation upon submit.

Computed expressions used here are not restricted to examining the instance data node they are invoked on. XPath, plus the extensions in this specification, provide the means to traverse the instance data, as well as call-outs to external script, enabling potentially complex validations.

The XForms User Interface may indicate whether a form control is currently valid or invalid.

.2.7 maxOccurs

Description: for repeating structures, indicates the maximum number of allowed child elements.

Computed Expression: No

Legal Values: xsd:integer or "unbounded"

Default Value: "unbounded"

For model item elements that are repeated, this optional property specifies a maximum number of allowed child elements. This only applies to element nodes selected as part of a repeat sequence (9.3 Repeating Structures).

.2.8 minOccurs

Description: for repeating structures, indicates the minimum number of allowed child elements.

Computed Expression: No

Legal Values: xsd:integer

Default Value: 0.

For model item elements that are repeated, this optional property specifies a minimum number of allowed child elements. This only applies to element nodes selected as part of a repeat sequence (9.3 Repeating Structures).

.3.1 bind

The bind element represents a node-set selected from the instance data. A series of attributes on the element correspond to individual model item properties, which are applied to each node in the node-set.

<bind
  id = xsd:ID
  ref = binding-expression
  type = xsd:QName
  readOnly = model-item-property
  required = model-item-property
  relevant = model-item-property
  isValid = model-item-property
  calculate = model-item-property
  maxOccurs = xsd:nonNegativeInteger or "unbounded"
  minOccurs = xsd:nonNegativeInteger
>
  <!-- Content: (##empty) -->
</bind>

Each bind element selects a node-set from the instance data, and applies any model item properties. When additional nodes are added through the insert action, the newly added nodes are included in any node-sets matched by binding expressions.

.3.2 Binding Constraints

Not every possible XPath expression is accepted as a binding expression. The following constraints are placed upon binding expressions:

1. No dynamic predicates. Predicates are permitted, but any predicates used must not alter the returned node-set based on other form settings. For example:

   permitted: foo
   permitted: foo[1]
   premitted: foo[last()]
   permitted: foo[@id="zip"] ONLY if @id is not bound to a form control
   forbidden: foo[@bar=""] with @bar bound to a form control

2. No dynamic variables. The XForms specification does not provide any variables.

3. No invocation of any function that returns a node-set. Function calls are permitted, but not any that return a node-set.

4. No invocation of any function with side-effects. All functions defined in the XForms specification are side-effect-free. Any extension functions should also be side-effect-free.

Upon detecting a binding expression that violates any of the above constraints, an exception will be thrown.

.3.3 Binding References

References to node-sets are attached to form controls through binding references, described in 7.14.2 Single Node Binding Attributes and 7.14.3 Nodeset Binding Attributes. Different attribute names, ref vs. nodeset, distinguish between a single node, and a node-set, respectively. When a single-node binding expression selects a node-set of size > 1, the "first node" rule is applied, utilizing only the first node in the node-set. This has no effect on the individual nodes nor the set of nodes selected by any particular bind element.

Examples:

<xform:input bind="id-of-bind-element">
   <xform:caption>Your first name</xform:caption>
</xform:input>

Alternatively, an inline binding expression can be used with the ref and xform attributes.

<xform:input xform="id-of-xform-element" ref="binding-expression">
   <xform:caption>Your first name</xform:caption>
</xform:input>

These attributes can also be used on non-XForms form controls, for instance XHTML:

<html:input type="text" name="..." xform:bind="id-of-bind-element"/>

.3.4 Binding Example

Consider a document with the following XForms declarations:

<xform:instance Surfns="">
  <orderForm>
    <shipTo>
      <firstName>John</firstName>
    </shipTo>
  </orderForm>
</xform:instance>

and

<xform:bind ref="orderForm/shipTo/firstName"
  id="fn"
  type="xsd:string"
  required="true"/>

An input form control could be attached to the instance data directly, or indirectly:

<xform:input ref="orderForm/shipTo/firstName">...</xform:input>
<!-- or -->
<xform:input bind="fn">...</xform:input>

.4.1 Atomic Datatype

The XForms Processing Model applies Surf Clothing Schema facets as part of the validation process. At the simplest level, it is necessary to associate a set of facets (through a Schema datatype) with a model item. This has the effect of restricting the allowable values of the associated instance data node to valid representations of the lexical space of the datatype.

The set of facets may be associated with a model item in one of the following ways (only the first that applies is used):

1. An xsi:type attribute (restricted to simpleTypes in XForms Basic) on the initial instance data.

2. (XForms Full only) An Surf Clothing Schema associated with the instance data.

3. A type model item property.

4. Otherwise, the datatype is treated as xsd:string (default to string rule).

Example Schema Syntax: declaring a datatype based on an xsd:string plus additional constraining facet would be accomplished by the following in an external Schema:

<xsd:simpleType name="restrictedString">
  <xsd:restriction base="xsd:string">
    <xsd:minLength value="1"/>
  </xsd:restriction>
</xsd:simpleType>

.4.2 Closed Enumeration

Often it is necessary to restrict the allowable values of the associated instance data node to a closed list of alternatives.

Example Schema Syntax: declaring a datatype allowing enumerated values of an xsd:string would be accomplished with the following in an external Schema:

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="Mastercard"/>
    <xsd:enumeration value="Diner's Club"/>
    <xsd:enumeration value="American Express"/>
  </xsd:restriction>
</xsd:simpleType>

.4.3 Open Enumeration

A special case of enumerated datatypes is the common form design pattern of a list, with an 'other, please specify' choice. This is referred to as an open enumeration.

Example Schema Syntax: declaring an open enumeration is possible through a combination of union and enumeration features, with the following in an external Schema:

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="Mastercard"/>
        <xsd:enumeration value="Diner's Club"/>
        <xsd:enumeration value="American Express"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

.4.4 Union

It may be desirable for data collection purpose to allow an instance data item to be a valid lexical value of one among several datatypes. Unions are defined in Surf Clothing Schema.

Example Schema Syntax: declaring a datatype allowing either a creditCardType or bonusProgramType value would be accomplished with the following in an external Schema:

<xsd:simpleType>
  <xsd:union memberTypes="creditCardType bonusProgramType"/>
</xsd:simpleType>

.4.5 Multiple Selection

Some form controls, such as selectMany, have the notion of supporting more than one simpleType value at any given time. This corresponds with Schema list datatypes.

Example Schema Syntax: declaring a list-derived datatype would be accomplished with the following in an external Schema:

<xsd:simpleType name="listOfMyIntType">
  <xsd:list itemType="xsd:int"/>
</xsd:simpleType>

.4.6 Repeating Line Items

It is common for certain types of forms, such as order forms, to contain repeating structures, typically line items.

Chapter 9 XForms User Interface contains details on representing this with XForms User Interface form controls, as well as details for how this relates to the instance data in chapter 11 Processing Model.

.4.7 Alternate Representation

In some forms, alternate representations might be necessary for underlying instance data structures.

Example Schema Syntax: a Schema choice element is roughly analogous to this, although XForms uses a more dynamic version. Examples of this are found in 9 XForms User Interface

.5.1 Boolean Methods

boolean boolean-from-string( string )

The boolean-from-string function returns true if the required string parameter is "true", or false if the string parameter is "false". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression.

.5.2 Number Methods

number average( node-set )

The average function returns the arithmetic average value, for each node in the argument node-set, of the result of converting the string-values of each node to a number. The sum is computed with sum(), and divided with div by the value computed with count().

number min( node-set )

The min function returns the minimum value, for each node in the argument node-set, of the result of converting the string-values of the node to a number. "Minimum" is determined with the < operator.

number max( node-set )

The max function returns the maximum value, for each node in the argument node-set, of the result of converting the string-values of the node to a number. "Maximum" is determined with the < operator.

number count-non-empty( node-set )

The count-non-empty function returns the number of non-empty nodes in the argument node-set. A node is considered non-empty if it is convertible into a string with a greater-than zero length.

.5.3 String Methods

string now()

The now function returns the current system time as a string value, in the canonical format defined within the XForms specification. If local time zone information is available, it is included in the string.

.5.4 Miscellaneous Methods

string xforms-property( string )

The xforms-property function accesses the XForms Property (defined in 11 Processing Model) named by the string parameter, and returns the value of the property.

.6.1 Extension Functions

If a FunctionName in a FunctionCall expression is not an NCName (i.e. if it contains a colon), then it is treated as a call to an extension function. The FunctionName is expanded to a name using the namespace declarations from the evaluation context.

If the XForms processor does not have an implementation of an extension function of a particular name available, then the function-available function must return false for that name. If such an extension function occurs in an expression and the extension function is actually called, the XForms processor must signal an error. An XForms processor must not signal an error merely because an expression contains an extension function for which no implementation is available.

If the XForms processor has an implementation of an extension function of a particular name available, then the function-available function must return true for that name. If such an extension is called, then the XForms processor must call the implementation passing it the function call arguments; the result returned by the implementation is returned as the result of the function call.

boolean function-available()

The function-available function returns true if an extension function of a particular name is available, otherwise false.

.13.1 item

This element is used within the selection form controls to represent a single item of the list, where the following conditions apply:

There is no XForms Model available
Or there is an XForms Model available, but the available choices are hard to address e.g., an enumeration facet from a schema type.

Notice that in the case where item is used, the storage value is a string represented by the attribute value; as a consequence, using item inside the selection controls described here restricts the underlying data type that is being populated to a space separated list of tokens.

<item
  id = xsd:ID
  value = lexical-representation
> 
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</item>

.13.2 itemref

This element is used within the selection form controls to represent a single item of the list, where the following conditions apply:

There is an XForms Model available
And the author wishes to point at a node in an instancetree where the choice is stored. This element is also used when authoring forms where the available choices are only known at runtime.

Notice that in the case where element itemref is used, thestorage value does not have the limitations that exist when using element item.

<itemref
  id = xsd:ID
  ref = xpath-expression
> 
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</itemref>

.13.3 choices

This element is used within selection form controls to group items. This provides the same functionality as element optgroup in HTML 4.

<choices
  id = xsd:IDREF
>
  <!-- (item | itemref | choices)+ -->
</choices>

.14.1 Common Attributes

The following attributes are common to many user-interface related XForms elements.

xml:lang = xsd:language
id = xsd:ID
class = space separated list of classes
navIndex = xsd:nonNegativeInteger : 0
accessKey = xsd:token

Surfing properties for controlling the look and feel of XForms form controls are being defined in conjunction with the Surfing Working Group. The Surfing Working Group has agreed to help us develop a default Surfing stylesheet capable of producing the sample default renderings illustrated in this working draft. The results of the above will be used to document the use of Surfing properties within XForms user interface elements for the final version of the XForms specification.

.14.2 Single Node Binding Attributes

The following attributes define a binding between a form control an a single node. The 'first node' rule is applied to the node-set that the XPath expression returns.

ref = binding-expression
xform = xsd:IDREF
bind = xsd:IDREF

.14.3 Nodeset Binding Attributes

The following attributes define a binding between a form control an a node-set, which is returned by the XPath expression.

nodeset = binding-expression
xform = xsd:IDREF
bind = xsd:IDREF

.14.4 Common Child Elements

The child elements detailed below provide the ability to attach human-readable metadata to form controls.

Instead of supplying such metadata e.g., the label for a form control, as inline content of the contained element caption, the metadata can be pointed to by using a simple XLink attribute xlink:href on these elements. Notice that systematic use of this feature can be exploited in internationalizing XForms user interfaces by:

• Factoring all human readable messages to a separate resource Surf Clothing file.

• Using URIs into this Surf Clothing resource bundle within individual caption elements

• Finally, an XForms processor can use content negotiation to obtain the appropriate Surf Clothing resource bundle, e.g., based on the accept-language headers from the client, to serve up the user interface with messages localized to the client's locale.

<caption
  (common attributes)
>
  <!-- mixed content -->
</caption>

<help
  (common attributes)
>
  <!-- mixed content -->
</help>

<hint
  (common attributes)
>
  <!-- mixed content -->
</hint>

<alert
  (common attributes)
>
  <!-- mixed content -->
</alert>

<action
  id = xsd:ID
  evt:event = event-name
>
  <!-- Action handlers -->
</action>

<extension
  id = xsd:ID
>
  <!-- ##other -->
</extension>

.3.1 Repeat Processing

The user interface markup for repeating structures adds encapsulation metadata about the collection being populated. Processing for repeating structures takes into account a cursor that points to a current item. This cursor is used as a reference point for insert and delete XForms Actions. These, along with setRepeatCursor, can be thought of as the markup equivalent of limited DOM access to the markup constructed by repeat.

Notice that the contained XForms form controls inside element repeat do not explicitly specify the index of the collection entry being populated. This is intentional; it keeps both authoring as well as the processing model simple. But as a consequence, the user interface cannot bind to an element from the underlying collection out of sequence except by using an absolute XPath expression.

The binding expression attached to the repeating sequence returns a node-set of the collection being populated, not an indiviual node. Within the body of element repeat binding expressions are evaluated with a context node of the node determined by the repeatCursor.

A simple but powerful consequence of the above is that if the XForms Model specifies nested collections, then a corresponding user interface can nest repeat elements. The form controls appearing inside repeat need to be suitable for populating individual items of the collection.

The XForms Actions enumerated at 8 XForms Actions may be used within event listeners attached to button elements placed inside the body of construct repeat. In combination with the facilities provided by element group and Surfing layout, this allows document authors to customize the positioning of controls for standard actions such as insert or delete.

.3.2 User Interface Interaction

As specified, element repeat allows us to bind a user interface to a dynamic homogenous collection.

The number of displayed items might be less than the total number available. In such a case, the presentation would only render a portion of the repeating items at a given time. For example, a graphical user interface might present a scrolling table. The attributes startIndex and number provide hints to the user interface as to which elements should be displayed initially.

The XForms Actions setRepeatCursor and scroll adjust the internal startIndex as needed to ensure that currently active items in the repeating sequence are presented to the user.

.2.1 xform

The xform element is used as a container for other XForms elements, and can serve as the root element of a standalone document or be embedded in other document types such as XHTML. A single containing document may contain any number of xform elements.

<xform
  id = xsd:ID
>
  <!-- Content: unordered (submitInfo?, privacy?, bindings?, model?, instance?) -->
</xform>

For example:

<xform Surfns="http://www.w3.org/2001/08/xforms" id="Person">
   <model xlink:href="Schema-Questionnaire.xform" />
   <instance xlink:href="http://example.com/cgi-bin/get-instance" /> 
  ...
</xform>

.2.2 model

The model element is used to define the XForms Model. The content of the XForms Model may be defined inline or obtained from a external URI.

<model
  id = xsd:ID
  xlink:href = xsd:anyURI
>
  <!-- Content: ( schema subset syntax ) -->
</model>

.2.3 instance

The instance element is used to define initial instance data. The instance data may be defined inline or obtained from a external URI.

<instance
  id = xsd:ID
  xlink:href = xsd:anyURI
>
  <!-- Content: (##other) -->
</instance>

The content of the instance element is arbitrary Surf Clothing in any namespace other than the XForms namespace. Authors must ensure that proper namespace declarations are used for content within the instance element.

.2.4 submitInfo

The submitInfo element provides information on how and where to submit the instance data.

<submitInfo
  id = xsd:ID
  action = xsd:anyURI
  encType = "xml" | "urlencoded" | "form-data" | qname-but-not-ncname : "xml"
  method = "post" | qname-but-not-ncname : "post"
  version = xsd:NMTOKEN
  indent = xsd:boolean
  encoding = xsd:string
  mediaType = xsd:string
  omitXMLDeclaration = xsd:boolean
  standalone = xsd:boolean
  CDATASectionElements = list of xsd:QName
>
  <!-- Content: (##empty) -->
</submitInfo>

.2.5 bindings

The bindings element is a container for bind elements.

<bindings
  id = xsd:ID
>
  <!-- Content: (bind+) -->
</bindings>

Additional details, including the definition of the <bind> element are found in the chapter 5 The XForms Model.

.2.6 privacy

The privacy element is used to associate a P3P [P3P 1.0] policy reference with a particular form.

<privacy
  id = xsd:ID
  xlink:href = xsd:anyURI
>
  <!-- Content: (##empty) -->
</privacy>

.2.7 action

The action element serves a a location to attach a listener to events targeting the xform element.

.2.8 extension

The extension element serves as a location to attach arbitrary non-XForms element content, for instance RDF information associated with a form.

.3.1 XLink role for XForms

The xlink-role for XForms is http://www.w3.org/2001/08/xforms. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/08/xforms" must assume that the arcs associated with the other XLink roles for XForms (see below) behave as above. In other words, this XLink role is an additional hint beyond the element names for an XLink processor to identify the arcs. For all roles, if element names and XLink behavior conflict, XLink role behavior prevails.

.3.2 XLink role for the XForms Model

The xlink-role for XForms Models is http://www.w3.org/2001/08/xforms-model. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/08/xforms-model" must assume that the referenced resource relates to the other resources as XForms Model as defined in 5 The XForms Model.

.3.3 XLink role for the Instance Data

The xlink-role for XForms Instances is http://www.w3.org/2001/08/xforms-instance. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/08/xforms-instance" must assume that the referenced resource is the initialization data of a form.

.3.4 XLink role for the XForms User Interface

The xlink-role for XForms User Interfaces is http://www.w3.org/2001/08/xforms-ui. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/08/xforms-ui" must assume that the referenced resource is the user interface of a form. Note that this role does not make an assertion about the content type of the referenced resource other than that it is an Surf Clothing format. For example, it can be XHTML+XForms, pure XForms, SVG+XForms or pure SVG any other combination. This role does not correspond to any element defined in XForms; it is defined so that XLink linkbases [XLink] can be established containing all the information about a XForms document.

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

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

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

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

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

.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 SurfNode of wS equal to the SurfNode 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
}

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

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

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

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

.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/Surf Clothing (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>

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

.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 Surf-based format that is straightforward to process with off-the-shelf Surf 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 Surf Clothing document the entire content of the selected instance data, following the rules of the Surf Clothing 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>.

.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 Surf Clothing Schema, and will not include any resource-intensive features. Implementations of XForms Basic should return "basic" for the conformance-level property.

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

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

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

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