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 are the response to this demand and provide a new platform-independent markup language for online interaction between an XForms Processor and a remote user 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]
xlink: The XLink namespace [XLink]
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 12 Glossary Of Terms]. Links to terms may be specially highlighted where necessary.

The XML representations of various elements within XForms are presented as follows: Listed are the element name, names of all attributes, allowed values of attributes appearing after a "=" character, default values of attributes appearing after a ":" character, and allowed content. One or more headings below the listing provide additional explanatory information.

Example: XML Syntax Representation <example>

<example
  count = xsd:integer
  size = (small | medium | large) : medium
>
  <!-- Content: (allowed-content) -->
</example>

count - description of this attribute
size - description of this attribute

Certain common attributes 3.2 Horizontally Applicable Markup are not shown in the syntax representations except when special attention needs to be called to their presence.

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 (issue-id):

Issue-Name

A specific issue to which input from readers is requested, not intended for final publication.

Resolution:

None recorded.

2 Introduction to XForms

This chapter provides an easily approachable description of XForms. Not every feature of XForms is covered here. For a complete and normative description of XForms, refer to the remainder of this document. The following subsections develop a complete example of an XForms application that is hosted in an XHTML document. The complete example is found in E.1 XForms In XHTML.

2.1 Separating Purpose From Presentation

A typical form starts off with a purpose, e.g., data collection. This purpose is realized by creating an interactive presentation that allows the user to provide the requisite information. The resulting data is the result of completing the form.

Purpose	Presentation	Data
Data collection	Arrangement of form controls	Registration information
List hours worked	UI for collecting dates and times worked	Days and hours worked
Shopping application	Present shopping user interface	Order, shipping, and payment info
Information collection	Integrate forms user interface into WWW page	User contact information

HTML forms failed to separate the purpose of a form from its presentation; additionally, they only offered a restricted representation for data captured through the form. 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. Type validation rules help client-side validation, and such validation code can be automatically generated.
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 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.
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.
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.
Declarative event handlers: By defining XML-based declarative event handlers such as setFocus, message, and setValue that cover common use cases, the majority of XForms documents can be statically analyzed; contrast this with the present practice of using imperative scripts for event handlers.

2.2 Current Approach: HTML

Consider a simple electronic commerce form authored in HTML:

Example: HTML Form

<html>
  <head>
    <title>eCommerce Form</title>
  </head>
  <body>
    <form action="http://example.com/submit" method="post">
      <table summary="Payment method selector">
      <tr>
      <td><p>Select Payment Method:</p></td>
      <td><label><input type="radio" name="as" value="cash"/>Cash</label>
      <label><input type="radio" name="as" value="credit"/>Credit</label></td>
      </tr>
      <tr>
      <td><label for="cc">Credit Card Number:</label></td>
      <td><input type="text" name="cc" id="cc"/></td>
      </tr>
      <tr>
      <td><label for="exp">Expiration Date:</label></td>
      <td><input type="text" name="exp" id="exp"/></td>
      </tr>
      <tr>
      <td colspan="2"><input type="submit"/></td>
      </tr>
      </table>
    </form>
  </body>
</html>

A user agent might render this form as follows:

This form makes no effort to separate purpose (data collection semantics) from presentation (the input form controls), and offers no control over the pair serialization of the resulting data as name-value pairs. In contrast, XForms greatly improve the expressive capabilities of electronic forms.

2.3 Transition to XForms

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. XForms 1.0 defines the XForms User Interface, which is a device-independent, platform-neutral set of form controls suitable for general-purpose use. The user interface is bound to the XForms model via the XForms binding mechanism; This flexible architecture allows others to attach user interfaces to an XForms Model as illustrated here:

puzzle pieces; 'XForms Model' on the left, on the right 'XForms User Interface', 'XHTML', 'WML', and a stack of 'proprietary' pieces

The simplest case involves authoring the new XForms form controls, leaving out the other sections of the form. To convert the previous form into XForms this way, a model element is needed in the head section of the document:

<xforms:model>
  <xforms:submitInfo action="http://examples.com/submit" id="submit"/>
</xforms:model>

With these changes to the containing document, the previous example could be rewritten like this (note that we have intentionally defaulted the XForms namespace prefix in this example):

<selectOne ref="as">
  <caption>Select Payment Method</caption>
  <choices>
    <item>
      <caption>Cash</caption>
      <value>cash</value>
    </item>
    <item>
      <caption>Credit</caption>
      <value>credit</value>
    </item>
  </choices>
</selectOne>

<input ref="cc">
  <caption>Credit Card Number</caption>
</input>

<input ref="exp">
  <caption>Expiration Date</caption>
</input>

<submit submitInfo="submit">
  <caption>Submit</caption>
</submit>

Notice the following features of this design:

The user interface is not hard-coded to use radio buttons. Different devices (such as a voice browser) can render the concept of "selectOne" as appropriate.
Form controls always have captions 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 (See 2.6 Multiple Forms per Document for details on how to author multiple forms per document)
Markup for specifying form controls has been simplified
Data gets submitted as XML.

With these changes, the XForms Processor will be able to directly submit XML instance data. The XML is constructed by creating a root element with child elements reflecting the names specified in each form control via attribute ref. In this example, the submitted data would look like this:

<instanceData>
  <as>Credit</as>
  <cc>1235467789012345</cc>
  <exp>2001-08</exp>
</instanceData>

2.4 Providing XML Instance Data

