XForms 1.0

1 About the XForms 1.0 Specification

1.1 Background

Forms are an important part of the Web, and they continue to be the primary means for enabling interactive Web applications. Web applications and electronic commerce solutions have sparked the demand for better Web forms with richer interactions. XForms 1.0 is the response to this demand, and provides a new platform-independent markup language for online interaction between a person (through an XForms Processor) and another, usually remote, agent. XForms are the successor to HTML forms, and benefit from the lessons learned from HTML forms.

Further background information on XForms can be found at http://www.w3.org/MarkUp/Forms.

1.2 Reading the Specification

This specification has been written with various types of readers in mind—in particular XForms authors and XForms implementors. We hope the specification will provide authors with the tools they need to write efficient, attractive and accessible documents without overexposing them to the XForms implementation details. Implementors, however, should find all they need to build conforming XForms Processors. The specification begins with a general presentation of XForms before specifying the technical details of the various XForms components.

The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.

This document uses the terms may, must, and should in accord with [RFC 2119].

1.3 How the Specification is Organized

The specification is organized into the following chapters:

Chapters 1 and 2: An introduction to XForms. The introduction outlines the design principles and includes a brief tutorial on XForms.
Chapters 3 and up: XForms reference manual. The bulk of the reference manual consists of the specification of XForms. This reference defines XForms and how XForms Processors must interpret the various components in order to claim conformance.
Appendixes: Appendixes contain a normative description of XForms described in XML Schema, information on references, and other useful information.

1.4 Documentation Conventions

Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:

xforms: The XForms namespace 3.1 The XForms Namespace
html: The XHTML namespace [XHTML 1.0]
xsd: The XML Schema namespace [XML Schema part 1]
xsi: The XML Schema for instances namespace [XML Schema part 1]
ev: The XML Events namespace [XML Events]
my: Any user defined namespace

This is only a convention; any namespace prefix may be used in practice.

The following typographical conventions are used to present technical material in this document.

Official terms are defined in the following manner: [Definition: You can find most terms in chapter 13 Glossary Of Terms]. Links to terms may be specially highlighted where necessary.

The XML representations of various elements within XForms are presented using the syntax for Abstract Modules in XHTML Modularization [XHTML Modularization].

Examples are set off typographically:

Example: Example item

Example Item

References to external documents appear as follows: [Sample Reference] with links to the references section of this document.

Sample Reference: Reference - linked to from above.

The following typesetting convention is used for non-normative commentary:

Note:

A gentle explanation or admonition to readers.

Editorial note: Editorial Note Name
Editorial commentary, not intended for final publication.

Issue (sample-implementation-issue):

Issue-Name

A specific issue for which input from implementors is requested, as part of the Candidate Recommendation phase.

Resolution:

None recorded.

2 Introduction to XForms

XForms have been designed on the basis of several years' experience with HTML forms. HTML Forms have formed the backbone of the e-commerce revolution, and having shown their worth, have also indicated numerous ways they could be improved.

The primary difference when comparing XForms with HTML Forms, apart from XForms being in XML, is the separation of the data being collected from the markup of the controls collecting the individual values. By doing this, it not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse of forms, since the underlying essential part of a Form is no longer irretrievably bound to the page it is used in.

A second major difference is that XForms, while designed to be integrated into XHTML, is no longer restricted only to be a part of that language, but may be integrated into any suitable markup language.

XForms has striven to improve authoring, reuse, internationalization, accessibility, usability, and device independence. Here is a summary of the primary benefits of using XForms:

Strong typing: Submitted data is strongly typed and can be checked using off-the-shelf tools. This speeds up form filling since it reduces the need for round trips to the server for validation.
XML submission: This obviates the need for custom server-side logic to marshal the submitted data to the application back-end. The received XML instance document can be directly validated and processed by the application back-end.
Existing schema re-use: This obviates duplication, and ensures that updating the validation rules as a result of a change in the underlying business logic does not require re-authoring validation constraints within the XForms application.
External schema augmentation: This enables the XForms author to go beyond the basic set of constraints available from the back-end. Providing such additional constraints as part of the XForms Model enhances the overall usability of the resulting Web application.
Internationalization: Using XML 1.0 for instance data ensures that the submitted data is internationalization ready.
Enhanced accessibility: XForms separates content and presentation. User interface controls encapsulate all relevant metadata such as labels, thereby enhancing accessibility of the application when using different modalities. XForms user interface controls are generic and suited for device-independence.
Multiple device support: The high-level nature of the user interface controls, and the consequent intent-based authoring of the user interface makes it possible to re-target the user interaction to different devices.
Less use of scripting: By defining XML-based declarative event handlers that cover common use cases, the majority of XForms documents can be statically analyzed, reducing the need for imperative scripts for event handlers.

2.1 An Example

In the XForms approach, forms are comprised of a section that describes what the form does, called the XForms Model, and another section that describes how the form is to be presented.

Consider a simple electronic commerce form that might be rendered as follows:

It is clear that we are collecting a value that represents whether cash or credit card is being used, and if a credit card, its number and expiration date.

This can be represented in the XForms model element, which in XHTML would be contained within the head element:

<xforms:model>
  <xforms:instance>
    <root>
      <method/>
      <number/>
      <expiry/>
    </root>
  </xforms:instance>
  <xforms:submission action="http://example.com/submit" method="post" id="submit"/>
</xforms:model>

This simply says that we are collecting three pieces of information (note that we have as yet not said anything about their types), and that they will be submitted using the URL in the action attribute.