XForms processing keeps track of the state of the partially filled form through instance data. Initial values for the instance may be provided via element instance. Element instance holds a skeleton XML document that gets updated as the user fills out the form. Element instance 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. The initial instance data is defined in the instance element inside the model element, as follows:

<xforms:model>
  <xforms:instance>
    <payment as="credit" xmlns="http://commerce.example.com/payment">
      <cc/>
      <exp/>
    </payment>
  </xforms:instance>
  <xforms:submitInfo action="http://example.com/submit" method="post"/>
</xforms:model>

This design has features worth calling out:

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

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

Example: Binding Expression

 xmlns:my="http://commerce.example.com/payment"...
  <xforms:selectOne ref="my:payment/@as">
    ...
  <xforms:input ref="my:payment/my:cc">
    ...
  <xforms:input ref="my:payment/my:exp">

Binding expressions are based on XPath [XPath 1.0], including the use of the @ character to refer to attributes, as seen here.

2.5 Constraining Values

XForms allows data to be checked for validity as the form is being filled. Referring to the earlier HTML form in 2.2 Current Approach: HTML, there are several desirable aspects that would only be possible to ensure through the addition of unstructured script code:

The credit card information form controls cc and exp are only relevant if the "credit" option is chosen in the as form control.
The credit card information form controls cc and exp should be required when the "credit" option is chosen in the as form control.
The form control cc should accept digits only, and should have between 14 and 18 digits.
The form control exp should accept only valid month/date combinations.

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

... xmlns:my="http://commerce.example.com/payment"...
<xforms:bind ref="my:payment/my:cc"
    relevant="../my:payment/@as = 'credit'"
    required="true"
    type="my:cc"/>

<xforms:bind ref="my:payment/my:exp"
    relevant="../my:payment/@as = 'credit'"
    required="true"
    type="xsd:gYearMonth"/>

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

2.6 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 so that they can be referenced from elsewhere in the containing document.

In addition, form controls need to specify the 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.

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

<xforms:model id="poll">
  <xforms:submitInfo .../>
</xforms:model>

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

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

<xforms:submit submitInfo="poll">
  <xforms:caption>Submit</xforms:caption>
</xforms:submit>

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

Note that complete examples can be found in E Complete XForms Examples

3 Document Structure

The XForms specification is an application of XML [XML 1.0] and has been designed for use within other XML vocabularies—in particular within XHTML [XHTML 1.0]. This chapter discusses the structure of XForms that allow this specification to be used with other document types.

3.1 The XForms Namespace

The XForms namespace has the URI: http://www.w3.org/2002/01/xforms. 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 Horizontally Applicable Markup

Every element defined in this specification declares attribute id of type xsd:ID—see the schema for XForms—this allows these elements to be referenced via attributes of type xsd:idref.

The XForms Processor must ignore any foreign-namespaced elements or attributes that are unrecognized.

Note that except where specifically allowed by the Schema for XForms, foreign-namespaced elements are not allowed as content of elements in the XForms namespace.

3.3 Model

This section describes XForms element model used as a container for XForms elements defining the XForms model. The containing document may contain one or more model elements. Element model defines the underlying model to which the XForms document binds user interaction. Hence, model elements occur before the user interaction markup. The content of element model is typically not rendered. As an example, model elements occur within element html:head of an XHTML document, whereas XForms user interface markup appears within element html:body.

XML Representation: <model>

<model
  extensionFunctions = list of QNames
>
  <!-- Content: instance?, schema?, (privacy|submitInfo|bind|action|extension)* -->
</model>

extensionFunctions - Optional list of XPath extension functions used by this XForms Model. It is an error to use an undeclared extension function.

Element model can contain the following elements.

Instance: Defines skeleton instance document and holds initialization data if any—see 3.4 instance.
Schema: Defines schema for the instance—see 3.5 schema
submitInfo: Holds submit details—see 3.6 submitInfo
Bindings: Elements bind that establish one or more XForms bindings to define model item constraints—see 6 Constraints.
Privacy: Establishes P3P properties—see 3.7 privacy
Action: Event handlers—see 10.16 action. This allows the author to handle events that arrive at node model—see the processing model 4 Processing Model.
Extension: Extension elements if any—see 8.12.4.5 extension

Example: Model

<model xmlns="http://www.w3.org/2002/01/xforms" id="Person">
   <instance xlink:href="http://example.com/cgi-bin/get-instance" /> 
   <schema xlink:href="Schema-Questionnaire.xsd" />
   ...
</model>

3.4 instance

Element instance contains a skeleton instance document that provides initial instance data. The instance data may be defined inline or obtained from an external URI.

XML Representation: <instance>

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

xlink:href - Optional link to externally defined instance data

The content of the instance element is arbitrary XML in any namespace. The content of this element is treated as opaque data. Authors must ensure that proper namespace declarations are used for content within the instance element.

3.5 schema

Element schema contains the schema defining the instance. The schema may be defined inline or obtained from an external URI.

XML Representation: <schema>

<schema xlink:href = xsd:anyURI >
  <!-- Content: ##other (though typically <xsd:schema>) -->
</schema>

xlink:href - Optional link to an externally defined schema.

3.6 submitInfo

Element submitInfo encodes how, where and what to submit.

XML Representation: <submitInfo>