XForms 1.0 defines a device-neutral, platform-independent set of form controls suitable for general-purpose use. The controls are bound to the XForms model via the XForms binding mechanism, in this simple case using the ref attribute on the controls. This markup would appear within the body of an XHTML document (note that we have intentionally defaulted the XForms namespace prefix here):

<select1 ref="method">
  <label>Select Payment Method</label>
  <item>
    <label>Cash</label>
    <value>cash</value>
  </item>
  <item>
    <label>Credit</label>
    <value>cc</value>
  </item>
</select1>
<input ref="number">
  <label>Credit Card Number</label>
</input>
<input ref="expiry">
  <label>Expiration Date</label>
</input>
<submit submission="submit">
  <label>Submit</label>
</submit>

Notice the following features of this design:

The user interface is not hard-coded to use radio buttons. Different devices (such as voice browsers) can render the concept of "select one" as appropriate.
Form controls always have labels directly associated with them as child elements—this is a key feature designed to enhance accessibility.
There is no need for an enclosing form element, as in HTML. (See 2.4 Multiple Forms per Document for details on how to author multiple forms per document)
Markup for specifying form controls has been simplified in comparison with HTML forms.

The fact that you can bind form controls to the model like this simplifies integrating XForms into other host languages, since any form control markup may be used to bind to the model.

2.2 Providing XML Instance Data

The XForms Processor can directly submit the data collected as XML instance data. In the example, the submitted data would look like this:

Example: Submitted Data

<root>
  <method>cc</method>
  <number>1235467789012345</number>
  <expiry>2001-08</expiry>
</root>

XForms processing keeps track of the state of the partially filled form through this instance data. Initial values for the instance data may be provided or left empty as in the example. Element instance essentially holds a skeleton XML document that gets updated as the user fills out the form. It gives the author full control on the structure of the submitted XML data, including namespace information. When the form is submitted, the instance data is serialized as an XML document. Here is a fuller version of the above example:

Example: Model

<xforms:model>
  <xforms:instance>
    <payment method="cc" xmlns="http://commerce.example.com/payment">
      <number/>
      <expiry/>
    </payment>
  </xforms:instance>
  <xforms:submission action="http://example.com/submit" method="post"/>
</xforms:model>

In this case the submitted data would look like this:

Example: Submitted Data

<payment method="cc" xmlns="http://commerce.example.com/payment">
  <number>1235467789012345</number>
  <expiry>2001-08</expiry>
</payment>

This design has features worth calling out:

There is complete flexibility in the structure of the XML instance data, including the use of attributes. Notice that XML namespaces are used, and that a wrapper element of the author's choosing contains the instance data.
Empty elements number and expiry serve as place-holders in the XML structure, and will be filled in with form data provided by the user.
An initial value ("cc") for the form control is provided through the instance data, in this case an attribute method. In the submitted XML, this initial value will be replaced by the user input, if the user changes the form control displaying that data.

To connect this instance data with form controls, the ref attributes on the form controls need to be changed to point to the proper part of the instance data, using binding expressions:

Example: Binding Form Controls to Instance Nodes with ref

... xmlns:my="http://commerce.example.com/payment"
...
<xforms:select1 ref="@method">
...
<xforms:input ref="my:number">
...
<xforms:input ref="/my:payment/my:expires">

Binding expressions are based on XPath [XPath 1.0], including the use of the @ character to refer to attributes, as seen here. Note that for illustrative purposes, the first two expressions make use of the XPath context node, which defaults to the top-level element (here my:payment). The third expression shows an absolute path.

2.3 Constraining Values

XForms allows data to be checked for validity as the form is being filled. In the absence of specific information about the types of values being collected, all values are returned as strings, but it is possible to assign types to values in the instance. For instance in the example, number should accept digits only, and should have between 14 and 18 digits and expiry should accept only valid month/date combinations.

Furthermore, the credit card information form controls for number and expiry are only relevant if the "cc" option is chosen for method, but are required in that case.

By specifying an additional component, model item properties, authors can include rich declarative validation information in forms. Such information can be taken from XML Schemas as well as XForms-specific additions, such as relevant. Such properties appear on bind elements, while Schema constraints are expressed in an XML Schema fragment, either inline or external. For example:

Example: Declarative Validation with Model Item Properties

... xmlns:my="http://commerce.example.com/payment"...

<xforms:model>
    ...
  <xforms:bind ref="/my:payment/my:number"
      relevant="/my:payment/@as = 'cc'"
      required="true()"
      type="my:ccnumber"/>

  <xforms:bind ref="/my:payment/my:expiry"
      relevant="/my:payment/@as = 'cc'"
      required="true()"
      type="xsd:gYearMonth"/>

  <xsd:schema ...>
    ...
    <xsd:simpleType name="ccnumber">
      <xsd:restriction base="xsd:string">
        <xsd:pattern value="\d{14,18}"/>
      </xsd:restriction>
    </xsd:simpleType>
    ...
  </xsd:schema>
</xforms:model>

Note:

In the above example, the relevant expression uses absolute XPath notation (beginning with /) because the evaluation context nodes for computed expressions are determined by the bind ref binding expression (see 7.3 Evaluation Context), and so any relative node path in the first bind relevant above would be relative to /my:payment/my:number

2.4 Multiple Forms per Document

XForms processing places no limits on the number of individual forms that can be placed in a single containing document. When a single document contains multiple forms, each form needs a separate model element. The first model element may omit a unique id attribute (as have all the examples above), but subsequent model elements require an id attribute so that they can be referenced from elsewhere in the containing document.