<submitInfo
  (single node binding attributes)
  action = xsd:anyURI
  mediaTypeExtension = "none" | qname-but-not-ncname : "none"
  method = "post" | "get" | 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
  replace = "all" | "instance" | "none" | qname-but-not-ncname : "all"
>
  <!-- Content: XForms Actions -->
</submitInfo>

single node binding attributes - optional selector enabling submission of a portion of the instance data
action - Required destination for submitting instance data.
mediaTypeExtension - Optional information describing the serialization format. This is in addition to the mediaType.
method - Optional indicator as to the protocol to be used to transmit the serialized instance data.
version - corresponds to the version attribute of xsl:output
indent - corresponds to the indent attribute of xsl:output
encoding - corresponds to the encoding attribute of xsl:output
mediaType - corresponds to the media-type attribute of xsl:output
omitXMLDeclaration - corresponds to the omit-xml-declaration attribute of xsl:output
standalone - corresponds to the standalone attribute of xsl:output
CDATASectionElements - corresponds to the cdata-section-elements attribute of xsl:output
replace - specifier for how the information returned after submit should be applied.

Note:

Many of these attributes correspond to XSLT attributes [XSLT]. Note that the XSLT attributes doctype-system and doctype-public are not supported in XForms processing.

Note:

Note also that attribute mediaTypeExtension is useful in cases where a media type alone is not sufficiently precise. For instance, a SOAP envelope would not be adequately described simply by "text/xml", additional information would be required.

3.7 privacy

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

XML Representation: <privacy>

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

xlink:href - Optional link to an externally defined P3P policyref file (not an actual policy).

3.8 XForms and XLink

XForms uses XLink [XLink] for linking and for defining an explicit relationship between resources that may be either local or remote. To this end, the XForms schema references the XLink namespace with sensible defaults. Other than in the case of attribute xlink:href, form authors will not be required to explicitly write XLink-specific elements or attributes.

All XLinks in XForms are simple links. For further details, see 3.8.1 XLink Conformance and Examples.

3.8.1 XLink Conformance and Examples

An XForms processor is not required to implement full XLink—correct behavior of the xlink:href attribute (as defined in this chapter) is sufficient. For example, an XForms Processor must accept and correctly process the schema in both of the following:

External schema constraints

<xforms:model>
  <xforms:schema xlink:href="URI-to-remote-schema.xsd" />
</xforms:model>

Inline schema constraints

<xforms:model>
  <xforms:schema>
    <xsd:schema ...>
      <!-- Content: ... -->
    </xsd:schema>
  </xforms:schema>
</xforms:model>

This second example is unusual in that the xforms:schema element defaults an attribute xlink:type="simple" but lacks an xlink:href attribute to make the link meaningful. In this situation, the XForms Processor should switch from simple mode to none mode for the element lacking attribute xlink:href. For compatibility with XLink, the second example should be explicitly authored as follows:

Inline schema constraints, with explicit xlink:type

<xforms:model>
  <xforms:schema xlink:type="none">
    <xsd:schema...>
      <!-- Content: ... -->
    </xsd:schema>
  </xforms:schema>
</xforms:model>

Notice the explicit override of the xlink:type attribute.

If both inline content and external reference is provided, a processor must use the external reference and ignore the inline content.

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.

The XForms processing model consists of the following three phases:

initialization
User interaction
Submission

Each of these phases is further subdivided as explained in detail in subsequent sections of this chapter. State transitions in the processing model occur when specific events are received, and the event handler that processes the event determines the new state.

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], with a 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
modelConstruct	No	No	`model`
modelInitialize	No	No	`model`
initializeDone	No	No	`model`
UIInitialize	No	No	`model`
formControlInitialize	No	No	`model`
4.3 Interaction Events
previous	Yes	Yes	form control
next	Yes	Yes	form control
focus	Yes	Yes	form control
blur	Yes	Yes	form control
activate	Yes	Yes	form control
valueChanging	Yes	Yes	form control
valueChanged	Yes	Yes	form control
scrollFirst	Yes	Yes	`repeat`
scrollLast	Yes	Yes	`repeat`
insert	Yes	Yes	`instance`
delete	Yes	Yes	`instance`
select	Yes	Yes	form control or `switch`
deselect	Yes	Yes	form control or `switch`
help	Yes	Yes	form control
hint	Yes	Yes	form control
alert	Yes	Yes	form control
valid	No	Yes	form control
invalid	No	Yes	form control
refresh	Yes	Yes	`model`
revalidate	Yes	Yes	form control or `model`
recalculate	Yes	Yes	`model`
reset	Yes	Yes	`model`
4.4 XForms Submit
submit	Yes	Yes	`submitInfo`
4.5 Error Indications
schemaConstraintsError	No	Yes	`model`
traversalError	No	Yes	`model`
invalidDatatypeError	No	Yes	`model`

4.2 Initialization Events

This section defines the various stages of the initialization phase. The processing application begins initialization by dispatching an event xforms:modelConstruct to each XForms Model in the containing document.

4.2.1 xforms:modelConstruct

Dispatched in response to: XForms Processor initialization.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

Schema is loaded, if any.
An XPath data model is constructed from the instance data, according to the following rules:
1. From an external source
2. If there is no reference to an external instance, from an inline instance
Note:

If neither of these are supplied, the instance is constructed from the user interface, during user interface construction.
Following this, an xforms:modelInitialize event is dispatched to element model.

4.2.2 xforms:modelInitialize

Dispatched in response to: completion of xforms:modelConstruct processing.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