In addition, form controls need to specify which model element contains the instance data to which they bind. This is accomplished through a model attribute alongside the ref attribute. The default for the model attribute is the first model element in document order.

The next example adds an opinion poll to our electronic commerce form.

Example: Adding a poll model

<xforms:model>
  <xforms:instance>
    ...payment instance data...
  </xforms:instance>
  <xforms:submission action="http://example.com/submit" method="post"/>
</xforms:model>

<xforms:model id="poll">
  <xforms:instance>
    <helpful/>
  </xforms:instance>
  <xforms:submission id="pollsubmit" .../>
</xforms:model>

Additionally, the following markup would appear in the body section of the document:

Example: Form Controls for poll model

<xforms:select1 ref="/helpful" model="poll">
  <xforms:label>How useful is this page to you?</xforms:label>
  <xforms:item>
    <xforms:label>Not at all helpful</xforms:label>
    <xforms:value>0</xforms:value>
  </xforms:item>
  <xforms:item>
    <xforms:label>Barely helpful</xforms:label>
    <xforms:value>1</xforms:value>
  </xforms:item>
  <xforms:item>
    <xforms:label>Somewhat helpful</xforms:label>
    <xforms:value>2</xforms:value>
  </xforms:item>
  <xforms:item>
    <xforms:label>Very helpful</xforms:label>
    <xforms:value>3</xforms:value>
  </xforms:item>
</xforms:select1>

<xforms:submit submission="pollsubmit">
  <xforms:label>Submit</xforms:label>
</xforms:submit>

The main difference here is the use of model="poll", which identifies the instance.

More XForms examples can be found in G Complete XForms Examples.

3 Document Structure

XForms 1.0 is an application of XML [XML 1.0] and has been designed for use within other XML vocabularies—in particular within a future version of XHTML [XHTML 1.0]. XForms always requires such a host language. This chapter discusses the structure of XForms that allow XForms to be used with other document types.

3.1 The XForms Namespace

The XForms namespace has the URI: http://www.w3.org/2002/08/xforms/cr. Any future Working Drafts are expected to use a different identifier, though a final identifier will be allocated before XForms becomes a W3C Recommendation.

XForms Processors must use the XML namespaces mechanism [XML Names] to recognize elements and attributes from this namespace.

3.2 XForms Core Attribute Collections

3.2.1 Common Attributes

The Common Attribute Collection applies to every element in the XForms namespace.

anyAttribute: Foreign attributes are allowed on all XForms elements.

A host language must include an attribute of type xsd:ID on each XForms element.

3.2.2 Linking Attributes

The Linking Attributes Collection applies to XForms elements include a link to a remote resource.

src: The src attribute assigns a URI to be automatically retrieved.

Note:

Since linking attribute URIs are defined in terms of the XML Schema datatype xsd:anyURI, the same internationalization benefits and whitespace cautions apply as discussed in [XML Schema part 2].

All linking attributes behave as an [XLink 1.0] link between the current document and the resource indicated, with an actuate value of "onLoad" and a show value of "embed". Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended.

Note:

The XForms Working Group is tracking with the HTML Working Group on a method of describing link structures.

3.2.3 Single-Node Binding Attributes

The following attributes define a binding between a form control or an action and an instance data node defined by an XPath expression.

ref: Binding expression. This attribute has no meaning when a bind attribute is present.
model: XForms Model selector. Optional when a containing document contains only one XForms Model, otherwise required, except when the bind attribute is present, in which case this attribute has no meaning.
bind: Reference to a bind element.

One of ref or bind is required. When bind is used, the node is determined by the referenced bind.

It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model idref value that refers to an id not on a model element, or a bind IDREF value that refers to an id not on a bind element.

First-node rule: When a Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set is used.

3.2.4 Node-Set Binding Attributes

The following attributes define a binding between a form control or an action and a node-set defined by the XPath expression.

nodeset: Binding expression. This attribute has no meaning when a bind attribute is present.
model: XForms Model selector. Optional when a containing document contains only one XForms Model, otherwise required, except when the bind attribute is present, in which case this attribute has no meaning.
bind: Reference to a bind element.

One of nodeset or bind is required. When bind is used, the node-set is determined by the referenced bind.

It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model IDREF value that refers to an id not on a model element, or a bind IDREF value that refers to an id not on a bind element.

3.3 The XForms Core Module

The XForms Core Module defines the major structural elements of XForms, intended for inclusion in a containing document. The elements and attributes included in this module are:

Element	Attributes	Minimal Content Model
model	Common, functions (QNameList), schema (list of xsd:anyURI)	(instance\|xsd:schema\| submission\|bind\|Action)*
instance	Common, Linking	(ANY)
submission	Common, ref (binding-expression), action (xsd:anyURI), mediatype (xsd:string), method ("post"\|"get"\|"put"\|qname-but-not-ncname), version (xsd:NMTOKEN), indent (xsd:boolean), encoding (xsd:string), omit-xml-declaration (xsd:boolean), standalone (xsd:boolean), cdata-section-elements (QNameList), replace ("all"\|"instance"\|"none"\|qname-but-not-ncname), separator (';' \| '&')	Action*
bind	Common, nodeset (model-binding-expression), type (xsd:QName), readonly (xsd:string), required (xsd:string), relevant (xsd:string), constraint (xsd:string), calculate (xsd:string), minOccurs (xsd:nonNegativeInteger\|"unbounded"), maxOccurs (xsd:nonNegativeInteger)	(bind)*

Elements defined in the XForms Actions module, when that module is included, are also allowed in the content model of model and submission, as shown above.