The instance data has been structurally validated against the Schema, if any. If structural validation fails, all XForms processing for this containing document halts.
If applicable, P3P has been initialized. [P3P 1.0]
The instance data has been constructed.
The xforms:initializeDone event is dispatched to the model element after initialization of that model element is completed but before rendering of the UI has started.
After all XForms Models are initialized, the host must dispatch an xforms:UIInitialize event to each model element.

4.2.3 xforms:initializeDone

Dispatched in response to: xforms:modelInitialize processing.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

4.2.4 xforms:UIInitialize

Dispatched in response to: XForms Processor user interface initialization.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

The host processor traverses the containing document, and for each form control, dispatches a xforms:formControlInitialize event to the form control.

4.2.5 xforms:formControlInitialize

Dispatched in response to: xforms:UIInitialize processing.

Target: model

Bubbles: No

Cancelable: No

Context Info: None

Default processing for this event results in the following:

If the referenced model doesn't have instance data, it is created by following the rules for default instance data described below. In the absence of a model, instance data items are treated as having type xsd:string. As each user interface control is processed, an instance data element node is created by using the binding expression from the user interface control as the name. The resulting instance data may be multiply rooted, and is intended only as a representation of a sequence of name-value pairs.

4.3 Interaction Events

4.3.1 DOM Mutation Events

Dispatched in response to: any change in the instance data.

Target: instance data node

Bubbles: Yes

Cancelable: No

Context Info: varies

In implementations that support the DOM, standard DOM mutation events should be dispatched to the changing target nodes whenever the instance data changes. Note that script, using the method getInstanceDocument() and a tree-walk, is required to associate event handlers with the instance data.

4.3.2 xforms:next and xforms:previous

Dispatched in response to: user request to navigate to the next or previous form control.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for these events results in the following: Navigation according to the default navigation order. For example, on a keyboard interface, "tab" would typically generate an xforms:next event, while "shift+tab" would generate an xforms:previous event.

Navigation is determined on a containing document-wide basis. The basic unit of navigation is the form control. The <group>, <repeat>, and <switch> structures also serve as navigation units, but instead of providing a single navigation point, they create a local navigation context for child form controls (and possibly other substructures). The navigation sequence is determined as follows:

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.
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.
Those form controls that are disabled, hidden, or not relevant are assigned a relative order in the overall sequence but do not participate as navigable controls.
The navigation sequence past 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.3.3 xforms:focus and xforms:blur

Dispatched in response to: a form control gaining or losing focus through any means.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for these events results in the following: None; notification events only.

4.3.4 xforms:activate

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.3.5 xforms:valueChanging

Dispatched in response to: an interactive change to an instance data node bound to a form control.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Certain form controls allow 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). 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.

Default processing for this event results in the following:

If the partial value meets all validity constraints, it is reflected in the instance data. If not, the instance data remains as it was before processing this event.
Event recalculate has been dispatched to element model.
Event refresh has been dispatched to element model.

Implementations that choose to implement valueChanging are expected optimize processing (for instance not flashing the entire screen for each character entered, etc.).

Note:

XForms Basic processors are not required to generate or respond to these events.

4.3.6 xforms:valueChanged

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

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

The value from the form control is reflected in the instance data.
Event revalidate has been dispatched to element model.
Event recalculate has been dispatched to element model.
Event refresh has been dispatched to element model.

4.3.7 xforms:scrollFirst

Dispatched in response to: a repeat view is scrolled past the beginning of the repeat items.

Target: repeat

Bubbles: Yes

Cancelable: Yes

Context Info: None

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

4.3.8 xforms:scrollLast

Dispatched in response to: a repeat view is scrolled past the end of the repeat items.

Target: repeat

Bubbles: Yes

Cancelable: Yes

Context Info: None

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

4.3.9 xforms:insert and xforms:delete

Dispatched in response to: A event handler invoking an XForms Action insert or delete.

Target: instance

Bubbles: Yes

Cancelable: Yes

Context Info: Path expression used for insert/delete.

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

4.3.10 xforms:select and xforms:deselect

Dispatched in response to: an item in a selectOne, selectMany, or switch becoming selected or deselected.

Target: form control or switch

Bubbles: Yes

Cancelable: Yes

Context Info: None

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

4.3.11 xforms:help and xforms:hint

Dispatched in response to: a user request for help or hint information.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for these events results in the following: None; notification event only. User agents may provide default help or hint messages.

4.3.12 xforms:alert

Dispatched in response to: a form control failing validation.

Target: form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following: An error message displayed, informing the user of the action needed to make the form control valid.

4.3.13 xforms:valid

Dispatched in response to: a form control becoming valid with respect to the bound instance data.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

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

4.3.14 xforms:invalid

Dispatched in response to: a form control becoming invalid with respect to the bound instance data.

Target: form control

Bubbles: Yes

Cancelable: No

Context Info: None

Default processing for this event results in the following:

Event alert is dispatched to the form control.

4.3.15 xforms:refresh

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 will reflect the state of the model. This means:

All form controls show the current value corresponding to the bound instance data.
All form controls show the validity state of the corresponding bound instance data.
Any form control associated with a model item property relevant evaluating to false is disabled/hidden/etc.

4.3.16 xforms:revalidate

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

Target: model or a form control

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

Revalidation may occur targeted to a context form control. The default handling for this event must satisfy the following conditions:

The bound instance data node is checked against any bound Schema Constraints. If any fail, the context form control is considered invalid.
The bound instance data node is checked against any bound XForms Constraints. If any fail, the context form control is considered invalid.
If the context form control is invalid, the XForms Processor must dispatch event invalid to the context form control. Otherwise, event valid must be dispatched to the form control.

When element model is targeted by this event, the above is applied to every form control in document order.

4.3.17 xforms:recalculate

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:

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.

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

4.3.18 xforms:reset

Dispatched in response to: a user request to reset the instance data.

Target: model

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

All of the instance data is selected for resetting.
New instance data for the selected instance data is prepared, based on the instance element associated with the current model element, according to the rules for initialization above.
The selected instance data is replaced with the new instance data.

4.4 XForms Submit

Form filling experience ends with submitting the form, or perhaps starting over. The XForms processing for these events are covered here. The following sections describe how the instance data is prepared for submission.

4.4.1 xforms:submit

Dispatched in response to: a user request to submit the instance data.

Target: submitInfo

Bubbles: Yes

Cancelable: Yes

Context Info: None

Default processing for this event results in the following:

A node from the instance data is selected, based on the attribute ref on element submitInfo. This node and all child nodes, are considered for the remainder of the submit process.
All selected instance data is revalidated. Any invalid instance data stops submit processing.
Selected instance data is serialized according to one of the processes defined below, as indicated by element submitInfo attributes mediaType and mediaTypeExtension. Nodes that have an associated relevant constraints that evaluates to false are not serialized.
Instance data is delivered over the network using the network protocol indicated by element submitInfo attribute method.

Note:

The HTTP "get" protocol is deprecated for use in form submission. Form authors should use "post" for greater compatibility.
The response returned from the submission is applied as follows: if element submitInfo attribute replace has the value of "all", the entire containing document is replaced. If the attribute value is "instance", the response is parsed as XML and the internal instance data is replaced with the result, using the same processing as remote instance data retrieved through xlink:href, and the xforms:initialize event is dispatched to element model. Behaviors of other possible values for attribute replace are not defined in this specification.

Under no circumstances may more than a single concurrent submit process be under way for a particular XForms Model.

4.4.2 application/x-www-form-urlencoded

This format is selected by the string application/x-www-form-urlencoded in element submitInfo attribute mediaType.

Note:

This serialization format is deprecated, and will be removed in a future version of the XForms specification. For greater compatibility with XML and non-western characters, form authors should choose a different serialization format.

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

Issue (issue-urlencoding-mods):

Modifications to urlencoding process

The urlencoding technique given here does not exactly match how legacy implementations produce urlencoded data. (In particular, we are adding contextual information with slashes and multiple location-steps) Will this approach interfere with legacy implementations?

Resolution:

None recorded.

Issue (issue-utf8-encoding):

Under discussion is the intent to have the data be UTF8 encoded; however, this is dependent upon IETF developments. Would UTF8 meet the needs of the forms community?

Resolution:

None recorded.

Instance data is urlencoded with the following rules:

Each element node is visited in document order. If the element contains only a single node, it is selected for inclusion. Note that attribute information is not preserved.
Elements selected for inclusion are encoded as "EltName=value;", where "=" and ";" are literal characters, "EltName" represents the element local name, and "value" represents the contents of the text node. Note that contextual path information is not preserved, nor are namespace prefixes, and multiple elements might have the same name.
All such encodings are concatenated, maintaining document order. The resulting string is urlencoded, as in HTML processing.

Example:

Example: application/x-www-form-urlencoded

FirstName=Roland;

This format consists of simple name-value pairs.

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

Here is the instance data for the above example. Note that very little of the data is preserved. Authors desiring greater data integrity should select a different serialization format.

4.4.3 multipart/form-data