Within the containing document, these structural elements are typically not rendered.

The XForms Processor must ignore any foreign-namespaced attributes that are unrecognized, and must process unrecognized foreign-namespaced elements according to the 3.4 The XForms MustUnderstand Module rules.

Note that the presence of foreign namespaced elements is subject to the definition of the containing document profile.

3.3.1 The model Element

This element represents a form definition and is used as a container for elements that define the XForms Model. No restriction is placed on how many model elements may exist within a containing document.

Common Attributes: Common

Special Attributes:

functions: Optional list of XPath extension functions used by this XForms Model. It is an error to use an undeclared extension function.
schema: Optional link to a list of XML Schema documents that should be processed along with this instance data. The XML Schemas may be a sibling element referenced by a URI fragment, such as "#myschema". The XForms Processor must process all Schemas listed on this attribute.

Issue (locating-schemas):

The Working Group requests implementation feedback on this technique of locating XML Schemas required for form processing.

Resolution:

None recorded.

This example shows a simple usage of model, with the XForms namespace defaulted:

Example: Model

<model id="Person" schema="MySchema.xsd">
   <instance src="http://example.com/cgi-bin/get-instance" />
   ...
</model>

3.3.2 The instance Element

This optional element contains or references initial instance data.

Common Attributes: Common

Special Attributes:

Linking Attributes: Optional link to externally defined instance data. If the link traversal fails, it is treated as an exception (4.5.2 The xforms-link-exception Event).

If both an attribute and inline content are provided, the linked version takes precedence as described at 4.2.1 The xforms-model-construct Event.

The content of the instance element is arbitrary XML in any namespace. The content of this element is treated as opaque data, used to create an XPath data model consisting of various nodes. Authors must ensure that proper namespace declarations are used for content within the instance element.

3.3.3 The submission Element

This element encodes how, where, and what to submit.

XML Representation: <submission>

This element represents declarative instructions on what to submit, and how.

Common Attributes: Common

Special Attributes:

ref: Optional selector binding expression enabling submission of a portion of the instance data. The selected node, and all children, are selected for submission.
action: Required destination URI for submitting instance data.
mediatype: Optional attribute specifying, in the form of a media-type string, a serialization format for the instance data. The default value is "application/xml".
method: Required attribute specifying the protocol to be used to transmit the serialized instance data. There is no default value.
version: Optional attribute specifying the version of XML to be serialized.
indent: Optional attribute specifying whether the serializer should add extra whitespace nodes for readability.
encoding: Optional attribute specifying an encoding for serialization.
omit-xml-declaration: Optional attribute specifying whether to omit the XML declaration on the serialized instance data.
standalone: Optional attribute specifying whether to include a standalone declaration in the serialized XML.
cdata-section-elements: Optional attribute specifying element names to be serialized with CDATAsections.
replace: Optional attribute specifying how the information returned after submit should be applied. In the absence of this attribute, "all" is assumed.
separator: Optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is ';'.

The following attributes correspond to (in spelling, processing, and default values) attributes on the output element of [XSLT 1.0], with the exception of using xsd:boolean to replace "yes"|"no":

version
indent
encoding
omit-xml-declaration
cdata-section-elements

Note:

The following XSLT attributes have no counterpart in XForms:

doctype-system
doctype-public

Elements defined in the XForms Actions module, when that module is included, are also allowed in the content model of submission.

3.3.4 The bind Element

Element bind selects a node-set selected from the instance data with a model binding expression in the nodeset attribute. Other attributes on element bind encode model item properties to be applied to each node in the node-set. If the bind has an attribute of type xsd:ID, the bind then associates that identifier with the selected node-set.

Common Attributes: Common

Special Attributes:

nodeset: A model binding expression that selects the set of nodes on which this bind operates, as defined in 7.4.1 Model Binding Expressions.
model item properties: One attribute for each model item property as defined in 6.1 Model Item Property Definitions.

When additional nodes are added through action insert, the newly added nodes are included in any node-sets matched by binding expressions—see action insert in 9.3.5 The insert Element.

See 7.3 Evaluation Context for details on how binding affects the evaluation context.

3.4 The XForms MustUnderstand Module

Certain elements, such as extension or foreign namespaced elements defined in a host language might be critical to the operation of a particular form. To indicate this, the MustUnderstand module defines a single attribute that can be used on any element.

Element	Attributes	Minimal Content Model
ANY	xforms:mustUnderstand (xsd:boolean)	n/a

It is a fatal error if an element is marked mustUnderstand="true", and the XForms processor does not have an implementation available for processing the element.

3.5 The XForms Extension Module

There are many different ways a host language might include XForms. One approach uses only well-formed processing, disregarding validation. Another case uses strict validation, for example XHTML 1.0, in which only predefined elements are allowed. Another common approach is to allow unregulated content in a few selected places. A host language that chooses this option can use the Extension module.

Element	Attributes	Minimal Content Model
extension	Common	ANY

3.5.1 The extension Element

Optional element extension is a container for application-specific extension elements from any namespace other than the XForms namespace. This specification does not define the processing of this element.

Common Attributes: Common

For example, RDF metadata could be attached to an individual form control as follows:

<input ref="dataset/user/email" id="email-input">
  <label>Enter your email address</label>
  <extension>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="#email-input">
        <my:addressBook>personal</my:addressBook>
      </rdf:Description>
    </rdf:RDF>
  </extension>
</input>

4 Processing Model