This format is selected by the string multipart/form-data in element submitInfo attribute mediaType.

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 (4.4.2 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:

Example: multipart/form-data

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
  Content-Disposition: form-data; name="/PersonName/@title"

Mr
--AaB03x
  Content-Disposition: form-data; name="/PersonName/FirstName"

Roland
--AaB03x

...Possibly more data...

--AaB03x-

This format consists of sets of a canonical binding expression paired with a value.

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

Here is the instance data for the above example.

4.4.4 text/xml

This format is selected by the string text/xml in element submitInfo attribute mediaType.

This format permits the expression of the instance data as XML that is straightforward to process with off-the-shelf XML processing tools. In addition, this format is suitable for the persistence of binary content.

The steps for building this persistence format is as follows:

An XML document is produced following the rules of the XML output method defined in XPath [XSLT] section 16 and 16.1, using the values supplied as attributes of the submitInfo element.
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 instanceData.

4.4.4.1 Binary Content

Instance data nodes with values of the types xsd:base64Binary and xsd:hexBinary are specifically allowed, and are included in the serialized data according to the rules defined in [XML Schema part 2]

Issue (issue-instance-metadata):

Where a value within the instance data represents binary content, can we store meta-information with an xform:mediaType attribute reflecting the appropriate content type (e.g., "image/jpg")?

Resolution:

None recorded.

4.5 Error Indications

4.5.1 xforms:schemaConstraintsError

Dispatched in response to: instance data becoming schema-invalid.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: None

Default processing for this event results in the following: None; notification event only. Default error handling may be used.

4.5.2 xforms:traversalError

Dispatched in response to: a failure in link traversal of an xlink:href attribute value.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: The URI that failed to load.

Default processing for this event results in the following: None; notification event only. Default error handling may be used.

4.5.3 xforms:invalidDatatypeError

Dispatched in response to: an invalid parameter passed to an XForms function.

Target: model

Bubbles: Yes

Cancelable: No

Context Info: None

Default processing for this event results in the following: None; notification event only. Default error handling may be used.

5 Datatypes

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

5.1 XML Schema Built-in Datatypes

XForms includes all XML Schema datatypes. 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. Base types included in module basic are marked with an asterisk *. Datatypes derived by restriction and derived by list from these base types are also included in the basic module.

Built-in primitive types:

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

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.

5.2.1 xforms:listItem

This datatype serves as a base for the listItem 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 8.11.3 itemset.

6 Constraints

This chapter defines constraints that can be bound to form data. The combination of these constraints with an instance data node is called a model item. Taken together, these constraints are called model item constraints. The term Schema constraint refers only to XML Schema datatype constraints, while the term XForms constraint refers to XForms-specific constraints defined in the following section.

6.1 XForms Constraints

XForms constraints are defined via attributes of element bind. There are two kinds of constraints in XForms 1.0 as defined below.

Fixed constraints are static values that the XForms Processor evaluates only once. Such constraints typically encode type information.
Computed expressions are XPath expressions that provide a value to the XForms Processor. Such values are recomputed at certain times as specified by the XForms Processing Model (see 4 Processing Model). These expressions encode dynamic 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.

The following constraints are available for all model items. For each constraint, the following information is provided:

Description
Computed Expression (yes or no)
Applies to children (inherited by instance data child elements and attributes)
Legal Values
Default Value

6.1.1 type

Description: associates a Schema datatype.

Computed Expression: No.

Applies to children: No.

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

Default Value: xsd:string.

The effect of this constraint is the same as placing attribute xsi:type on the instance data.

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

Computed Expression: Yes.

Applies to children: Yes.

Legal Values: Any expression that is convertible to boolean.

Default Value: false.

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

In addition to restricting value changes, the readOnly constraint provides a hint to the XForms User Interface. Form controls bound to instance data with the readOnly constraint should indicate that entering or changing the value is not allowed. This specification does not define any effect on visibility, focus, or navigation order.

6.1.3 required

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

Computed Expression: Yes.

Applies to children: Yes.

Legal Values: Any expression that is convertible to boolean.

Default Value: false.

A form may require certain values, and this requirement may be dynamic. When evaluating to true, this constraint 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 constraint 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.

6.1.4 relevant

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

Computed Expression: Yes.

Applies to children: Yes.

Legal Values: Any expression that is convertible to boolean.

Default Value: true.

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.

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

	`required="true"`	`required="false"`
`relevant="true"`	The form control (and any children) should be visible or available to the user. The XForms User Interface may indicate that a value is required.	The form control (and any children) should be visible or available to the user. The XForms User Interface may indicate that a value is optional.
`relevant="false"`	The form control (and any children) should be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed. The XForms User Interface may indicate that should the form control become relevant, a value would be required.	The form control (and any children) should be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed.

6.1.5 calculate

Description: supplies an expression used to calculate the value of the associated instance data node.

Computed Expression: Yes.

Applies to children: No.

Legal Values: Any XPath expression

Default Value: none.

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

6.1.6 isValid

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

Computed Expression: Yes.

Applies to children: No.

Legal Values: Any expression that is convertible to boolean.

Default Value: true.

When evaluating to false, the associated model item is not valid; the converse is not necessarily true. Chapter 4 Processing Model describes details such as immediate validation versus validation upon submit.

The XForms User Interface may indicate the validity of a form control.

6.1.7 maxOccurs

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

Computed Expression: No.

Applies to children: No.

Legal Values: xsd:integer or "unbounded".

Default Value: "unbounded".

For model item elements that are repeated, this optional constraint specifies a maximum number of allowed child elements.

6.1.8 minOccurs

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

Computed Expression: No.

Applies to children: No.

Legal Values: xsd:integer.

Default Value: 0.

For model item elements that are repeated, this optional constraint specifies a minimum number of allowed child elements.

6.2 Schema Constraints

Chapter 5 Datatypes described how XForms uses the XML Schema datatype system to constrain the value space of data values collected by an XForm. Such datatype constraints can be provided via an XML Schema. Alternatively, this section lists various mechanisms for attaching type constraints to instance data. Attributes xsi:schemaLocation and xsi:noNamespaceSchemaLocation are ignored for purposes for locating a Schema. XForms Basic processors have restricted Schema processing requirements as defined in 11.1.1 XForms Basic.

6.2.1 Atomic Datatype

The XForms Processing Model applies XML 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, and if multiple type constraints apply to the same node, the first definition in document order is used).

An XML Schema associated with the instance data.
An XML Schema xsi:type attribute in the instance data.
An XForms type constraint associated with the instance data node using XForms binding.
If no type constraint is provided, the data instance node defaults to type=xsd:string (default to string rule).

The following declares a datatype based on xsd:string with an additional constraining facet.

Example: Type Constraint Using Schema.

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

This new datatype would then be associated with one or more model items through one of the methods outlined here.

Example: Attaching A Type Constraint

<my:first-name xsi:type="nonEmptyString"/>

This defines element first-name to be of type nonEmptyString.

Example: Attaching Type Constraint Using XForms Binding

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

Here, we have attached type information to element first-name via element bind. This enables the XForms author extend external Schemas that she does not have the ability to change.