This chapter defines the XForms Processing Model declaratively by enumerating the various states attained by an XForms Processor and the possible state transitions that exist in each of these states. The chapter enumerates the pre-conditions and post-conditions that must be satisfied in each of these states. XForms Processors may be implemented in any manner, so long as the end results are identical to that described in this chapter.

State transitions are in general initiated by sending events to parts of the XForms tree. The XForms Processing Model consists of events in the following categories:

Initialization
Interaction
Notification
Error Conditions

4.1 Events Overview

XForms processing is defined in terms of events, event handlers, and event responses. XForms uses the events system defined in [DOM2 Events][XML Events], with an event capture phase, arrival of the event at its Target, and finally the event bubbling phase.

Event name	Cancelable?	Bubbles?	Target element
4.2 Initialization Events
xforms-model-construct	No	No	`model`
xforms-model-initialize	No	No	`model`
xforms-initialize-done	No	No	`model`
xforms-ui-initialize	No	No	`model`
xforms-form-control-initialize	No	No	form control
xforms-model-destruct	No	No	`model`
4.3 Interaction Events
xforms-previous	Yes	No	form control
xforms-next	Yes	No	form control
xforms-focus	Yes	No	form control
xforms-help	Yes	Yes	form control
xforms-hint	Yes	Yes	form control
xforms-refresh	Yes	Yes	`model`
xforms-revalidate	Yes	Yes	`model`
xforms-recalculate	Yes	Yes	`model`
xforms-reset	Yes	Yes	`model`
xforms-submit	Yes	Yes	`submission`
4.4 Notification Events
xforms-activate	Yes	Yes	form control
xforms-value-changing	Yes	Yes	form control
xforms-value-changed	Yes	Yes	form control
xforms-select	Yes	Yes	`item` or `case`
xforms-deselect	Yes	Yes	`item` or `case`
xforms-scroll-first	Yes	Yes	`repeat`
xforms-scroll-last	Yes	Yes	`repeat`
xforms-insert	Yes	Yes	`instance`
xforms-delete	Yes	Yes	`instance`
xforms-valid	No	Yes	form control
xforms-invalid	No	Yes	form control
DOMFocusIn	No	No	form control
DOMFocusOut	No	No	form control
xforms-readonly	No	Yes	form control
xforms-readwrite	No	Yes	form control
xforms-required	No	Yes	form control
xforms-optional	No	Yes	form control
xforms-enabled	No	Yes	form control
xforms-disabled	No	Yes	form control
xforms-submit-done	No	Yes	`submission`
xforms-submit-error	No	Yes	`model`
4.5 Error Indications
xforms-bind-exception	No	Yes	`model`
xforms-link-exception	No	Yes	`model`
xforms-link-error	No	Yes	`model`
xforms-compute-exception	No	Yes	`model`

4.2 Initialization Events

This section defines the various stages of the initialization phase. The processor begins initialization by dispatching an event xforms-model-construct to each XForms Model in the containing document.

4.2.1 The xforms-model-construct Event

Dispatched by the containing document processor to bootstrap XForms Processor initialization.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

All XML Schemas loaded. If an error occurs while attempting to access a remote document, processing halts with an exception (4.5.2 The xforms-link-exception Event).
If an external source for the instance is given, an XPath data model [7 XPath Expressions in XForms] is constructed from it; otherwise if an inline instance is given, that is used instead. If neither are given, the data model is not constructed in this phase, but during user interface construction (4.2.5 The xforms-form-control-initialize Event).
Following this, an xforms-model-initialize event is dispatched to element model.

4.2.2 The xforms-model-initialize Event

Dispatched at the conclusion of xforms-model-construct processing.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

If applicable, P3P initialized. [P3P 1.0]
Instance data is constructed. All strings inserted into the instance data are subject to Unicode normalization. All model item properties are initialized by processing all bind elements in document order. For each bind:
1. The attribute nodeset attached to the bind is evaluated, resulting in a set of nodes selected.
2. For each node in the node-set, model item properties are applied according to the remaining attributes on bind: the string value of each attribute (with a name matching one of the properties defined in 6.1 Model Item Property Definitions) is copied as the local value of the model item property of the same name.
3. If the node already contains a model item property of the same name, XForms processing for this containing document halts with an exception (4.5.1 The xforms-binding-exception Event).
The xforms-initialize-done event is dispatched to the model element after initialization of that model element is completed but before rendering of the UI has started.
The events xforms-rebuild, xforms-recalculate, and xforms-revalidate are dispatched to the model element in sequence. (The xforms-refresh event is not dispatched since the user interface has not yet been initialized).
After all XForms Models are initialized, (which includes completely processing xforms-rebuild, xforms-recalculate, and xforms-revalidate) an xforms-ui-initialize event is dispatched to each model element.

4.2.3 The xforms-initialize-done Event

Dispatched as part of xforms-model-initialize processing.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following: None; notification event only.

4.2.4 The xforms-ui-initialize Event

Dispatched as part of xforms-model-initialize processing.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

The processor traverses the containing document, and for each form control, dispatches a xforms-form-control-initialize event to the form control.

4.2.5 The xforms-form-control-initialize Event

Dispatched as part of xforms-ui-initialize processing.

Target: form control

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

Processing can proceed in one of two different ways depending on whether an instance in a model exists when the first xforms-form-control-initialize event is processed.

If the instance referenced on the form control existed when the first xforms-form-control-initialize event was processed:

The binding expression is evaluated to ensure that it points to a node that exists. If this is not the case then the form control should behave in the same manner as if it had bound to a model item with the relevant model item property resolved to false.

If the instance referenced on the form control did not exist when the first xforms-form-control-initialize event for a form control that referenced the same instance was processed:

For the first reference to an instance a default instance is created by following the rules described below.
1. A root instanceData element is created.
2. An instance data element node will be created using the binding expression from the user interface control as the name. If the name is not a valid QName, processing halts with an exception (4.5.1 The xforms-binding-exception Event).
For the second and subsequent references to an instance which was automatically created the following processing is performed:
1. If a matching instance data node is found, the user interface control will be connected to that element.
2. If a matching instance data node is not found, an instance data node will be created using the binding expression from the user interface control as the name. If the name is not a valid QName, processing halts with an exception (4.5.1 The xforms-binding-exception Event).

4.2.6 The xforms-model-destruct Event

Bubbles: No

Cancelable: Yes

Context Info: None

Default processing for these events results in the following: If the form control has help/hint elements supplied, these are used to construct a message that is displayed to the user. Otherwise, user agents may provide default help or hint messages, but are not required to.

4.3.4 The xforms-refresh Event

Dispatched in response to: a request to update all form controls associated with a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following: The user interface reflects the state of the model, which means that all forms controls reflect for their corresponding bound instance data:

its current value
its validity
whether it is required, readonly or relevant.

4.3.5 The xforms-revalidate Event

Dispatched in response to: a request to revalidate a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

The default handling for this event must satisfy the following conditions:

All instance data nodes in all instance elements in the model are checked against any specified XML Schema.
All instance data nodes in all instance elements in the model are checked against any bound model item properties which define constraints on the value, i.e. required, constraint, minOccurs, maxOccurs (6 Model Item Properties).
The appropriate xforms-valid or xforms-invalid events are dispatched to all form controls that are bound to instance data nodes in the model. (See 4.4.7 The xforms-valid Event and 4.4.8 The xforms-invalid Event).

Note:

Prior to completion of the xforms-ui-initialize event handler, there are no form controls bound to instance data, so xforms-valid and xforms-invalid events are not dispatched.

4.3.6 The xforms-recalculate Event

Dispatched in response to: a request to recalculate all calculations associated with a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

The values of all instance data items match their associated 'calculate' constraints, if any. All model item properties that can contain computed expressions are resolved.

An XPath expression is bound either to the value or to a model item property (e.g., required, relevant) of one or more instance nodes. The combination of an XPath expression with a single instance node's value or model item property is considered as a single computational unit, a compute, for the purposes of recalculation.

When it is time to recalculate a compute, the XPath expression is evaluated in the context of the instance node whose value or model item property is associated with the compute. The XPath expression may reference or refer to another instance node, in which case the value of the instance node is referenced. Each referenced instance node has as dependents those computes which directly refer to the instance node. Self-references are explicitly ignored, i.e., if an expression associated with a compute refers to the instance node associated with the compute, then the instance node does not take itself as a dependent. A compute is computationally dependent on an instance node (whose value may or may not be computed) if there is a path of dependents leading from the instance node through zero or more other instance nodes to the compute. A compute is part of a circular dependency if it is computationally dependent on itself.

When a recalculation event begins, there will be a list L of one or more instance nodes whose values have been changed, e.g., by user input being propagated to the instance.

An XForms processor must not recalculate computes that are not computationally dependent on one or more of the elements in L.
An XForms processor must perform a single recalculation of each compute that is computationally dependent on one or more of the elements in L.
An XForms processor must recalculate a compute C after recalculating all computes of instance nodes on which C is computationally dependent. (Equivalently, an XForms Processor must recalculate a compute C before recalculating any compute that is computationally dependent on the instance node associated with C.)
Finally, if a compute is part of a circular dependency and also computationally dependent on an element in L, then an XForms processor must report an exception (4.5.4 The xforms-compute-exception Event).

Issue (recalculation-strictness):

The Working Group requests implementation feedback on whether bullets 1 and 2 above, forbidding certain computational redundancies, are neccessary for conformance to XForms 1.0.

Resolution:

None recorded.

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

4.3.7 The xforms-rebuild Event

Dispatched in response to: a request to rebuild the internal data structures that track computational dependencies within a particular XForms Model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

The default processing for this event is that the computational dependency data structures are rebuilt, then the change list L is set to contain references to all instance nodes that have an associated computational expression such that a full recalculate is performed the next time the xforms-recalculate event is dispatched to the model.

4.3.8 The xforms-reset Event

Dispatched in response to: a user request to reset the model.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

The instance data is reset to the tree structure and values it had immediately after having processed the xforms-initialize-done event. Then, the events xforms-rebuild, xforms-recalculate, xforms-revalidate and xforms-refresh are dispatched to the model element in sequence.

4.3.9 The xforms-submit Event

See chapter 11 Submit.

4.4 Notification Events

4.4.1 The xforms-activate Event

Dispatched in response to: the "default action request" for a form control, for instance pressing a button or hitting enter.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following: None; notification event only.

4.4.2 The xforms-value-changing Event

Dispatched in response to: an interactive change to an instance data node bound to a form control that has the attribute 'incremental' set to 'true'.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following: None; notification event only.

Setting the value of attribute incremental to true on a form control enables interactive response without finalizing on a value. Examples of this include edit boxes (users can type various characters before navigating away) and slider controls (users can be continuously adjusting the value before releasing at a certain value).

Note:

This specification does not define how often XForms Processors fire these events. Implementations are expected to optimize processing (for instance not flashing the entire screen for each character entered, etc.).

Note:

The change to the instance data associated with this event happens before the event is dispatched.

4.4.3 The xforms-value-changed Event