6.3 Additional Schema Examples

The following non-normative sections illustrate mapping between Schema concepts and data structures commonly used in form authoring.

6.3.1 Closed Enumeration

It is often necessary to restrict the allowable values of the associated instance data node to a closed list of alternatives, e.g., when asking for a credit card type. Here is a schema fragment that declares a datatype that allows enumerated values of an xsd:string.

Example: Closed Enumeration

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="MusterCard"/>
    <xsd:enumeration value="Donor'sClub"/>
    <xsd:enumeration value="WildExpress"/>
    <xsd:enumeration value="EntryPermit"/>
  </xsd:restriction>
</xsd:simpleType>

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

Declaring an open enumeration is possible through a combination of union and enumeration.

Example: Open Enumeration

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="MusterCard"/>
        <xsd:enumeration value="Donor'sClub"/>
        <xsd:enumeration value="WildExpress"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

6.3.3 Union

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

The following defines a datatype that accepts either a creditCardType or bonusProgramType.

Example: Union Of Types

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

6.3.4 Lists

Form controls such as selectMany collect more than one value. This corresponds to Schema list datatypes.

The following declares a list-derived datatype.

List Datatype

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

6.4 Binding

Binding is the glue that connects the separate pieces of XForms—here, we use XForms binding to associate instance data with model item constraints.

Binding is specified via binding expressions, which select nodes from the instance data. Binding expressions are based on XPath and are defined in chapter 7 XPath Expressions in XForms. This section describes how binding expressions are used when defining the XForms model.

6.4.1 bind

Element bind operates on a node-set selected from the instance data. Attributes on element bind encode XForms constraints to be applied to each node in the node-set.

XML Representation: <bind>

<bind ref = binding-expression
  <!-- model item constraints -->
  type = xsd:QName
  readOnly = model-item-constraint
  required = model-item-constraint
  relevant = model-item-constraint
  isValid = model-item-constraint
  calculate = model-item-constraint
  maxOccurs = xsd:nonNegativeInteger or 'unbounded'
  minOccurs = xsd:nonNegativeInteger
>
  <!-- Content: (bind)* -->
</bind>

ref - A binding expression that selects the set of nodes that this bind operates on.
model item constraints Model item constraints as defined in 6.1 XForms Constraints.

Each bind element selects a node-set from the instance data, and applies the specified constraints. 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 10.11 insert.

6.4.2 Rules For Binding Expressions

Not every possible XPath expression is acceptable as a binding expression. The following rules are used to limit the range of XPath expressions that can appear as valid binding expressions.

No dynamic predicates. Predicates are permitted, but such predicates must not depend on other form settings. Here are a few examples to illustrate this.
Example: Permissible Binding Expressions
```
permitted: elem
  permitted: elem[1]
  permitted: elem[last()]
  permitted: elem[@id="zip"]  if @id is not bound to a form control
  forbidden: elem[@attr="xy"]  if @attr is bound to a form control
```
No invocation of any function that returns a node-set. Function calls are permitted, but not any that return a node-set.
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, form processing terminates with a fatal error.

6.4.3 Binding References

Binding references can be used to bind form controls to the underlying data instance as described in 8.12.2 Single Node Binding Attributes and 8.12.3 Nodeset Binding Attributes. Different attribute names, ref and nodeset distinguish between a single node and a node-set respectively.

First node rule: When a single-node binding expression selects a node-set of size > 1, the first node in the node-set is used. This has no effect on the individual nodes nor the set of nodes selected by any particular bind element.

Consider a document with the following XForms declarations:

Example: First Node Rule

<xforms:model id="orders">
  <xforms:instance xmlns="">
    <orderForm>
      <shipTo>
        <firstName>John</firstName>
      </shipTo>
    </orderForm>
  </xforms:instance>
  <xforms:bind ref="/orderForm/shipTo/firstName" id="fn" />
</xforms:model>

The following examples show three ways of binding user interface control xforms:input to instance element firstName declared in the model shown above.

Example: UI Binding Using Attribute ref

<xforms:input ref="/orderForm/shipTo/firstName">...

Example: UI Binding Using Attribute bind

<xforms:input bind="fn">...

Example: Specifies Model Containing The Instance Explicitly

<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...

The XForms binding mechanism allows other XML vocabularies to bind user interface controls to an XForms model using any of the techniques shown here. As an example, XForms binding attribute bind might be used within legacy HTML user interface controls as shown below.

Example: XForms Binding In Legacy HTML User Interface Controls

<html:input type="text" name="..." xforms:bind="fn"/>

7 XPath Expressions in XForms

XForms uses XPath to address instance data nodes in binding expressions, to express constraints, and to specify calculations.

7.1 XPath Datatypes

XPath data types are used only in Binding expressions and computed expressions. XForms uses XPath datatypes boolean, string, number and node-set. A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes.

7.2 Instance Data

For each model element, the XForms processor maintains the state in an internal structure called instance data that conforms to the XPath Data Model [XPath 1.0]. Elements and attributes in the instance data may have namespace information associated with them, as defined in the XPath Data Model. Unless otherwise specified, all instance data elements and attributes are unqualified. In addition, XForms processors must provide DOM access to this instance data via the interface defined below.

interface XFormsModelElement : org.w3c.dom.Element

The method getInstanceDocument returns a DOM Document that corresponds to the instance data associated with this XForms Model.

Return value: org.w3c.dom.Document