Dispatched in response to: a confirmed change to an instance data node bound to a form control, such as when the user navigates away from the form control.

Target: form control

This chapter defines the datatypes used in defining an XForms model.

5.1 XML Schema Built-in Datatypes

XForms supports all XML Schema datatypes except for xsd:duration. Concepts value space, lexical space and constraining facets are as specified in [XML Schema part 2]. XML Schema features used in XForms are divided into two modules, called Basic and Full, which are used respectively by XForms Basic and XForms Full. Base types included in module Basic are marked with an asterisk *. Both modules support datatypes derived by restriction and derived by list from these base types.

Built-in primitive types:

dateTime *
time *
date *
gYearMonth *
gYear *
gMonthDay *
gDay *
gMonth *
string *
boolean *
base64Binary *
hexBinary
float
decimal *
double
anyURI *
QName
NOTATION

Note:

The built-in datatype xsd:duration is not supported at any conformance level, except as an abstract datatype. Instead, either xforms:dayTimeDuration or xforms:yearMonthDuration should be used.

Built-in derived types:

normalizedString
token
language
Name
NCName
ID
IDREF
IDREFS
ENTITY
ENTITIES
NMTOKEN
NMTOKENS
integer *
nonPositiveInteger *
negativeInteger *
long *
int *
short *
byte *
nonNegativeInteger *
unsignedLong *
unsignedInt *
unsignedShort *
unsignedByte *
positiveInteger *

5.2 XForms Datatypes

The Schema for XForms derives the following types to facilitate defining model in XForms. These types are included in XForms Basic as well as XForms Full.

5.2.1 xforms:listItem

This datatype serves as a base for the xforms:listItems datatype. The value space for listItem permits one or more characters valid for xsd:string, except whitespace characters.

5.2.2 xforms:listItems

XForms includes form controls that produce simpleType list content. This is facilitated by defining a derived-by-list datatype. The value space for listItems is defined by list-derivation from listItem.

Note:

In most cases, it is better to use markup to distinguish items in a list. See 9.3.3 The itemset Element.

5.2.3 xforms:dayTimeDuration

XForms includes a totally ordered duration datatype that can represent a duration of days, hours, minutes, and fractional seconds. The value space for this datatype is the set of fractional second values. This datatype is derived from xsd:duration.

5.2.4 xforms:yearMonthDuration

XForms includes a totally ordered duration datatype that can represent a duration of a whole number of months and years. The value space for this datatype is the set of integer month values. This datatype is derived from xsd:duration.

6 Model Item Properties

This chapter defines infoset contributions that can be bound to instance data nodes with element bind (see 3.3.4 The bind Element). The combination of these contributions to an instance data node is called a model item. Taken together, these contributions are called model item properties, and are defined in the following section. In contrast, the term Schema constraint refers only to XML Schema constraints from the facets of a given datatype.

6.1 Model Item Property Definitions

Model item properties can be distinguished along various axes.

Computed expressions vs. fixed properties:

Fixed properties are static values that the XForms Processor evaluates only once. Such properties consist of literals, and are not subject to XPath evaluation.
Computed expressions are XPath expressions that provide a value to the XForms Processor. Such values are recalculated at certain times as specified by the XForms Processing Model (see 4 Processing Model). These expressions encode dynamic properties, often constraints, such as the dependency among various data items. Computed expressions are not restricted to examining the value of the instance data node to which they apply. XPath expressions provide the means to traverse the instance data; more complex computations may be encoded as call-outs to external scripts.

Inheritance rules:

Some model item properties define inheritance rules, in which case the XForms processor needs to keep track of two separate values: 1) the local value, which is applied from an attribute of element bind, and 2) the inherited value, which is determined by combining the evaluated local value with the evaluated values from ancestor nodes.

Note:

The sample recalculation algorithm defined in D Recalculation Sequence Algorithm is defined to operate only on the local values of a model item property. It assumes that an implementation propagates the combined values to a node's descendants.

Assigning local values:

Local values are assigned by processing all bind elements in an XForms Model in document order. It is an error to attempt to set a model item property twice on the same node. The details of this process are given at 4.2.2 The xforms-model-initialize Event.

The following sections list the model item properties available as part of all model items. For each, the following information is provided:

Description
Computed Expression (yes or no)
Legal Values
Default Value
Inheritance Rules

6.1.1 The type Property

Description: associates a Schema datatype.

Computed Expression: No.

Legal Values: Any xsd:QName representing a datatype definition in an XML Schema.

Default Value: xsd:string.

Inheritance Rules: does not inherit.

The effect of this model item property is the same as placing attribute xsi:type on the instance data. However, in contrast to xsi:type, type can be added to both elements and attributes.

Example: Attaching a XML Schema type constraint

<instance>
  <my:person-name>
    <my:first-name />
    <my:last-name xsi:type="nonEmptyString" />
  </my:person-name>
</instance>
<bind type="nonEmptyString" ref="/my:first-name" />

Here, we have illustrated two ways in which an XML Schema type can be associated with an element.

6.1.2 The readonly Property

Description: describes whether the value is restricted from changing.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: false().

Inheritance Rules: If any ancestor node evaluates to true, this value is treated as true. Otherwise, the local value is used.

Note:

This is the equivalent of taking the logical OR of the evaluated readonly property on the local and every ancestor node.

When evaluating to true, this model item 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 model item property provides a hint to the XForms user interface. Form controls bound to instance data with the readonly model item property should indicate that entering or changing the value is not allowed. This specification does not define any effect on visibility, focus, or navigation order.

Example: Attaching a readonly property

<instance>
  <my:person-name>
    <my:first-name>Roland</my:first-name>
    <my:last-name xsi:type="nonEmptyString" />
  </my:person-name>
</instance>
<bind type="nonEmptyString" ref="/my:first-name" readonly="true()"/>

Here, we have associated a readonly property with an element.

6.1.3 The required Property

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

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: false().

Inheritance Rules: does not inherit.

A form may require certain values, and this requirement may be dynamic. When evaluating to true, this model item property indicates that a non-empty instance data node is required before a submission of instance data can occur. Non-empty is defined as:

If the bound instance data node is an element, the element must not have the xsi:nil attribute set to true.
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 model item 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 an indication that a form control is required, and may provide immediate feedback, including limiting navigation. Chapter 4 Processing Model contains details on how the XForms Processor enforces required values.

Example: Attaching a required property

<instance>
  <my:person-name>
    <my:first-name>Roland</my:first-name>
    <my:last-name />
  </my:person-name>
</instance>
<bind ref="/my:last-name" required="true()"/>

Here, we have associated a required property with element my:last-name to indicate that a value must be supplied.

Note:

XML Schema has a similarly named concept with use="required|optional|prohibited". This is different than the XForms model item property, in two ways: 1) use applies only to attributes, while XForms required applies to any node. 2) use is concerned with whether the entire attribute must be specified (without regard to value), while required determines whether a value is required of the node before submission.

6.1.4 The relevant Property

Description: indicates whether the model item is currently relevant. Instance data nodes with this property evaluating to false are not serialized for submission.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: true().

Inheritance Rules: If any ancestor node evaluates to XPath false, this value is treated as false. Otherwise, the local value is used.

Note:

This is the equivalent of taking the logical AND of the evaluated relevant property on the local and every ancestor node.

Many forms have data entry fields that depend 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.

The relevant model item 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.

Example: Attaching a relevant property

<instance>
  <my:order>
    <my:item>
      <my:amount />
      <my:discount>100</my:discount>
    <my:item>
  </my:order>
</instance>
<bind ref="my:item/my:discount" readonly="true()"
  relevant="../my:amount &gt; 1000"/>

Here, we have associated a relevant property with element my:discount to indicate a discount is relevant when the order amount is greater than 1000.

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

	`required="true()"`	`required="false()"`
`relevant="true()"`	The form control (and any children) must be visible or available to the user. The XForms user interface may indicate that a value is required.	The form control (and any children) must be visible or available to the user. The XForms user interface may indicate that a value is optional.

XForms 1.0

W3C Working Draft 21 August 2002

Abstract

Status of this Document

Table of Contents

Appendices

1 About the XForms 1.0 Specification

1.1 Background

1.2 Reading the Specification

1.3 How the Specification is Organized

1.4 Documentation Conventions

2 Introduction to XForms

2.1 An Example

2.2 Providing XML Instance Data

2.3 Constraining Values

2.4 Multiple Forms per Document

3 Document Structure

3.1 The XForms Namespace

3.2 XForms Core Attribute Collections

3.2.1 Common Attributes

3.2.2 Linking Attributes

3.2.3 Single-Node Binding Attributes

3.2.4 Node-Set Binding Attributes

3.3 The XForms Core Module

3.3.1 The model Element

3.3.2 The instance Element

3.3.3 The submission Element

3.3.4 The bind Element

3.4 The XForms MustUnderstand Module

3.5 The XForms Extension Module

3.5.1 The extension Element

4 Processing Model

4.1 Events Overview

4.2 Initialization Events

4.2.1 The xforms-model-construct Event

4.2.2 The xforms-model-initialize Event

4.2.3 The xforms-initialize-done Event

4.2.4 The xforms-ui-initialize Event

4.2.5 The xforms-form-control-initialize Event

4.2.6 The xforms-model-destruct Event

4.3 Interaction Events

4.3.1 The xforms-next and xforms-previous Events

4.3.2 The xforms-focus Event

4.3.3 The xforms-help and xforms-hint Events

4.3.4 The xforms-refresh Event

4.3.5 The xforms-revalidate Event

4.3.6 The xforms-recalculate Event

4.3.7 The xforms-rebuild Event

4.3.8 The xforms-reset Event

4.3.9 The xforms-submit Event

4.4 Notification Events

4.4.1 The xforms-activate Event

4.4.2 The xforms-value-changing Event

4.4.3 The xforms-value-changed Event

4.4.4 The xforms-select and xforms-deselect Events

4.4.5 The xforms-scroll-first and xforms-scroll-last Events

4.4.6 The xforms-insert and xforms-delete Events

4.4.7 The xforms-valid Event

4.4.8 The xforms-invalid Event

4.4.9 The DOMFocusIn Event

4.4.10 The DOMFocusOut Event

4.4.11 The xforms-readonly Event

4.4.12 The xforms-readwrite Event

4.4.13 The xforms-required Event

4.4.14 The xforms-optional Event

4.4.15 The xforms-enabled Event

4.4.16 The xforms-disabled Event

4.4.17 The xforms-submit-done Event

4.4.18 The xforms-submit-error Event

4.5 Error Indications

4.5.1 The xforms-binding-exception Event

4.5.2 The xforms-link-exception Event

4.5.3 The xforms-link-error Event

4.5.4 The xforms-compute-exception Event

5 Datatypes

5.1 XML Schema Built-in Datatypes

5.2 XForms Datatypes

5.2.1 xforms:listItem

5.2.2 xforms:listItems

5.2.3 xforms:dayTimeDuration