raises (DOMException); if there is no model with the specified model-id.

If the instance data is multiply rooted, the returned document has unqualified element instanceData as the documentElement, with the content of the XForms Model as children.

7.3 Evaluation Context

Within XForms, XPath expressions reference abstract instance data (using the "path" portion of XPath), instead of a concrete XML document. This reference is called a binding expression in this specification. Every XPath expression requires an evaluation context. The following rules are used in determining evaluation context when evaluating elements containing binding expressions in XForms:

The context node for outermost binding elements is the XPath root (/). A " binding element" is any element that is explicitly allowed to have a binding expression attribute. A binding element is "outermost" when the node-set returned by the XPath expression ancestor::* includes no binding element nodes.
The context node for non-outermost binding elements is the first node of the binding expression of the immediately enclosing element. An element is "immediately enclosing" when it is the first binding element node in the node-set returned by the XPath expression ancestor::*. This is also referred to as "scoped resolution".
The context node for computed expressions (occurring on element bind) is the first node of the node-set returned from the binding expression in the sibling ref attribute.
The context size and position are both exactly 1.
No variable bindings are in place.
The available function library is defined below, plus any function names declared in attribute extensionFunctions on element model.
Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.

Example: Binding Expression Context Nodes

<group ref="level1/level2/level3">
  <selectOne ref="elem" ... />
  <selectOne ref="@attr" ... />
</group>

In this example, the group has a binding expression of level1/level2/level3. According to the rules above, this outermost element would have a context node of /, which is the root of the instance data, or the parent to the elem element. Both of the selectOnes then inherit a context node from their parent, the context node being /level1/level2/level3. Based on this, the selectOne binding expressions evaluate respectively to /level1/level2/level3/elem and /level1/level2/level3/@attr. Matching instance data follows:

Example: Sample Instance

<level1>
  <level2>
    <level3 attr="xyz">
      <elem>xyz</elem>
    </level3>
  </level2>
</level1>

7.4 XForms Core Function Library

The XForms Core Function Library includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans.

This section defines a set of required functions for use within XForms.

7.4.1 Boolean Methods

7.4.1.1 boolean-from-string()

boolean boolean-from-string(string)

Function boolean-from-string returns true if the required parameter string is "true", or false if parameter string is "false". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression. If the parameter string matches neither "true" nor "false", according to a case-insensitive comparison, processing stops with a fatal error.

7.4.1.2 if()

string if(boolean, string, string)

Function if evaluates the first parameter as boolean, returning the second parameter when true, otherwise the third parameter.

7.4.2 Number Methods

Note:

The XPath number datatype and associated methods and operators use IEEE specified representations. XForms Basic Processors are not required to use IEEE, and thus might yield slightly different results.

7.4.2.1 avg()

number avg(node-set)

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

7.4.2.2 min()

number min(node-set)

Function min returns the minimum value of the result of converting the string-values of each node in argument node-set to a number. "Minimum" is determined with the < operator. If the parameter is an empty node set, the return value is NaN.

7.4.2.3 max()

number max(node-set)

Function

XForms 1.0

W3C Working Draft 18 January 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 Separating Purpose From Presentation

2.2 Current Approach: HTML

2.3 Transition to XForms

2.4 Providing XML Instance Data

2.5 Constraining Values

2.6 Multiple Forms per Document

3 Document Structure

3.1 The XForms Namespace

3.2 Horizontally Applicable Markup

3.3 Model

3.4 instance

3.5 schema

3.6 submitInfo

3.7 privacy

3.8 XForms and XLink

3.8.1 XLink Conformance and Examples

4 Processing Model

4.1 Events Overview

4.2 Initialization Events

4.2.1 xforms:modelConstruct

4.2.2 xforms:modelInitialize

4.2.3 xforms:initializeDone

4.2.4 xforms:UIInitialize

4.2.5 xforms:formControlInitialize

4.3 Interaction Events

4.3.1 DOM Mutation Events

4.3.2 xforms:next and xforms:previous

4.3.3 xforms:focus and xforms:blur

4.3.4 xforms:activate

4.3.5 xforms:valueChanging

4.3.6 xforms:valueChanged

4.3.7 xforms:scrollFirst

4.3.8 xforms:scrollLast

4.3.9 xforms:insert and xforms:delete

4.3.10 xforms:select and xforms:deselect

4.3.11 xforms:help and xforms:hint

4.3.12 xforms:alert

4.3.13 xforms:valid

4.3.14 xforms:invalid

4.3.15 xforms:refresh

4.3.16 xforms:revalidate

4.3.17 xforms:recalculate

4.3.18 xforms:reset

4.4 XForms Submit

4.4.1 xforms:submit

4.4.2 application/x-www-form-urlencoded

4.4.3 multipart/form-data

4.4.4 text/xml

4.4.4.1 Binary Content

4.5 Error Indications

4.5.1 xforms:schemaConstraintsError

4.5.2 xforms:traversalError

4.5.3 xforms:invalidDatatypeError

5 Datatypes

5.1 XML Schema Built-in Datatypes

5.2 XForms Datatypes

5.2.1 xforms:listItem

5.2.2 xforms:listItems

6 Constraints

6.1 XForms Constraints

6.1.1 type

6.1.2 readOnly

6.1.3 required

6.1.4 relevant

6.1.5 calculate

6.1.6 isValid

6.1.7 maxOccurs

6.1.8 minOccurs