View source for XForms 1.1 in Wiki

__NUMBEREDHEADINGS__
{{TR|title=XForms 1.1}}
<div id='editors'>
; Editors:
: John M. Boyer, IBM
</div>
<div style="font-weight:bold;">Abstract</div>
<div id='abstract'>XForms is an XML application that represents the next generation of forms for the Web. XForms is not a free-standing document type, but is intended to be integrated into other markup languages, such as <nowiki>[</nowiki>[[#ref-xhtml-1.0|XHTML 1.0]]<nowiki>]</nowiki>, <nowiki>[</nowiki>[[#ref-odf-1.1|ODF]]<nowiki>]</nowiki> or <nowiki>[</nowiki>[[#ref-svg-1.1|SVG]]<nowiki>]</nowiki>. An XForms-based web form gathers and processes XML data using an architecture that separates presentation, purpose and content. The underlying data of a form is organized into '''instances''' of data schema (though formal schema definitions are not required). An XForm allows processing of data to occur using three mechanisms:

* a declarative '''model''' composed of formulae for data calculations and constraints, data type and other property declarations, and data submission parameters
* a '''view''' layer composed of intent-based user interface controls
* an imperative '''controller''' for orchestrating data manipulations, interactions between the model and view layers, and data submissions.

Thus, XForms accommodates form component reuse, fosters strong data type validation, eliminates unnecessary round-trips to the server, offers device independence and reduces the need for scripting.

XForms 1.1 refines the XML processing platform introduced by <nowiki>[</nowiki>[[#ref-xforms-1.0 |XForms 1.0]]<nowiki>]</nowiki> by adding several new submission capabilities, action handlers, utility functions, user interface improvements, and helpful datatypes as well as a more powerful action processing facility, including conditional, iterated and background execution, the ability to manipulate data arbitrarily and to access event context information.
 </div>
<div style="font-weight:bold;">Status of this Document</div>
<div>{{status|xforms}}</div>

[http://www.w3.org/Consortium/Legal/ipr-notice#Copyright Copyright] &copy; 2010 [http://www.w3.org/ W3C]<sup>&reg;</sup> ([http://www.csail.mit.edu/ MIT], [http://www.ercim.org/ ERCIM], [http://www.keio.ac.jp/ Keio]), All Rights Reserved. W3C [http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer liability], [http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks trademark] and [http://www.w3.org/Consortium/Legal/copyright-documents document use] rules apply.

<div id='docbody'>
<div class="body"><div class="div1">

==<span id="intro">About the XForms Specification</span>==

<div class="div2">

===<span id="intro-background">Background</span>===

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 is the response to this demand, and provides a new platform-independent markup language for online interaction between a person (through an [[#def-xforms-processor|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/ http://www.w3.org/MarkUp/Forms].

</div><div class="div2">

===<span id="intro-reading">Reading the Specification</span>===

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.

With regard to implementing behaviors defined for XForms content herein, this document uses the terms '''must''', '''must not''', '''required''', '''shall''', '''shall not''', '''recommended''', '''should''', '''should not''', '''may''', and '''optional''' in accord with <nowiki>[</nowiki>[[#ref-rfc-2119 |RFC 2119]]<nowiki>]</nowiki>. Generally, the elements, attributes, functions and behaviors of XForms content defined in this specification are required to implement unless explicitly specified otherwise. The term '''author-optional''', when applied to a content item such as an element, attribute, or function parameter, indicates to form authors that they may omit the content item and obtain the default behavior. The term author-optional is orthogonal to the conformance status (required, recommended, or optional) of the content item.

</div><div class="div2">

===<span id="intro-org">How the Specification is Organized</span>===

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 an XML Schema description of XForms, references, examples, and other useful information.

</div><div class="div2">

===<span id="intro-conventions">Documentation Conventions</span>===

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

<blockquote>

'''xforms:''' The XForms namespace, e.g. <code>http://www.w3.org/2002/xforms</code> (see [[#Namespace for XForms|Namespace for XForms]])<br />'''html:''' An XHTML namespace, e.g. <code>http://www.w3.org/1999/xhtml</code> (see <nowiki>[</nowiki>[[#ref-xhtml-1.0 |XHTML 1.0]]<nowiki>]</nowiki>)<br />'''xs:''' The XML Schema namespace <code>http://www.w3.org/2001/XMLSchema</code> (see <nowiki>[</nowiki>[[#ref-xschema-1 |XML Schema part 1]]<nowiki>]</nowiki>)<br />'''xsd:''' The XML Schema namespace <code>http://www.w3.org/2001/XMLSchema</code> (see <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>)<br />'''xsi:''' The XML Schema for instances namespace <code>http://www.w3.org/2001/XMLSchema-instance</code> (see <nowiki>[</nowiki>[[#ref-xschema-1 |XML Schema part 1]]<nowiki>]</nowiki>)<br />'''ev:''' The XML Events namespace <code>http://www.w3.org/2001/xml-events</code> (see <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki>)<br />'''my:''' Any user defined namespace

</blockquote>

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<nowiki>: You can find most </nowiki>'''terms''' in chapter [[#Glossary Of Terms|Glossary Of Terms]]]. Links to '''term'''s 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 <nowiki>[</nowiki>[[#ref-xhtml-mod |XHTML Modularization]]<nowiki>]</nowiki>.

Examples are set off typographically:

<div class="exampleOuter"><div class="exampleHead">Example item</div><div class="exampleInner">

 Example Item

</div></div>

References to external documents appear as follows: <nowiki>[</nowiki>[[#ref-example |Sample Reference]]<nowiki>]</nowiki> with links to the references section of this document.

; Sample Reference
: <cite>Reference</cite> - linked to from above.

The following typesetting convention is used for additional commentary:

<div class="note">

'''Note:'''

A gentle explanation to readers.

</div>

{| summary="Editorial note: Editorial Note Name" border="1"
| width="50%" align="left" valign="top" | '''Editorial note: Editorial Note Name'''
| width="50%" align="right" valign="top" |
|-
| colspan="2" align="left" valign="top" | Editorial commentary, not intended for final publication.
|}

<div class="issue">

'''Issue (sample-implementation-issue):'''

'''Issue-Name'''

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

'''Resolution:'''

None recorded.

</div></div><div class="div2">

===<span id="intro-diffs">Differences between XForms 1.1 and XForms 1.0</span>===

This informative section provides an overview of the new features and changed behaviors available in XForms 1.1.

<div class="div3">

====<span id="intro-diffs-model-instance">Model and Instance</span>====

The <code>model</code> element now must support a <code>version</code> attribute to help authors bridge the transition between XForms 1.0 to XForms 1.1.

The <code>instance</code> element now has a <code>resource</code> attribute that allows instance data to be obtained from a URI only if the instance does not already contain data. By contrast, the <code>src</code> attribute overrides the inline content in an <code>instance</code>. The <code>resource</code> attribute is more useful in systems that must support save and reload of XForms-based documents.

</div><div class="div3">

====<span id="intro-diffs-submission">Enhanced Submissions</span>====

The <code>submission</code> element offers many new features that allow significantly improved data communications capabilities for XForms, including:

* Access to SOAP-based web services, RESTful services, ATOM-based services, and non-XML services
* Improved control over submission processing and serialization
* Ability to control the submission URI and headers with instance data
* Targetted instance data replacement capabilities

The <code>submission</code> element now has a <code>resource</code> attribute and <code>resource</code> child element that allow the instance data to dynamically control the submission URI. As a result, the <code>action</code> attribute is deprecated, though still supported in XForms 1.1.

In XForms 1.0, submissions were already more capable than AJAX, based on the ability to automatically update a form with results from HTTP and HTTPS services, including RSS feeds. In XForms 1.1, the <code>method</code> attribute now supports <code>delete</code> as well as any other QName. The <code>method</code> child element also allows the method to be dynamically controlled by instance data. Submission headers can now be added, and even dynamically controlled by instance data, using the <code>header</code> child element. These features complete the capabilities needed for ATOM and RESTful services. XForms 1.1 also offers special submission header behavior through the <code>mediatype</code> attribute to allow communications with SOAP 1.1 and 1.2 web services.

The <code>submission</code> element now supports attributes <code>relevant</code> and <code>validate</code>, which allow form authors to turn off instance data relevance pruning and validity checking. This allows <code>submission</code> to be used to save and reload unfinished data on a server or the local file system.

The <code>submission</code> element now supports the <code>targetref</code> attribute, which allows partial instance replacement by identifying a node to be replaced with the submission result. The <code>replace</code> attribute also now supports a <code>text</code> setting, which allows the content of the target node, rather than the target node itself, to be replaced with a non-XML (text) submission result.

The <code>submission</code> element now also supports the <code>xforms-submit-serialize</code> event, which allows the form author to provide a custom serialization, such as plain text or the full XForms document, as the submission data. The <code>serialization</code> attribute also provides increased control over the submission data serialization, including the setting <code>none</code>, which allows <code>submission</code> to be used for simple URI activation.

The <code>xforms-submit-done</code> and <code>xforms-submit-error</code> events now have event context information available that provide more information about both successful and failed submissions, such as the response headers of successful submissions and the reason code for failed submissions.

Finally, over a dozen new examples have been added to illustrate <code>submission</code> usage.

</div><div class="div3">

====<span id="intro-diffs-datatypes-mips">Datatypes and Model Item Properties</span>====

XForms 1.1 now offers <code>email</code> and <code>card-number</code> datatypes so form authors can easily validate email address and credit card number input values.

To further simplify authoring, XForms 1.1 now also provides its own definitions of the XML Schema datatypes, except the XForms versions permit the empty string. Allowing empty string means that input like an age or a birthdate can be collected without being required input for validity (an empty string is not in the lexical space of XML schema datatypes like <code>xsd:positiveInteger</code> and <code>xsd:date</code>). If an input is required, the form author can still use the XForms versions of the datatypes in combination with the <code>required</code> model item property. The XForms datatypes also aid authoring by allowing type definitions to omit namespace qualification, e.g. <code>type="date"</code> rather than <code>type="xsd:date"</code>, if the default namespace of the model is set to XForms.

The <code>readonly</code> model item property was defined to be an inviolate property of the data model. This means it cannot be violated by anything outside of the model item property system, including not just form controls but also XForms actions and instance data access from the DOM interface.

</div><div class="div3">

====<span id="intro-diffs-xpath">Functions and XPath Expressions</span>====

XForms 1.1 now contains many new functions that can be used in <code>calculate</code> and other XPath expressions to enable numerous features, including:

* basic date math and working with local dates and times: <code>local-date()</code>, <code>local-dateTime()</code>, <code>days-to-date()</code>, <code>seconds-to-dateTime()</code>, and <code>adjust-dateTime-to-timezone()</code>
* working with tabular data and parallel lists: <code>current()</code>, <code>choose()</code> and <code>context()</code>
* basic security capabilities: <code>digest()</code>, <code>hmac()</code>, and <code>random()</code>
* improved numeric and string processing: <code>power()</code>, <code>is-card-number()</code>, and <code>compare()</code>
* search across instances of a model: two parameter <code>id()</code> function
* access to context information added to many XForms events: <code>event()</code>

The specification now provides a better classification of binding expression types as well as a more rigorous definition for dynamic dependencies. These definitions ensure that XPath expressions in form controls and actions which use the <code>index()</code> are automatically re-evaluated when appropriate.

Due to the addition of the <code>choose()</code> function, the <code>if()</code> function is still supported but deprecated as futureproofing against the conflict with the <code>if</code> keyword in XPath 2.0.

</div><div class="div3">

====<span id="intro-diffs-ui">User Interface</span>====

The behavioral description common to all form controls has been improved to indicate default layout styling and rendering requirements for required data.

The <code>output</code> form control has been improved to render non-text mediatypes, particularly images, obtained from instance data.

An example was added to show the use of a <code>DOMActivate</code> handler on an <code>input</code> to automatically initiate a submission once a user enters and commits input, such as a search query.

The processing model and implementation requirements on selection controls were elaborated upon to ensure consistency of behavior between selection data expressed as textual lists versus element lists.

The ability to create wizard-like interfaces with dynamically available form controls has been improved. Details are in the description of improvements to actions.

The specification provides more rigorous definitions and classifications of form controls, which have been applied throughout the specification to ensure proper support of varied features related to form controls, such as events, applicability of model item properties, and focusability.

The XForms repeat has been made more powerful and flexible. The specification now provides rigorous definitions and processing model descriptions for repeated content, including creation, destruction, IDREF resolution and event flow between repeated content and the containing content (which may itself be repeated). The <code>repeat</code> is now capable of operating over any nodeset, not just an homogeneous collection. A formal processing model for repeat index handling has been defined.

</div><div class="div3">

====<span id="intro-diffs-actions">Actions and Events</span>====

The <code>insert</code> and <code>delete</code> actions have been converted from specialized actions associated with <code>repeat</code> to generalized data insertion and deletion operations. An entire appendix of 15 examples was added to illustrate this additional capability in detail.

All XForms actions, as well as sets of actions, can be executed conditionally or iteratively. Combined with the generalized <code>insert</code> and <code>delete</code>, this means that the information processing power of XForms 1.1 is Turing-complete.

The <code>dispatch</code> action now allows the event name and target to be specified by instance data. A new attribute, <code>delay</code>, has also been added to allow an event to be scheduled for dispatch at a later time. Since the event handler for the event can schedule same event for later dispatch, it is possible in XForms 1.1 to create background daemon tasks.

The <code>setfocus</code> and <code>toggle</code> have been improved to help with creating wizard interfaces and handling dynamically available content. The control to focus and the case to select can now be specified by instance data. These actions have also been improved relative to the recalculation processing model. They now perform deferred updates before their regular processing to ensure the user interface is automatically refreshed.

As part of the improvement to repeat index management, the <code>setindex</code> action now behaves more like <code>setvalue</code>, which means it now sets the flags for automatic recalculation, revalidation and user interface refresh. As well, this action now also performs deferred updates before its regular processing to ensure the user interface is up to date.

Finally, the <code>setvalue</code> action has been improved due to the addition of the <code>context()</code> function. Now it is possible to express the <code>value</code> attribute in terms of the same context node used to evaluate the single node binding. This improves the ability to use <code>setvalue</code> inside of a <code>repeat</code> to set values of instance nodes that are outside of the repeat nodeset based on values that are within the repeat nodeset.

</div></div></div><div class="div1">

==Introduction to XForms==

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

<div class="div2">

===<span id="concepts-xhtml">An Example</span>===

In the XForms approach, forms are comprised of a section that describes what the form does, called the [[#def-xforms-model|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:

[[Image:concepts-xhtml.png|screen shot of a graphic rendering]]

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

This can be represented in the XForms <code>model</code> element, which in XHTML would typically be contained within the <code>head</code> section:

<div class="exampleOuter"><div class="exampleInner">

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

</div></div>

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 <code>action</code> attribute.

XForms defines a device-neutral, platform-independent set of [[#def-form-control|form control]]s suitable for general-purpose use. The controls are ''bound'' to the XForms Model via the XForms binding mechanism, in this simple case using the <code>ref</code> attribute on the controls. In XHTML, this markup would typically appear within the <code>body</code> section (note that we have intentionally defaulted the XForms namespace prefix here):

<div class="exampleOuter"><div class="exampleInner">

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

</div></div>

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.
* [[#Core Form Controls|Core 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 <code>form</code> element, as in HTML. (See [[#Multiple Forms per Document|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 [[#def-host-language|host language]]s, since any form control markup may be used to bind to the model.

</div><div class="div2">

===<span id="concepts-xml-instance-data">Providing XML Instance Data</span>===

The [[#def-xforms-processor|XForms Processor]] can directly submit the data collected as XML. In the example, the submitted data would look like this:

<div class="exampleOuter"><div class="exampleHead">Submitted Data</div><div class="exampleInner">

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

</div></div>

XForms processing keeps track of the state of the partially filled form through this [[#def-instance-data|instance data]]. Initial values for the instance data may be provided or left empty as in the example. Element <code>instance</code> 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 an alternative version of the earlier example:

<div class="exampleOuter"><div class="exampleHead">Model</div><div class="exampleInner">

 <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" includenamespaceprefixes="#default"/>
 </xforms:model>

</div></div>

In this case the submitted data would look like this:

<div class="exampleOuter"><div class="exampleHead">Submitted Data</div><div class="exampleInner">

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

</div></div>

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 <code>number</code> and <code>expiry</code> serve as place-holders in the XML structure, and will be filled in with form data provided by the user.
* An initial value (<code>"cc"</code>) for the form control is provided through the instance data, in this case an attribute <code>method</code>. 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 <code>ref</code> attributes on the form controls need to be changed to point to the proper part of the instance data, using [[#def-binding-expression|binding expressions]]<nowiki>:</nowiki>

<div class="exampleOuter"><div class="exampleHead">Binding Form Controls to Instance Nodes with <code>ref</code></div><div class="exampleInner">

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

</div></div>

Binding expressions are based on XPath <nowiki>[</nowiki>[[#ref-xpath-1.0|XPath 1.0]]<nowiki>]</nowiki>, including the use of the <code>@</code> 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 <code>my:payment</code>). The third expression shows an absolute path.

</div><div class="div2">

===<span id="concepts-model">Constraining Values</span>===

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 data. In this example, <code>number</code> should accept digits only, and should have between 14 and 18 digits and <code>expiry</code> should accept only valid month/date combinations.

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

By specifying an additional component, [[#def-model-item-property|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 <code>relevant</code>. Such properties appear on <code>bind</code> elements, while [[#def-schema-constraint|Schema constraint]]s are expressed in an XML Schema fragment, either inline or external. For example:

<div class="exampleOuter"><div class="exampleHead">Declarative Validation with Model Item Properties</div><div class="exampleInner">

 ... xmlns:my="http://commerce.example.com/payment"...
 
   <xforms:model>
     ...
     <xforms:bind nodeset="/my:payment/my:number"
 		 relevant="/my:payment/@method = 'cc'"
 		 required="true()"
 		 type="my:ccnumber"/>
 
     <xforms:bind nodeset="/my:payment/my:expiry"
 		 relevant="/my:payment/@method = 'cc'"
 		 required="true()"
 		 type="xsd:gYearMonth"/>
 
     <xs:schema ...>
       ...
       <xs:simpleType name="ccnumber">
 	<xs:restriction base="xsd:string">
 	  <xs:pattern value="\d{14,18}"/>
 	</xs:restriction>
       </xs:simpleType>
       ...
     </xs:schema>
   </xforms:model>

</div></div><div class="note">

'''Note:'''

In the above example, the <code>relevant</code> expression uses absolute XPath notation (beginning with <code>/</code>) because the evaluation context nodes for [[#def-computed-expression|computed expression]]s are determined by the [[#def-binding-expression|binding expression]] (see [[#Evaluation Context|Evaluation Context]]), and so any relative node path in the first <code>bind</code> <code>relevant</code> above would be relative to <code>/my:payment/my:number</code>

</div></div><div class="div2">

===<span id="concepts-multiple">Multiple Forms per Document</span>===

XForms processing places no limits on the number of individual forms that can be placed in a single [[#def-containing-document|containing document]]. When a single document contains multiple forms, each form needs a separate <code>model</code> element, each with an <code>id</code> attribute so that they can be referenced from elsewhere in the containing document.

In addition, form controls should specify which <code>model</code> element contains the instance data to which they bind. This is accomplished through a <code>model</code> attribute that is part of the binding attributes. If no <code>model</code> attribute is specified on the binding element, the nearest ancestor binding element's <code>model</code> attribute is used, and failing that, the first XForms Model in document order is used. This technique is called 'scoped resolution', and is used frequently in XForms.

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

<div class="exampleOuter"><div class="exampleHead">Adding a <code>poll</code> model</div><div class="exampleInner">

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

</div></div>

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

<div class="exampleOuter"><div class="exampleHead">Form Controls for <code>poll</code> model</div><div class="exampleInner">

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

</div></div>

The main difference here is the use of <code>model="poll"</code>, which identifies the instance. Note that <code>submit</code> refers to the <code>submission</code> element by ID and does not require binding attributes.

More XForms examples can be found in [[#Complete XForms Examples (Non-Normative)|Complete XForms Examples]].

</div></div><div class="div1">

==<span id="structure">Document Structure</span>==

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

<div class="div2">

===<span id="structure-namespace">Namespace for XForms</span>===

The namespace URI for XForms is <code>http://www.w3.org/2002/xforms</code>. The XForms schema has the target namespace specified and as such is compatible with the XForms 1.0 definition.

<div class="exampleOuter"><div class="exampleHead">XForms used in combination with XHTML 1.0</div><div class="exampleInner">

 <switch xmlns="http://www.w3.org/2002/xforms">
   <case id="in" selected="true">
     <input ref="yourname">
       <label>Please tell me your name</label>
       <toggle ev:event="DOMActivate" case="out"/>
     </input>
   </case>
   <case id="out" selected="false">
     <html:p>Hello <output ref="yourname" />
       <trigger id="editButton">
         <label>Edit</label>
         <toggle ev:event="DOMActivate" case="in"/>
       </trigger>
     </html:p>
   </case>
 </switch>

</div>

The above example is unchanged from the specification in XForms 1.0 (in the example, the prefixes html and ev are defined by an ancestor of the <code>switch</code> element).

</div></div><div class="div2">

===<span id="structure-attrs">XForms Core Attribute Collections</span>===

<div class="div3">

====<span id="structure-attrs-common">Common Attributes</span>====

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

; anyAttribute
: Foreign attributes are allowed on all XForms elements.
; id
: The author-optional <code>id</code> attribute of type <code>xsd:ID</code> assigns an identity to the containing element.

<div class="note">

'''Note:'''

Elements can be identified using any attribute of type ID (such as <code>xml:id</code>), not just the <code>id</code> attribute defined above.

</div><div class="note">

'''Note:'''

The [[#action-xmlevents|XML Events attributes]] are foreign attributes and therefore are allowed on any XForms element that includes the [[#structure-attrs-common|Common]] attributes. This specification lists both [[#structure-attrs-common|Common]] and [[#action-xmlevents| Events]] attributes on XForms actions for reading convenience, i.e. since authors are most likely to place [[#action-xmlevents |Events]] attributes on the actual event handler elements.

</div></div><div class="div3">

====<span id="structure-attrs-link">Linking Attributes</span>====

The [[#def-host-language|host language]] may permit a Linking Attributes Collection to be applied to XForms elements as an alternate means of obtaining content related to the element. An example is the <code>src</code> attribute from <nowiki>[</nowiki>[[#ref-xhtml-1.0 |XHTML 1.0]]<nowiki>]</nowiki>. The schedule by which link traversal occurs is defined by the host language. If the link traversal fails, the host language may dispatch [[#evt-linkException| xforms-link-exception]] to the <code>model</code> associated with the in-scope evaluation context node of the element that bears the Linking Attributes Collection for the failed link.

<div class="note">

'''Note:'''

Section [[#The instance Element|The instance Element]] defines attribute <code>src</code> for the <code>instance</code> element.

</div></div><div class="div3">

====<span id="structure-attrs-single-node">Single-Node Binding Attributes</span>====

The following attributes can be used to define a binding between an XForms element such as a form control or an action and an instance data node defined by an XPath expression.

; ref
: [[#def-binding-expression|Binding expression]] interpreted as XPath. This attribute has no meaning when a <code>bind</code> attribute is present.
; model
: Author-optional XForms Model selector. Specifies the <code>ID</code> of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when a <code>bind</code> attribute is present. Rules for determining the context XForms Model are located at [[#Evaluation Context|Evaluation Context]].
; bind
: Author-optional reference to a <code>bind</code> element.

In this specification, when an XForms element is declared to have a Single-Node Binding, then the author must specify the Single-Node Binding unless the element explicitly states that it is author-optional.

In some cases, an XForms element may allow a Single-Node Binding, but one or more attributes in the Single-Node Binding attribute group are inappropriate for that XForms element. In such cases, the exact attributes are listed for the XForms element, but those attributes still express a Single-Node Binding if they appear in the element. For example, the <code>submission</code> element forbids the <code>model</code> attribute because the model is defined to be the one containing the <code>submission</code>, so the attributes <code>ref</code> and <code>bind</code> are listed for <code>submission</code> rather than referring to the Single-Node Binding attribute group, but if a <code>ref</code> or <code>bind</code> attribute is used on a <code>submission</code>, it does express a Single-Node Binding.

When the Single-Node Binding is required, one of <code>ref</code> or <code>bind</code> is required. When <code>bind</code> is used, the node is determined by the referenced <code>bind</code>. See [[#References to Elements within a bind Element|References to Elements within a bind Element]] for details on selecting an identified <code>bind</code> that is iterated by one or more containing <code>bind</code> elements. When <code>ref</code> is used, the node is determined by evaluating the XPath expression with the evaluation context described in Section [[#Evaluation Context|Evaluation Context]].

'''First-node rule'''<nowiki>: When a Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set, based on document order, is used.</nowiki>

It is an exception ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]) if the [[#def-xforms-processor|XForms Processor]] encounters a <code>model</code> attribute <code>IDREF</code> value that refers to an <code>ID</code> not on a <code>model</code> element, or a <code>bind</code> attribute <code>IDREF</code> value that refers to an <code>ID</code> not on a <code>bind</code> element.

</div><div class="div3">

====<span id="structure-attrs-nodeset">Node-Set Binding Attributes</span>====

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

; nodeset
: [[#def-binding-expression|Binding expression]] interpreted as XPath. This attribute has no meaning when a <code>bind</code> attribute is present.
; model
: Author-optional XForms Model selector. Specifies the <code>ID</code> of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when a <code>bind</code> attribute is present. Rules for determining the context XForms Model are located at [[#Evaluation Context|Evaluation Context]].
; bind
: Author-optional reference to a <code>bind</code> element.

In this specification, when an XForms element is declared to have a Node-Set Binding, then the author must specify the Node-Set Binding unless the element explicitly states that it is author-optional.

In some cases, an XForms element may allow a Node-Set Binding, but one or more attributes in the Node-Set Binding attribute group are inappropriate for that XForms element. In such cases, the exact attributes are listed for the XForms element, but those attributes still express a Node-Set Binding if they appear in the element. For example, the <code>bind</code> element only allows the <code>nodeset</code> attribute. The <code>model</code> and <code>bind</code> attributes are not allowed on a <code>bind</code> element, but if the <code>nodeset</code> attribute appears on a <code>bind</code> element, it does express a Node-Set Binding.

When the Node-Set Binding is required, one of <code>nodeset</code> or <code>bind</code> is required. When <code>bind</code> is used, the node-set is determined by the referenced <code>bind</code>. See [[#References to Elements within a bind Element|References to Elements within a bind Element]] for details on selecting an identified <code>bind</code> that is iterated by one or more containing <code>bind</code> elements. When <code>nodeset</code> is used, the node-set is determined by evaluating the XPath expression with the evaluation context described in Section [[#Evaluation Context|Evaluation Context]].

It is an exception ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]) if the [[#def-xforms-processor|XForms Processor]] encounters a <code>model</code> attribute <code>IDREF</code> value that refers to an <code>ID</code> not on a <code>model</code> element, or a <code>bind</code> attribute <code>IDREF</code> value that refers to an <code>ID</code> not on a <code>bind</code> element.

</div><div class="div3">

====<span id="structure-attrs-mip">Model Item Property Attributes</span>====

This collection contains one attribute for each model item property, with an attribute name exactly matching the name of the model item property, as defined in [[#Model Item Property Definitions|Model Item Property Definitions]].

</div></div><div class="div2">

===<span id="structure-abstract">The XForms Core Module</span>===

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:

{| summary="listing of XForms Core elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#structure-model|model]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], functions (QNameList), schema (list of xsd:anyURI), version ([[#def-versionList|xforms:versionList]])
| rowspan="1" colspan="1" |
(instance|xs:schema| submission|bind|[[#action-content-set|Action]])*
|-
| rowspan="1" colspan="1" |
[[#structure-model-instance|instance]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], src (xsd:anyURI), resource (xsd:anyURI)
| rowspan="1" colspan="1" | (ANY)
|-
| rowspan="1" colspan="1" | submission
| rowspan="1" colspan="1" |
<blockquote>

[[#structure-attrs-common|Common]]<br />ref ([[#def-binding-expression|binding-expression]])<br />bind (xsd:IDREF)<br />resource (xsd:anyURI)<br />action (xsd:anyURI) [deprecated]<br />mode ("asynchronous"|"synchronous")<br />method ("post"|"get"|"put"|"delete"|"multipart-post"|"form-data-post"|"urlencoded-post"|Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]<nowiki>|</nowiki>[[#def-QNameButNotNCName|QNameButNotNCName]])<br />validate (xsd:boolean)<br />relevant (xsd:boolean)<br />serialization ("application/xml"|"application/x-www-form-urlencoded"|"multipart/related"|"multipart/form-data"|"none")<br />version (xsd:NMTOKEN)<br />indent (xsd:boolean)<br />mediatype (xsd:string)<br />encoding (xsd:string)<br />omit-xml-declaration (xsd:boolean)<br />standalone (xsd:boolean)<br />cdata-section-elements (QNameList)<br />replace ("all"|"instance"|"text"|"none" | [[#def-QNameButNotNCName|QNameButNotNCName]])<br />instance (xsd:IDREF)<br />targetref (nodeset XPath Expression)<br />separator (';' | '&')<br />includenamespaceprefixes (xsd:NMTOKENS)

</blockquote>
| rowspan="1" colspan="1" |
([[#submit-resource-elem| resource]] | [[#submit-method-elem| method]] | [[#submit-header| header]])*, [[#action-content-set|Action]]<nowiki>*</nowiki>
|-
| rowspan="1" colspan="1" |
[[#structure-bind-element| bind]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-mip| Model Item Properties]], nodeset ([[#def-model-binding-expression|model-binding-expression]])
| rowspan="1" colspan="1" | (bind)*
|}

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

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

The [[#def-xforms-processor|XForms Processor]] must ignore any foreign-namespaced attributes that are unrecognized.

Note that the presence of foreign namespaced elements is subject to the definition of the containing or [[#def-compound-document|compound document]] profile.

<div class="div3">

====<span id="structure-model">The model Element</span>====

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 <code>model</code> elements may exist within a containing document.

Common Attributes: [[#structure-attrs-common|Common]]

Special Attributes:

; functions
: Author-optional space-separated list of XPath extension functions (represented by QNames) required by this XForms Model. Guidance on the use of this attribute is at [[#Extension Functions|Extension Functions]].
; schema
: Author-optional list of <code>xsd:anyURI</code> links to XML Schema documents outside this <code>model</code> element. The [[#def-xforms-processor|XForms Processor]] must process all Schemas listed in this attribute. Within each XForms Model, there is a limit of one Schema per namespace declaration, including inline and linked Schemas.

The schema definitions for a namespace are determined to be '''applicable''' to instance nodes based on an instance schema validation episode initialized to [[#def-lax-schema-processing|lax processing]]. When an element lacks a schema declaration, the XML Schema specification defines the recursive checking of children and attributes as optional. For this specification, this recursive checking is required. Schema processing for a node with matching schema declarations is governed by its content processing definition, which is [[#def-strict-schema-processing|strict]] by default.<div class="note">'''Note:'''The <code>schema</code> list may include URI fragments referring to elements located outside the current model elsewhere in the containing document; e.g. <code>"#myschema"</code>. <code>xs:schema</code> elements located inside the current model need not be listed.</div>
; version
: Author-optional attribute with a default value of empty string and legal values defined by the datatype [[#def-versionList|xforms:versionList]]. Examples are <code>"1.0"</code> and <code>"1.0 1.1"</code>. If one or more versions are indicated by this attribute on the default <code>model</code>, then an [[#def-xforms-processor|XForms Processor]] must support at least one of the listed language versions of XForms. Otherwise, the [[#def-xforms-processor|XForms Processor]] must terminate processing after dispatching the event [[#evt-versionException|xforms-version-exception]] to the default <code>model</code>. If the [[#def-xforms-processor|XForms Processor]] supports more than one language version indicated by the version setting on the default <code>model</code> or if the version setting on the default <code>model</code> is empty string (whether specified or by default), then the [[#def-xforms-processor|XForms Processor]] may execute the XForms content using any language conformance level available to it. If any non-default <code>model</code> has a version setting that is incompatible with the language version selected by the [[#def-xforms-processor|XForms Processor]], then the [[#def-xforms-processor|XForms Processor]] must terminate processing after dispatching the event [[#evt-versionException|xforms-version-exception]] to the default <code>model</code>.

Examples:

<div class="exampleOuter"><div class="exampleHead">This example shows a simple usage of <code>model</code>, with the XForms namespace defaulted:</div><div class="exampleInner">

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

</div></div><div class="exampleOuter"><div class="exampleHead">Handler for xforms-version-exception</div><div class="exampleInner">

 <model>
   <message level="modal" ev:event="xforms-version-exception">
       <output value="event('errorinformation')"/>
   </message>
   ...
 </model>
 ...
 <model id="m2" version="1.1">
   ...
 </model>

</div>

Since the <code>version</code> attribute is not specified on the <code>model</code>, the [[#def-xforms-processor|XForms Processor]] may choose any language conformance level, which may be incompatible with the version setting of the second <code>model</code>. Therefore, the message action occurs during initialization of the second <code>model</code> due to its version incompatibility with the default <code>model</code>.

</div><div class="exampleOuter"><div class="exampleHead">An Example of Differing but Compatible Version Settings</div><div class="exampleInner">

 <model version="1.0 1.1">
   ...
 </model>
 ...
 <model id="m2">
   ...
 </model>

</div>

Since the <code>version</code> attribute is not specified on the second <code>model</code>, it is compatible with any choice made based on the version setting on the default model.

</div></div><div class="div3">

====<span id="structure-model-instance">The instance Element</span>====

This author-optional element contains or references initial instance data.

Common Attributes: [[#structure-attrs-common|Common]]

Special Attributes:

; src
: Author-optional link to externally defined initial instance data. If the link traversal fails, it is treated as an exception ([[#The xforms-link-exception Event|The xforms-link-exception Event]]).
; resource
: Author-optional link to externally defined initial instance data. If the link is traversed and the traversal fails, it is treated as an exception ([[#The xforms-link-exception Event|The xforms-link-exception Event]]).

If the <code>src</code> attribute is given, then it takes precedence over inline content and the <code>resource</code> attribute, and the XML data for the instance is obtained from the link. If the <code>src</code> attribute is omitted, then the data for the instance is obtained from inline content if it is given or the <code>resource</code> attribute otherwise. If both the <code>resource</code> attribute and inline content are provided, the inline content takes precedence.

If the initial instance data is given by a link (from <code>src</code> or <code>resource</code>), then the instance data is formed by creating an XPath data model of the linked resource. If the link cannot be traversed, then processing halts after dispatching an [[#evt-linkException| xforms-link-exception]] with a <code>resource-uri</code> of the link that failed.

If the initial instance data is given by inline content, then instance data is obtained by first creating a detached copy of the inline content (including namespaces inherited from the enveloping ancestors), then creating an XPath data model over the detached copy. The detached copy must consist of content that would be well-formed XML if it existed in a separate document. Note that this restricts the element content of <code>instance</code> to a single child element.

If creation of the XPath data model for the instance data fails due to an XML error, then processing halts after dispatching an [[#evt-linkException| xforms-link-exception]] with a <code>resource-uri</code> indicating either the URI for an external instance, a fragment identifier URI reference (including the leading # mark) for an identified internal instance, or empty string for an unidentified internal instance. This exception could happen, for example, if the content had no top-level element or more than one top-level element, neither of which is permitted by the grammar of XML.

<div class="note">

'''Note:'''

All data relevant to the XPath data model must be preserved during processing and as input to submission serialization, including processing instructions, comment nodes and all whitespace.

</div><div class="note">

'''Note:'''

XForms authors who need additional control over the serialization of namespace nodes can use the <code>includenamespaceprefixes</code> attribute on the <code>submission</code> element.

</div></div><div class="div3">

====<span id="structure-model-submission">The submission Element</span>====

Details about the <code>submission</code> element and its processing are described in [[#The XForms Submission Module|The XForms Submission Module]].

</div><div class="div3">

====<span id="structure-bind-element">The bind Element</span>====

Element <code>bind</code> selects a node-set from the [[#def-instance-data|instance data]] with either a [[#def-model-binding-expression|model binding expression]] in the <code>nodeset</code> attribute or the default of the in-scope evaluation context node. Other attributes on element <code>bind</code> encode [[#def-model-item-property|model item properties]] to be applied to each node in the node-set. When <code>bind</code> has an attribute of type <code>xsd:ID</code>, the <code>bind</code> then associates that identifier with the selected node-set.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-mip| Model Item Properties]] (author-optional)

Special Attributes:

; nodeset
: An author-optional attribute containing a [[#def-model-binding-expression|model binding expression]] that selects the set of nodes on which this <code>bind</code> operates. If the attribute is omitted, the default is the in-scope evaluation context node.

See [[#Model Item Properties|Model Item Properties]] for details on model item properties.

See [[#Evaluation Context|Evaluation Context]] for details on how the evaluation context is determined for each attribute of the <code>bind</code> element.

</div></div><div class="div2">

===<span id="module-extension">The XForms Extension Module</span>===

There are many different ways a [[#def-host-language|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 select places. A host language that chooses this option can use the Extension module.

{| summary="listing of XForms Core elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#structure-extension|extension]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]]
| rowspan="1" colspan="1" | ANY
|}

<div class="div3">

====<span id="structure-extension">The extension Element</span>====

Author-optional element <code>extension</code> 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: [[#structure-attrs-common|Common]]

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

<div class="exampleOuter"><div class="exampleInner">

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

</div></div></div></div><div class="div2">

===<span id="module-mustUnderstand">The XForms MustUnderstand Module</span>===

This section is deleted.

</div></div><div class="div1">

==<span id="rpm">Processing Model</span>==

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

<div class="div2">

===<span id="rpm-events">Events Overview</span>===

XForms processing is defined in terms of events, event handlers, and event responses. XForms uses the events system defined in <nowiki>[</nowiki>[[#ref-dom2-events |DOM2 Events]]<nowiki>]</nowiki><nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki>, with an event capture phase, arrival of the event at its Target, and finally the event bubbling phase.

{| summary="list of all events, with cancelable, bubbleable, and target node info" border="1" frame="box" frame="box"
! rowspan="1" colspan="1" | Event name
! rowspan="1" colspan="1" | Cancelable?
! rowspan="1" colspan="1" | Bubbles?
! rowspan="1" colspan="1" | Target element
|-
| rowspan="1" colspan="4" |
[[#Initialization Events|Initialization Events]]
|-
| rowspan="1" colspan="1" | xforms-model-construct
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-model-construct-done
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-ready
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-model-destruct
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="4" |
[[#Interaction Events|Interaction Events]]
|-
| rowspan="1" colspan="1" | xforms-rebuild
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-recalculate
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-revalidate
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-refresh
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-reset
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-previous
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-next
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-focus
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code><nowiki>|</nowiki><code>repeat</code>
|-
| rowspan="1" colspan="1" | xforms-help
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-hint
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-submit
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>submission</code>
|-
| rowspan="1" colspan="1" | xforms-submit-serialize
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>submission</code>
|-
| rowspan="1" colspan="4" |
[[#Notification Events|Notification Events]]
|-
| rowspan="1" colspan="1" | xforms-insert
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>instance</code>
|-
| rowspan="1" colspan="1" | xforms-delete
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>instance</code>
|-
| rowspan="1" colspan="1" | xforms-value-changed
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-valid
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-invalid
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-readonly
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-readwrite
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-required
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-optional
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-enabled
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | xforms-disabled
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | DOMActivate
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | DOMFocusIn
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code><nowiki>|</nowiki><code>repeat</code>
|-
| rowspan="1" colspan="1" | DOMFocusOut
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code><nowiki>|</nowiki><code>repeat</code>
|-
| rowspan="1" colspan="1" | xforms-select
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>item</code> or <code>case</code>
|-
| rowspan="1" colspan="1" | xforms-deselect
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>item</code> or <code>case</code>
|-
| rowspan="1" colspan="1" | xforms-in-range
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-out-of-range
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" |
[[#elems-form-controls| Core Form Controls]]
|-
| rowspan="1" colspan="1" | xforms-scroll-first
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>repeat</code>
|-
| rowspan="1" colspan="1" | xforms-scroll-last
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>repeat</code>
|-
| rowspan="1" colspan="1" | xforms-submit-done
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>submission</code>
|-
| rowspan="1" colspan="4" |
[[#Error Indications|Error Indications]]
|-
| rowspan="1" colspan="1" | xforms-binding-exception
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | any element that can contain a binding expression
|-
| rowspan="1" colspan="1" | xforms-compute-exception
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-version-exception
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | The default <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-link-exception
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | xforms-output-error
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>output</code>
|-
| rowspan="1" colspan="1" | xforms-submit-error
| rowspan="1" colspan="1" | No
| rowspan="1" colspan="1" | Yes
| rowspan="1" colspan="1" | <code>submission</code>
|}

</div><div class="div2">

===<span id="rpm-init">Initialization Events</span>===

This section defines the various stages of the ''initialization'' phase. The processor begins initialization by dispatching an event <code>xforms-model-construct</code> to each XForms Model in the containing document. How the XForms Processor itself is requested to initialize is implementation dependent.

<div class="div3">

====<span id="evt-modelConstruct">The xforms-model-construct Event</span>====

Dispatched to each XForms model by the XForms processor.

Target: <code>model</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following:

# All XML Schemas are loaded. If an error occurs while attempting to access or process a remote document, processing halts with an exception ([[#The xforms-link-exception Event|The xforms-link-exception Event]]).
# For each <code>instance</code> element, an XPath data model <nowiki>[</nowiki>[[#XPath Expressions in XForms|XPath Expressions in XForms]]] is constructed from it as described in Section [[#The instance Element|The instance Element]]. If there are no <code>instance</code> elements, the data model is not constructed in this phase, but during user interface construction ([[#The xforms-model-construct-done Event|The xforms-model-construct-done Event]]).
# If applicable, P3P initialization occurs. <nowiki>[</nowiki>[[#ref-p3p-1.0 |P3P 1.0]]<nowiki>]</nowiki>
# Perform the behaviors of <code>xforms-rebuild</code>, <code>xforms-recalculate</code>, and <code>xforms-revalidate</code> in sequence on this <code>model</code> element without dispatching events to invoke the behaviors. The notification event markings for these operations are discarded, and the <code>xforms-refresh</code> behavior is not performed since the user interface has not yet been initialized.

After all XForms Models have been initialized, an <code>xforms-model-construct-done</code> event is dispatched to each <code>model</code> element.

</div><div class="div3">

====<span id="evt-modelConstructDone">The xforms-model-construct-done Event</span>====

Dispatched after the completion of <code>xforms-model-construct</code> processing.

Target: <code>model</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event happens once, no matter how many XForms Models are present in the containing document, and results in the following, for each [[#def-form-control|form control]]<nowiki>:</nowiki>

Processing can proceed in one of two different ways depending on whether an <code>instance</code> in a <code>model</code> exists when the first form control is processed.

If the <code>instance</code> referenced on the form control existed when the first form control was processed:

# The single node binding expression is evaluated, if it exists on the form control, 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 <code>relevant</code> model item property resolved to <code>false</code>.
# Otherwise, the user interface for the form control is created and initialized.

If the <code>instance</code> referenced on the form control did not exist when the first form control for the same <code>instance</code> was processed:

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

The above steps comprise the default processing of <code>xforms-model-construct-done</code>.

After all form controls have been initialized and all <code>xforms-model-construct-done</code> events have been processed, an <code>xforms-ready</code> event is dispatched to each <code>model</code> element.

</div><div class="div3">

====<span id="evt-ready">The xforms-ready Event</span>====

Dispatched as part of <code>xforms-model-construct-done</code> processing.

Target: <code>model</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

</div><div class="div3">

====<span id="evt-modelDestruct">The xforms-model-destruct Event</span>====

Dispatched by the processor to advise of imminent shutdown of the XForms Processor, which can occur from user action, or from the <code>load</code> XForms Action, or as a result of form submission.

Target: <code>model</code>

Bubbles: No

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

</div></div><div class="div2">

===<span id="rpm-interaction">Interaction Events</span>===

<div class="div3">

====<span id="evt-rebuild">The xforms-rebuild Event</span>====

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

Target: <code>model</code>

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for this event results in the following:

All model item properties are initialized by processing all <code>bind</code> elements in document order. For each <code>bind</code><nowiki>:</nowiki>

# If the attribute <code>nodeset</code> is attached to the bind, it is evaluated to select an XPath node-set. Otherwise, if the <code>bind</code> does not have a <code>nodeset</code> attribute, then the selected XPath node-set consists of the in-scope evaluation context.
# For each node in the selected XPath node-set, model item properties are applied according to the remaining attributes on the <code>bind</code> element (for details on the model item properties, see [[#Model Item Properties|Model Item Properties]]). If a node already contains a model item property of the same name due to the processing of prior <code>bind</code> elements, then XForms processing for the containing document halts with an exception ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]).
# For each node in the selected XPath node-set, any child <code>bind</code> elements are recursively processed as described in the three points of this list.

After initial processing of the <code>bind</code> elements, the computational dependency data structures are rebuilt, and then the change list ''L'' is set to contain references to all instance nodes that have an associated computational expression so that a ''full'' recalculation is performed the next time the behavior of <code>xforms-recalculate</code> is invoked.

</div><div class="div3">

====<span id="evt-recalculate">The xforms-recalculate Event</span>====

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

Target: <code>model</code>

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action 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. In addition to contributing further node value changes that will cause xforms-value-changed notifications in xforms-refresh, the model item properties that change are marked to help xforms-refresh to determine the notification events to dispatch.

* If the required model item property changes, then either the xforms-required event must be marked for dispatch if required is true or the xforms-optional event must be marked for dispatch if required is false. Marking one of these events for dispatch unmarks the other.
* If the readonly model item property changes, then either the xforms-readonly event must be marked for dispatch if readonly is true or the xforms-readwrite event must be marked for dispatch if readonly is false. Marking one of these events for dispatch unmarks the other.
* If the relevant model item property changes, then either the xforms-enabled event must be marked for dispatch if relevant is true or the xforms-disabled event must be marked for dispatch if relevant is false. Marking one of these events for dispatch unmarks the other.

An XPath expression is bound either to the value or to a model item property (e.g., <code>required</code>, <code>relevant</code>) 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 model item property, the XPath expression is evaluated. The evaluation context is determined from the model binding expression that applied the model item property, as defined for computed expressions in [[#Evaluation Context|Evaluation Context]]. 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. References to the current node's value in <code>calculate</code> expressions 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.

<div class="note">

'''Note:'''

Referring to a node's value in a <code>calculate</code> on the node, as in the following example, may have effects that vary by implementation: <code><bind nodeset="x" calculate=".+1"/></code>. Model item properties other than <code>calculate</code>, such as <code>required</code> or <code>readonly</code> are well-defined in the presence of self-references.

</div><div class="note">

'''Note:'''

An example of a calculate formula that contains a self-reference (i.e. that refers to the node it calculates) appears in Section [[#The readonly Property|The readonly Property]]. The example enforces a default value for a node and, as mentioned above, does not create a circular dependency. An example of a circular dependency is <code><bind nodeset="A|B" calculate="../A + ../B"/></code>. In this example, node <code>A</code> depends in part on <code>B</code>, and node <code>B</code> depends in part on <code>A</code>.

</div>

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

# An XForms Processor must recalculate computes for nodes in ''L'', if any, and nodes that are computationally dependent on nodes in ''L''.
# An XForms Processor must perform only 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 ([[#The xforms-compute-exception Event|The xforms-compute-exception Event]]).

[[#Recalculation Sequence Algorithm|Recalculation Sequence Algorithm]] describes one possible method for achieving the required recalculation behavior.

</div><div class="div3">

====<span id="evt-revalidate">The xforms-revalidate Event</span>====

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

Target: <code>model</code>

Bubbles: Yes

Cancelable: Yes

Context Info: None

An instance node is [[#def-valid|valid]] if and only if the following conditions hold:

* the constraint model item property is true
* the value is non-empty if the required model item property is true
* the node satisfies all applicable XML schema definitions (including those associated by the type model item property, by an external or an inline schema, or by <code>xsi:type</code>)

<div class="note">

'''Note:'''

<code>xsi:type</code> attributes on instance data elements are processed even in the absence of external or inline schema.

</div><div class="note">

'''Note:'''

The applicable XML schema definitions are determined as defined in Section [[#The model Element|The model Element]].

</div>

The default action for this event results in the following:

All instance data nodes in all <code>instance</code> elements in the <code>model</code> are checked for validity according to the above definition. If the validity of a node changes, then either the xforms-valid event must be marked for dispatch if the node changes from invalid to valid or the xforms-invalid event must be marked for dispatch if the node changes from valid to invalid. Marking one of these events for dispatch unmarks the other.

<div class="note">

'''Note:'''

Since the event sequence for <code>xforms-model-construct</code> excludes <code>xforms-refresh</code> and discards event notification marks, form controls bound to invalid nodes do not receive an initial <code>xforms-invalid</code> event.

</div></div><div class="div3">

====<span id="evt-refresh">The xforms-refresh Event</span>====

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

Target: <code>model</code>

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for this event results in the following:

# All [[#UI Expressions|UI Expressions]] are reevaluated (implementations may optimize this operation but must behave as if all UI Expressions are reevaluated).
# A node can be changed by a number of mechanisms in XForms, including confirmed user input to a form control, an <code>xforms-recalculate</code> ([[#The xforms-recalculate Event|The xforms-recalculate Event]]), and the <code>setvalue</code> action ([[#The setvalue Element|The setvalue Element]]). If the value of an instance data node was changed, then the node must be marked for dispatching the xforms-value-changed event.
# If the xforms-value-changed event is marked for dispatching, then all of the appropriate model item property notification events must also be marked for dispatching (xforms-optional or xforms-required, xforms-readwrite or xforms-readonly, and xforms-enabled or xforms-disabled).
# The user interface reflects the state of the model, which means that all forms controls and related UI elements reflect their corresponding instance data, including:
#* current values (for the appropriate form controls and related UI elements)
#* [[#def-valid|validity]]
#* other model item properties (<code>required</code>, <code>readonly</code> and <code>relevant</code>).
#* the proper number of and content for repeat objects.

This process includes sending the notification events to the form controls. For each form control, each notification event for which the form control is a legitimate target and that is marked for dispatching on the bound node must be dispatched (xforms-value-changed, xforms-valid, xforms-invalid, xforms-optional, xforms-required, xforms-readwrite, xforms-readonly, and xforms-enabled, xforms-disabled). The notification events xforms-out-of-range or xforms-in-range must also be dispatched as appropriate. This specification does not specify an ordering for the events.

</div><div class="div3">

====<span id="evt-reset">The xforms-reset Event</span>====

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

Target: <code>model</code>

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action 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 <code>xforms-ready</code> event. Then, the events <code>xforms-rebuild</code>, <code>xforms-recalculate</code>, <code>xforms-revalidate</code> and <code>xforms-refresh</code> are dispatched to the <code>model</code> element in sequence.

</div><div class="div3">

====<span id="evt-next">The xforms-next and xforms-previous Events</span>====

Dispatched in response to: user request to navigate to the next or previous [[#elems-form-controls|Core Form Control]].

Target: [[#elems-form-controls| Core Form Controls]]

Bubbles: No

Cancelable: Yes

Context Info: None

The default action for these events results in the following: Navigation according to the default navigation order. For example, on a keyboard interface, "tab" might generate an <code>xforms-next</code> event, while "shift+tab" might generate an <code>xforms-previous</code> event.

Navigation is determined on a containing document-wide basis. The host language is responsible for defining overall navigation order. The following describes a possible technique based on a <code>navindex</code> attribute, using individual form controls as a navigation unit: The <<code>group</code>>, <<code>repeat</code>>, and <<code>switch</code>> structures serve as container navigation units that, instead of providing a single navigation point, create a local navigation context for child form controls (and possibly other substructures). The navigation sequence is determined as follows:

# Form controls that have a <code>navindex</code> specified and assign a positive value to it are navigated first.
## Outermost form controls are navigated in increasing order of the <code>navindex</code> value. Values need not be sequential nor must they begin with any particular value. Form controls that have identical <code>navindex</code> values are to be navigated in document order.
## Ancestor form controls (<<code>group</code>>, <<code>repeat</code>>, and <<code>switch</code>>) establish a local navigation sequence. All form controls within a local sequence are navigated, in increasing order of the <code>navindex</code> value, before any outside the local sequence are navigated. Form controls that have identical <code>navindex</code> values are navigated in document order.
# Those form controls that do not specify <code>navindex</code> 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 <code>relevant</code> 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.

</div><div class="div3">

====<span id="evt-focus">The xforms-focus Event</span>====

Dispatched in response to: set focus to a form control.

Target: [[#elems-form-controls|Core Form Control]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code><nowiki>|</nowiki><code>repeat</code>

Bubbles: No

Cancelable: Yes

Context Info: None

The default action for these events results in the following:

Focus is given to the target form control if the form control is able to accept focus. Changing the focus to a form control within a repeat object may cause one or more repeat index values to be changed as described in Section [[#User Interface Interaction|User Interface Interaction]]. Setting focus to a <code>repeat</code> container form control sets the focus to the [[#def-repeat-object|repeat object]] associated with the repeat index. Setting the focus to a <code>group</code> or <code>switch</code> container form control set the focus to the first form control in the container that is able to accept focus. Any form control is able to accept the focus if it is relevant.

<div class="note">

'''Note:'''

This event is implicitly invoked to implement XForms accessibility features such as <code>accesskey</code> and when the user changes the focus.

</div></div><div class="div3">

====<span id="evt-help">The xforms-help and xforms-hint Events</span>====

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

Target: [[#elems-form-controls|Core Form Control]]

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action 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.

</div><div class="div3">

====<span id="evt-submit">The xforms-submit Event</span>====

See chapter [[#The xforms-submit Event|The xforms-submit Event]].

</div><div class="div3">

====<span id="evt-submit-serialize">The xforms-submit-serialize Event</span>====

See chapter [[#The xforms-submit-serialize Event|The xforms-submit-serialize Event]].

</div></div><div class="div2">

===<span id="evt-notify">Notification Events</span>===

<div class="div3">

====<span id="evt-insert">The xforms-insert Event</span>====

Dispatched in response to: Successful insertion of one or more nodes by an XForms <code>insert</code> action.

Target: <code>instance</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-insert event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | inserted-nodes
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | The instance data node or nodes inserted.
|-
| rowspan="1" colspan="1" | origin-nodes
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | The instance data nodes referenced by the <code>insert</code> action's <code>origin</code> attribute if present, or the empty nodeset if not present.
|-
| rowspan="1" colspan="1" | insert-location-node
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | The <code>insert location node</code> as defined by the <code>insert</code> action.
|-
| rowspan="1" colspan="1" | position
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | The insert position, <code>before</code> or <code>after</code>.
|}

Default Action: None; notification event only.

<div class="note">

'''Note:'''

Notification events are those with no default processing defined. Although this event is dispatched by <code>insert</code> processing as a notification, <code>repeat</code> processing associates behavior with the capture phase of this event.

</div></div><div class="div3">

====<span id="evt-delete">The xforms-delete Event</span>====

Dispatched in response to: Successful deletion of one or more nodes by an XForms <code>delete</code> action.

Target: <code>instance</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-delete event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | deleted-nodes
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | The instance data node or nodes deleted. Note that these nodes are no longer referenced by their parents.
|-
| rowspan="1" colspan="1" | delete-location
| rowspan="1" colspan="1" | number
| rowspan="1" colspan="1" | The <code>delete location</code> as defined by the <code>delete</code> action, or NaN if there is no delete location.
|}

Default Action: None; notification event only.

<div class="note">

'''Note:'''

Notification events are those with no default processing defined. Although this event is dispatched by <code>delete</code> processing as a notification, <code>repeat</code> processing associates behavior with the capture phase of this event.

</div></div><div class="div3">

====<span id="evt-valueChanged">The xforms-value-changed Event</span>====

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

Target: [[#elems-form-controls| Core Form Controls]]

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event due to a change.

<div class="note">

'''Note:'''

For incremental processing, 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.).

</div><div class="note">

'''Note:'''

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

</div></div><div class="div3">

====<span id="evt-valid">The xforms-valid Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming [[#def-valid|valid]].

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-revalidate Event|The xforms-revalidate Event]].

</div><div class="div3">

====<span id="evt-invalid">The xforms-invalid Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming invalid (not [[#def-valid|valid]]).

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-revalidate Event|The xforms-revalidate Event]].

</div><div class="div3">

====<span id="evt-readonly">The xforms-readonly Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming readonly.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-recalculate Event|The xforms-recalculate Event]] or [[#The xforms-refresh Event|The xforms-refresh Event]].

</div><div class="div3">

====<span id="evt-readwrite">The xforms-readwrite Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming read-write.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-recalculate Event|The xforms-recalculate Event]] or [[#The xforms-refresh Event|The xforms-refresh Event]].

</div><div class="div3">

====<span id="evt-required">The xforms-required Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming required.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-recalculate Event|The xforms-recalculate Event]] or [[#The xforms-refresh Event|The xforms-refresh Event]].

</div><div class="div3">

====<span id="evt-optional">The xforms-optional Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming optional.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-recalculate Event|The xforms-recalculate Event]] or [[#The xforms-refresh Event|The xforms-refresh Event]].

</div><div class="div3">

====<span id="evt-enabled">The xforms-enabled Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming enabled.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-recalculate Event|The xforms-recalculate Event]] or [[#The xforms-refresh Event|The xforms-refresh Event]].

</div><div class="div3">

====<span id="evt-disabled">The xforms-disabled Event</span>====

Dispatched in response to: an instance data node either changing and being or becoming disabled.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched during [[#The xforms-refresh Event|The xforms-refresh Event]] if the bound instance data node has been marked for dispatching this event in [[#The xforms-recalculate Event|The xforms-recalculate Event]] or [[#The xforms-refresh Event|The xforms-refresh Event]].

</div><div class="div3">

====<span id="evt-activate">The DOMActivate Event</span>====

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

Target: [[#elems-form-controls| Core Form Controls]]

Bubbles: Yes

Cancelable: Yes

Context Info: None

The default action for this event results in the following: None; notification event only.

</div><div class="div3">

====<span id="evt-DOMFocusIn">The DOMFocusIn Event</span>====

Dispatched in response to: a form control receiving focus.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code><nowiki>|</nowiki><code>repeat</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

</div><div class="div3">

====<span id="evt-DOMFocusOut">The DOMFocusOut Event</span>====

Dispatched in response to: a form control losing focus.

Target: [[#elems-form-controls| Core Form Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code><nowiki>|</nowiki><code>repeat</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

</div><div class="div3">

====<span id="evt-select">The xforms-select and xforms-deselect Events</span>====

Dispatched in response to: an <code>item</code> in a <code>select</code>, <code>select1</code>, or a <code>case</code> in a <code>switch</code> becoming selected or deselected.

Target: <code>item</code> or <code>case</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

</div><div class="div3">

====<span id="evt-in-range">The xforms-in-range Event</span>====

Dispatched in response to: the value of an instance data node has changed such that the value can now be represented by the form control.

Target: [[#elems-form-controls| Core Form Controls]]

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched whenever the value of an instance data node that was not possible to represent given the constraints specified on a form control has changed such that the value can now be represented by the form control.

</div><div class="div3">

====<span id="evt-out-of-range">The xforms-out-of-range Event</span>====

Dispatched in response to: the value of an instance data node has changed such that the value can not be represented by the form control.

Target: [[#elems-form-controls| Core Form Controls]]

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

This event is dispatched whenever the value of an instance data node can not be represented given the constraints specified on a form control.

</div><div class="div3">

====<span id="evt-scroll">The xforms-scroll-first and xforms-scroll-last Events</span>====

Dispatched in response to: a setindex action attempting to set an index outside the range of a <code>repeat</code>.

Target: <code>repeat</code>

Bubbles: Yes

Cancelable: No

Context Info: None

The default action for this event results in the following: None; notification event only.

</div><div class="div3">

====<span id="evt-submit-done">The xforms-submit-done Event</span>====

See chapter [[#The xforms-submit-done Event|The xforms-submit-done Event]].

</div></div><div class="div2">

===<span id="rpm-errors">Error Indications</span>===

Error indications happen as a result of unusual conditions in the XForms Processor. Some of these are "fatal" errors, which halt processing, and bear the suffix "exception". Others are simply for notification, and bear the suffix "error". For all events in this section, it is permissible for the XForms Processor to perform some kind of default handling, for example logging error messages to a file.

<div class="div3">

====<span id="evt-bindingException">The xforms-binding-exception Event</span>====

Dispatched as an indication of: an illegal binding expression, or a <code>model</code> attribute that fails to point to the ID of a <code>model</code> element, or a <code>bind</code> attribute that fails to point to the ID of a <code>bind</code> element, or a <code>submission</code> attribute that fails to point to the ID of a <code>submission</code> element, or an <code>instance</code> attribute on the <code>submission</code> element that fails to point to an <code>instance</code> element in the same <code>model</code> element as the <code>submission</code>.

Target: any element that can contain a binding expression

Bubbles: Yes

Cancelable: No

Context Info: None

Default Action: Fatal error (halts processing).

</div><div class="div3">

====<span id="evt-computeException">The xforms-compute-exception Event</span>====

Dispatched as an indication of: an error occurring during XPath evaluation for a model item property (see [[#Model Item Properties|Model Item Properties]]).

Target: <code>model</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-compute-exception event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | error-message
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | An implementation-specific string that should contain the expression being processed when the exception was detected.
|}

Default Action: Fatal error (halts processing).

</div><div class="div3">

====<span id="evt-versionException">The xforms-version-exception Event</span>====

Dispatched as an indication of failure of the version checks defined in the description of the <code>version</code> attribute in Section [[#The model Element|The model Element]].

Target: the default <code>model</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-version-exception event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | error-information
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | An implementation-specific error string
|}

Default Action: Fatal error (halts processing).

<div class="note">

'''Note:'''

This exception occurs early in processing. XForms processors are not expected to product XForms user interface elements nor even execute XForms action handlers (such as a <code>message</code> action) in response to this event. This exception is dispatched for the benefit of implementation-specific processing code that may be monitoring the behavior of an XForms processor.

</div></div><div class="div3">

====<span id="evt-linkException">The xforms-link-exception Event</span>====

Dispatched as an indication of: a failure to traverse or process the result of a link in a situation critical to form processing, such as schema or instance initialization.

Target: <code>model</code> associated with the in-scope evaluation context node of the element performing the link

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-link-exception event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | resource-uri
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | The URI associated with the failed link (xsd:anyURI)
|}

Default Action: Fatal error (halts processing).

<div class="note">

'''Note:'''

This exception occurs early in processing. XForms processors are not expected to produce XForms user interface elements nor even execute XForms action handlers (such as a <code>message</code> action) in response to this event. This exception is dispatched for the benefit of implementation-specific processing code that may be monitoring the behavior of an XForms processor.

</div></div><div class="div3">

====<span id="evt-output-error">The xforms-output-error Event</span>====

Dispatched by the processor immediately after the failure of an <code>output</code> to render or update the rendition of content.

Target: <code>output</code>

Bubbles: Yes

Cancelable: No

Context Info: None.

Default Action: None; notification event only.

<div class="note">

'''Note:'''

The <code>output</code> element content can include XForms actions, so an <code>output</code> element can contain an event handler for the <code>xforms-output-error</code> event. See Section [[#The output Element|The output Element]].

</div></div><div class="div3">

====<span id="evt-submit-error">The xforms-submit-error Event</span>====

See chapter [[#The xforms-submit-error Event|The xforms-submit-error Event]].

</div></div><div class="div2">

===<span id="rpm-event-sequences">Event Sequencing</span>===

The previous sections describe processing associated with individual events. This section gives the overall sequence of related events that must occur in several common situations. In the following lists, events that may be fired more than once are prefixed with [n].

<div class="div3">

====<span id="sequence-for-input">For <code>input</code>, <code>secret</code>, <code>textarea</code>, <code>range</code>, or <code>upload</code> Controls</span>====

* When the form control is interactively changed, and has the <code>incremental="true"</code> setting, the event sequence described at [[#Sequence: Value Change|Sequence: Value Change]] may be initiated at implementation dependent intervals.
* When the form control is interactively changed and does not have the <code>incremental="true"</code> setting, no events are required to be dispatched, and thus no order is defined.
* When the user activates the control and the value has changed, then, after the new value is placed into the bound instance node, the event sequence consists of the events described at [[#Sequence: Value Change|Sequence: Value Change]] followed by dispatching the DOMActivate event. See [[#The input Element|The input Element]] for an example.
* When focus changes from the form control and the value has changed, then, after the new value is placed into the bound instance node, the event sequence is as described at [[#Sequence: Value Change|Sequence: Value Change]].

</div><div class="div3">

====<span id="sequence-for-output">For output Controls</span>====

* The implementation of an <code>output</code> dispatches <code>xforms-output-error</code> if it unable to process the output data (such as corrupt image data when the output mediatype indicates it is image data). This event may occur each time the <code>output</code> is given new data (such as a change of data in the bound data node or a change of the bound data node).

</div><div class="div3">

====<span id="sequence-for-select">For select or select1 Controls</span>====

* When a selection is interactively changed, and the form control has the <code>incremental="true"</code> setting (which is the default for the <code>select</code> or <code>select1</code> elements), the event sequence is described at [[#Sequence: Selection Without Value Change|Sequence: Selection Without Value Change]], which may be followed immediately by the sequence described at [[#Sequence: Value Change|Sequence: Value Change]].
* When a selection is interactively changed, and the <code>select</code> or <code>select1</code> form control has the <code>incremental="false"</code> setting, the event sequence is described at [[#Sequence: Selection Without Value Change|Sequence: Selection Without Value Change]].
* When the user activates the control and the selection has changed, then, after the new value is placed into the bound instance node, the event sequence consists of the events described at [[#Sequence: Value Change|Sequence: Value Change]] followed by dispatching the DOMActivate event. Note that this event sequence will have been preceded by the event sequence described at [[#Sequence: Selection Without Value Change|Sequence: Selection Without Value Change]] at the moment the selection was changed.
* When focus changes from the form control and the selection has changed, then, after the new value is placed into the bound instance node, the event sequence is as described at [[#Sequence: Value Change|Sequence: Value Change]]. Note that this event sequence will have been preceded by the event sequence described at [[#Sequence: Selection Without Value Change|Sequence: Selection Without Value Change]] at the moment the selection was changed.

</div><div class="div3">

====<span id="sequence-for-trigger">For trigger Controls</span>====

* Activating the form control causes the event sequence defined at [[#Sequence: Activating a Trigger|Sequence: Activating a Trigger]].

</div><div class="div3">

====<span id="sequence-for-submit">For submit Controls</span>====

* Activating the form control causes the event sequence defined at [[#Sequence: Activating a Trigger|Sequence: Activating a Trigger]], followed immediately by the event sequence defined at [[#Sequence: Submission|Sequence: Submission]].

</div><div class="div3">

====<span id="rpm-event-seq-swovc">Sequence: Selection Without Value Change</span>====

# xforms-deselect (for each <code>item</code> deselected by the change, if any)
# xforms-select (for each <code>item</code> selected by the change, if any)

</div><div class="div3">

====<span id="rpm-event-seq-vc">Sequence: Value Change</span>====

# xforms-recalculate
# xforms-revalidate
# xforms-refresh performs reevaluation of UI binding expressions then dispatches these events according to value changes, model item property changes and validity changes:
#* [n] xforms-value-changed
#* [n] xforms-valid or xforms-invalid
#* [n] xforms-enabled or xforms-disabled
#* [n] xforms-optional or xforms-required
#* [n] xforms-readonly or xforms-readwrite
#* [n] xforms-out-of-range or xforms-in-range<br/><br/>(The order in which these events are dispatched is not defined).
# Perform further deferred updates as necessary

</div><div class="div3">

====<span id="rpm-event-seq-aat">Sequence: Activating a Trigger</span>====

# DOMActivate

</div><div class="div3">

====<span id="rpm-event-seq-s">Sequence: Submission</span>====

# xforms-submit
# xforms-submit-serialize
# xforms-submit-done or xforms-submit-error

</div></div><div class="div2">

===<span id="idref-resolve">Resolving ID References in XForms</span>===

The element of a document for which an IDREF must be resolved is called the '''source element''', and the element bearing the matching ID, if there is one, is called the '''target element'''. Due to the run-time expansion of repeated content in XForms, it is possible that there will be more than one occurrence of both the source and target elements. This section describes how XForms IDREF resolution works to accommodate such repetition of the originating document's content.

Each run-time occurrence of the source element is called a '''source object''', and each run-time occurrence of the target element is called a '''target object'''. It is the source object that performs the IDREF resolution, and the result of the search is either null or a target object.

Whether or not repeated content is involved, a null search result for an IDREF resolution is handled differently depending on the source object. If there is a null search result for the target object and the source object is an XForms action such as <code>dispatch</code>, <code>send</code>, <code>setfocus</code>, <code>setindex</code> or <code>toggle</code>, then the action is terminated with no effect. Similarly, a <code>submit</code> form control does not dispatch <code>xforms-submit</code> if its <code>submission</code> attribute does not indicate an existing <code>submission</code> element. Likewise, when an XPath function associated with the source object performs the IDREF search and a null result is obtained, the function returns an empty result such as <code>NaN</code> for the <code>index()</code> function or empty nodeset for the <code>instance()</code> function. However, an <code>xforms-binding-exception</code> occurs if there is a null search result for the target object indicated by attributes <code>bind</code>, <code>model</code> and <code>instance</code>.

If the target element is not repeated, then the search for the target object is trivial since there is only one associated with the target element that bears the matching ID. This is true regardless of whether or not the source object is repeated. However, if the target element is repeated, then additional information must be used to help select a target object from among those associated with the identified target element.

<div class="div3">

====<span id="idref-resolve-repeat">References to Elements within a repeat Element</span>====

When the target element that is identified by the IDREF of a source object has one or more <code>repeat</code> elements as ancestors, then the set of ancestor repeats are partitioned into two subsets, those in common with the source element and those that are not in common. Any ancestor <code>repeat</code> elements of the target element not in common with the source element are descendants of the <code>repeat</code> elements that the source and target element have in common, if any.

For the <code>repeat</code> elements that are in common, the desired target object exists in the same set of run-time objects that contains the source object. Then, for each ancestor <code>repeat</code> of the target element that is not in common with the source element, the current index of the <code>repeat</code> determines the set of run-time objects that contains the desired target object.

</div><div class="div3">

====<span id="idref-resolve-bind">References to Elements within a bind Element</span>====

When a source object expresses a Single Node Binding or Node Set Binding with a <code>bind</code> attribute, the IDREF of the <code>bind</code> attribute is resolved to a target bind object whose associated nodeset is used by the Single Node Binding or Node Set Binding. However, if the target <code>bind</code> element has one or more <code>bind</code> element ancestors, then the identified <code>bind</code> may be a target element that is associated with more than one target bind object.

If a target <code>bind</code> element is outermost, or if all of its ancestor <code>bind</code> elements have <code>nodeset</code> attributes that select only one node, then the target <code>bind</code> only has one associated bind object, so this is the desired target bind object whose nodeset is used in the Single Node Binding or Node Set Binding. Otherwise, the in-scope evaluation context node of the source object containing the <code>bind</code> attribute is used to help select the appropriate target bind object from among those associated with the target <code>bind</code> element.

From among the bind objects associated with the target <code>bind</code> element, if there exists a bind object created with the same in-scope evaluation context node as the source object, then that bind object is the desired target bind object. Otherwise, the IDREF resolution produced a null search result.

</div></div><div class="div2">

===<span id="expr-instance">DOM Interface for Access to Instance Data</span>===

For each <code>model</code> element, the XForms Processor maintains the state in an internal structure called [[#def-instance-data|instance data]] that conforms to the XPath Data Model <nowiki>[</nowiki>[[#ref-xpath-1.0|XPath 1.0]]<nowiki>]</nowiki>. XForms Processors that implement DOM must provide DOM access to this instance data via the interface defined below.

<div class="note">

'''Note:'''

Instance data always has a single root element, and thus corresponds to a DOM Document.

</div>

The IDL for this interface follows:

<div class="exampleInner">

 <nowiki>#include "dom.idl"
 
    pragma prefix "w3c.org"
 
    module xforms {
       interface XFormsModelElement : dom::Element {
          dom::Document getInstanceDocument(in dom::DOMString instanceID)
             raises(dom::DOMException);
          void rebuild();
          void recalculate();
          void revalidate();
          void refresh();
       };
    };</nowiki>

</div><div class="div3">

====<span id="idl-getInstanceDocument">The getInstanceDocument() Method</span>====

If the <code>instance-id</code> parameter is the empty string, then the document element of the default instance is returned. Otherwise, this method returns a DOM Document that corresponds to the instance data associated with the <code>instance</code> element containing an <code>ID</code> matching the <code>instance-id</code> parameter. If there is no matching instance data, a <code>DOMException</code> is thrown.

The implementation of the DOM interface for the instance document must not permit direct mutations of readonly instance nodes. Specifically, the implementation must not allow insertion of a node whose parent is readonly, direct deletion of a readonly node, nor setting the content of a readonly node. A node that is not readonly can be deleted, including all descendants, even if it has readonly descendants.

</div><div class="div3">

====<span id="idl-rebuild">The rebuild() Method</span>====

This method signals the XForms Processor to rebuild any internal data structures used to track computational dependencies within this XForms Model. This method takes no parameters and raises no exceptions.

</div><div class="div3">

====<span id="idl-recalculate">The recalculate() Method</span>====

This method signals the XForms Processor to perform a full recalculation of this XForms Model. This method takes no parameters and raises no exceptions.

</div><div class="div3">

====<span id="idl-revalidate">The revalidate() Method</span>====

This method signals the XForms Processor to perform a full revalidation of this XForms Model. This method takes no parameters and raises no exceptions.

</div><div class="div3">

====<span id="idl-refresh">The refresh() Method</span>====

This method signals the XForms Processor to perform a full refresh of form controls bound to instance nodes within this XForms Model. This method takes no parameters and raises no exceptions.

</div></div><div class="div2">

===<span id="expr-hasfeature">Feature string for the hasFeature method call</span>===

For this version of the XForms specification, the feature string for the <nowiki>[</nowiki>[[#ref-dom2-core |DOM2 Core]]<nowiki>]</nowiki> <code>DOMImplementation</code> interface <code>hasFeature</code> method call is <code>"org.w3c.xforms.dom"</code> and the version string is <code>"1.0"</code>.

</div></div><div class="div1">

==<span id="datatypes">Datatypes</span>==

This chapter defines the datatypes used in defining an [[#def-xforms-model|XForms Model]].

<div class="div2">

===<span id="datatypes-schema">XML Schema Built-in Datatypes</span>===

XForms supports all XML Schema 1.0 [[#def-datatype|datatype]]s except for <code>xsd:duration</code>, <code>xsd:ENTITY</code>, <code>xsd:ENTITIES</code>, and <code>xsd:NOTATION</code>. Concepts [[#def-value-space|value space]], [[#def-lexical-space|lexical space]] and constraining [[#def-facet|facet]]s are as specified in <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>. XForms Processors must treat these datatypes as in-scope without requiring the inclusion of an XML Schema.

<div class="note">

'''Note:'''

The built-in datatype <code>xsd:duration</code> is not supported, except as an abstract datatype. Instead, either <code>xforms:dayTimeDuration</code> or <code>xforms:yearMonthDuration</code> should be used.

</div></div><div class="div2">

===<span id="datatypes-xforms">XForms Datatypes</span>===

XForms defines the following types in the XForms namespace. These datatypes can be used in the <code>type</code> model item property without a namespace prefix when the default namespace is the XForms namespace. All of these datatypes allow empty content. XForms Processors must treat these datatypes as in-scope without requiring the inclusion of an XML Schema.

<div class="div3">

====<span id="empty-content-types">Additional XForms Datatypes to Allow Empty Content</span>====

Many default XML schema types report empty content as invalid, which conflicts with the use of the <code>required</code> model item property. The following XForms datatypes are defined as having a lexical space consisting of either the empty string or the lexical space of the corresponding XML schema datatype. Although some XML schema datatypes do allow empty string content, they have also been added to the available XForms datatypes for form authoring consistency.

Built-in primitive types (in the XForms namespace):

<blockquote>

dateTime<br />time<br />date<br />gYearMonth<br />gYear<br />gMonthDay<br />gDay<br />gMonth<br />string<br />boolean<br />base64Binary<br />hexBinary<br />float<br />decimal<br />double<br />anyURI<br />QName

</blockquote>

Built-in derived types (in the XForms namespace):

<blockquote>

normalizedString<br />token<br />language<br />Name<br />NCName<br />ID<br />IDREF<br />IDREFS<br />NMTOKEN<br />NMTOKENS<br />integer<br />nonPositiveInteger<br />negativeInteger<br />long<br />int<br />short<br />byte<br />nonNegativeInteger<br />unsignedLong<br />unsignedInt<br />unsignedShort<br />unsignedByte<br />positiveInteger

</blockquote></div><div class="div3">

====<span id="dt-listItem">xforms:listItem</span>====

This datatype serves as a base for the [[#dt-listItems| listItems]] datatype. The lexical space for listItem permits one or more characters valid for xsd:string, except white space characters.

</div><div class="div3">

====<span id="dt-listItems">xforms:listItems</span>====

XForms includes form controls that produce simpleType list content. This is facilitated by defining a <code>derived-by-list</code> datatype. The lexical space for listItems is defined by list-derivation from [[#dt-listItem| listItem]].

<div class="note">

'''Note:'''

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

</div></div><div class="div3">

====<span id="dt-dayTimeDuration">xforms:dayTimeDuration</span>====

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 <code>xsd:duration</code>.

The dayTimeDuration datatype is made available by the XForms processor based on the following lexical space definition:

<div class="exampleOuter"><div class="exampleHead">xforms:dayTimeDuration type definition</div><div class="exampleInner">

 <xs:simpleType name="dayTimeDuration">
   <xs:restriction base="xsd:string">
 
     <xs:pattern value="([\-]?P([0-9]+D(T([0-9]+(H([0-9]+(M([0-9]+(\.[0-9]*)?S
 			|\.[0-9]+S)?|(\.[0-9]*)?S)|(\.[0-9]*)?S)?|M([0-9]+
 			(\.[0-9]*)?S|\.[0-9]+S)?|(\.[0-9]*)?S)|\.[0-9]+S))?
 			|T([0-9]+(H([0-9]+(M([0-9]+(\.[0-9]*)?S|\.[0-9]+S)?
 			|(\.[0-9]*)?S)|(\.[0-9]*)?S)?|M([0-9]+(\.[0-9]*)?S|\.[0-9]+S)?
 			|(\.[0-9]*)?S)|\.[0-9]+S)))?"/>
 
   </xs:restriction>
 </xs:simpleType>

</div></div></div><div class="div3">

====<span id="dt-yearMonthDuration">xforms:yearMonthDuration</span>====

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 <code>xsd:duration</code>.

The yearMonthDuration datatype is made available by the XForms processor based on the following lexical space definition:

<div class="exampleOuter"><div class="exampleHead">xforms:yearMonthDuration type definition</div><div class="exampleInner">

 <xs:simpleType name="yearMonthDuration">
   <xs:restriction base="xsd:string">
 
     <xs:pattern value="([\-]?P[0-9]+(Y([0-9]+M)?|M))?"/>
 
   </xs:restriction>
 </xs:simpleType>

</div></div></div><div class="div3">

====<span id="dt-email">xforms:email</span>====

This datatype represents an email address, as defined by <nowiki>[</nowiki>[[#ref-rfc-2822 |RFC 2822]]<nowiki>]</nowiki>. Internationalized email addresses are not restricted by XForms beyond the definition in the RFC. For simplicity, some extremely uncommon features of the RFC syntax are not allowed, such as "Obsolete Addressing" from section 4.4, square-bracketed "domain-literal"s, and insignificant whitespace and comments.

Examples of valid xforms:email addresses

<blockquote>

editors@example.com<br />~my_mail+{nospam}$?@sub-domain.example.info

</blockquote>

Examples of invalid xforms:email addresses

<blockquote>

editors@(this is a comment)example.info<br />editors{at}example{dot}info<br />mailto:editors@example.com

</blockquote><div class="note">

'''Note:'''

The string <code>mailto:editors@example.com</code> is a valid xsd:anyURI but not a valid xforms:email because the colon separator for the URI scheme is not allowed before the '@' symbol. A valid xforms:email address does not include a <code>mailto:</code> URI scheme.

</div><div class="note">

'''Note:'''

It is outside the scope of XForms to determine whether a given email address actually corresponds to an active mailbox.

</div>

The email datatype is made available by the XForms processor based on the following lexical space definition:

<div class="exampleOuter"><div class="exampleHead">xforms:email type definition</div><div class="exampleInner">

 <xs:simpleType name="email">
   <xs:restriction base="xsd:string">
 
     <xs:pattern value="([A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~
 ]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*)?"/>
 
   </xs:restriction>
 </xs:simpleType>

</div></div></div><div class="div3">

====<span id="dt-card-number">xforms:card-number</span>====

This type defines the basic lexical properties of a datatype that can be used to represent various ID, debit and credit card numbers.. The lexical space of the xforms:card-number datatype is a pattern restriction on <code>xsd:string</code><nowiki>: it must be zero or more digits (0 - 9).</nowiki>

<div class="note">

'''Note:'''

The display representation of this datatype by form controls is not required to match the lexical space of the bound instance data. User agents should apply appropriate conventions to the display and input of values, including separator characters.

</div><div class="exampleOuter"><div class="exampleHead">xforms:card-number type definition</div><div class="exampleInner">

 <xs:simpleType name="card-number">
    <xs:annotation>
       <xs:documentation>
          This type defines the basic lexical properties for a datatype that can be used to represent
          various ID numbers such as for debit and credit cards.
          This type does not apply the Luhn checksum algorithm.
       </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xsd:string">
       <xs:pattern value="[0-9]*"/>
    </xs:restriction>
 </xs:simpleType>

</div></div>

The standard defines the structure of the number as well as how to apply the Luhn formula to ensure a correct check digit. This type only specifies the format of the number. The complementary XPath function <code>is-card-number()</code> should be used to validate that the ID number conforms to the specification.

<div class="exampleOuter"><div class="exampleHead">Credit Card Example</div><div class="exampleInner">

 <model xmlns="http://www.w3.org/2002/xforms">
    <instance>
       <payment method="cc" xmlns="http://commerce.example.com/payment">
          <number>4111111111111111</number>
          <expiry/>
       </payment>
    </instance>
    <bind nodeset="number" type="card-number" constraint="is-card-number(.)"/>
 </model>

</div>

This example specifies that the element <code>number</code> is of the type <code>card-number</code> and that to be valid the <code>is-card-number()</code> function must evaluate to true indicating that check digit is valid.

</div></div></div></div><div class="div1">

==<span id="model">Model Item Properties</span>==

This chapter defines infoset contributions that can be bound to instance data nodes with element <code>bind</code> (see [[#The bind Element|The bind Element]]). The combination of these contributions to an [[#def-instance-data-node|instance data node]] is called a [[#def-model-item|model item]]. Taken together, these contributions are called [[#def-model-item-property|model item properties]], and are defined in the following section. In contrast, the term [[#def-schema-constraint|Schema constraint]] refers only to XML Schema constraints from the [[#def-facet|facet]]s of a given datatype.

<div class="div2">

===<span id="model-xformsconstraints">Model Item Property Definitions</span>===

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.
* [[#def-computed-expression|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 [[#Processing Model|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 <code>bind</code>, and 2) the '''inherited value''', which is determined by combining the evaluated local value with the evaluated values from ancestor nodes in the instance data.

<div class="note">

'''Note:'''

The sample recalculation algorithm defined in [[#Recalculation Sequence Algorithm|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.

</div>

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 (see [[#The xforms-rebuild Event|The xforms-rebuild Event]] for details)..

The following sections list the model item properties available as part of all [[#def-model-item|model item]]s. For each, the following information is provided:

<blockquote>

Description<br />Computed Expression (yes or no)<br />Legal Values<br />Default Value<br />Inheritance Rules

</blockquote><div class="div3">

====<span id="model-prop-type">The type Property</span>====

Description: The <code>type</code> model item property can be applied to both elements and attributes. The <code>type</code> model item property is not applied to instance nodes that contain child elements. The <code>type</code> model item property associates a datatype (as defined in <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>) with the string-value (as defined in <nowiki>[</nowiki>[[#ref-xpath-1.0|XPath 1.0]]<nowiki>]</nowiki>) of an instance node. The datatype being associated can be obtained from a simpleType definition or a simpleContent definition from a complexType. If the datatype cannot be obtained as just described, then the Default Value of <code>xsd:string</code> is used. This model item property does not prevent form controls and XForms actions from setting invalid values into data nodes.

Computed Expression: No.

Legal Values: Any <code>xsd:QName</code> representing a datatype definition in an XML Schema. The namespace context from the parent <code>bind</code> of the <code>type</code> attribute is used to resolve the namespace qualification of the value.

Default Value: <code>xsd:string</code>.

Inheritance Rules: does not inherit.

This model item property contributes to the overall validity assessment of a node; the effect of validity state on bound form controls is described in Section [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]].

<div class="note">

'''Note:'''

In XML Schema, an element can be made nillable. Although this means it can have empty content, nillable is defined by <nowiki>[</nowiki>[[#ref-xschema-1 |XML Schema part 1]]<nowiki>]</nowiki> to be a property of an element, not a type. Therefore, the nillable property from XML Schema cannot be applied to instance nodes using the <code>type</code> model item property.

</div><div class="exampleOuter"><div class="exampleHead">Associating datatypes with instance nodes</div><div class="exampleInner">

 <model xmlns:my="http://example.org">
 
    <xs:schema targetNamespace="http://example.org" xmlns:my="http://example.org">
       <xs:simpleType name="Currency">
 	<xs:restriction base="xsd:string">
            <xs:enumeration value="USD"/>
            <xs:enumeration value="EUR"/>
 	</xs:restriction>
       </xs:simpleType>
 
       <xs:complexType name="Price">
          <xs:simpleContent>
             <xs:extension base="xsd:double">
                <xs:attribute name="currency" type="my:Currency" use="optional" default="USD"/>
             </xs:extension>
          </xs:simpleContent>
       </xs:complexType>
    </xs:schema>
 
    <instance>
       <data xmlns="http://example.org">
          <aString>Hello, world!</aString>
          <simpleType>
             <price>100.00</price>
             <price>abc</price>
             <price currency="EUR">100.00</price>
             <price currency="EUR">abc</price>
          </simpleType>
          <complexType>
             <price>100.00</price>
             <price>abc</price>
             <price currency="abc">100.00</price>
             <price currency="EUR">abc</price>
          </complexType>
       </data>
    </instance>
 
    <bind nodeset="my:aString" type="xsd:string"/>
    <bind nodeset="my:simpleType/my:price" type="xsd:double"/>
    <bind nodeset="my:complexType/my:price" type="my:Price"/>
    <bind nodeset="my:complexType/my:price[3]/@currency" type="my:Currency"/>
    <bind nodeset="/my:data" type="xsd:string"/>
 
 </model>

</div>

The first bind expresses the default datatype of xsd:string.

The second and third binds place type model item properties on each of the four <code>price</code> element children of the elements <code>simpleType</code> and <code>complexType</code>. Both binds associate the datatype <code>xsd:double</code> with the nodes. In both cases, the first and third nodes are considered valid according to the type model item property because their content matches the <code>xsd:double</code> datatype constraint. For both binds, the second and fourth <code>price</code> nodes are not valid due to their content.

The fourth bind places a type model item property on the <code>currency</code> attribute of the third <code>price</code> element. According to this association, the <code>currency</code> attribute node is not valid because its content does not match the enumeration given for <code>my:Currency</code>. Note that the containing element <code>price</code> is valid according to its type model item property.

The fifth bind attempts to associate a datatype with the <code>data</code> element. The association is ignored since the <code>data</code> element contains child elements.

</div></div><div class="div3">

====<span id="model-prop-readOnly">The readonly Property</span>====

Description: describes whether the node content is restricted from changing.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath <code>boolean</code> with <code>boolean()</code>.

Default Value: <code>false()</code>, unless a <code>calculate</code> is specified for the value property, then <code>true()</code>.

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

<div class="note">

'''Note:'''

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

</div>

When <code>true</code>, this model item property indicates that the XForms Processor must not allow any direct changes to the content of the bound instance data node from constructs other than the model item property system (i.e. other than a <code>calculate</code>). Instance mutations performed by <code>submission</code>, form controls, DOM interface access, and XForms actions must not insert or copy a new node into a parent node that is readonly, delete or replace a node whose parent is readonly, nor change the value or content of a readonly node. A node that is readonly but whose parent is not readonly can be entirely deleted or replaced by a submission even though doing so indirectly results in deletion or replacement of readonly descendant nodes.

In addition to restricting value changes, the <code>readonly</code> model item property provides information to the XForms user interface about how bound form controls should be rendered. Form controls bound to instance data with the <code>readonly</code> model item property that evaluates to <code>true</code> should indicate that entering or changing the value is not allowed. This specification does not define any effect of the <code>readonly</code> model item property on visibility, focus, or navigation order.

<div class="exampleOuter"><div class="exampleHead">Attaching a readonly property</div><div class="exampleInner">

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

</div>

Here, we have associated a <code>readonly</code> property with an element.

</div>

The following example illustrates the ability to override the default <code>readonly</code> setting on calculated nodes.

<div class="exampleOuter"><div class="exampleHead">Setting a default value</div><div class="exampleInner">

 <nowiki><model>
   <instance>
     <my:data></my:data>
   </instance>
   <bind nodeset="/my:data" readonly="false()" calculate="choose(.='', 'default', .)"/>
 <model>
 <input ref="/my:data"> ...
 </nowiki>

</div>

The calculate on <code>my:data</code> is executed on any recalculate that follows a rebuild, including the form initialization, so the user initially sees the word 'default'. The user may make any change to <code>my:data</code> with the <code>input</code>, and the calculation will be executed again as a result. Therefore, if the user enters an empty value, then the calculate will change <code>my:data</code> back to 'default'.

</div></div><div class="div3">

====<span id="model-prop-required">The required Property</span>====

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 <code>boolean</code> with <code>boolean()</code>.

Default Value: <code>false()</code>.

Inheritance Rules: does not inherit.

A form may ''require'' certain values, and this requirement may be dynamic. When evaluating to <code>true</code>, 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: The value of the bound instance data node must be convertible to an XPath <code>string</code> with a length greater than zero.

<div class="note">

'''Note:'''

The XML Schema feature represented by <code>nillable</code> and <code>xsi:nil</code> is unrelated to the XForms <code>required</code> model item property. An element may have the <code>xsi:nil</code> attribute set to <code>true</code> to indicate that its empty content is schema valid, but if the <code>required</code> model item property for that element node is <code>true</code>, then the element violates the <code>required</code> constraint because a required node must be non-empty as defined above.

</div>

Except as noted below, the <code>required</code> 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 <code>required</code> data are visible. An XForms Processor must provide an indication that a form control is required, and may provide immediate feedback, including limiting navigation. This model item property does not prevent form controls and XForms actions from setting empty strings into data nodes.

<div class="exampleOuter"><div class="exampleHead">Attaching a required property</div><div class="exampleInner">

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

</div>

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

</div><div class="note">

'''Note:'''

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

</div></div><div class="div3">

====<span id="model-prop-relevant">The relevant Property</span>====

Description: indicates whether the model item is currently ''relevant''. Instance data nodes with this property evaluating to <code>false</code> are unavailable in the user interface and can be removed from submission serialization.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath <code>boolean</code> with <code>boolean()</code>.

Default Value: <code>true()</code>.

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

<div class="note">

'''Note:'''

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

</div>

Many forms have data entry sections 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.

Through single node UI bindings, the <code>relevant</code> model item property provides information to the XForms user interface regarding visibility, focus, and navigation order. In general, when <code>true</code>, associated form controls should be made available for user interaction. When <code>false</code>, associated form controls (and any children) and group and switch elements (including content) must be made unavailable, removed from the navigation order, and not allowed focus. Typically, non-relevant user interface content is not presented, or it may be styled as disabled. Elements other than form controls may also use a single node binding that selects a non-relevant node, but such elements are not made unavailable or non-operable due to the single node binding because it is not a [[#def-ui-binding-expression|UI binding expression]]. For example, actions such as [[#The setvalue Element|The setvalue Element]] and [[#The message Element|The message Element]] or the [[#The submission Element|The submission Element]] remain operable if their single node bindings select a non-relevant node. However, some such elements may indirectly be affected by the <code>relevant</code> model item property. For example, it is possible for non-relevant nodes to be excluded from the data of a submission. Similarly, non-relevance indirectly affects the running of actions because a non-relevant form control disables event handlers that listen for events targeted at the form control element.

<div class="note">

'''Note:'''

A core form control, group or switch must express a single node binding in order to be associated with an instance node. Due to the definition of [[#def-repeat-object|repeat object]], the <code>relevant</code> model item property of the node in the associated [[#def-repeat-item|repeat item]] affects the availability of the repeat object.

</div><div class="exampleOuter"><div class="exampleHead">Attaching a relevant property</div><div class="exampleInner">

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

</div>

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

</div></div><div class="div3">

====<span id="model-prop-calculate">The calculate Property</span>====

Description: supplies an expression used to calculate a string value for the associated instance data node.

Computed Expression: Yes.

Legal Values: Any XPath expression.

Default Value: none.

Inheritance Rules: does not inherit.

An XForms Model may include model items whose string values 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. The formula for such a computed value can be expressed with a <code>calculate</code> property, whose XPath expression is evaluated, converted to a string with the XPath <code>string()</code> function, and stored as the value content of the calculated data node. Chapter [[#Processing Model|Processing Model]] contains details of when and how the calculation is performed.

<div class="exampleOuter"><div class="exampleHead">Attaching a calculate property</div><div class="exampleInner">

 <instance>
   <my:order>
     <my:item>
       <my:amount />
       <my:discount />
     </my:item>
   </my:order>
 </instance>
 <bind nodeset="my:item/my:discount" calculate="../my:amount * 0.1"
       relevant="../my:amount > 1000"/>

</div>

Here, we have associated a <code>relevant</code> property with element <code>my:discount</code> to indicate a discount of 10% is relevant when the order amount is greater than 1000.

</div></div><div class="div3">

====<span id="model-prop-constraint">The constraint Property</span>====

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

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath <code>boolean</code> with <code>boolean()</code>.

Default Value: <code>true()</code>.

Inheritance Rules: does not inherit.

When evaluating to XPath <code>false</code>, the associated model item is not valid; the converse is not necessarily true. This model item property does not prevent form controls and XForms actions from setting invalid values into data nodes. Chapter [[#Processing Model|Processing Model]] contains details of when and how the constraint is calculated as well as when validation is performed. This model item property contributes to the overall validity assessment of a node; the effect of validity state on bound form controls is described in Section [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]].

<div class="exampleOuter"><div class="exampleHead">Attaching a constraint property</div><div class="exampleInner">

 <instance>
   <my:range>
     <my:from />
     <my:to />
   </my:range>
 </instance>
 <bind nodeset="my:to" constraint=". > ../my:from" />

</div>

Here, a <code>constraint</code> property associated with element <code>my:to</code> indicates that its value must be greater than that of element <code>my:from</code>.

</div><div class="note">

'''Note:'''

Specifying minimum and maximum occurrences for nodes in the instance data can be achieved by using the <code>count()</code> function within a <code>constraint</code> property.

</div></div><div class="div3">

====<span id="model-prop-p3ptype">The p3ptype Property</span>====

Description: Attaches a P3P data element to an instance data node, indicating the specific kind of data collected there.

Computed Expression: No.

Legal Values: <code>xsd:string</code>.

Default Value: none

Inheritance Rules: does not inherit.

This model item property holds a description of the kind of data collected by the associated instance data node, based on the P3P datatype system <nowiki>[</nowiki>[[#ref-p3p-1.0 |P3P 1.0]]<nowiki>]</nowiki>. This information may be used to enhance the form-fill experience, for example by supplying previously-known data.

<div class="exampleOuter"><div class="exampleHead">Attaching a type constraint using Binding</div><div class="exampleInner">

 <instance>
   <my:person-name>
     <my:first-name />
     <my:last-name />
   </my:person-name>
 </instance>
 <bind type="my:nonEmptyString" nodeset="my:first-name"
       p3ptype="user.name.given"/>

</div>

Here, we have attached both XML Schema and P3P type information to element <code>first-name</code> via element <code>bind</code>.

</div></div></div><div class="div2">

===<span id="model-using">Schema Constraints</span>===

Chapter [[#Datatypes|Datatypes]] described how XForms uses the XML Schema datatype system to constrain the [[#def-value-space|value space]] of data values collected by an XForms Model. Such datatype constraints can be provided via an XML Schema. Alternatively, this section lists various mechanisms for attaching type constraints to instance data. Attributes <code>xsi:schemaLocation</code> and <code>xsi:noNamespaceSchemaLocation</code> are ignored for purposes for locating a Schema.

<div class="div3">

====<span id="model-using-atomic">Atomic Datatype</span>====

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 an XML 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 associated with a model item must be determined by the following list, as if it were processed in the given order. When multiple datatype restrictions apply to the same model item, the combination of all given restrictions must apply. Note that it is possible to produce a combination of restrictions that is impossible to satisfy; authors are encouraged to avoid this practice.

# Applicable XML schema definitions (including those associated an external or an inline schema, or by <code>xsi:type</code>)
# An XForms <code>type</code> constraint associated with the instance data node using XForms [[#def-binding|binding]].
# If no type constraint is provided, the instance data node defaults to <code>type="xsd:string"</code> (default to string rule).

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

<div class="exampleOuter"><div class="exampleHead">Type Constraint Using XML Schema</div><div class="exampleInner">

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

</div>

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

</div><div class="exampleOuter"><div class="exampleHead">Attaching A Type Constraint</div><div class="exampleInner">

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

</div>

This defines element <code>first-name</code> to be of type <code>my:nonEmptyString</code>.

</div><div class="exampleOuter"><div class="exampleHead">Attaching Type Constraint Using XForms Binding</div><div class="exampleInner">

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

</div>

Here, we have attached type information to element <code>first-name</code> via element <code>bind</code>. Thus the XForms author can extend external schemas without having the ability to change them.

</div></div></div></div><div class="div1">

==<span id="expr">XPath Expressions in XForms</span>==

XForms uses XPath to address [[#def-instance-data-node|instance data node]]s in binding expressions, to express constraints, and to specify calculations. XPath expressions in XForms are based on <nowiki>[</nowiki>[[#ref-xpath-1.0|XPath 1.0]]<nowiki>]</nowiki>. A future version of XForms is expected to enable use of <nowiki>[</nowiki>[[#ref-xpath-2.0 |XPath 2.0]]<nowiki>]</nowiki>. At the time of evaluation, an XPath expression must be syntactically correct. In addition, the namespaces the expression references must be in scope and the functions and variables it references must be defined. If any of these conditions is not satisfied, an exception ([[#The xforms-compute-exception Event|The xforms-compute-exception Event]]) is raised, except for binding expressions, which produce a different exception ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]).

<div class="div2">

===<span id="expr-datatypes">XPath Datatypes</span>===

XPath datatypes are used only in [[#def-binding-expression|binding expression]]s and [[#def-computed-expression|computed expression]]s. XForms uses XPath datatypes <code>boolean</code>, <code>string</code>, <code>number</code>, and <code>node-set</code>. Additionally, the type <code>object</code> is used to denote a parameter or return value that can be any one of the four XPath datatypes. A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes.

</div><div class="div2">

===<span id="expr-eval">Evaluation Context</span>===

Within XForms, the '''default model''' is the first <code>model</code> in document order. The '''default instance''' of any <code>model</code> is the first child <code>instance</code> in document order within that <code>model</code>. XPath expressions appearing in various XForms attributes are used to reference instance data. Every XPath expression requires an evaluation context consisting of a node, position, size, variable bindings, function set, and namespace context. For all evaluation contexts in XForms,

# No variable bindings are in place.
# The available function library is defined below in [[#The XForms Function Library|The XForms Function Library]].
# Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.
# The context node, position and size are determined according to rules described below.

A '''binding element''' is any element that is explicitly allowed to have a binding expression attribute, and a '''bound element''' is any element that explicitly declares a binding expression attribute. A binding expression attribute contains an XPath expression that references zero or more nodes of instance data. Every XPath expression requires an evaluation context. The '''in-scope evaluation context''' of a binding element provides an evaluation context for the binding expression attribute. The following rules are used in determining the node, position and size of the in-scope evaluation context:

# A binding element is "'''outermost'''" if the element has no ancestor binding elements. If an outermost binding element is contained by a <code>model</code>, then the context node for the outermost binding element is the top-level document element node of the default instance of the containing <code>model</code> element. Otherwise, the context node for outermost binding elements is the top-level document element node of the default instance in the default model. For outermost binding elements, the context size and position are 1.
# The context node, position and size for non-outermost binding elements is determined using the binding expression attribute or in-scope evaluation context of the nearest ancestor binding element. This is also referred to as "scoped resolution". For a non-outermost binding element:
## If the nearest ancestor binding element is not a bound element, then the in-scope evaluation context of the non-outermost binding element is equivalent to the in-scope evaluation context of the nearest ancestor binding element.
## If the nearest ancestor binding element expresses a Single-Node binding, then the in-scope evaluation context of the non-outermost binding element has a context size and position of 1 and the context node is the one resulting from the Single-Node binding of the nearest ancestor binding element.
## If the nearest ancestor binding element expresses a Node Set binding, then the XForms processor dynamically generates an occurrence of the non-outermost binding element for each of the nodes in the Node Set Binding of the nearest ancestor binding element. The '''dynamic in-scope evaluation context''' for each generated occurrence of the non-outermost binding element has a context size equal to the size of the nodeset identified by the Node Set Binding of the nearest ancestor binding element, the context node is the node for which the occurrence of the non-outermost binding element was generated, and the position is equal to the position of the generator node in the nodeset identified by the Node Set Binding of the nearest ancestor binding element.
## If the nearest ancestor binding element expresses a Node Set binding, then the non-outermost binding element has its own in-scope evaluation context separately from those of its dynamically generated occurences described above. The in-scope evaluation context has a context position of 1, and the context node and size are set by the first node and the size of the nodeset identified by the Node Set binding of the nearest ancestor binding element.
# Once the context node of the in-scope evaluation context has been determined according to the rules above, if the binding element expresses a <code>model</code> attribute that refers to a <code>model</code> other than the one containing the context node, then the context node of the in-scope evaluation context is changed to be the top-level document element node of the default instance of the referenced <code>model</code>, and the context position and size are changed to 1.

The '''in-scope evaluation context''' of an element that is not a binding element is the same as if the element were a binding element. For example, the in-scope evaluation context for the <code>setindex</code> action element is required to provide the context for evaluating the <code>index</code> attribute, so it is determined as if the element could contain a binding expression attribute.

XPath expressions also appear in model item property attributes of the <code>bind</code> element to define computed expressions. If the <code>bind</code> element does not express a Node Set binding, then the in-scope evaluation context for model item property attributes of the <code>bind</code> is equal to the in-scope evaluation context for the <code>bind</code>. Otherwise, the <code>bind</code> has a Node Set binding, and computed expressions for each model item property attribute are generated for each node. For each computed expression generated, the evaluation context node, position and size are determined by the same method as dynamic in-scope evaluation context rule above, except the computed expression is used in lieu of a binding expression attribute such that the <code>bind</code> element is the nearest ancestor binding element.

XPath expressions also appear in the special attributes of several other XForms elements, such as the <code>value</code> attribute on <code>setvalue</code> and <code>output</code>, the <code>at</code> attribute of <code>insert</code> and <code>delete</code>, or the <code>index</code> attribute of <code>setindex</code>. Generally, if the containing element does not express a Single Node Binding or Node Set Binding, then the special attribute is evaluated using the in-scope evaluation context. Special attributes may be evaluated using the in-scope evaluation context even if the containing element expresses a Single Node Binding or Node Set Binding. However, for some special attributes, the evaluation context node, position and size are based on the result of the Single Node Binding or Node set Binding. Each special attribute that contains an XPath expression describes how its evaluation context node, position and size are determined.

In the following example, the <code>group</code> has a binding expression of <code>level2/level3</code>. According to the rules above, this outermost element node would have a context node of <code>/level1</code>, which is the document element node of the instance data. The <code>select1</code> form control then inherits a context node from the parent group.

<div class="exampleOuter"><div class="exampleHead">Sample XML Instance Data</div><div class="exampleInner">

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

</div></div><div class="exampleOuter"><div class="exampleHead">Binding Expression Context Nodes</div><div class="exampleInner">

 <group ref="level2/level3">
   <select1 ref="@attr" ... >
      <label>...</label>
   </select1>
 </group>

</div></div>

This section describes how the in-scope evaluation context of an element is determined, not whether the in-scope evaluation will be used. The Single-Node Binding or Node Set Binding of a non-outermost binding element is not evaluated if the in-scope evaluation context does not contain a context node. This can occur if the Single-Node Binding or Node Set Binding of the nearest ancestor bound element produces an empty nodeset. Also, if the Single-Node Binding or Node Set Binding of an element is expressed with the <code>bind</code> attribute, then the resulting node or nodeset is obtained from the referenced <code>bind</code> element. The <code>nodeset</code> attribute of a <code>bind</code> element is evaluated using the in-scope evaluation of the <code>bind</code> element, not the in-scope evaluation context of an element that references it with a <code>bind</code> attribute.

</div><div class="div2">

===<span id="expr-dependencies">References, Dependencies, and Dynamic Dependencies</span>===

An XPath expression '''references''' a node of instance data if the node is selected during the evaluation of the expression. A node is selected by matching an XPath [http://www.w3.org/TR/xpath#NT-NodeTest NodeTest] or by being returned by a function call. For examples, a node can match a name test, a wildcard test, a node type test, or it can be returned by or used as a parameter to a function, or it can appear in a filter expression (where all of the prior examples recursively apply). Once selected, a node is considered to be referenced even if a filter expression subsequently excludes the node from further participation in the expression evaluation. The '''reference list''' of an XPath expression is the set of instance nodes that it references.

<div class="exampleOuter"><div class="exampleHead">Example of References and Non-References</div>

Given the following default instance:

<div class="exampleInner">

 <xforms:instance>
    <data xmlns="">
       <a attr="X">
          &lt;b attr="Y">
             <c/>
          &lt;/b>
          <d/>
       </a>
       <a attr="Z">
          &lt;b attr="Z">
             <c/>
          &lt;/b>
          <d/>
       </a>
    </data>
 </xforms:instance>

</div>

and the following XPath expression:

<div class="exampleInner">

 a[@attr='X']/b[@attr='X']/c

</div>

Both nodes named <code>a</code> are referenced since both are matched by a NameTest. The <code>attr</code> attribute in each element <code>a</code> is referenced during the evaluation of the filter expression. The filter expression rejects the second element <code>a</code>, but that element is still considered to have been referenced because it was selected for further processing during the expression evaluation.

The element named <code>b</code> in the first element <code>a</code> is referenced, but element <code>b</code> in the second <code>a</code> is not referenced because the expression evaluation did not proceed beyond the filter expression that rejected the second <code>a</code> element.

While performing the NameTest for element <code>b</code>, observe that an XPath expression evaluator may visit all the children of the first element <code>a</code> in order to perform the NodeTest. However, a node is not referenced if it is only visited but fails the NodeTest. In this case, the NodeTest is a NameTest for <code>b</code>, which the element <code>d</code> fails. Therefore, <code>d</code> is not referenced.

The filter expression test on <code>b</code> rejects the only element <code>b</code> that has been selected so far because the attribute value of <code>attr</code> does not match the equality test. Still, <code>b</code> and its attribute <code>attr</code> have been referenced by this expression.

Element <code>c</code> is not considered to be referenced by this expression given this data. Although a NameTest for <code>c</code> appears in the expression, the evaluation of the expression did not proceed to perform the NameTest due to the rejection of <code>b</code> by the filter expression.

Finally, note that an XPath expression can reference many nodes even if its final result is an empty nodeset.

</div><div class="note">

'''Note:'''

Defining a '''reference''' in terms of matching a NodeTest was a deliberate design decision that creates more references than necessary in order to make the computation system more responsive to certain types of changes without needing a rebuild operation. When a leaf node is filtered from an expression by a predicate, the leaf node is still considered to be referenced so that if the condition changes such that the leaf node would be included in the result value of the expression, then the expression will be recalculated without needing a rebuild. However, once a node is rejected from an expression, further location steps are not evaluated relative to the rejected node, so references for that location step are only created based on its execution relative to accepted nodes. For example, if the above expression were in a <code>calculate</code>, and if the attribute of either <code>b</code> element changes to the value <code>X</code>, the expression would be recalculated but it still does not record a reference to any <code>c</code> elements until the references are obtained in the next rebuild operation. Moreover, the excess references created by the definition may cause some recalculation constructs to cease operation due to circular references that would not be created with a stricter definition of a reference. A future version of XForms may use a stricter version of referencing for recalculation and a less strict definition of referencing for the purpose of detecting and performing automatic rebuild operations.

</div>

The referencing of a repeat index by the <code>index()</code> function is handled as a special case. Implementations must behave as if each occurrence of a <code>repeat</code> is associated with an implicitly managed instance data node containing the repeat index. If a <code>repeat</code> identified as <code>R1</code> contains a <code>repeat</code> identified as <code>R2</code>, then a repeat index instance node is managed for each occurrence of <code>R2</code> that is generated by <code>R1</code>. An invocation of the function <code>index()</code> in an XPath expression is considered to reference the repeat index instance node corresponding to the repeat index value that it returns.

If an XPath expression references an instance node, then the expression result is '''dependent''' on the instance node. A '''dependency list''' for an instance node is the list of XPath expressions of a given category that are dependent upon the instance node. For example, in Section [[#The xforms-recalculate Event|The xforms-recalculate Event]], the dependency list of computed expressions for each instance node helps establish the recalculation order for the computed expressions when the values of instance data nodes are changed.

The references of an XPath expression may be altered by insertion of instance nodes since the new nodes may be referenced by the XPath expression if it is re-evaluated. Similarly, the references of an XPath expression may be altered by deletion of instance nodes that are being referenced by the XPath expression. An XPath expression is '''dynamically dependent''' on an instance node if its reference list is altered by inserting, deleting or changing the value of the instance node. An instance node is a '''dynamic dependency''' for an XPath expression if the expression is dynamically dependent on the instance node. If an XPath expression contains a dynamic dependency and the XForms processor is maintaining dependency lists for the category of the XPath expression, then changing the dynamic dependency implies a change to the dependency lists of instance nodes referenced by the XPath expression.

The computational dependency data structure described in Section [[#The xforms-recalculate Event|The xforms-recalculate Event]] essentially stores the dependency lists of instance nodes corresponding to all the references made by computed expressions (see Appendix [[#Recalculation Sequence Algorithm|Recalculation Sequence Algorithm]] for details). The computational dependency data structure is not reconstructed in response to a dynamic dependency change. Instead, the form author may request a rebuild of the computational dependency data structures using the <code>rebuild</code> action. Additionally, the <code>insert</code> and <code>delete</code> actions set a rebuild flag so that computational dependency data structures will be rebuild at the end of an action sequence.

Due to the rebuild flag setting on <code>insert</code> and <code>delete</code>, a form author can use many kinds of dynamic dependencies in model binding expressions and computed expressions without ever explicitly invoking the <code>rebuild</code> action. This includes the use of functions such as <code>position()</code>, <code>last()</code>, and <code>count()</code> on element and attribute nodes because the return values of the functions in these cases is fixed except when an <code>insert</code> or <code>delete</code> occurs. By comparison, functions such as <code>id()</code>, <code>instance()</code>, and <code>index()</code> can establish dynamic dependencies that can necessitate invoking a <code>rebuild</code> if they are used in model binding expressions or computed expressions because the results of the functions are affected by changing the values of instance nodes, not by inserting or deleting nodes.

</div><div class="div2">

===<span id="expr-expression-categories">Expression Categories</span>===

There are several different categories of XPath expressions used in XForms, and they are processed at different times depending on the category. A [[#def-binding-expression|binding expression]] is an XPath expression used to bind a [[#def-model-item-property|model item property]] to one or more instance nodes, or to bind a form control to instance data, or to specify the node or node set for operation by an action. The evaluation schedule for binding expressions differs based on whether the binding expression is a model binding expression, UI binding expression, or a binding expression for an XForms action. XPath expressions are also used in various other attributes of XForms binds, actions, form controls, and <code>submission</code>s, and their descendant elements. These expressions follow one of the three schedules associated with binding expressions as described below.

<div class="div3">

====<span id="expr-model-binding-expression-computed-expression">Model Binding Expressions and Computed Expressions</span>====

A [[#def-model-binding-expression|model binding expression]] is a kind of binding expression that can be used to declare model item properties, and is used in the Node-Set binding of the <code>bind</code> element. A [[#def-computed-expression|computed expression]] is an XPath expression used to determine the value of a [[#def-model-item-property|model item property]] based on instance data. Several of the attributes of <code>bind</code> are computed expressions, including <code>calculate</code>, <code>readonly</code>, <code>relevant</code>, and <code>required</code>.

Dynamic dependencies in model binding expressions and computed expressions will require manual rebuilding of dependencies.

<div class="note">

'''Note:'''

If the <code>index()</code> function is being invoked from a model binding expression or computed expression, it will be necessary to invoke <code>rebuild</code> manually. If the repeat index change occurs due to an implicit behavior such as a change to the focused form control, then the rebuild (along with recalculate, revalidate and refresh) can be invoked from a handler for <code>DOMFocusIn</code> attached to the <code>repeat</code> or each repeat object.

</div></div><div class="div3">

====<span id="expr-actions-submissions">Expressions in Actions and Submissions</span>====

Binding expressions on XForms actions and XPath expressions appearing in other attributes of XForms actions are evaluated at the time the XForms action is performed. In some cases, XForms actions have child elements that allow the values of some of their attributes to be determined based on instance data. In these cases, the <code>value</code> attribute of the child element is evaluated at the time the corresponding attribute is needed in the processing model of the containing XForms action.

Similarly, XPath expressions used in the attributes of <code>submission</code> and its child elements (other than XForms actions) are evaluated as needed within the submission processing model.

Form authors can use dynamic dependencies in the XPath expressions of XForms Actions and Submissions without invoking any special data structure reconstruction actions because implementations must behave as if these expressions are evaluated as needed.

</div><div class="div3">

====<span id="expr-ui-expressions">UI Expressions</span>====

A [[#def-ui-binding-expression|UI Binding Expression]] is a Single Node Binding or Node Set Binding in a form control. A '''UI expression''' is a UI Binding Expression or an XPath expression appearing in a descendant element of a form control, except for XPath expressions in the categories described above (such as XForms action expressions). These include the Single Node Bindings and Node Set Bindings of the additional elements that contribute to the behavior of a form control (including <code>label</code>, <code>help</code>, <code>hint</code> and <code>alert</code>, <code>filename</code> and <code>mediatype</code>) and the selection helper elements (<code>itemset</code>, <code>label</code>, <code>value</code> and <code>copy</code>). This also includes the <code>value</code> attribute on <code>output</code> and <code>value</code> elements.

Form authors can use dynamic dependencies in UI Expressions without invoking any special data structure reconstruction actions because the state of the user interface at the end of processing [[#evt-refresh|xforms-refresh]] is required to reflect the instance data as if all UI Expressions had been re-evaluated.

<div class="note">

'''Note:'''

Implementations may record UI Expression dependency lists on instance nodes to help streamline detection of the need to re-evaluate a UI Expression at the beginning of processing for [[#evt-refresh|xforms-refresh]]. Such implementations may determine that a UI Expression is stale (needs re-evaluation) when a node on which it depends has been changed. An implementation may also indicate that all UI Expressions are stale if a node of instance data is inserted, deleted or replaced, or the implementation may streamline detection of which UI Expressions may be affected by the insertion, deletion or replacement of an instance data node.

</div></div><div class="div3">

====<span id="ui-binding-foreign">UI Binding in other XML vocabularies</span>====

The XForms binding mechanism allows other XML vocabularies to make single node bindings between custom user interface controls and XForms instance data. As an example, XForms binding attribute <code>bind</code> might be used within XHTML 1.x user interface controls as shown below. See [[#Single-Node Binding Attributes|Single-Node Binding Attributes]].

<div class="exampleOuter"><div class="exampleHead">XForms Binding In XHTML 1.x User Interface Controls</div><div class="exampleInner">

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

</div></div></div><div class="div3">

====<span id="ui-binding-examples">Binding Examples</span>====

Consider the following document with the one-and-only XForms model:

<div class="exampleOuter"><div class="exampleInner">

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

</div></div>

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

<div class="exampleOuter"><div class="exampleHead">UI Binding Using Attribute <code>ref</code></div><div class="exampleInner">

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

</div></div><div class="exampleOuter"><div class="exampleHead">UI Binding Using Attribute <code>bind</code></div><div class="exampleInner">

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

</div></div><div class="exampleOuter"><div class="exampleHead">Specifies Model Containing The Instance Explicitly</div><div class="exampleInner">

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

</div></div></div></div><div class="div2">

===<span id="expr-lib">The XForms Function Library</span>===

The XForms Function Library includes the entire <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> Core Function Library, including operations on node-sets, strings, numbers, and booleans.

The following sections define additional required functions for use within XForms : [[#Boolean Functions|Boolean Functions]], [[#Number Functions|Number Functions]], [[#String Functions|String Functions]], [[#Date and Time Functions|Date and Time Functions]], [[#Node-set Functions|Node-set Functions]] , and [[#Object Functions|Object Functions]].

The function library provided by an XForms processor may also contain other extension functions as described in [[#Extension Functions|Extension Functions]].

If an error occurs in an XPath function, then an [[#The xforms-compute-exception Event|The xforms-compute-exception Event]] or [[#The xforms-binding-exception Event|The xforms-binding-exception Event]] occurs..

</div><div class="div2">

===<span id="expr-lib-bool">Boolean Functions</span>===

<div class="div3">

====<span id="fn-boolean-from-string">The boolean-from-string() Function</span>====

''boolean'' '''boolean-from-string'''(<var>string</var>)

Function <code>boolean-from-string</code> returns <code>true</code> if the required parameter <code>string</code> is "true" or "1", or <code>false</code> if parameter <code>string</code> is "false", or "0". This is useful when referencing a Schema <code>xsd:boolean</code> datatype in an XPath expression. If the parameter string matches none of the above strings, according to a case-insensitive comparison, the return value is <code>false</code>.

</div><div class="div3">

====<span id="fn-is-card-number">The is-card-number() Function</span>====

''boolean'' '''is-card-number'''(<var>string</var>?)

If the string parameter conforms to the pattern restriction of the [[#xforms:card-number|card-number]] datatype, then this function applies the <code>Luhn</code> algorithm described in <nowiki>[</nowiki>[[#ref-luhn |Luhn Patent]]<nowiki>]</nowiki> and returns true if the number satisfies the formula. Otherwise, false is returned. If the parameter is omitted, it defaults to the string-value of the current context node.

Examples (see also [[#xforms:card-number|xforms:card-number]]):

<div class="exampleOuter"><div class="exampleInner">

 is-card-number(.)

</div>

returns <code>true</code> if and only if the context node contains a string that contains of zero or more digits and satisfies the formula.

<div class="exampleInner">

 is-card-number('4111111111111111')

</div>

returns <code>true</code>. Other examples of string constants that will return <code>true</code> are : <code>5431111111111111</code>, <code>341111111111111</code> and <code>6011601160116611</code>.

<div class="exampleInner">

 is-card-number('123')

</div>

returns <code>false</code>.

</div></div></div><div class="div2">

===<span id="expr-lib-num">Number Functions</span>===

<div class="div3">

====<span id="fn-avg">The avg() Function</span>====

''number'' '''avg'''(<var>node-set</var>)

Function <code>avg</code> 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 <code>sum()</code>, and divided with <code>div</code> by the value computed with <code>count()</code>. If the parameter is an empty node-set, or if any of the nodes evaluate to <code>NaN</code>, the return value is <code>NaN</code>.

</div><div class="div3">

====<span id="fn-min">The min() Function</span>====

''number'' '''min'''(<var>node-set</var>)

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

</div><div class="div3">

====<span id="fn-max">The max() Function</span>====

''number'' '''max'''(<var>node-set</var>)

Function <code>max</code> returns the maximum value of the result of converting the string-values of each node in argument <code>node-set</code> to a number. "Maximum" is determined with the <code><</code> operator. If the parameter is an empty node-set, or if any of the nodes evaluate to <code>NaN</code>, the return value is <code>NaN</code>.

</div><div class="div3">

====<span id="fn-count-non-empty">The count-non-empty() Function</span>====

''number'' '''count-non-empty'''(<var>node-set</var>)

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

</div><div class="div3">

====<span id="fn-index">The index() Function</span>====

''number'' '''index'''(<var>string</var>)

Function <code>index</code> takes a string argument that is the <code>IDREF</code> of a <code>repeat</code> and returns the current 1-based position of the repeat index for the identified <code>repeat</code>—see [[#The repeat Element|The repeat Element]] for details on <code>repeat</code> and its associated repeat index. If the specified argument does not identify a <code>repeat</code>, the function returns <code>NaN</code>.

<div class="note">

'''Note:'''

The IDREF obtained from the function parameter may not uniquely identify the desired <code>repeat</code> if the <code>repeat</code> element bearing the matching ID resides in a repeating construct such as element <code>repeat</code>. The general method described in [[#Resolving ID References in XForms|Resolving ID References in XForms]] is used to determine the desired run-time repeat object.

</div><div class="exampleOuter"><div class="exampleHead">index</div><div class="exampleInner">

 <xforms:trigger>
   <xforms:label>Add to Shopping Cart</xforms:label>
   <xforms:insert ev:event="DOMActivate" position="after"
                  nodeset="items/item" at="index('cartUI')"/>
 </xforms:trigger>

</div></div></div><div class="div3">

====<span id="fn-power">The power() Function</span>====

''number'' '''power'''(<var>number</var>, <var>number</var>)

Raises the first argument to the power of the second argument, returning the result. If the calculation does not result in a real number, then <code>NaN</code> is returned.

Examples:

<div class="exampleOuter"><div class="exampleInner">

 power(2, 3)

</div>

returns <code>8</code>

<div class="exampleInner">

 power(-1, 0.5)

</div>

returns <code>NaN</code>.

<div class="exampleInner">

 if (prin>0 and dur>0 and rate>0, prin*rate/(1-power(1+rate, -dur)), 0)

</div>

returns a compounded interest payment value given a non-zero principal (<code>prin</code>), duration (<code>dur</code>) and periodic interest rate (<code>rate</code>).

</div></div><div class="div3">

====<span id="fn-random">The random() Function</span>====

''number'' '''random'''(<var>boolean</var>?)

This function generates and returns a uniformly distributed random or pseudorandom number in the range from 0.0 up to but excluding 1.0. This function accepts an author-optional boolean parameter that is <code>false</code> by default. If <code>true</code>, the random number generator for this function is first seeded with a source of randomness before generating the return value. A typical implementation may seed the random number generator with the current system time in milliseconds when <code>random(true)</code> is invoked, and it may apply a linear congruential formula to generate return values on successive invocations of the function.

Example:

<div class="exampleOuter"><div class="exampleInner">

 random()

</div>

could return <code>0.14159265358979</code>

</div></div><div class="div3">

====<span id="fn-compare">The compare() Function</span>====

''number'' '''compare'''(<var>string</var>, <var>string</var>)

This function returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of second argument based on lexicographic comparison using Unicode code point values <nowiki>[</nowiki>[[#ref-unicode-collation |Unicode Collation Algorithm]]<nowiki>]</nowiki>.

Example:

<div class="exampleOuter"><div class="exampleInner">

 compare('apple', 'orange')

</div>

returns <code>-1</code>

</div></div></div><div class="div2">

===<span id="expr-lib-string">String Functions</span>===

<div class="div3">

====<span id="fn-if">The if() Function</span>====

''string'' '''if'''(<var>boolean</var>, <var>string</var>, <var>string</var>)

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

<div class="note">

'''Note:'''

This function is deprecated because a future version of XForms is expected to be based on <nowiki>[</nowiki>[[#ref-xpath-2.0 |XPath 2.0]]<nowiki>]</nowiki>, which contains an <code>if</code> construct that is incompatible with this function.Form authors and design tools are encouraged to use the function <code>choose()</code> from Section [[#The choose() Function|The choose() Function]] instead of this function.

</div></div><div class="div3">

====<span id="fn-property">The property() Function</span>====

''string'' '''property'''(<var>string</var>)

This function accepts a string identifying a property name. If the property name is not recognized, empty string is returned. The property definitions for this function are as follows:

{| summary="Property function parameters and return values" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Return Value
|-
| rowspan="1" colspan="1" | <code>version</code>
| rowspan="1" colspan="1" | <code>1.1</code>
|-
| rowspan="1" colspan="1" | <code>conformance-level</code>
| rowspan="1" colspan="1" | <code>full</code>, <code>basic</code> or a string beginning with <code>full</code> or <code>basic</code>
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#The XForms Function Library|The XForms Function Library]] for the exception type)
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName|QNameButNotNCName]]
| rowspan="1" colspan="1" | An implementation-specific property value, such as a locale or timezone for the user agent. If the implementation does not support the property, then empty string is returned.
|}

Examples:

<div class="exampleOuter"><div class="exampleInner">

 property('version')

</div>

returns <code>1.1</code>

<div class="exampleInner">

 property('conformance-level')

</div>

may return <code>full</code>

</div></div><div class="div3">

====<span id="fn-digest">The digest() Function</span>====

''string'' '''digest'''(<var>string</var>, <var>string</var>, <var>string</var>?)

This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:

{| summary="Hash algorithms for the digest() function" border="1"
! rowspan="1" colspan="1" | Keywords
! rowspan="1" colspan="1" | Hash Algorithm
! rowspan="1" colspan="1" | Status
|-
| rowspan="1" colspan="1" | <code>MD5</code>
| rowspan="1" colspan="1" |
The MD5 hash algorithm defined in <nowiki>[</nowiki>[[#ref-md5 |MD5]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-1</code>
| rowspan="1" colspan="1" |
The SHA-1 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-256</code>
| rowspan="1" colspan="1" |
The SHA-256 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-384</code>
| rowspan="1" colspan="1" |
The SHA-384 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Optional]]
|-
| rowspan="1" colspan="1" | <code>SHA-512</code>
| rowspan="1" colspan="1" |
The SHA-512 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Optional]]
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#The XForms Function Library|The XForms Function Library]] for the exception type)
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName|QNameButNotNCName]]
| rowspan="1" colspan="1" |
An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see [[#The XForms Function Library|The XForms Function Library]] for the exception type).
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|}

This recommendation defines the values <code>hex</code> and <code>base64</code> for the third string parameter that indicates the encoding method. If the parameter is missing, then the default is <code>base64</code>. The <code>hex</code> and <code>base64</code> encoding methods of this function correspond to the encodings defined in <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki> for the datatypes <code>hexBinary</code> and <code>base64Binary</code>, respectively. For the hexadecimal encoding, the digits 'a' through 'f' are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see [[#The XForms Function Library|The XForms Function Library]] for the exception type).

<div class="exampleOuter"><div class="exampleInner">

 digest('abc', 'SHA-1', 'hex')

</div>

returns <code>a9993e364706816aba3e25717850c26c9cd0d89d</code>.

<div class="exampleInner">

 digest('abc', 'MD5', 'hex')

</div>

returns <code>900150983cd24fb0d6963f7d28e17f72</code>.

<div class="exampleInner">

 digest('abc', 'SHA-256', 'hex')

</div>

returns <code>ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad</code>

</div></div><div class="div3">

====<span id="fn-hmac">The hmac() Function</span>====

''string'' '''hmac'''(<var>string</var>, <var>string</var>, <var>string</var>, <var>string</var>?)

This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in <nowiki>[</nowiki>[[#ref-hmac |HMAC]]<nowiki>]</nowiki> and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.

The following table presents the keywords for the third string parameter and the corresponding hash algorithms:

{| summary="Hash algorithms for the hmac() function" border="1"
! rowspan="1" colspan="1" | Keywords
! rowspan="1" colspan="1" | Hash Algorithm
! rowspan="1" colspan="1" | Status
|-
| rowspan="1" colspan="1" | <code>MD5</code>
| rowspan="1" colspan="1" |
The MD5 hash algorithm defined in <nowiki>[</nowiki>[[#ref-md5 |MD5]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-1</code>
| rowspan="1" colspan="1" |
The SHA-1 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-256</code>
| rowspan="1" colspan="1" |
The SHA-256 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" | <code>SHA-384</code>
| rowspan="1" colspan="1" |
The SHA-384 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Optional]]
|-
| rowspan="1" colspan="1" | <code>SHA-512</code>
| rowspan="1" colspan="1" |
The SHA-512 hash algorithm defined in <nowiki>[</nowiki>[[#ref-sha2 |SHA2]]<nowiki>]</nowiki>
| rowspan="1" colspan="1" |
[[#intro-reading|Optional]]
|-
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" |
Reserved. Their use results in an exception (see [[#The XForms Function Library|The XForms Function Library]] for the exception type)
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|-
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName|QNameButNotNCName]]
| rowspan="1" colspan="1" |
An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see [[#The XForms Function Library|The XForms Function Library]] for the exception type).
| rowspan="1" colspan="1" |
[[#intro-reading|Required]]
|}

This recommendation defines the values <code>hex</code> and <code>base64</code> for the fourth string parameter that indicates the encoding method. If the parameter is missing, then the default is <code>base64</code>. The <code>hex</code> and <code>base64</code> encoding methods of this function correspond to the encodings defined in <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki> for the datatypes <code>hexBinary</code> and <code>base64Binary</code>, respectively. For the hexadecimal encoding, the digits 'a' through 'f' are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see [[#The XForms Function Library|The XForms Function Library]] for the exception type).

<div class="exampleOuter"><div class="exampleInner">

 hmac('Jefe', 'what do ya want for nothing?', 'SHA-1', 'hex')

</div>

returns <code>effcdf6ae5eb2fa2d27416d5f184df9c259a7c79</code>

<div class="exampleInner">

 hmac('Jefe', 'what do ya want for nothing?', 'MD5', 'hex')

</div>

returns <code>750c783e6ab0b503eaa86e310a5db738</code>

<div class="exampleInner">

 hmac('Jefe', 'what do ya want for nothing?', 'SHA-256', 'hex')

</div>

returns <code>5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843</code>

</div></div></div><div class="div2">

===<span id="expr-lib-date">Date and Time Functions</span>===

<div class="note">

'''Note:'''

The following XML Schema datatypes do not have specific functions for manipulation within XForms expressions: <code>xsd:time</code>, <code>xsd:gYearMonth</code>, <code>xsd:gYear</code>, <code>xsd:gMonthDay</code>, <code>xsd:gDay</code>, <code>xsd:gMonth</code>. Extension functions ([[#Extension Functions|Extension Functions]]) may be used to perform needed operations on these datatypes.

</div><div class="div3">

====<span id="fn-local-date">The local-date() Function</span>====

''string'' '''local-date'''()

This function returns a lexical <code>xsd:date</code> obtained as if by the following rules: the result of <code>now()</code> is converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion of the result of <code>now()</code> is returned.

Example:

<div class="exampleOuter"><div class="exampleInner">

 local-date()

</div>

could return <code>2006-10-13-07:00</code>

<div class="exampleInner">

 substring(local-date(), 1, 10)

</div>

could return <code>2006-10-13</code>

<div class="exampleInner">

 days-to-date(days-from-date(local-date()) + 31)

</div>

returns a date that is 31 days from today. For example, if <code>local-date()</code> returns <code>2006-10-13-07:00</code>, then the result is <code>2006-11-13</code>.

</div></div><div class="div3">

====<span id="fn-local-dateTime">The local-dateTime() Function</span>====

''string'' '''local-dateTime'''()

This function returns a lexical <code>xsd:dateTime</code> obtained as if by the following rules: the result of <code>now()</code> is converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result of <code>now()</code> is returned.

Example:

<div class="exampleOuter"><div class="exampleInner">

 local-dateTime()

</div>

could return <code>2006-10-13T16:04:17-07:00</code>

<div class="exampleInner">

 adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(local-dateTime()) + 7200))

</div>

Adds two hours (7200 seconds) to the local date and time, returning the result in the local time zone. For example, if <code>local-dateTime()</code> returns <code>2007-10-02T14:26:43-07:00</code>, then the above expression returns <code>2007-10-02T16:26:43-07:00</code>

</div></div><div class="div3">

====<span id="fn-now">The now() Function</span>====

''string'' '''now'''()

The <code>now</code> function returns the current UTC date and time as a string value in the canonical XML Schema <code>xsd:dateTime</code> format. If time zone information is available, it is used to convert the date and time to UTC. If no time zone information is available, then the date and time are assumed to be in UTC.

<div class="note">

'''Note:'''

Attaching a calculation of "<code>now()</code>" to an instance data node would not result in a stream of continuous recalculations of the XForms Model.

<div class="exampleOuter"><div class="exampleInner">

 now()

</div>

returns <code>2006-10-14T01:04:17Z</code> if <code>local-dateTime()</code> returns <code>2006-10-13T18:04:17-07:00</code>

<div class="exampleInner">

 seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)

</div>

Computes two hours from now, returning the result in UTC time. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code>, then the above expression returns <code>2007-10-02T23:26:43Z</code>

</div></div></div><div class="div3">

====<span id="fn-days-from-date">The days-from-date() Function</span>====

''number'' '''days-from-date'''(<var>string</var>)

This function returns a whole number of days, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:date</code> or <code>xsd:dateTime</code>, the return value is equal to the number of days difference between the specified date or dateTime (normalized to UTC) and <code>1970-01-01</code>. Hour, minute, and second components are ignored after normalization. Any other input parameter causes a return value of <code>NaN</code>.

<div class="note">

'''Note:'''

If an <code>xsd:date</code> is given as the parameter, the timezone is ignored if provided because there is no way to normalize to the date in the UTC timezone without both the time and timezone.

</div>

Examples:

<div class="exampleOuter"><div class="exampleInner">

 days-from-date("2002-01-01")

</div>

returns <code>11688</code>

<div class="exampleInner">

 days-from-date("2002-01-01-07:00")

</div>

returns <code>11688</code>

<div class="exampleInner">

 days-from-date("1969-12-31")

</div>

returns <code>-1</code>

</div></div><div class="div3">

====<span id="fn-days-to-date">The days-to-date() Function</span>====

''string'' '''days-to-date'''(<var>number</var>)

This function returns a string containing a lexical <code>xsd:date</code> that corresponds to the number of days passed as the parameter according to the following rules:

The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and <code>1970-01-01</code>. An input parameter value of <code>NaN</code> results in output of the empty string.

Examples:

<div class="exampleOuter"><div class="exampleInner">

 days-to-date(11688)

</div>

returns <code>2002-01-01</code>

<div class="exampleInner">

 days-to-date(-1)

</div>

returns <code>1969-12-31</code>

</div></div><div class="div3">

====<span id="fn-seconds-from-dateTime">The seconds-from-dateTime() Function</span>====

''number'' '''seconds-from-dateTime'''(<var>string</var>)

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:dateTime</code>, the return value is equal to the number of seconds difference between the specified dateTime (normalized to UTC) and <code>1970-01-01T00:00:00Z</code>. If no time zone is specified, UTC is used. Any other input string parameter causes a return value of <code>NaN</code>. This function does not support leap seconds.

Example:

<div class="exampleOuter"><div class="exampleInner">

 seconds-from-dateTime('1970-01-01T00:00:00Z')

</div>

returns <code>0</code>

<div class="exampleInner">

 seconds-from-dateTime('1970-01-01T00:00:00-08:00')

</div>

returns <code>28800</code>

</div></div><div class="div3">

====<span id="fn-seconds-to-dateTime">The seconds-to-dateTime() Function</span>====

''string'' '''seconds-to-dateTime'''(<var>number</var>)

This function returns a string containing a lexical <code>xsd:dateTime</code> that corresponds to the number of seconds passed as the parameter according to the following rules:

The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired UTC dateTime and <code>1970-01-01T00:00:00Z</code>. An input parameter value of <code>NaN</code> results in output of the empty string. This function does not support leap seconds.

Examples:

<div class="exampleOuter"><div class="exampleInner">

 seconds-to-dateTime(0)

</div>

returns <code>1970-01-01T00:00:00Z</code>

<div class="exampleInner">

 seconds-from-dateTime(28800)

</div>

returns <code>1970-01-01T08:00:00Z</code>

<div class="exampleInner">

 seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)

</div>

Computes two hours from now, returning the result in UTC time. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code>, then the above expression returns <code>2007-10-02T23:26:43Z</code>

<div class="exampleInner">

 adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))

</div>

Computes two hours from now, returning the result in the local time zone. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code> and the local date and time is <code>2007-10-02T14:26:43-07:00</code>, then the above expression returns <code>2007-10-02T16:26:43-07:00</code>

</div></div><div class="div3">

====<span id="fn-adjust-dateTime-to-timezone">The adjust-dateTime-to-timezone() Function</span>====

''string'' '''adjust-dateTime-to-timezone'''(<var>string</var>)

This function adjusts a legal lexical <code>xsd:dateTime</code> received as the string parameter to the local time zone of the implementation, and returns the result. If the string argument contains no time zone, then the result is the string argument with the local time zone as the time zone component. If the implementation does not have access to time zone information, UTC is used. The result is empty string if the string argument is the empty sequence or not a legal lexical <code>xsd:dateTime</code>.

Examples:

<div class="exampleOuter"><div class="exampleInner">

 adjust-dateTime-to-timezone('2007-10-07T02:22:00')

</div>

returns <code>2007-10-07T02:22:00-07:00</code> in the Pacific time zone since daylight savings time applies.

<div class="exampleInner">

 adjust-dateTime-to-timezone('2007-10-02T21:26:43Z')

</div>

returns <code>2007-10-02T14:26:43-07:00</code> in the Pacific time zone since daylight savings time applies.

<div class="exampleInner">

 adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))

</div>

Computes two hours from now, returning the result in the local time zone. For example, if <code>now()</code> returns <code>2007-10-02T21:26:43Z</code> and the local date and time is <code>2007-10-02T14:26:43-07:00</code>, then the above expression returns <code>2007-10-02T16:26:43-07:00</code>

</div></div><div class="div3">

====<span id="fn-seconds">The seconds() Function</span>====

''number'' '''seconds'''(<var>string</var>)

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:duration</code>, the return value is equal to the number specified in the seconds component plus 60 * the number specified in the minutes component, plus 60 * 60 * the number specified in the hours component, plus 60 * 60 * 24 * the number specified in the days component. The sign of the result will match the sign of the duration. Year and month components, if present, are ignored. Any other input parameter causes a return value of <code>NaN</code>.

<div class="note">

'''Note:'''

Even though this function is defined based on a lexical <code>xsd:duration</code>, it is intended for use only with derived-from-<code>xsd:duration</code> datatypes, specifically <code>xforms:dayTimeDuration</code>.

</div>

Examples:

<div class="exampleOuter"><div class="exampleInner">

 seconds("P3DT10H30M1.5S")

</div>

returns <code>297001.5</code> (3 days, 10 hours, 30 minutes, and 1.5 seconds)

<div class="exampleInner">

 seconds("P1Y2M")

</div>

returns <code>0</code> because the year and month parts of the duration are ignored and the remaining portions are unspecified and default to 0

<div class="exampleInner">

 seconds("3")

</div>

returns <code>NaN</code> because the parameter is not a lexically valid duration

</div></div><div class="div3">

====<span id="fn-months">The months() Function</span>====

''number'' '''months'''(<var>string</var>)

This function returns a whole number of months, according to the following rules:

If the string parameter represents a legal lexical <code>xsd:duration</code>, the return value is equal to the number specified in the months component plus 12 * the number specified in the years component. The sign of the result will match the sign of the duration. Day, hour, minute, and second components, if present, are ignored. Any other input parameter causes a return value of <code>NaN</code>.

<div class="note">

'''Note:'''

Even though this function is defined based on a lexical <code>xsd:duration</code>, it is intended for use only with derived-from-<code>xsd:duration</code> datatypes, specifically <code>xforms:yearMonthDuration</code>.

</div>

Examples:

Examples:

<div class="exampleOuter"><div class="exampleInner">

 months("P1Y2M")

</div>

returns <code>14</code> (1 year and 2 months)

<div class="exampleInner">

 months("-P19M")

</div>

returns <code>-19</code> because the duration is negative and expresses 0 years and 19 months

</div></div></div><div class="div2">

===<span id="expr-lib-nodeset">Node-set Functions</span>===

<div class="div3">

====<span id="fn-instance">The instance() Function</span>====

''node-set'' '''instance'''(<var>string</var>?)

An XForms Model can contain more than one instance. This function allows access to instance data, within the same XForms Model, but outside the instance data containing the context node.

If the argument is omitted or is equal to the empty string, then the root element node (also called the document element node) is returned for the default instance in the model that contains the current context node.

Otherwise, the argument is converted to a string as if by a call to the <code>string</code> function. This string is treated as an IDREF, which is matched against <code>instance</code> elements in the containing document. If a match is located, and the matching instance data is associated with the same XForms Model as the current context node, this function returns a node-set containing just the root element node (also called the document element node) of the referenced instance data. In all other cases, an empty node-set is returned.

Example:

For instance data corresponding to this XML:

<div class="exampleOuter"><div class="exampleInner">

 <xforms:instance xmlns="" id="orderform">
   <orderForm>
     <shipTo>
       <firstName>John</firstName>
     </shipTo>
   </orderForm>
 </xforms:instance>

</div></div>

The following expression selects the <code>firstName</code> node. Note that the <code>instance</code> function returns an element node, effectively replacing the leftmost location step from the path:

<div class="exampleOuter"><div class="exampleInner">

 ref="instance('orderform')/shipTo/firstName"

</div></div></div><div class="div3">

====<span id="fn-current">The current() Function</span>====

''node-set'' '''current'''()

Returns the <nowiki>[</nowiki>[[#ref-xpath-1.0|context node]]] used to initialize the evaluation of the containing XPath expression.

Examples:

<div class="exampleOuter">

For the following instance data:

<div class="exampleInner">

 <xforms:instance xmlns="">
    <converter>
       <amount>100</amount>
       <currency>jpy</currency>
       <convertedAmount></convertedAmount>
    </converter>
 </xforms:instance>
 
 <xforms:instance xmlns="" id="convTable">
    <convTable date="20040212" currency="cdn">
       <rate currency="eur">0.59376</rate>
       <rate currency="mxn">8.37597</rate>
       <rate currency="jpy">80.23451</rate>
       <rate currency="usd">0.76138</rate>
    </convTable>
 </xforms:instance>

</div>

and the following value calculation bind:

<div class="exampleInner">

 <bind nodeset="convertedAmount"
       calculate="../amount *
                  instance('convTable')/rate|@currency=current()/../currency]"/>

</div>

the content value of <code>/converter/convertedAmount</code> is the product of <code>/converter/amount</code> and the conversion table rate given by the <code>rate</code> element whose <code>currency</code> attribute value matches the content of <code>/converter/currency</code>.

</div><div class="exampleOuter">

For the following instance data:

<div class="exampleInner">

 <xforms:instance xmlns="" id="i1">
    <months>
       <mon>01</mon>
       <mon>02</mon>
       <mon>03</mon>
    </months>
 </xforms:instance>
 <xforms:instance xmlns="" id="i2">
    <months>
       <month code="01">Jan</month>
       <month code="02">Feb</month>
       <month code="03">Mar</month>
    </months>
 </xforms:instance>

</div>

and the following repeat structure:

<div class="exampleInner">

 <repeat nodeset="mon">
    <output value="instance('i2')/month[@code = current()]/>
 </repeat>
 

</div>

the output should contain <code>Jan Feb Mar</code>.

</div></div><div class="div3">

====<span id="fn-id">The id() Function</span>====

''node-set'' '''id'''(<var>object</var>, <var>node-set</var>?)

The <code>object</code> parameter provides one or more IDREFs. This may be in the form of a string containing a space-separated list of IDREFs or a node-set, each node of which contains an IDREF. The <code>node-set</code> parameter provides nodes in one or more instance data documents to be searched. If the node-set parameter is not given or is empty, then the instance data document to be searched is the one containing the context node of the function call. For each node in the node-set parameter (or its default), the set of element nodes are collected with IDs that match the IDREFs from the <code>object</code> parameter. The result of this function is a node-set containing the union of the collected element nodes from each string. An element node can be assigned an ID by means of an <code>xml:id</code> attribute or an attribute that is assigned the type ID by a DTD or xsd:ID or any type derived from xsd:ID by an XML schema, or the <code>type</code> model item property.

Example:

<div class="exampleOuter"><div class="exampleInner">

 id('X Y', instance('Z'))

</div>

Returns nodes identified by X or Y from the instance data document associated with the root element of the <code>instance</code> identified by Z.

</div></div><div class="div3">

====<span id="fn-context">The context() Function</span>====

''node-set'' '''context'''()

This function returns the in-scope evaluation context node of the nearest ancestor element of the node containing the XPath expression that invokes this function. The nearest ancestor element may have been created dynamically as part of the run-time expansion of repeated content as described in Section [[#Resolving ID References in XForms|Resolving ID References in XForms]]<nowiki>]</nowiki>.

Example:

<div class="exampleOuter"><div class="exampleInner">

 <setvalue ref="x" value="context()/y"/>

</div>

This action sets node <code>x</code> to the value of node <code>y</code>, where both nodes are children of the in-scope evaluation context node for the <code>setvalue</code> element.

</div><div class="note">

'''Note:'''

An intended use of this function is in conjunction with the <code>repeat</code> element (Section [[#The repeat Element|The repeat Element]] and the <code>setvalue</code> action element (Section [[#The setvalue Element|The setvalue Element]]). The intent is to provide form authors with a means of expressing a <code>value</code> attribute that is relative to the repeat context node when the Single Node Binding result is not.

</div></div></div><div class="div2">

===<span id="expr-lib-object">Object Functions</span>===

<div class="div3">

====<span id="fn-choose">The choose() Function</span>====

''object'' '''choose'''(<var>boolean</var>, <var>object</var>, <var>object</var>)

This function provides a conditional test that chooses an object to return based on the boolean parameter. If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. Each of the object parameters can be of any XPath datatype as described in Section [[#XPath Datatypes|XPath Datatypes]], and this function does no type conversion of the parameter it chooses to return.

<div class="note">

'''Note:'''

All parameters of an XPath function are evaluated, so the parameter that is not returned by this function is still evaluated, and its result is discarded by this function.

</div><div class="note">

'''Note:'''

Form authors and design tools are encouraged to use this function instead of the function <code>if()</code> described in Section [[#The if() Function|The if() Function]], which has been deprecated. Because this function returns an object instead of a string, migrating from <code>if()</code> to <code>choose()</code> may occasionally require conversion of the return result using the <code>string()</code> function.

</div>

Example:

<div class="exampleOuter"><div class="exampleInner">

 choose(count(x) > 0, x, y)

</div>

Returns the node-set of matching <code>x</code> if it is non-empty and the node-set matching <code>y</code> otherwise.

<div class="exampleInner">

 choose(@x, @x, 0)

</div>

If the context node of the function contains attribute <code>x</code>, then the nodeset containing that attribute is returned. Otherwise, the number <code>0</code> is returned.

</div></div><div class="div3">

====<span id="fn-event">The event() Function</span>====

''object'' '''event'''(<var>string</var>)

Function <code>event</code> returns context specific information determined by the ''string'' argument. The returned context information is an XPath object whose type and content depends upon the requested property. Each event describes what properties can be accessed by this function and the type and value that will be returned as the result.

The event context properties available for each event are provided in the sections that describe the events.

This function is intended for use in the XPath expressions of XForms actions. If invoked for any other XPath expression, such as a binding expression or model item property expression, this function returns the empty string. If this function is invoked from an XPath expression for an XForms action, then event context information is used from the most recently dispatched event whose action handler contains the XForms action.

Some properties defined for an event may be unavailable if certain prerequisite conditions were not met prior to the event being dispatched. Implementations may also add custom properties. If the event context information does not contain the property indicated by the ''string'' argument, then an empty node-set is returned.

Examples:

<div class="exampleOuter"><div class="exampleInner">

 event('inserted-nodes')

</div>

If called from an <code>xforms-insert</code> event handler, a nodeset is returned containing the instance data node or nodes inserted.

</div></div></div><div class="div2">

===<span id="expr-lib-extension">Extension Functions</span>===

XForms documents may use additional XPath extension functions beyond those described here. A number of useful community extensions are defined at <nowiki>[</nowiki>[[#ref-exslt |EXSLT]]<nowiki>]</nowiki>. The names of any such extension functions must be declared in attribute <code>functions</code> on element <code>model</code>. Such declarations are used by the XForms Processor to check against available extension functions. XForms Processors perform this check at the time the document is loaded, and halt processing by signaling an exception ([[#The xforms-compute-exception Event|The xforms-compute-exception Event]]) if the XForms document declares an extension function for which the processor does not have an implementation.

<div class="note">

'''Note:'''

Explicitly declaring extension functions enables XForms Processors to detect the use of unimplemented extension functions at document load-time, rather than throwing a fatal exception ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]] or [[#The xforms-compute-exception Event|The xforms-compute-exception Event]]) during user interaction. Failure by authors to declare extension functions will result in an XForms Processor potentially halting processing during user interaction with a fatal error.

</div></div></div><div class="div1">

==<span id="controls">Core Form Controls</span>==

This chapter covers the XForms view layer features for directly interacting with instance data and properties from the XForms Model. This includes features that provide data from the model to the view layer as well as features of the view layer that commit data collected from the user to the model.

<div class="div2">

===<span id="N74868">The XForms Core Form Controls Module</span>===

[[#def-form-control|Form control]]s are declared using markup elements, and their behavior refined via markup attributes. The core form controls are described in this module, including their attributes and their content models (their metadata elements). A '''core form control''' is an element that acts as a direct point of user interaction and often provides read, write, or read/write access to a node of instance data. See Section [[#Container Form Controls|Container Form Controls]] for a description of container form controls.

{| summary="listing of XForms Core Form Control elements, their attributes and content models (their metadata elements)" border="1"
! rowspan="1" colspan="1" | Core Form Control Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-input|input]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], inputmode (xsd:string), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-secret|secret]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], inputmode (xsd:string), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-textarea|textarea]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], inputmode (xsd:string), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-output|output]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional), appearance ("full"|"compact"|"minimal"|[[#def-QNameButNotNCName|QNameButNotNCName]]), value (XPath Expression), mediatype (xsd:string)
| rowspan="1" colspan="1" |
label?, [[#ui-output-mediatype|mediatype]]?, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-upload|upload]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], mediatype (xsd:string), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, [[#ui-upload-filename|filename]]?, [[#ui-upload-mediatype|mediatype]]?, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-range|range]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], start (xsd:string), end (xsd:string), step (xsd:string), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-trigger|trigger]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" |
label, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-submit|submit]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional), submission (xsd:IDREF)
| rowspan="1" colspan="1" |
label, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-selectMany|select]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], selection ("open" | "closed"), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, ([[#elems-list-ui-common|List UI Common]])+, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-selectOne|select1]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]], selection ("open" | "closed"), incremental (xsd:boolean)
| rowspan="1" colspan="1" |
label, ([[#elems-list-ui-common|List UI Common]])+, ([[#elems-ui-common|UI Common]])*
|}

<div class="note">

'''Note:'''

Unless bound to form controls, instance data nodes are not presented to the user; consequently, there is no need for a form control corresponding to HTML <code>input type="hidden"</code>.

</div>

The following table summarizes additional support elements for form controls.

{| summary="listing of support elements for form controls, their attributes and their content models" border="1"
! rowspan="1" colspan="1" | Support Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-commonelems-label|label]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" |
(PCDATA|([[#elems-inline|UI Content]]))*
|-
| rowspan="1" colspan="1" |
[[#ui-commonelems-help|help]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" |
(PCDATA|([[#elems-inline|UI Content]]))*
|-
| rowspan="1" colspan="1" |
[[#ui-commonelems-hint|hint]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" |
(PCDATA|([[#elems-inline|UI Content]]))*
|-
| rowspan="1" colspan="1" |
[[#ui-commonelems-alert|alert]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" |
(PCDATA|([[#elems-inline|UI Content]]))*
|-
| rowspan="1" colspan="1" |
[[#ui-upload-filename|filename]] (for [[#ui-upload|upload]])
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#ui-upload-mediatype|mediatype]] (for [[#ui-upload|upload]])
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#ui-output-mediatype|mediatype]] (for [[#ui-output|output]])
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]], value (string XPath Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-choices|choices (for selection controls)]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]]
| rowspan="1" colspan="1" |
label?, ([[#elems-list-ui-common|List UI Common]])+
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-item|item]] (for selection controls)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]]
| rowspan="1" colspan="1" |
label, value, ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-value|value (for selection controls)]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" | PCDATA
|}

See also: [[#The itemset Element|The itemset Element]] (for selection controls) and [[#The copy Element|The copy Element]] (for selection controls).

The following attributes are common to many user-interface related XForms elements, here called the <code>UI Common</code> attribute group.

{| id="attrs-ui-common" summary="listing of XForms Common UI attributes" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
|-
| rowspan="1" colspan="1" | (various)
| rowspan="1" colspan="1" |
appearance ("full"|"compact"|"minimal" | [[#def-QNameButNotNCName|QNameButNotNCName]])
|}

; appearance
: Author-optional attribute to define an appearance hint. If absent, the user agent may freely choose any suitable rendering.

<div class="note">

'''Note:'''

A host language is expected to add attributes such as <code>xml:lang</code> as well as an attribute, named <code>class</code>, that holds a list of strings that can be matched by CSS class selectors.

Further, a host language must provide a way to indicate overall navigation order among form controls and other elements included in the host language, as well as keyboard or direct access navigation to specific elements. One such proposal is to uses a pair of attributes named <code>navindex</code> and <code>accesskey</code>, defined as follows:

; navindex
: This author-optional attribute is a non-negative integer in the range of 0-32767 used to define the navigation sequence. This gives the author control over the sequence in which [[#def-form-control|form control]]s are traversed. The default navigation order is specified in the chapter [[#Processing Model|Processing Model]].
; accesskey
: This author-optional attribute defines a shortcut for moving the input focus directly to a particular [[#def-form-control|form control]]. The value of this is a single character which when pressed together with a platform specific modifier key (e.g., the ''alt'' key) results in the focus being set to this [[#def-form-control|form control]].The user agent must provide a means of identifying the accesskeys that can be used in a presentation. This may be accomplished in different ways by different implementations, for example through direct interaction with the application or via the user's guide. The accesskey requested by the author might not be made available by the player (for example it may not exist on the device used, or it may be used by the player itself). Therefore the user agent should make the specified key available, but may map the accesskey to a different interaction behavior.

</div>

Additionally, this module defines the following content sets:

{| summary="listing of XForms Core elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Content Set
! rowspan="1" colspan="1" | Minimal Content Model
|-
| id="elems-ui-common" rowspan="1" colspan="1" | '''UI Common'''
| rowspan="1" colspan="1" |
(help|hint|alert|[[#action-content-set|Action]])*
|-
| id="elems-list-ui-common" rowspan="1" colspan="1" | '''List UI Common'''
| rowspan="1" colspan="1" | (choices|item|itemset)+
|-
| id="elems-form-controls" rowspan="1" colspan="1" | '''Core Form Controls'''
| rowspan="1" colspan="1" | (input|secret|textarea|output|upload|range|trigger|submit|select|select1)*
|-
| id="elems-inline" rowspan="1" colspan="1" | '''UI Content'''
| rowspan="1" colspan="1" | (output)*
|}

As shown above, the XML Events module adds the Actions content set into the UI Common content set. A host language may add markup to the [[#elems-inline|UI Content]] set. When the XForms Extension module is present, it too should be included in the UI Common content set.

<div class="div3">

====<span id="ui-processing">Implementation Requirements Common to All Form Controls</span>====

XForms user interface controls are bound to the underlying instance data using [[#def-binding|binding]] attributes as defined in the chapter [[#Model Item Properties|Model Item Properties]].

Form controls enable accessibility by taking a uniform approach to such features as labels, help text, navigation, and keyboard shortcuts. Internationalization issues are addressed by following the same design principles as in XHTML. All form controls are suitable for styling as aural or visual media.

Form controls encapsulate high-level semantics without sacrificing the ability to deliver real implementations. For instance, the form control <code>select</code> enables the user to ''select items from a set''. These form controls distinguish the functional aspects of the underlying control from the presentational and behavioral aspects. This separation enables the expression of the intent underlying a particular form control—see <nowiki>[</nowiki>[[#ref-AUI97 |AUI97]]<nowiki>]</nowiki> for a definition of such high-level user interaction primitives.

Form controls when rendered display the underlying data values to which they are bound. While the data presented to the user through a form control must directly correspond to the bound instance data, the display representation is not required to match the lexical space value of the bound instance data. For example, user agents should apply appropriate conventions to the display of dates, times, durations and numeric values including separator characters.

All form controls must meet the following implementation requirements:

* All form controls, including [[#Container Form Controls|container form controls]], should have an inline layout by default (e.g. for a host language that supports [[#ref-css2|CSS]], the default styling should be <code>display:inline</code>). By default, [[#def-repeat-item|repeat items]] should have a block layout (e.g. a default styling of <code>display:block</code> for host languages that support CSS).
* If a form control violates its data binding restriction, an <code>xforms-binding-exception</code> must occur.<div class="note">'''Note:'''Form controls that read or write simpleContent produce this exception whenever and as soon as they are bound to an element node that has an element child node.</div>
* Form controls that write simpleContent to instance data must do so exactly as defined by the XForms Action <code>setvalue</code> ([[#The setvalue Element|The setvalue Element]]).<div class="note">'''Note:'''If a form control binds to an element node, then regardless of how many child nodes the element has, the result of the form control writing to the bound element node is that it has either a single non-empty text node child, or no children if the simpleContent written is the empty string (which is in accord with the data model of <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki>).</div>
* All form controls that read simpleContent instance data must do so as follows:
** Element nodes: If element child nodes are present, then an <code>xforms-binding-exception</code> occurs. Otherwise, return the string value of the node.
** Attribute nodes: returns the string-value of the node.
** Text nodes: returns the string-value of the node.
** Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
** the XPath root node: an <code>xforms-binding-exception</code> occurs.
* Form controls are considered to be <span id="form-control-non-relevance-conditions">'''relevant'''</span> if none of the following apply and '''non-relevant''' if any of the following apply:
** the Single Node Binding is expressed and resolves to empty nodeset,
** the Single Node Binding is expressed and resolves to a non-relevant instance node,
** the form control is contained by a non-relevant <code>switch</code> or <code>group</code> (which includes a non-relevant <code>repeat</code> item), or
** the form control is contained by a non-selected <code>case</code> element of a <code>switch</code>.<p>When a form control becomes non-relevant, it must receive event <code>xforms-disabled</code> and then the XForms action handlers that are listening for events on the non-relevant form control must be disabled.</p><p>When a non-relevant form control changes to being relevant, the XForms action handlers that listen for events on the form control must become enabled and then the form control must be updated to represent the current value(s) and model item properties of the instance node(s) to which it is bound or to which it refers. The following events must be dispatched to the form control: <code>xforms-enabled</code>, <code>xforms-value-changed</code>, one of <code>xforms-valid</code> or <code>xforms-invalid</code>, one of <code>xforms-readonly</code> or <code>xforms-readwrite</code>, one of <code>xforms-required</code> or <code>xforms-optional</code>, and one of <code>xforms-in-range</code> or <code>xforms-out-of-range</code>.</p>
* Except as noted, relevant form controls must distinguish rendering between being bound to a required node versus a non-required node. Exceptions are form controls that do not directly render the string value of the bound node (including <code>trigger</code> and the [[#Container Form Controls|container form controls]]). Control of this behavior should be made available to stylesheets.
* Relevant form controls must distinguish rendering between valid and invalid states. Control of this behavior should be made available to stylesheets.
* Relevant form controls must indicate when the bound instance data contains a value or content that the form control is not capable of rendering. Control of this behavior should be made available to stylesheets.
* If a form control binds to a readonly node, then the form control must not allow the user to modify the node value. The relevant form control that is bound to a readonly node should render in a way which indicates that entering or changing the value is not allowed. Control of the render behavior should be made available to stylesheets.

Sections in this chapter define the various form controls by specifying the following:

<blockquote>

Description<br />Common Attributes<br />Special Attributes<br />Examples<br />Data Binding Restrictions<br />Implementation Requirements

</blockquote></div><div class="div3">

====<span id="ui-input">The input Element</span>====

Description: This form control enables free-form data entry or a user interface component appropriate to the datatype of the bound node..

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; inputmode
: Author-optional. This form control accepts an input mode hint. [[#Input Modes (Non-Normative)|Input Modes]].
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default value for this attribute is <code>false</code>.

Data Binding Restrictions: Binds to any simpleContent (except <code>xsd:base64Binary</code>, <code>xsd:hexBinary</code> or any datatype derived from these).

<div class="note">

'''Note:'''

This control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: Must allow entry of a lexical value for the bound datatype. Implementations should provide a convenient means for entry of datatypes and take into account localization and internationalization issues such as representation of numbers. For example, an <code>input</code> bound to an instance data node of type <code>xsd:date</code> might provide a calendar control to enter dates; similarly, an input control bound to of type <code>boolean</code> might be rendered as a checkbox.

Examples:

<div class="exampleOuter"><div class="exampleHead">Simple Free-Form Data Entry</div><div class="exampleInner">

 <input ref="order/shipTo/street" class="streetAddress">
   <label>Street</label>
   <hint>Please enter the number and street name</hint>
 </input>

</div>

In the above, the <code>class</code> attribute can be used by a style sheet to specify the display size of the form control. Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from these display properties.

A graphical browser might render the above example as follows:

[[Image:ui-input.png|An average-looking text entry form control. The label, 'Street' has been aligned to the left]]

</div><div class="exampleOuter"><div class="exampleHead">Datatype-sensitive Data Entry</div><div class="exampleInner">

 <input ref="order/shipDate">
   <label>Ship By</label>
   <hint>Please specify the ship date for this order.</hint>
 </input>

</div>

A graphical browser might render the above example as follows:

[[Image:calendar-picker-closed.png|A text box for a date control, with a button to open into a calendar.]]

The user can type a date into the text edit box, or press the button to open a calendar:

[[Image:calendar-picker-open.png|A calendar picker graphical widget.]]

</div><div class="exampleOuter"><div class="exampleHead">Data Entry with Activation Behavior</div><div class="exampleInner">

 <input ref="/search/expr">
   <label>Search term(s):</label>
   <send ev:event="DOMActivate" submission="doSearch" />
 </input>
 
 <submit submission="doSearch">
   <label>Search</label>
 </submit>

</div>

This example shows the <code>input</code> and <code>submit</code> form controls working together to provide the common user experience of a simple search. The <code>input</code> collects the search term(s) and then automatically initiates the <code>submission</code> identified by <code>doSearch</code> if the user activates the <code>input</code> control. Alternatively, the user initiate the <code>doSearch</code> <code>submission</code> by activating the <code>submit</code> control.

</div><div class="note">

'''Note:'''

A graphical browser on a desktop device might activate form controls such as <code>input</code> in response to a special user action such as pressing the Enter key or either clicking or double-clicking with the mouse (depending on the type of form control).

</div></div><div class="div3">

====<span id="ui-secret">The secret Element</span>====

Description: This form control is used to provide the user with the ability to supply information to the system in a manner that makes it difficult for someone, other than the user, who may be observing the process to discern the value that is being supplied. A common use is for password entry.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; inputmode
: Author-optional. This form control accepts an input mode hint. [[#Input Modes (Non-Normative)|Input Modes]].
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default value for this attribute is <code>false</code>.

Data Binding Restrictions: Binds to any simpleContent (except <code>xsd:base64Binary</code>, <code>xsd:hexBinary</code> or any datatype derived from these).

<div class="note">

'''Note:'''

This control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: Implementations, including accessibility aids, must obscure the value being entered into this form control. One possible approach would be to render a "*" or similar character instead of the actual characters entered. Note that this provides only a casual level of security; truly sensitive information will require additional security measures outside the scope of XForms.

Example:

<div class="exampleOuter"><div class="exampleHead">Password Entry</div><div class="exampleInner">

 <secret ref="/login/password">
   <label>Password</label>
   <hint>The password you enter will not be displayed.</hint>
 </secret>

</div>

A graphical browser might render this form control as follows:

[[Image:ui-secret-with-hint.png|A password entry form control, with '*' characters where the text would be expected and a hint box displaying hint text.]]

</div></div><div class="div3">

====<span id="ui-textarea">The textarea Element</span>====

Description: This form control enables free-form data entry and is intended for use in entering multiline content, e.g., the body of an email message.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; inputmode
: Author-optional. This form control accepts an input mode hint. [[#Input Modes (Non-Normative)|Input Modes]].
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default value for this attribute is <code>false</code>.

Data Binding Restrictions: Binds to any simpleContent (except <code>xsd:base64Binary</code>, <code>xsd:hexBinary</code> or any datatype derived from these).

<div class="note">

'''Note:'''

This control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: Must allow entry of a lexical value for the bound datatype, including multiple lines of text.

Example:

<div class="exampleOuter"><div class="exampleHead">Email Message Body</div><div class="exampleInner">

 <textarea ref="message/body" class="messageBody">
   <label>Message Body</label>
   <hint>Enter the text of your message here</hint>
 </textarea>

</div>

In the above, the <code>class</code> attribute can be used by a style sheet to specify the display size of the form control. Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from these display properties.

A graphical browser might render the above example as follows:

[[Image:ui-textarea.png|A larger-than-average text entry form control. The title, 'Message Body:' provides an additional hint that large amounts of text are allowed here.]]

</div></div><div class="div3">

====<span id="ui-output">The output Element</span>====

Description: This form control renders content based in part on instance data, but it provides no means for entering or changing data.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes:

; appearance
: This form control does not use the UI Common attribute group, but nevertheless still contains an author-optional <code>appearance</code> attribute, as defined above.
; value
: Author-optional. An XPath expression to be evaluated. The string result of the evaluation is rendered by the form control. If binding attributes are present to select a node, this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the single node binding. This XPath expression is re-evaluated whenever there is a change in any node to which the expression refers. An empty string is used if the XPath evaluation fails.
; <span id="ui-output-mediatype-attr">mediatype</span>
: Author-optional attribute used to indicate that data obtained from the Single-Node Binding should be rendered (after decoding, if needed) according to a desired media type indicated by the attribute value string, such as <code>image/*</code> for image rendition. If the [[#ui-output-mediatype|mediatype]] element appears as a child of the <code>output</code>, then it overrides this attribute. If the media type is not specified by this attribute or by the <code>mediatype</code> element, then the the default is to present the indicated data as plain text (with no decoding according to datatype).

Data Binding Restrictions: Binds to any simpleContent.

<div class="note">

'''Note:'''

This control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: Must allow display of a value for the bound datatype. Implementations should provide a convenient means for display of datatypes and take into account localization and internationalization issues such as representation of numbers and dates.

Element <code>output</code> can be used to display the value of a particular instance node by using a Single-Node Binding; it can also be used to display the result of evaluating an XPath expression by specifying the XPath expression to be evaluated via attribute <code>value</code>. Note that the Single-Node Binding attributes and <code>value</code> on element <code>output</code> are mutually exclusive.

By default, the <code>output</code> element simply renders the plain text of the <code>value</code> attribute or the node indicated by the Single-Node Binding. However, if the Single-Node Binding indicates a non-empty data node, and the media type is specified based on the [[#ui-output-mediatype-attr|mediatype attribute]] or [[#ui-output-mediatype|mediatype child element]], then the content of the data node [[#intro-reading|must]] be decoded or dereferenced according to its datatype, and the result [[#intro-reading|should]] be rendered according to the indicated media type if it is possible to do so (e.g. a voice-only device cannot render a digital image).

<div class="note">

'''Note:'''

When the media type is specified, implementations [[#intro-reading|may]] handle the output content as presentation-only or as interactive content, and interactive content [[#intro-reading|may]] be isolated from or capable of accessing the enclosing document that contains the <code>output</code>. Further implementation experience and user feedback is required. For example, if the output content includes XForms user interface elements, it may be desirable for them to access a default XForms model in the output content or from the enclosing document.

</div>

If the Single Node Binding is absent or if it does not indicate a non-empty instance node, then the media type specification is ignored if given. Otherwise, if the Single Node Binding produces a non-empty node, and the media type is specified, then decoding or dereferencing of the instance node prior to rendition is performed by datatype as follows:

* If the instance node either is of type or is derived from type <code>xsd:base64Binary</code>, then the data is base-64 decoded.
* If the instance node either is of type or is derived from type <code>xsd:hexBinary</code>, then the data is hex-binary decoded.
* If the instance node either is of type or is derived from type <code>xsd:anyURI</code>, then the data is treated as a URI and dereferenced.
* If the instance node is of any other type, then the data is used without modification.

If the <code>output</code> rendition is based on the <code>value</code> attribute, then the rendition is updated if the nodes referenced by the <code>value</code> expression change or if the content of any of the referenced nodes changes. Otherwise, the rendition of an <code>output</code> is updated if the node referenced by the Single-Node Binding changes, if the content of the referenced node changes, or if the media type changes. The media type can change by a change to the <code>mediatype</code> element's referenced node or its content (a host language may also allow DOM mutation of the content of the <code>mediatype</code> attribute or element). A change to the label associated with the <code>output</code> causes an update to the rendition of the label (which may affect the layout position of the main output content).

Failure to render the content indicated by the <code>output</code> element [[#intro-reading|should]] result in an [[#evt-output-error|xforms-output-error]], a non-fatal error that does not halt XForms processing. Failures can occur on initial creation of the <code>output</code> or during user interface refresh (see Section [[#The xforms-refresh Event|The xforms-refresh Event]]). Failures can occur for many reasons, including

* Data to be decoded does not conform to the format of <code>xsd:base64Binary</code> or <code>xsd:hexBinary</code>
* An error dereferencing the URI in a node of or derived from type <code>xsd:anyURI</code>
* A data format error (e.g. invalid or unsupported image format)
* An unrecognized media type identifier string

The content model for the <code>output</code> element includes [[#elems-ui-common|UI Common]] in order to allow action handlers for the [[#evt-output-error|xforms-output-error]] as well as to allow more comprehensive behavior and information to be provided for the <code>output</code>, e.g. via the <code>hint</code> element.

Examples:

<div class="exampleOuter"><div class="exampleHead">Explanatory Message</div><div class="exampleInner">

 I charged you -
 <output ref="order/totalPrice"/>
 - and here is why:

</div>

A graphical browser might render an output form control as follows:

[[Image:ui-output.png|Average-looking text, reading 'I charged you 100.0 - and here is why:']]

</div><div class="exampleOuter"><div class="exampleHead">Displaying an image uploaded to instance data</div><div class="exampleInner">

 <xforms:model>
 	<xforms:instance xmlns="">
 		<data></data>
 	</xforms:instance>
 	<xforms:bind nodeset="/data" type="xsd:base64Binary"/>
 </xforms:model>

</div>

Given the <code>model</code> above, the following controls can upload an image to instance data and display it:

<div class="exampleInner">

 <xforms:upload ref="/data" mediatype="image/*">
 	<xforms:label>Press me to attach a picture</xforms:label>
 </xforms:upload>
 
 <xforms:output ref="/data" mediatype="image/*">
    <xforms:hint>This is the image you attached to the form.</xforms:hint>
    <xforms:message ev:event="xforms-output-error">Error attaching image data.</xforms:message>
 </xforms:output>

</div></div><div class="exampleOuter"><div class="exampleHead">Output of node bound to xsd:date</div><div class="exampleInner">

 <bind nodeset="birthdate"
 type="xsd:date" />
 ...
 <output ref="birthdate">
    <label>Lexical: </label>
 </output>
 <output ref="birthdate" appearance="full">
    <label>Full: </label>
 </output>
 <output ref="birthdate" appearance="minimal">
    <label>Minimal: </label>
 </output>

</div></div>

A graphical browser may take into account the <code>appearance</code> and the localization information from the host language and present the above output form controls as follows:

Lexical: 1998-01-19 Full: 19 janvier 1998 Minimal: 19/01/1998

<div class="div4">

=====<span id="ui-output-mediatype">The mediatype Element (for output)</span>=====

Binding attributes on author-optional element <code>mediatype</code> specify the location in the instance of the string that indicates the desired media type rendition for the parent <code>output</code>. If the binding attributes are not used, the <code>value</code> attribute must be used instead to specify the desired media type rendition.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; value
: An XPath expression to be evaluated. The string result of the evaluation is used to specify the desired media type for output rendition. If a single node binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the single node binding. An empty string is used if the XPath evaluation fails.

</div></div><div class="div3">

====<span id="ui-upload">The upload Element</span>====

Description: This form control enables the common feature found on Web sites to upload a file from the local file system, as well as accepting input from various devices including microphones, pens, and digital cameras.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; mediatype
: Author-optional. Space-separated list of suggested media types, used by the XForms Processor to determine the possible sources of data to upload.
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default for this form control is <code>false</code>.

Data Binding Restrictions: This form control can only be bound to datatypes <code>xsd:anyURI</code>, <code>xsd:base64Binary</code> or <code>xsd:hexBinary</code>, or types derived by restriction from these.

<div class="note">

'''Note:'''

This control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: For base64Binary or hexBinary data binding:

* When bound to an instance data node of type <code>xsd:base64binary</code>, <code>xsd:hexBinary</code>, or a type derived by restriction thereof, on activation <code>upload</code> places the binary content in the content of the node with the indicated encoding.

Implementation Requirements: For anyURI data binding:

* When bound to an instance data node of type <code>xsd:anyURI</code> (or a type derived by restriction thereof), on activation <code>upload</code> places a URI in the content of the node.<br/><br/>For security reasons, the XForms Processor must not dereference the URI bound to this form control without explicit user permission.<div class="note">'''Note:'''Implementors note that <code>upload</code> must associate the binary content, mediatype, and filename with that URI for [[#Serialization as multipart/related|Serialization as multipart/related]] and [[#Serialization as multipart/form-data|Serialization as multipart/form-data]] serialization.</div>

* Implementations with a file system should support ''file upload''—selecting a specific file. The types of files presented by default should reflect the mediatype specified by attribute <code>mediatype</code>, for example defaulting to only audio file types in the file dialog when the mediatype is "audio/*".

Implementation Requirements: For all data bindings:

* Implementations with specific pen/digitizer hardware should (and implementations with other pointing devices may) support ''scribble''—allowing in-place creation of pen-based data.
* Implementations with specific audio recording capabilities should support ''record audio''—in-place recording of an audio clip.
* Implementations with a digital camera, scanner interface or screen capture should support ''acquire image''—in-place upload of images from an attached device.
* Implementations with video recording capability should provide a ''record video'' option.
* Implementations with 3d capabilities should provide a 3d interface option.
* Implementations may provide proprietary implementations (for example, a mediatype of <code>text/rtf</code> could invoke an edit window with a proprietary word processing application)
* Implementations are encouraged to support other input devices not mentioned here.
* Implementations which cannot support upload for the given mediatype must make this apparent to the user.

See the child elements <code>filename</code> ([[#The filename Element|The filename Element]]) and <code>mediatype</code> ([[#The mediatype Element (for upload)|The mediatype Element (for upload)]]).

Example:

<div class="exampleOuter"><div class="exampleHead">Uploading An Image</div><div class="exampleInner">

 <upload ref="mail/attachment" mediatype="image/*">
   <label>Select image:</label>
   <filename ref="@filename" />
   <mediatype ref="@mediatype" />
 </upload>

</div>

A graphical browser might render this form control as follows:

[[Image:ui-upload.png|A drop-down box; main display reads 'Select Image:' with a cute icon. The drop-down itself has three items: (icon)-From Scanner or Camera...; (icon)-Scribble...; Browse...]]

Implementation Requirements:

* On activation, if child element <code>filename</code> is present and a filename is available, <code>upload</code> places the filename of the data to upload in the instance at the node indicated by the binding attributes on child element <code>filename</code>.
* On activation, if child element <code>mediatype</code> is present and a mediatype is available, <code>upload</code> places the mediatype of the data to upload in the instance at the node indicated by the binding attributes on child element <code>mediatype</code>.

</div><div class="div4">

=====<span id="ui-upload-filename">The filename Element</span>=====

Binding attributes on author-optional element <code>filename</code> specify the location in the instance for the parent element <code>upload</code>, when activated, to place the filename for the chosen binary resource. For security reasons, <code>upload</code> must not take action due to any existing value of the node.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]]

Content: EMPTY

In the following example, the user is prompted to select an image. When activated, <code>upload</code> places in <code>mail/attachment</code> either the binary data of the image or a URI for it, depending on the type declared for the <code>mail/attachment</code>. The filename, perhaps "<code>me.jpg</code>", is placed in the attribute node <code>mail/attachment/@filename</code>, and the mediatype, perhaps "<code>image/jpeg</code>" in the attribute node <code>mail/attachment/@mediatype</code>.

Example:

<div class="exampleOuter"><div class="exampleInner">

 <upload ref="mail/attachment" mediatype="image/*">
    <label>Select an image to attach</label>
    <filename ref="@filename"/>
    <mediatype ref="@mediatype"/>
 </upload>

</div></div></div><div class="div4">

=====<span id="ui-upload-mediatype">The mediatype Element (for upload)</span>=====

Binding attributes on author-optional element <code>mediatype</code> specify the location in the instance for the parent element <code>upload</code>, when activated, to place the mediatype of the chosen binary resource, if available.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]]

Content: EMPTY

</div></div><div class="div3">

====<span id="ui-range">The range Element</span>====

Description: This form control allows selection from a sequential range of values.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; start
: Author-optional attribute containing a hint for the lexical starting bound for the range—a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model.
; end
: Author-optional attribute containing a hint for the ending bound for the range—a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model.
; step
: Author-optional attribute containing a delta-value to use for incrementing or decrementing the value. Must be of a type capable of expressing the difference between two legal values of the underlying data.
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default for this form control is <code>false</code>.

Data Binding Restrictions: Binds only the following list of datatypes, or datatypes derived by restriction from those in the list: <code>xsd:duration</code>, <code>xsd:date</code>, <code>xsd:time</code>, <code>xsd:dateTime</code>, <code>xsd:gYearMonth</code>, <code>xsd:gYear</code>, <code>xsd:gMonthDay</code>, <code>xsd:gDay</code>, <code>xsd:gMonth</code>, <code>xsd:float</code>, <code>xsd:double</code>, and <code>xsd:decimal</code>.

<div class="note">

'''Note:'''

The above list of datatypes includes by derivation all of the integer datatypes (), all of the XForms datatypes defined in Section [[#XForms Datatypes|XForms Datatypes]] that correspond to the allowed XML schema datatypes, and the datatypes defined in [[#xforms:dayTimeDuration|xforms:dayTimeDuration]] and [[#xforms:yearMonthDuration|xforms:yearMonthDuration]].

</div><div class="note">

'''Note:'''

This control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: Must allow input of a value corresponding to the bound datatype. Implementations should inform the user of the upper and lower bounds, as well as the step size, if any. If the instance data value is outside the upper or lower bounds, this form control must indicate an out-of-range condition. In graphical environments, this form control may be rendered as a "slider" or "rotary control".

In the event of overlapping restrictions between the underlying datatype and the <code>start</code> and <code>end</code> hints, the most restrictive range should be used.

Notice that the attributes of this element encapsulate sufficient metadata that in conjunction with the type information available from the XForms Model proves sufficient to produce meaningful prompts when using modalities such as speech, e.g., when using an accessibility aid. Thus, in the example below, an aural user agent might speak a prompt of the form ''Please pick a date in the range January 1, 2001 through December 31, 2001.''

Examples:

<div class="exampleOuter"><div class="exampleHead">Picking From A Range</div><div class="exampleInner">

 <range ref="/stats/balance" start="-2.0" end="2.0" step="0.5">
   <label>Balance</label>
 </range>

</div>

A graphical browser might render this as follows:

[[Image:ui-range.png|a slider control, from -2 to +2]]

</div><div class="exampleOuter"><div class="exampleHead">Picking a date from a range</div><div class="exampleInner">

 <range ref="/order/shipDate" start="2001-01-01" end="2001-12-31">
   <label>Ship Date</label>
 </range>

</div></div></div><div class="div3">

====<span id="ui-trigger">The trigger Element</span>====

Description: This form control is similar to the HTML element <code>button</code> and allows for user-triggered actions. This form control may also be used to construct other custom form controls.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Data Binding Restrictions: Binds to any node. This form control does not directly interact with form data, but is affected by model item properties of the bound node, thus binding attributes are not required.

Implementation Requirements: The user agent must provide a means to generate an <code>DOMActivate</code> event on the form control. Graphical implementations might render this form control as a push-button with the label on the button face. Style sheets can be used to style this form control as an image, hyperlink, or other presentation.

Although a <code>trigger</code> element receives events associated with model item properties of a bound node, such as <code>xforms-readonly</code> and <code>xforms-invalid</code>, the XForms processor must not impart special behaviors on this control for model item properties other than the model item property <code>relevant</code> of a bound data node. For example, the <code>readonly</code> model item property of a bound data node does not affect whether or not the <code>trigger</code> can be activated.

Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute <code>appearance</code>. Suggested renditions for the pre-defined values of this attribute are as follows:

<blockquote>

"full": visually rendered as a standard button control with border.<br />"compact": visually rendered as a standard button control without border<br />"minimal": rendered with no border, a transparent background and underline font effect. This rendition hint is meant to be analogous to the typical visual rendition of an XHTML anchor element.

</blockquote>

Example:

<div class="exampleOuter"><div class="exampleHead">Simple Trigger</div><div class="exampleInner">

 <trigger>
   <label>Click here</label>
 </trigger>

</div></div></div><div class="div3">

====<span id="ui-submit">The submit Element</span>====

Description: This form control initiates a submission .

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes:

; submission
: Author-optional attribute containing a reference to element <code>submission</code>. If this attribute is given but does not identify a <code>submission</code> element, then activating the <code>submit</code> does not result in the dispatch of an <code>xforms-submit</code> event. If this attribute is omitted, then the first <code>submission</code> in document order from the <code>model</code> associated with the in-scope evaluation context is used.

Data Binding Restrictions: Binds to any node. This form control does not directly interact with form data, but is affected by model item properties of the bound node, thus binding attributes are not required.

Implementation Requirements: The default action for event <code>DOMActivate</code> is to dispatch event <code>xforms-submit</code> to the <code>submission</code> element specified by attribute <code>submission</code> (or its default). Upon activation, this control must become unavailable for further activations until the submit process concludes with either an <code>xforms-submit-done</code> or <code>xforms-submit-error</code> event.

Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute <code>appearance</code>. Suggested renditions for the pre-defined values of this attribute are the same as for [[#ui-trigger|trigger]].

Example:

<div class="exampleOuter"><div class="exampleHead">Submit</div><div class="exampleInner">

 <submit submission="timecard">
   <label>Submit Timecard</label>
 </submit>

</div></div></div><div class="div3">

====<span id="ui-selectMany">The select Element</span>====

Description: This form control allows the user to make multiple selections from a set of choices.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; selection
: Author-optional attribute determining whether free entry is allowed in the list. Default is "closed".
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default for this form control is <code>true</code>.

Data Binding Restrictions: any simpleContent capable of holding a sequence. The restriction to binding simpleContent exists when the choices are authored as part of the user interface control as shown in this section. Element <code>itemset</code> (described in [[#The itemset Element|The itemset Element]]) creates dynamic selection items and allows the available choices to be obtained from an XForms Model. When <code>itemset</code> uses the <code>value</code> element, the restriction to binding simpleContent remains in effect. However, the <code>itemset</code> also allows for the selection and deselection of subtrees of instance data using the <code>copy</code> element, and when using that construct, the data binding restriction to simpleContent is relaxed, but the form control must bind to an element with no mixed content.

<div class="note">

'''Note:'''

Except in the case described above where the simpleContent data binding restriction is relaxed, this control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div><div class="note">

'''Note:'''

A limitation of the XML Schema list datatypes is that white space characters in the storage values (the <code>value</code> element) are always interpreted as separators between individual data values. Therefore, authors should avoid using white space characters within storage values with list simpleContent.

<div class="exampleOuter"><div class="exampleHead">Incorrect Type Declaration</div><div class="exampleInner">

 <item>
   <value>United States of America</value>
   ...
 </item>

</div></div>

When selected, this item would introduce not one but four additional selection values: "America", "of", "States", and "United".

</div>

Implementation Requirements: The label for each choice must be presented, and the control must allow any number of selections, possibly none. When this form control uses the <code>value</code> element for selection, it stores the values corresponding to the selected choices in a space separated list in the location addressed by the binding attributes. The values to be stored for selected items are either directly specified as the contents of element <code>value</code>, or specified indirectly through binding attributes on element <code>value</code>. When this form control uses the <code>copy</code> element for selection, it stores copies of the subtrees corresponding to the selected choices in the location addressed by the binding attributes.

The datatype bound to this form control may include a non-enumerated value space, e.g., <code>xsd:string</code>, or a union of a enumeration and a non-enumerated datatype (called an open enumeration). In this case, control <code>select</code> may have attribute <code>selection="open"</code>. The form control must then allow free data entry, as described in [[#The input Element|The input Element]]. The form control may permit multiple values to be entered through free entry.

'''For closed selections:''' If the instance data matches the storage data of one or more of the selection items, those items are selected. If there is no match, no items are initially selected. If any of the stored values or subtree copies do not correspond to an item with a matching storage value or subtree, the form control must indicate an out-of-range condition. If the form control switches to or from being out-of-range, then <code>xforms-out-of-range</code> or <code>xforms-in-range</code> must be dispatched to the form control.

'''For open selections:''' When using dynamic selections with the <code>itemset</code> and <code>copy</code> elements, open selection has no effect. If the instance data matches the storage values specified by one or more of the selection items, then all such matching items are selected. If any instance data list values do not match the storage value specified by one or more of the items, all such non-matching values are retained, as if entered through free entry. Free entry text is handled the same as form control <code>input</code> ([[#The input Element|The input Element]]), possibly in multiplicity.

For both closed and open selections, any selection item with an empty storage data subtree or a storage value that is either empty or contains only white space characters must remain deselected.

For both closed and open selections, the above rules describe which items are considered to be selected and deselected by the control. The <code>select</code> form control changes the states of selected and deselected items on creation, refresh, and user selection or deselection of an item. Newly selected items receive the event <code>xforms-select</code> immediately after all newly deselected items receive the event <code>xforms-deselect</code>. The content of the instance node bound to the selection control must only be changed by the addition or deletion of storage data associated with items that have been selected or deselected. Content not associated with selection items is preserved. For selection controls that use the <code>value</code> element, the net effect of newly selected and deselected items is computed into a string, preserving content not associated with selection items, and the result is then committed to the bound instance node by using the XForms Action [[#The setvalue Element|The setvalue Element]]. For selection controls that use the <code>copy</code> element, the individual subtrees associated with the newly selected and deselected items are added or removed individually by using [[#The insert Element|The insert Element]] and [[#The delete Element|The delete Element]].

'''Implementation Hints:'''

For closed selections, when the form control is created or refreshed to reflect bound instance data, behavior equivalent to the following steps occurs:

# The content parts (space-separated values or subtree copies) in the bound instance data node are compared with the form control items' storage data (values or subtree copies).
# Each item with storage data (value or subtree copy) equal to an instance data content part becomes selected if it was not already selected.
# Each item with storage data missing from the instance data content becomes deselected if it was not already deselected.
# If there are instance data content parts for which there is no corresponding selection item, the form control indicates an out-of-range condition.

When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:

# If the item's storage data (value or subtree copy) was not present in the bound instance data, the item's storage data is inserted into the instance data content list. The exact location of the insertion is implementation-dependent. Any other item having the same storage data becomes selected as well.
# If the item's storage data was already present in the bound instance data, the bound instance data is left unchanged.

When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:

# If the item's storage data was present in the bound instance data, the item's storage data is removed from the instance data content list. Any other item having the same storage data becomes deselected as well.
# If the item's storage data was already absent from the bound instance data, the bound instance data is left unchanged.

For open selections: when the form control is created or refreshed to reflect bound instance data, the behavior is the same as with closed selection, except the form control never indicates an out-of-range condition.

An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.

Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute <code>appearance</code>. The value of the attribute consists of one of the following values:

<blockquote>

"full": all choices should be rendered at all times.<br />"compact": a fixed number of choices should be rendered, with scrolling facilities as needed<br />"minimal": a minimum number of choices should be rendered, with a facility to temporarily render additional choices

</blockquote>

Example:

<div class="exampleOuter"><div class="exampleHead">Selecting Ice Cream Flavor</div><div class="exampleInner">

 <select ref="my:flavors">
   <label>Flavors</label>
   <choices>
     <item>
       <label>Vanilla</label>
       <value>v</value>
     </item>
     <item>
       <label>Strawberry</label>
       <value>s</value>
     </item>
     <item>
       <label>Chocolate</label>
       <value>c</value>
     </item>
   </choices>
 </select>

</div>

In the above example, more than one flavor can be selected.

A graphical browser might render form control <code>select</code> as any of the following:

{| summary="Selection controls" border="1"
! rowspan="1" colspan="1" | <code>appearance="full"</code>
! rowspan="1" colspan="1" | <code>appearance="compact"</code>
! rowspan="1" colspan="1" | <code>appearance="minimal"</code>
|-
| rowspan="1" colspan="1" |
[[Image:ui-selectMany-checkbox.png|Check boxes for three choices: Vanilla, Strawberry, and Chocolate. Strawberry and Chocolate are selected.]]
| rowspan="1" colspan="1" |
[[Image:ui-selectMany-listbox.png|A list box with three choices: Vanilla, Strawberry, and Chocolate visible. Strawberry and Chocolate are selected.]]
| rowspan="1" colspan="1" |
[[Image:menu.png|A popup menu with three choices: Strawberry, Vanilla, and Chocolate. Strawberry and Chocolate are selected.]]
|}

</div></div><div class="div3">

====<span id="ui-selectOne">The select1 Element</span>====

Description: This form control allows the user to make a single selection from multiple choices.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; selection
: Author-optional attribute determining whether free entry is allowed in the list. Default is "closed".
; incremental
: Author-optional. When <code>true</code>, this form control will generate additional <code>xforms-value-changed</code> events. The default for this form control is <code>true</code>.

Data Binding Restrictions: Binds to any simpleContent. The restriction to binding simpleContent exists when the choices are authored as part of the user interface control as shown in this section. Element <code>itemset</code> (described in [[#The itemset Element|The itemset Element]]) creates dynamic selection items and allows the available choices to be obtained from an XForms Model. When <code>itemset</code> uses the <code>value</code> element, the restriction to binding simpleContent remains in effect. However, the <code>itemset</code> also allows for the selection and deselection of subtrees of instance data using the <code>copy</code> element, and when using that construct, the data binding restriction to simpleContent is relaxed, but the form control must bind to an element with no mixed content.

<div class="note">

'''Note:'''

Except in the case described above where the simpleContent data binding restriction is relaxed, this control cannot bind to element nodes that have element children. See [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]] for user interface processing rules common to all form controls.

</div>

Implementation Requirements: The label for each choice must be presented, and the control must allow at all times exactly one selection. When this form control uses the <code>value</code> element for selection, it stores the value corresponding to the selected choice in the location addressed by the binding attributes. The value to be stored is either directly specified as the contents of element <code>value</code>, or specified indirectly through binding attributes on element <code>value</code>. When this form control uses the <code>copy</code> element for selection, it stores a copy of the subtree corresponding to the selected choice in the location addressed by the binding attributes.

The datatype bound to this form control may include a non-enumerated value space, e.g., <code>xsd:string</code>, or a union of a enumeration and a non-enumerated datatype (called an open enumeration). In this case, control <code>select1</code> may have attribute <code>selection="open"</code>. The form control must then allow free-form data entry, as described in [[#The input Element|The input Element]].

'''For closed selections:''' If the instance data matches the storage data of one of the selection items, that item is selected. If there is no match, no items are initially selected. If there is no match and the storage data is non-empty, the form control must indicate an out-of-range condition. If the form control switches to or from being out-of-range, then <code>xforms-out-of-range</code> or <code>xforms-in-range</code> must be dispatched to the form control.

'''For open selections:''' When using dynamic selections with the <code>itemset</code> and <code>copy</code> elements, open selection has no effect. If the instance data matches the storage value specified by one of the selection items, then the first such matching item is selected. Otherwise, no items are selected and the instance data value is retained, as if entered through free text entry. Free entry text is handled the same as form control <code>input</code> ([[#The input Element|The input Element]]).

For both closed and open selections, any selection item with a storage value which is empty or which contains only white space characters must remain deselected.

For both closed and open selections, the above rules describe which items are considered to be selected by the control. Items that are not selected are considered to be deselected. The <code>select1</code> form control changes the states of selected and deselected items on creation, refresh, and user selection or deselection of an item. A newly selected item receives the event <code>xforms-select</code> immediately after all other items receive the event <code>xforms-deselect</code>. The content of the instance node bound to the selection control must only be changed by the addition or deletion of storage data associated with items that have been selected or deselected. Content not associated with selection items is preserved. For selection controls that use the <code>value</code> element, the net effect of newly selected and deselected items is computed into a string, preserving content not associated with selection items, and the result is then committed to the bound instance node by using the XForms Action [[#The setvalue Element|The setvalue Element]]. For selection controls that use the <code>copy</code> element, the individual subtrees associated with the newly selected and deselected items are added or removed individually by using [[#The insert Element|The insert Element]] and [[#The delete Element|The delete Element]].

'''Implementation Hints:'''

For closed selections, when the form control is created or refreshed to reflect bound instance data, behavior equivalent to the following steps occurs:

# The bound instance data is compared with the items' storage data (values or subtree copies).
# If no item with storage data (value or subtree copy) in the bound instance data node is selected, then the first item with storage data in the instance data content, if any, becomes selected. Otherwise, if an item with storage data in the bound instance data node is selected, then the first selected item remains selected, and any other items with storage data matching the selected item are deselected.
# If there is a selected item, then all items with storage data not equal to the selected item are deselected, and their representative storage data is removed from the bound instance node content.
# If no item has storage data in the bound instance data node content and the instance data node content is not empty, then the form control indicates an out-of-range condition.

When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:

# All selected items other than the newly selected item are deselected, if any, and the storage data of any deselected items whose storage data does not match the newly selected item are removed from the bound instance node data.
# The newly selected item becomes selected. If its storage data (value or subtree copy) is not present in the bound instance data, then the item's storage data is inserted into the instance data. The exact location of the insertion is implementation-dependent, but the newly inserted data is not accompanied by any other data unless the data does not match any items for the selection control.

When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:

# The item is deselected and its storage data is removed from the bound instance node data.
# If the bound instance data node is not empty, then the form control indicates an out-of-range condition.

For open selections: when the form control is created or refreshed to reflect bound instance data, the behavior is the same as with closed selection, except the form control never indicates an out-of-range condition.

An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.

User interfaces may choose to render this form control as a pulldown list or group of radio buttons, among other options. The <code>appearance</code> attribute offers a hint as to which rendering might be most appropriate, although any styling information (such as CSS) should take precedence.

Example:

<div class="exampleOuter"><div class="exampleHead">Pick A Flavor</div><div class="exampleInner">

 <select1 ref="my:flavor">
   <label>Flavor</label>
   <item>
     <label>Vanilla</label>
     <value>v</value>
   </item>
   <item>
     <label>Strawberry</label>
     <value>s</value>
   </item>
   <item>
     <label>Chocolate</label>
     <value>c</value>
   </item>
 </select1>

</div>

In the above example, selecting one of the choices will result in the associated value given by element <code>value</code> on the selected item being set in the underlying instance data at the location <code>icecream/flavor</code>.

A graphical browser might render this form control as any of the following:

{| summary="Selection controls"
! rowspan="1" colspan="1" | appearance="full"
! rowspan="1" colspan="1" | appearance="compact"
! rowspan="1" colspan="1" | appearance="minimal"
|-
| rowspan="1" colspan="1" |
[[Image:ui-selectOne-radio.png|Radio buttons for three choices: Vanilla, Strawberry, Chocolate. Strawberry is selected.]]
| rowspan="1" colspan="1" |
[[Image:ui-selectOne-listbox.png|A list boxwith three choices: Vanilla, Strawberry, and Chocolate visible. Strawberry is selected.]]
| rowspan="1" colspan="1" |
[[Image:ui-selectOne-pulldown.png|A collapsible pull-down list with the three choices. The list is collapsd, and Vanilla is selected.]]
|}

</div></div></div><div class="div2">

===<span id="ui-commonelems">Common Support Elements</span>===

The child elements detailed below provide the ability to attach metadata to many form controls and other elements.

* Factoring all human readable messages to a separate resource XML file.
* Using URIs into this XML resource bundle within individual <code>label</code> elements
* Finally, an XForms implementation could use content negotiation to obtain the appropriate XML resource bundle, e.g., based on the <code>accept-language</code> headers from the client, to serve up the user interface with messages localized to the client's locale.

<div class="div3">

====<span id="ui-commonelems-label">The label Element</span>====

This element provides a descriptive label for the containing form control. The descriptive label can be presented visually and made available to accessibility software so the visually-impaired user can obtain a short description of form controls while navigating among them.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes: None

The label specified can exist in instance data or as inline text. If more than one source of label is specified in this element, the order of precedence is: single node binding attributes, inline text.

An accessibility aid might speak the metadata encapsulated here when the containing form control gets focus.

</div><div class="div3">

====<span id="ui-commonelems-help">The help Element</span>====

The author-optional element <code>help</code> provides a convenient way to attach help information to a form control.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes: None

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, inline text.

An example of this element is at [[#The message Element|The message Element]].

</div><div class="div3">

====<span id="ui-commonelems-hint">The hint Element</span>====

The author-optional element <code>hint</code> provides a convenient way to attach hint information to a form control.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes: None

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, inline text.

An example of this element is at [[#The message Element|The message Element]].

</div><div class="div3">

====<span id="ui-commonelems-alert">The alert Element</span>====

The author-optional element <code>alert</code> provides a convenient way to attach alert or error information to a form control. Rendering of this element is implementation-defined, and there is no default <code>level</code> such as <code>modal</code> or <code>ephemeral</code> for the displayed message.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes: None

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, inline text. See [[#XForms and Styling (Non-Normative)|XForms and Styling]] for examples to see how this might be presented to the user.

</div></div><div class="div2">

===<span id="ui-selection-commonelems">Common Markup for Selection Controls</span>===

<div class="div3">

====<span id="ui-selection-commonelems-choices">The choices Element</span>====

This element is used within selection form controls to group available choices. This provides the same functionality as element <code>optgroup</code> in HTML.

Common Attributes: [[#structure-attrs-common|Common]]

</div><div class="div3">

====<span id="ui-selection-commonelems-item">The item Element</span>====

This element specifies the storage value and label to represent an item in a list. It is found within elements <code>select1</code> and <code>select</code>, or grouped in element <code>choices</code>.

Common Attributes: [[#structure-attrs-common|Common]]

</div><div class="div3">

====<span id="ui-selection-commonelems-value">The value Element</span>====

This element provides a storage value to be used when an <code>item</code> is selected. The storage value is determined by one of three methods, in order of precedence:

# the value of a node indicated by a single node binding expression, if specified
# the result of evaluating an XPath expression appearing in attribute <code>value</code>, if specified
# the inline content of the <code>value</code> element (when neither the single node binding nor the <code>value</code> attribute are expressed).

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes:

; value
: Author-optional. An XPath expression to be evaluated. The string result of the evaluation is used as the storage value of the <code>item</code> when it is selected. If a single node binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the single node binding. An empty string is used if the XPath evaluation fails.

Data Binding Restriction: All lexical values must be valid according to the datatype bound to the selection control. If the single node binding attributes are used and indicate a node in a model other than the bound node of the containing selection control, then an <code>xforms-binding-exception</code> must occur.

</div></div></div><div class="div1">

==<span id="ui">Container Form Controls</span>==

This chapter covers XForms view layer features for combining [[#Core Form Controls|core form controls]] into user interfaces using [[#Container Form Controls|container form controls]]. All core form controls defined in [[#Core Form Controls|Core Form Controls]] are treated as individual units for purposes of visual layout e.g., in XHTML processing. A '''container form control''' is a form control that provides the ability to combine other form controls in its content into user interfaces.

Aggregation of form controls with markup defined in this chapter provides semantics about the relationship among user interface controls; such knowledge can be useful in delivering a coherent UI to small devices. For example, if the user interface needs to be split up over several screens, controls appearing inside the same aggregation would typically be rendered on the same screen or page.

<div class="div2">

===<span id="ui-group-module">The XForms Group Module</span>===

A <code>group</code> element is a [[#Container Form Controls|container form control]] that allows a form author to aggregate other form controls into a single, aggregate user interface component. The elements and attributes included in this module are:

{| summary="listing of XForms Group element and its attribute and content model" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-group|group]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" |
label?, (([[#elems-form-controls| Core Form Controls]])|group|switch|repeat|[[#elems-ui-common|UI Common]])*
|}

<div class="div3">

====<span id="ui-group">The group Element</span>====

The <code>group</code> element is used as a container for defining a hierarchy of form controls. Groups can be nested to create complex hierarchies. The author-optional <code>label</code> element has special significance when it appears as the first element child of <code>group</code>, representing a label for the entire group.

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Although a <code>group</code> element receives events associated with model item properties of a bound node, such as <code>xforms-readonly</code> and <code>xforms-invalid</code>, no special behavior is imparted by the <code>group</code> onto the content elements in the group as a direct result of any model item property. The model item property <code>relevant</code> of a bound data node can indirectly affect the content of the group via its contribution to deciding whether the <code>group</code> is relevant or non-relevant. A group is considered to be non-relevant if and only if:

* the Single Node Binding is expressed and resolves to empty nodeset,
* the Single Node Binding is expressed and resolves to a non-relevant instance node,
* the <code>group</code> is contained by a non-relevant <code>switch</code> or <code>group</code> (which includes a non-relevant <code>repeat</code> object), or
* the <code>group</code> is contained by a non-selected <code>case</code> element of a <code>switch</code>.

All content elements (e.g. core form controls, groups, switches, repeats and host language content) within a non-relevant group are handled as non-relevant. When a <code>group</code> becomes non-relevant, it must receive event <code>xforms-disabled</code> and then the XForms action handlers that are listening for events on the non-relevant <code>group</code> must be disabled. When a non-relevant <code>group</code> changes to being relevant, the XForms action handlers that listen for events on the <code>group</code> must become enabled and then the <code>group</code> must receive the event <code>xforms-enabled</code>.

<div class="note">

'''Note:'''

If a group is non-relevant, then the rendering approach used to signify non-relevance is applied to the entire content of the group.

</div>

Example:

<div class="exampleOuter"><div class="exampleHead">Grouping Related Controls</div><div class="exampleInner">

 <group ref="address">
   <label>Shipping Address</label>
   <input ref="line_1">
     <label>Address line 1</label>
   </input>
   <input ref="line_2">
     <label>Address line 2</label>
   </input>
   <input ref="postcode">
     <label>Postcode</label>
   </input>
 </group>

</div></div>

Setting the input focus on a group results in the focus being set to the first form control in the navigation order within that group.

</div></div><div class="div2">

===<span id="ui-switch-module">The XForms Switch Module</span>===

A <code>switch</code> element is a [[#Container Form Controls|container form control]] that allows the creation of user interfaces where the user interface can be varied based on user actions and events. The elements and attributes included in this module are:

{| summary="listing of XForms Switch elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-switch|switch]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" | case+
|-
| rowspan="1" colspan="1" |
[[#ui-case|case]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], selected (xsd:boolean)
| rowspan="1" colspan="1" |
label?, (([[#elems-form-controls| Core Form Controls]])|group|switch|repeat|[[#action-content-set|Action]])*
|-
| rowspan="1" colspan="1" |
[[#action-toggle|toggle]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], case (xsd:IDREF)
| rowspan="1" colspan="1" | case?
|}

<div class="div3">

====<span id="ui-switch">The switch Element</span>====

This element contains one or more <code>case</code> elements, any one of which is rendered at a given time.

<div class="note">

'''Note:'''

This is separate from XForms <code>relevant</code> processing (see [[#The relevant Property|The relevant Property]]), which is based on the current state of the XForms Model. As an example, portions of a questionnaire pertaining to the user's automobile may become relevant only if the user has answered in the affirmative to the question 'Do you own a car?'.

</div>

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Although a <code>switch</code> element receives events associated with model item properties of a bound node, such as <code>xforms-readonly</code> and <code>xforms-invalid</code>, no special behavior is imparted by the <code>switch</code> onto the content elements in the selected <code>case</code> as a direct result of any model item property. The model item property <code>relevant</code> of a bound data node can indirectly affect the content of the selected <code>case</code> via its contribution to deciding whether the <code>switch</code> is relevant or non-relevant. The non-relevance of a switch is determined in the same way as it is for <code>group</code> and similarly applies to the entire content. Also, as with <code>group</code>, when a <code>switch</code> becomes non-relevant, it must receive event <code>xforms-disabled</code> and then the XForms action handlers that are listening for events on the non-relevant <code>switch</code> must be disabled. As well, when a non-relevant <code>switch</code> changes to being relevant, the XForms action handlers that listen for events on the <code>switch</code> must become enabled and then the <code>switch</code> must receive the event <code>xforms-enabled</code>.

Example:

<div class="exampleOuter"><div class="exampleHead">switch</div><div class="exampleInner">

 <switch>
   <case id="in" selected="true">
     <input ref="yourname">
       <label>Please tell me your name</label>
       <toggle ev:event="DOMActivate" case="out"/>
     </input>
   </case>
   <case id="out" selected="false">
     <html:p>Hello <output ref="yourname" />
       <trigger id="editButton">
         <label>Edit</label>
         <toggle ev:event="DOMActivate" case="in"/>
       </trigger>
     </html:p>
   </case>
 </switch>

</div></div>

The above results in the portion of the user interface contained in the first <code>case</code> being displayed initially. This prompts for the user's name; filling in a value and ''activating'' the control e.g., by pressing <code>enter</code> results switches to the alternate case, with a read-only <code>output</code> rendering. Activating the trigger labeled "Edit" in turn switches back to the original case.

</div><div class="div3">

====<span id="ui-case">The case Element</span>====

This element encloses markup to be conditionally rendered. The content elements (e.g. form controls, groups, switches, repeats and host language elements) within a non-selected <code>case</code> behave as if they were in a non-relevant <code>group</code> (see [[#The group Element|The group Element]]). Similarly, content elements in a <code>case</code> that becomes selected behave as if they were in a <code>group</code> that has become relevant. The attribute <code>selected</code> determines the initial selected state.

Common Attributes: [[#structure-attrs-common|Common]]

Special Attributes:

; selected
: Author-optional selection status for the case. The default value is <code>"false"</code>.

If multiple <code>case</code>s within a <code>switch</code> are marked as <code>selected="true"</code>, the first selected <code>case</code> remains and all others are deselected. If none are selected, the first becomes selected.

</div></div><div class="div2">

===<span id="ui-repeat-module">The XForms Repeat Module</span>===

The XForms specification allows the definition of repeating structures such as multiple items within a purchase order. When defining the XForms Model, such higher-level collections are constructed out of basic building blocks; similarly, this section defines a [[#Container Form Controls|container form control]] called <code>repeat</code> that can bind to data structures such as lists and collections and provide a user interface for each node of the list or collection.. The elements and attributes included in this module are:

{| summary="listing of XForms Repeat elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-repeat|repeat]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-nodeset|Node Set Binding]], startindex (xsd:positiveInteger), number (xsd:nonNegativeInteger)
| rowspan="1" colspan="1" |
(([[#elems-form-controls| Core Form Controls]])|group|switch|repeat|[[#action-content-set|Action]])*
|-
| rowspan="1" colspan="1" |
[[#action-setindex|setindex]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], repeat (xsd:IDREF), index (number XPath Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-itemset|itemset]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-nodeset|Node Set Binding]]
| rowspan="1" colspan="1" |
label, (value|copy), ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-copy|copy]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" | (various)
| rowspan="1" colspan="1" | [repeat-nodeset, repeat-bind, repeat-model] (Node Set Binding attributes), repeat-startindex (xsd:positiveInteger), repeat-number (xsd:nonNegativeInteger)
| rowspan="1" colspan="1" | N/A
|}

<div class="div3">

====<span id="ui-repeat">The repeat Element</span>====

This element defines a UI mapping over a node-set selected by Node Set Binding Attributes. This node-set is called a <span id="defn-repeat-collection">'''repeat collection'''</span>.

For example:

<div class="exampleOuter"><div class="exampleHead">Shopping Cart</div><div class="exampleInner">

 <repeat nodeset="/cart/items/item">
   <input ref="." ...>
      <label>...</label>
   </input>
   <html:br/>
 </repeat>

</div></div>

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-nodeset|Node Set Binding]]

Special Attributes:

; startindex
: Author-optional 1-based initial value of the repeat index. The default value is 1.
; number
: Author-optional hint to the XForms Processor as to how many elements from the collection to display.

This element operates over a [[#defn-repeat-collection|repeat collection]] by binding the encapsulated user interface controls to each element of the collection. If an element of the collection is non-relevant, then the rendering approach used to signify non-relevance is applied to the associated user interface controls. Attributes on this element specify how many members of the collection are presented to the user at any given time. XForms Actions <code>insert</code>, <code>delete</code>, and <code>setindex</code> can be used to operate on the collection—see [[#XForms Actions|XForms Actions]]. Another way to view repeat processing (disregarding special user interface interactions) is to consider "unrolling" the repeat. The above example is similar to the following (given four <code>item</code> elements in the returned node-set):

<div class="exampleOuter"><div class="exampleHead">Repeat Unrolled</div><div class="exampleInner">

 <!-- unrolled repeat -->
   <input ref="/cart/items/item[1]"><label>...</label></input><html:br/>
   <input ref="/cart/items/item[2]"><label>...</label></input><html:br/>
   <input ref="/cart/items/item[3]"><label>...</label></input><html:br/>
   <input ref="/cart/items/item[4]"><label>...</label></input><html:br/>

</div></div><div class="exampleOuter"><div class="exampleHead">Repeat Collection</div><div class="exampleInner">

 <model>
   <instance>
     <my:lines>
       <my:line name="a">
         <my:price>3.00</my:price>
       </my:line>
       <my:line name="b">
         <my:price>32.25</my:price>
       </my:line>
       <my:line name="c">
         <my:price>132.99</my:price>
       </my:line>
       </my:lines>
   </instance>
 </model>
   ...
 <repeat id="lineset" nodeset="/my:lines/my:line">
   <input ref="my:price">
     <label>Line Item</label>
   </input>
   <input ref="@name">
     <label>Name</label>
   </input>
 </repeat>
 
 <trigger>
   <label>Insert a new item after the current one</label>
   <action ev:event="DOMActivate">
     <insert nodeset="/my:lines/my:line" at="index('lineset')"
       position="after"/>
     <setvalue ref="/my:lines/my:line[index('lineset')]/@name"/>
     <setvalue ref="/my:lines/my:line[index('lineset')]/price">0.00</setvalue>
   </action>
 </trigger>
 
 <trigger>
   <label>remove current item</label>
   <delete ev:event="DOMActivate" nodeset="/my:lines/my:line"
     at="index('lineset')"/>
 </trigger>

</div></div></div><div class="div3">

====<span id="ui-nested-repeats">Nested Repeats</span>====

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

It is possible to nest repeat elements to create more powerful user interface for editing structured data. [[#Editing Hierarchical Bookmarks Using XForms|Editing Hierarchical Bookmarks Using XForms]] is an example of a form using nested repeats to edit hierarchical data consisting of bookmarks within multiple sections. Consider the following <code>insert</code> statement that appears as part of that example.

<div class="exampleOuter"><div class="exampleHead">Repeat Index and Nested Repeats</div><div class="exampleInner">

 <xforms:insert nodeset="/bookmarks/section[index('repeatSections')]/bookmark"
                at="index('repeatBookmarks')"
                position="after"/>

</div></div>

The above <code>insert</code> statement is used in that example to add new bookmark entries into the ''currently selected'' section. The inner (nested) repeat operates on bookmarks in this selected section; The index—as returned by XForms function <code>index</code>—for this inner repeat starts at <code>1</code>. Hence, after a new empty section of bookmarks is created and becomes ''current'', the first ''insert bookmark'' operation adds the newly created bookmark at the front of the list.

</div><div class="div3">

====<span id="ui-repeat-processing">Repeat Processing</span>====

The markup contained within the body of element <code>repeat</code> specifies the user interface to be generated for each [[#def-repeat-item|repeat item]] of the underlying repeat collection. During user interface initialization (see [[#The xforms-model-construct-done Event|The xforms-model-construct-done Event]]), the following steps are performed for <code>repeat</code><nowiki>:</nowiki>

# The Node Set Binding is evaluated to locate the [[#defn-repeat-collection|repeat collection]] to be operated on by this <code>repeat</code>.
# The ''index'' for this repeating structure is initialized to the value of <code>startindex</code>. If the initial <code>startindex</code> is less than 1 it defaults to 1. If the index is greater than the initial node-set then it defaults to the size of the node-set.
# User interface as specified by the <code>repeat</code> is generated for the requisite number of members of the collection as specified by attributes on element <code>repeat</code>.

For each node of the repeat collection, a <span id="def-repeat-item">'''repeat item'''</span> is defined to be the aggregation of the node, its position, the size of the repeat collection, and a [[#def-repeat-object|repeat object]].

A <span id="def-repeat-object">'''repeat object'''</span> is an implicitly generated <code>group</code> element that contains the set of run-time objects generated to represent the repeat template content for a single repeat item of the [[#defn-repeat-collection|repeat collection]]. These run-time objects are form controls, XForms actions and other host language elements that correspond to elements in the repeat template.

<div class="note">

'''Note:'''

The capture and bubble phases of events dispatched to the run-time objects behave as if the repeat object were a child of element <code>repeat</code>. The repeat template content, including action handlers, is made unavailable to the host language processor. Copies of the repeat template content, including Action handlers, are made available via the repeat objects.

</div><div class="exampleOuter"><div class="exampleHead">Example: Handling an Event Dispatched to a <code>repeat</code> Element</div><div class="exampleInner">

 <repeat id="X" ... >
         ...
 </repeat>
 
 <action ev:event="xforms-scroll-first" ev:target="X" ev:observer="X">
    ...
 </action>

</div></div>

A new repeat item is created dynamically at any time in the lifecycle of the form (i.e. any time after <code>xforms-model-construct-done</code>) whenever a new node is added to the [[#defn-repeat-collection|repeat collection]]. There are many ways to add new nodes to a [[#defn-repeat-collection|repeat collection]], including but not limited to the following:

* An <code>insert</code> action can add one or more nodes that match the repeat nodeset;
* The new instance data subtree created by a <code>submission</code> instance replacement may contain nodes that match the repeat nodeset;
* A <code>setvalue</code> action or a <code>calculate</code> may change a value that causes one or more nodes to match the repeat nodeset.

Any time a new repeat item is created, XML Event handlers declared within the corresponding repeat object are initialized, and the user interface form controls generated for the repeat object are initialized in the same manner as the user interface initialization that is performed during default processing of <code>xforms-model-construct-done</code>. For example, if the repeat object contains an inner <code>repeat</code> run-time object, then it is initialized according to the list of steps at the beginning of this section ([[#Repeat Processing|Repeat Processing]]).

The processing model for repeating structures includes an ''index'' that points to the ''current'' repeat item in the [[#defn-repeat-collection|repeat collection]] . This repeat index is accessed via XForms function <code>index</code> ([[#The index() Function|The index() Function]]) and manipulated via XForms Action <code>setindex</code> ([[#The setindex Element|The setindex Element]]). This index can be used as a reference point for <code>insert</code> and <code>delete</code> actions. Notice that the contained XForms form controls inside element <code>repeat</code> do not explicitly specify the index of the collection entry being populated. This is intentional; it keeps both authoring as well as the processing model simple.

If one or more nodes have been added to the repeat collection by an <code>insert</code> action, then the repeat items corresponding to the new nodes must be created and initialized, and the repeat index must be updated to indicate the repeat item corresponding to the last node added by the <code>insert</code>.

<div class="note">

'''Note:'''

The change of index on a <code>repeat</code> does not cause the index of any <code>repeat</code> nested within it to be re-initialized.

</div>

The repeat item generation and repeat index update on insertion must behave as if it occurs in response to the <code>xforms-insert</code> event dispatched by the <code>insert</code> action. The index update must behave as if it occurs when the <code>xforms-insert</code> event reaches the parent of the target <code>instance</code> element in the capture phase.

<div class="note">

'''Note:'''

An event handler that listens for <code>xforms-insert</code> on <code>instance</code> in the default phase has access to the updated index value via function <code>index()</code>.

</div>

A repeat item can also be destroyed dynamically at any time in the lifecycle of the form whenever a node is removed from the [[#defn-repeat-collection|repeat collection]]. When a repeat item is destroyed, the repeat object and all of its inner form controls are eliminated, including inner repeats, switches and groups, and all XML Event handlers created by the repeat object are eliminated. There are many ways to remove repeat items from a [[#defn-repeat-collection|repeat collection]], including but not limited to the following:

* A <code>delete</code> action can remove nodes that matched the repeat nodeset;
* The new instance data subtree created by a <code>submission</code> instance replacement may replace nodes that matched the repeat nodeset;
* A <code>setvalue</code> action or a <code>calculate</code> may change a value that causes one or more nodes to stop matching the repeat nodeset.

If one or more nodes have been removed from the repeat collection by a <code>delete</code> action, then the repeat items corresponding to the deleted nodes must be destroyed and the repeat index must be updated based on the rules below.

# If, prior to node deletion, the repeat index indicated a repeat that is still contained in the repeat collection after node deletion, then the index is adjusted, if necessary, to indicate that same repeat item.
# Otherwise, if all repeat items in the collection have been destroyed, the repeat index is set to 0 .
# Otherwise, if the repeat index was pointing to one of the deleted repeat items, and if the new size of the collection is smaller than the index, the index is changed to the new size of the collection.
# Otherwise, if the repeat index was pointing to one of the deleted repeat items, and if the new size of the collection is equal to or greater than the index, the index is not changed.

<div class="note">

'''Note:'''

The change of index on a <code>repeat</code> does not cause the index of any <code>repeat</code> nested within it to be re-initialized.

</div>

The repeat index update on deletion behaves as if it occurs in response to the <code>xforms-delete</code> event dispatched by the <code>delete</code> action. Specifically, the index update behaves as if it occurs when the <code>xforms-delete</code> event reaches the parent of the target <code>instance</code> element in the capture phase.

</div><div class="div3">

====<span id="ui-repeat-ui">User Interface Interaction</span>====

Element <code>repeat</code> enables the binding of user interaction to a node-set, referred to as [[#defn-repeat-collection|repeat collection]]. The number of displayed items might be less than the total number available in the collection. In this case, the presentation would render only a portion of the repeating items at a given time. For example, a graphical user interface might present a scrolling table. The current item indicated by the repeat index should be made available to the user at all times, for example, not allowed to scroll out of view. The XForms Actions enumerated at [[#XForms Actions|XForms Actions]] may be used within event listeners to manipulate the [[#defn-repeat-collection|repeat collection]] being populated by scrolling, inserting, and deleting entries.

Notice that the markup encapsulated by element <code>repeat</code> acts as the template for the user interface that is presented to the user. As a consequence, statically authored <code>IDREF</code> attributes must be interpreted based on a combination of repeat indexes and where the IDREF attributes appear relative to the element bearing the matching ID. Based on the IDREF resolution rules given in [[#Resolving ID References in XForms|Resolving ID References in XForms]], it is possible to toggle the <code>case</code> of a <code>switch</code> even when it is within one or more <code>repeat</code> elements. Similarly, it is possible to set the focus to controls and dispatch events to elements that are within one or more <code>repeat</code> elements.

If the focus is transferred to a form control within a <code>repeat</code> by any means, such as by an XForms action or by user interaction, the index of the <code>repeat</code> is updated to indicate the item of the [[#defn-repeat-collection|repeat collection]] that contains the control. If the repeat item containing the focused control contains any inner repeat objects, their indexes are not changed. However, the repeat index update is recursive for all outer repeats that contain the focused control; the index of each outer containing <code>repeat</code> is adjusted appropriately. These changes of repeat index occurs as if by invoking the <code>setindex</code> action.

</div><div class="div3">

====<span id="ui.repeat.via.attrs">Creating Repeating Structures Via Attributes</span>====

Element <code>repeat</code> enables the creation of user interfaces for populating repeating structures. When using XForms within host languages like XHTML, it is often necessary to create repeating structures within constructs such as <code>table</code>. Thus, one might wish to use element <code>repeat</code> within a <code>table</code> to create the rows of a table, where each row of the table binds to a distinct member of a [[#defn-repeat-collection|repeat collection]]. Since <code>html:table</code> doesn't (and perhaps never will) allow <code>xforms:repeat</code> elements as children, another syntax is needed.

<div class="exampleOuter"><div class="exampleHead">Tables And Repeating Structures</div><div class="exampleInner">
<pre>
 <table>
   <repeat nodeset="...">
     <tr>
       <td>...</td>
       ...
     </tr>
   </repeat>
 </table>
</pre>
</div></div>

More generally, there is a need to integrate repeat behavior into host languages at points where the content model of the host language does not or cannot provide the appropriate extension hooks via modularization. To accommodate this, XForms defines an alternative syntax that is functionally equivalent to the <code>repeat</code> element, using the following attributes:

<blockquote>

<code>repeat-model</code><br /><code>repeat-bind</code><br /><code>repeat-nodeset</code><br /><code>repeat-startindex</code><br /><code>repeat-number </code>

</blockquote>

The above attributes are equivalent to the <code>repeat</code> attributes of the same name, but without the prefix <code>repeat-</code>. A host language can include these attributes in the appropriate places to enable repeating constructs. For example, a version of XHTML might use:

<div class="exampleOuter"><div class="exampleHead">Tables And Repeating Structures</div><div class="exampleInner">

 <html:table xforms:repeat-nodeset="...">
   <html:tr>
     <html:td><xforms:output ref="..."/></html:td>
   </html:tr>
 </html:table>

</div>

Which could be validated against an appropriately configured XHTML Schema that includes the XForms Repeat module. Note that what gets repeated is the child elements of the element with the <code>repeat-</code> attributes.

</div>

Additionally, when using XForms Action <code>setindex</code>, attribute <code>repeat</code> of type <code>idref</code> can point to any element carrying the repeat attributes. Similarly, when using function <code>index</code> against a repeating structure created via the <code>repeat-</code>attributes, the <code>id</code> of that element can be used as the argument to function <code>index</code>.

</div><div class="div3">

====<span id="ui-selection-commonelems-itemset">The itemset Element</span>====

This element allows the creation of dynamic selections within controls <code>select</code> and <code>select1</code>, where the available choices are determined at run-time. The node-set that holds the available choices is specified via the Node Set Binding. Child elements <code>label</code> and <code>value</code> indirectly specify the label and storage values. Notice that the run-time effect of <code>itemset</code> is the same as using element <code>choices</code> with child <code>item</code> elements to statically author the available choices.

For each node of the Node Set Binding, an associated <code>item</code> element is created. XForms Actions appearing in the content of an <code>itemset</code> are created within each <code>item</code> element, and the in-scope evaluation context for these XForms Actions is based on the node for which the <code>item</code> was generated as described in Section [[#Evaluation Context|Evaluation Context]].

<div class="note">

'''Note:'''

As with the <code>repeat</code> element, the <code>itemset</code> template content, including XForms Actions, is made unavailable. Copies of the <code>itemset</code> template content, including XForms Actions, are made available via repeated <code>item</code> objects.

</div>

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-nodeset|Node Set Binding]]

<div class="note">

'''Note:'''

Whenever a <code>refresh</code> event is dispatched the <code>nodeset</code> is re-evaluated to update the list of available choices.

</div>

The following example shows element <code>itemset</code> within control <code>select</code> to specify a dynamic list of ice cream flavors:

<div class="exampleOuter"><div class="exampleHead">Dynamic Choice Of Ice Cream Flavors</div><div class="exampleInner">

 <model id="cone">
   <instance>
     <my:icecream>
       <my:order/>
     </my:icecream>
   </instance>
 </model>
 <model id="flavors">
   <instance>
     <my:flavors>
       <my:flavor type="v">
         <my:description>Vanilla</my:description>
       </my:flavor>
       <my:flavor type="s">
         <my:description>Strawberry</my:description>
       </my:flavor>
       <my:flavor type="c">
         <my:description>Chocolate</my:description>
       </my:flavor>
     </my:flavors>
   </instance>
 </model>
 <!-- user interaction markup -->
 <select model="cone" ref="my:order">
   <label>Flavors</label>
   <itemset model="flavors" nodeset="/my:flavors/my:flavor">
     <label ref="my:description"/>
     <copy ref="my:description"/>
   </itemset>
 </select>
 
 <!-- For all three items selected, this example produces instance data like
      <my:icecream>
        <my:order>
 		  <my:description>Vanilla</my:description>
 		  <my:description>Strawberry</my:description>
 		  <my:description>Chocolate</my:description>
        </my:order>
      </my:icecream>
 -->

</div></div></div><div class="div3">

====<span id="ui-selection-commonelems-copy">The copy Element</span>====

Structurally, this element is similar to [[#The value Element|The value Element]]. It differs in that it can only be used within <code>itemset</code>, and that it works with subtrees of instance data rather than simple values.

Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

If the single node binding attributes indicate a node in a model other than the bound node of the containing selection control, then an <code>xforms-binding-exception</code> must occur.. When a <code>copy</code> item is selected, the following rules apply:

* The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an exception results ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]).
* The element node associated with the <code>item</code>, selected by the binding attributes on <code>copy</code>, is deep copied as a child of the target node by using an <code>insert</code> action ([[#The insert Element|The insert Element]]).
* A full computational dependency rebuild is done, followed by recalculate, revalidate, and refresh.

When a <code>copy</code> item is deselected, the following rules apply:

* The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an exception results ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]).
* The child element node associated with the <code>item</code>, selected by the binding attributes on <code>copy</code>, is deleted by using a <code>delete</code> action ([[#The delete Element|The delete Element]]).
* A full computational dependency rebuild, followed by recalculate, revalidate, and refresh.

<div class="note">

'''Note:'''

If the target node of the <code>select</code> or <code>select1</code> is readonly, then the insertion or deletion associated with the copy operation is not performed.

</div></div></div></div><div class="div1">

==<span id="action">XForms Actions</span>==

This chapter defines the controller layer of XForms, an XML Events-based <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> common set of actions that can be invoked in response to events.

<div class="note">

'''Note:'''

XForms itself defines no method for script-based event handling. The definition of such facilities is a responsibility of the hosting language.

</div>

All form controls as well as other elements defined in this specification have a set of common ''behaviors'' that encourage consistent authoring and look and feel for XForms-based applications. This consistency comes from attaching a common set of behaviors to the various form controls. In conjunction with the event binding mechanism provided by XML Events, these handlers provide a flexible means for forms authors to specify event processing at appropriate points within the XForms user interface. XForms Actions are declarative XML event handlers that capture high-level semantics. As a consequence, they significantly enhance the accessibility of XForms-based applications in comparison to previous Web technologies that relied exclusively on scripting.

The elements and attributes included in this module are:

{| summary="listing of XForms action elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#The action Element|action]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" |
([[#action-content-set|Action]])*
|-
| rowspan="1" colspan="1" |
[[#action-setvalue|setvalue]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Node Binding]], value (string XPath Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#The insert Element|insert]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Node Set Binding]], context (node XPath Expresson), at (number XPath Expression), position ("before"|"after"), origin (nodeset XPath Expresson)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#The delete Element|delete]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Node Set Binding]], context (node XPath Expresson), at (number XPath Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-setindex|setindex]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], repeat (xsd:IDREF), index (number XPath Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-toggle|toggle]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], case (xsd:IDREF)
| rowspan="1" colspan="1" | case?
|-
| rowspan="1" colspan="1" |
[[#action-setfocus|setfocus]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], control (xsd:IDREF)
| rowspan="1" colspan="1" | control?
|-
| rowspan="1" colspan="1" |
[[#The dispatch Element|dispatch]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], name (xsd:NMTOKEN), targetid (xsd:IDREF), delay (xsd:nonNegativeInteger), bubbles (xsd:boolean), cancelable (xsd:boolean)
| rowspan="1" colspan="1" | name?, targetid?, delay? [in any order]
|-
| rowspan="1" colspan="1" |
[[#action-rebuild|rebuild]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], model (xsd:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-recalculate|recalculate]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], model (xsd:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-revalidate|revalidate]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], model (xsd:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-refresh|refresh]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], model (xsd:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-reset|reset]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], model (xsd:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#The load Element|load]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional), resource (xsd:anyURI), show ("new" | "replace")
| rowspan="1" colspan="1" | resource?
|-
| rowspan="1" colspan="1" |
[[#action-send|send]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], submission (xsd:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-message|message]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional), level ("ephemeral" | "modeless" | "modal"|[[#def-QNameButNotNCName|QNameButNotNCName]])
| rowspan="1" colspan="1" |
(PCDATA|[[#elems-inline|UI Inline]])*
|}

This module also defines the content set <span id="action-content-set">'''"Action"'''</span>, which includes the following elements:

<div class="exampleInner">

 (action|setvalue|insert|delete|setindex|toggle|setfocus|dispatch|rebuild|recalculate|revalidate|refresh|reset|
 load||send|message)*

</div>

The following group of attributes, here called '''Action Common''', are available to all [[#action-content-set|Action]] elements:

{| id="attrs-action-common" summary="listing of XForms Common Action attributes" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes
|-
| rowspan="1" colspan="1" |
[[#action-content-set|Action]]
| rowspan="1" colspan="1" | if (boolean XPath Expression), while (boolean XPath Expression)
|}

; if
: Author-optional attribute defined in Section [[#Conditional Execution of XForms Actions|Conditional Execution of XForms Actions]].
; while
: Author-optional attribute defined in Section [[#Iteration of XForms Actions|Iteration of XForms Actions]].

Additionally, this module defines the attribute group <span id="action-xmlevents">'''"XML Events"'''</span>, which includes all of the "global" attributes defined in the <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> specification.

The following example shows how events can be used:

<div class="exampleOuter"><div class="exampleHead">Action Syntax</div><div class="exampleInner">

 <xforms:trigger>
   <xforms:label>Reset</xforms:label>
   <xforms:reset ev:event="DOMActivate" model="thismodel"/>
 </xforms:trigger>

</div></div>

This example recreates the behavior of the HTML ''reset'' control, which this specification does not define as an independent form control.

For each built-in XForms Action, this chapter lists the following:

<blockquote>

Name<br />Common Attributes<br />Special Attributes<br />Description of behavior

</blockquote>

All elements defined in this chapter explicitly allow global attributes from the XML Events namespace, and apply the processing defined in that specification in section 2.3 <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki>.

An <span id="action-outermost-action">'''outermost action handler'''</span> is an action that is activated when the XForms processor is not executing any other action handlers.

An <span id="action-inner-action">'''inner action handler'''</span> is an action that is activated when the XForms processor is executing the declared actions of an [[#action-outermost-action|outermost action handler]]. An inner action handler may be within the content of the outermost action handler, or it may be executed as the response to an event dispatched while performing all of the actions initiated by the [[#action-outermost-action|outermost action handler]].

<span id="action-deferred-updates">'''Deferred Updates'''</span><nowiki>: Sequences of one or more XForms Actions have a deferred effect on XForms model and user interface processing. Implementations are free to use any strategy to accomplish deferred updates, but the end result must be as follows: Instance data changes performed by a set of actions do not result in immediate computation dependency rebuilding, recalculation, revalidate and form control refreshing until the termination of the </nowiki>[[#action-outermost-action|outermost action handler]], as described here. Each XForms model can be thought of as having a set of deferred update Boolean flags, initially <code>false</code> at the start of an [[#action-outermost-action|outermost action handler]], to indicate whether each of the actions <code>rebuild</code>, <code>recalculate</code>, <code>revalidate</code>, and <code>refresh</code> are required for that model upon termination of the [[#action-outermost-action|outermost action handler]].

By default, the behavior of an action handler is performed one time when the action is encountered in the execution sequence. However, execution of an action handler may be conditional or iterated, as described in [[#Conditional Execution of XForms Actions|Conditional Execution of XForms Actions]] and [[#Iteration of XForms Actions|Iteration of XForms Actions]].

Execution of an [[#action-outermost-action|outermost action handler]] begins by setting the XForms processor into the state of executing an [[#action-outermost-action|outermost action handler]]. The [[#action-outermost-action|outermost action handler]] is then performed, which may include the execution of [[#action-inner-action|inner action handlers]]. Finally, the XForms processor is set into the state of not executing an [[#action-outermost-action|outermost action handler]] and then the deferred update is performed for each model.

The <span id="action-deferred-update-behavior">'''deferred update behavior'''</span> for a model consists of examining each deferred update Boolean flag in the order of <code>rebuild</code>, <code>recalculate</code>, <code>revalidate</code>, and <code>refresh</code>, and for each <code>true</code> flag, set the flag to <code>false</code> and then dispatch the proper event to the model for that deferred update flag (i.e. dispatch <code>xforms-rebuild</code> for a true <code>rebuild</code> flag, <code>xforms-recalculate</code> for a true <code>recalculate</code> flag, <code>xforms-revalidate</code> for a true <code>revalidate</code> flag, and <code>xforms-refresh</code> for a true <code>refresh</code> flag).

<div class="note">

'''Note:'''

The XForms processor is not considered to be executing an [[#action-outermost-action|outermost action handler]] at the time that it performs deferred update behavior for XForms models. Therefore, event handlers for events dispatched to the user interface during the deferred refresh behavior are considered to be new [[#action-outermost-action|outermost action handler]].

</div>

Actions that manipulate properties of the XForms view layer begin by invoking the [[#action-deferred-update-behavior|deferred update behavior]] so that the model and all data are up to date prior to performing the action. The XForms Actions in this category are:

<blockquote>

<code>setfocus</code><br /><code>toggle</code><br /><code>setindex</code>

</blockquote>

Actions that directly invoke rebuild, recalculate, revalidate, or refresh always have an immediate effect, and clear the corresponding deferred update flag. The XForms Actions in this category are:

<blockquote>

<code>rebuild</code><br /><code>recalculate</code><br /><code>revalidate</code><br /><code>refresh</code>

</blockquote>

Similarly, if the default processing of any of the events <code>xforms-rebuild</code>, <code>xforms-recalculate</code>, <code>xforms-revalidate</code>, or <code>xforms-refresh</code> are performed, then the corresponding deferred update flag is cleared. The XForms Actions that can dispatch these events are:

<blockquote>

<code>reset</code><br /><code>dispatch</code>

</blockquote>

XForms Actions that change the tree structure of instance data result in setting all four deferred update flags to <code>true</code> for the model over which they operate. The XForms Actions in this category are:

<blockquote>

<code>insert</code><br /><code>delete</code>

</blockquote>

XForms Actions that change only the value of an instance node results in setting the deferred update flags for <code>recalculate</code>, <code>revalidate</code>, and <code>refresh</code> to <code>true</code> and making no change to the deferred update flag for <code>rebuild</code> for the model over which they operate. The XForms Actions in this category are:

<blockquote>

setvalue<br />setindex

</blockquote>

Finally, the XForms <code>submission</code> process can affect deferred update behavior. See Section [[#The xforms-submit Event|The xforms-submit Event]] for details. XForms actions that are capable of initiating an XForms submission are:

<blockquote>

send<br />dispatch

</blockquote><div class="div2">

===<span id="action-action">The action Element</span>===

This action causes its child actions to be invoked in the order that they are specified in the document.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

<div class="exampleOuter"><div class="exampleHead">Grouping Actions</div><div class="exampleInner">

 <trigger>
   <label>Click me</label>
   <action ev:event="DOMActivate">
     <reset model="thismodel"/>
     <setvalue ref="."/>
   </action>
 </trigger>

</div></div></div><div class="div2">

===<span id="action-setvalue">The setvalue Element</span>===

This action explicitly sets the value of the specified instance data node. This action has no effect if the Single Node Binding does not select an instance data node or if a readonly instance data node is selected. An <code>xforms-binding-exception</code> occurs if the Single Node Binding indicates a node whose content is not simpleContent (i.e., a node that has element children).

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Node Binding]]

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate, with the result stored in the selected instance data node. The evaluation context for this XPath expression is the result from the Single Node Binding. To obtain the value, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

The element content of <code>setvalue</code> specifies the literal value to set; this is an alternative to specifying a computed value via attribute <code>value</code>. If neither a <code>value</code> attribute nor text content are present, the effect is to set the value of the selected node to the empty string (""). If both are present, the <code>value</code> attribute is used. The following examples contrast these approaches:

<div class="exampleOuter"><div class="exampleHead">setvalue with Expression</div><div class="exampleInner">

 <setvalue bind="put-here" value="a/b/c"/>

</div>

This causes the string value at <code>a/b/c</code> in the instance data to be placed on the single node selected by the bind element with <code>id="put-here"</code>.

</div><div class="exampleOuter"><div class="exampleHead">setvalue with Literal</div><div class="exampleInner">

 <setvalue bind="put-here">literal string</setvalue>

</div>

This causes the value "literal string" to be placed on the single node selected by the bind element with <code>id="put-here"</code>.

</div><div class="note">

'''Note:'''

See Section [[#The context() Function|The context() Function]] for an example in which the <code>context()</code> function is used to provide the same initial evaluation context node to both the <code>ref</code> and <code>value</code> attributes. See Appendix [[#Patterns for Data Mutations|Patterns for Data Mutations]] for numerous further usage patterns for <code>sevalue</code>, <code>insert</code> and <code>delete</code>.

</div>

All strings are inserted into the instance data as follows:

* Element nodes: If element child nodes are present, then an <code>xforms-binding-exception</code> occurs. Otherwise, regardless of how many child nodes the element has, the result is that the string becomes the new content of the element. In accord with the data model of <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki>, the element will have either a single non-empty text node child, or no children string was empty.
* Attribute nodes: The string-value of the attribute is replaced with a string corresponding to the new value.
* Text nodes: The text node is replaced with a new one corresponding to the new value, or the text node is eliminated if the new value is the empty string.
* Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
* the XPath root node: an <code>xforms-binding-exception</code> occurs.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]] by setting the deferred update flags for recalculate, revalidate and refresh.

</div></div><div class="div2">

===<span id="action-insert">The insert Element</span>===

The <code>insert</code> action is used to create one or more nodes of instance data by cloning one or more existing instance nodes. Attributes of the <code>insert</code> action specify the node or nodes to be cloned and the location within instance data where the clones will appear. The clones are deep copies of the original nodes except the contents of nodes of type <code>xsd:ID</code> are modified to remain as unique values in the instance data after the clones are inserted.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Node Set Binding]] (author-optional)

Special Attributes:

; context
: Author-optional attribute containing an XPath expression evaluated using the in-scope evaluation context. If the <code>model</code> attribute is present, then it is processed as described in [[#Evaluation Context|Evaluation Context]] before evaluating this attribute. The Node Set Binding is required unless this attribute is present. The result of the XPath expression is used to override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then the insert action is terminated with no effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context node, and the context position and size are set to 1. By adjusting the in-scope evaluation context, this attribute affects the subsequent evaluation of many other attributes that can appear on <code>insert</code>, including <code>if</code>, <code>while</code>, <code>nodeset</code> and <code>origin</code>.
; origin
: Author-optional attribute containing an XPath expression evaluated using the in-scope evaluation context , which may have been amended by the <code>context</code> attribute. The <code>origin node-set</code> is the set of one or more nodes to be cloned by the <code>insert</code> action. If this attribute is present and resolves to a non-empty nodeset, then the result overrides the default setting of the <code>origin node-set</code> as described below in the processing of the <code>insert</code> action.
; at
: Author-optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to help determine the <code>insert location node</code>. This attribute is ignored if the Node Set Binding is not specified or specifies an empty node-set. The <code>insert location node</code> is a node within the Node Set Binding node-set that is used to help determine where in the instance to insert each node cloned by the <code>insert</code>. If this attribute is present, then its result is used to override the default setting of the <code>insert location node</code> as described below in the processing of the <code>insert</code> action.
; position
: Author-optional selector that indicates where to put the cloned node or nodes relative to the <code>insert location node</code>. Valid values are <code>before</code> and <code>after</code>, and the latter is the default. This attribute is ignored if the Node Set Binding node-set is not specified or empty. If the node at the <code>insert location node</code> within the Node Set Binding node-set is the document element of an instance, then this attribute is ignored.

Processing for the <code>insert</code> action is as follows:

# The <code>insert context</code> is determined. If the <code>context</code> attribute is not given, the <code>insert context</code> is the in-scope evaluation context. Otherwise, the XPath expression provided by the <code>context</code> attribute is evaluated using the in-scope evaluation context, and the first node rule is applied to obtain the <code>insert context</code>. The <code>insert</code> action is terminated with no effect if the <code>insert context</code> is the empty node-set.
# The Node Set Binding node-set is determined. If a <code>bind</code> attribute is present, it directly determines the Node Set Binding node-set. If a <code>nodeset</code> attribute is present, it is evaluated within the <code>insert context</code> to determine the Node Set Binding node-set. If the Node Set Binding attributes are not present, then the Node Set Binding node-set is the empty node-set. The <code>insert</code> action is terminated with no effect if any of the following conditions is true:
## The <code>context</code> attribute is not given and the Node Set Binding node-set is the empty node-set.
## The <code>context</code> attribute is given, the <code>insert context</code> does not evaluate to an element node and the Node Set Binding node-set is the empty node-set.
# The <code>origin node-set</code> is determined. If the <code>origin</code> attribute is not given and the Node Set Binding node-set is empty, then the <code>origin node-set</code> is the empty node-set. Otherwise, if the <code>origin</code> attribute is not given, then the <code>origin node-set</code> consists of the last node of the Node Set Binding node-set. If the <code>origin</code> attribute is given, the <code>origin node-set</code> is the result of the evaluation of the <code>origin</code> attribute in the <code>insert context</code>. Namespace nodes and root nodes (parents of document elements) are removed from the <code>origin node-set</code>. The <code>insert</code> action is terminated with no effect if the <code>origin node-set</code> is the empty node-set.
# The <code>insert location node</code> is determined. If the Node Set Binding node-set is not specified or empty, the <code>insert location node</code> is the <code>insert context</code> node. Otherwise, if the <code>at</code> attribute is not given, then the <code>insert location node</code> is the last node of the Node Set Binding node-set. Otherwise, an <code>insert location node</code> is determined from the <code>at</code> attribute as follows:
## The evaluation context node is the first node in document order from the Node Set Binding node-set, the context size is the size of the Node Set Binding node-set, and the context position is <code>1</code>.
## The return value is processed according to the rules of the XPath function <code>round()</code>. For example, the literal <code>1.5</code> becomes <code>2</code>, and the literal <code>'string'</code> becomes <code>NaN</code>.
## If the result is in the range 1 to the Node Set Binding node-set size, then the <code>insert location</code> is equal to the result. If the result is non-positive, then the <code>insert location</code> is <code>1</code>. Otherwise, the result is <code>NaN</code> or exceeds the Node Set Binding node-set size, so the <code>insert location</code> is the Node Set Binding node-set size.
## The <code>insert location node</code> is the node in the Node Set Binding node-set at the position given by the <code>insert location</code>.
# The <code>insert</code> action is terminated with no effect if the insertion will create nodes whose parent is readonly. This occurs if the <code>insert location node</code> is readonly and the Node Set Binding node-set is not specified or empty, or otherwise if the parent of the <code>insert location node</code> is readonly.
# Each node in the <code>origin node-set</code> is cloned in the order it appears in the <code>origin node-set</code>.
# The <code>target location</code> of each of the cloned nodes is determined as follows:
## If the Node Set Binding node-set is not specified or empty, then the <code>insert location node</code> provided by the <code>context</code> attribute is intended to be the parent of the cloned node. The <code>target location</code> is dependent on the types of the cloned node and the <code>insert location node</code> as follows:
##* If the <code>insert location node</code> is not an element node or root node, then it cannot be the parent of the cloned node, so the <code>target location</code> is undefined.
##* If the <code>insert location node</code> is the root node of an instance (which is the parent of the root element), and the cloned node is an element, then the <code>target location</code> is the root element of the instance.
##* If the <code>insert location node</code> is the root node of an instance (which is the parent of the root element), and the cloned node is not an element, then the <code>target location</code> is before the first child of the <code>insert location node</code>.
##* If the <code>insert location node</code> is an element, and the cloned node is an attribute, then the <code>target location</code> is the attribute list of the <code>insert location node</code>.
##* If the <code>insert location node</code> is an element, and the cloned node is not an attribute, then the <code>target location</code> is before the first child of the <code>insert location node</code>, or the child list of the <code>insert location node</code> if it is empty.
## Otherwise, the Node Set Binding node-set is specified and non-empty, so the <code>insert location node</code> provided by the Node Set Binding and author-optional <code>at</code> attribute is intended to be the sibling of the cloned node. If the <code>insert location node</code> is an attribute or root node, then the <code>target location</code> is undefined. If the <code>insert location node</code> is not an attribute or root node, then the <code>target location</code> is immediately before or after the <code>insert location node</code>, based on the <code>position</code> attribute setting or its default.
# The cloned node or nodes are inserted in the order they were cloned into their <code>target locations</code> depending on their node type. If the parent node of the target location is the instance root node (which is the parent of the root document element of the instance), and if the cloned node is an element, then the instance root element is deleted before the cloned node is inserted at the target location. If the cloned node is a duplicate of another attribute in its parent element, then either the duplicate attribute is first removed or the existing attribute value is updated. If a cloned node cannot be placed at the <code>target location</code> due to a node type conflict or because the <code>target location</code> is undefined, then the insertion for that particular cloned node is ignored. Each cloned node that is inserted is added to the <code>inserted-nodes</code> list that will be provided in the <code>xforms-insert</code> event context information. For each cloned node used to update an existing attribute node, the existing attribute node is added to the list of <code>inserted-nodes</code>.<div class="note">'''Note:'''A node type conflict is a mismatch between the XPath node type and the <code>target location</code>. For example, an attribute cannot be inserted as a sibling before or after an element.</div>
# If the list of <code>inserted-nodes</code> is empty, then the <code>insert</code> action is terminated with no effect.
# The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
# The <code>insert</code> action is successfully completed by dispatching the <code>xforms-insert</code> event with appropriate context information.<div class="note">'''Note:'''A <code>repeat</code> updates its index in response to this event if its repeat collection changes size as a result of the insertion. See Section [[#Repeat Processing|Repeat Processing]] for details.</div>

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]] by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.

</div>

Examples:

<div class="exampleOuter"><div class="exampleHead">Inserting into a <code>repeat</code>, whether or not it is empty</div>

When the <code>repeat</code> is empty, the <code>at</code> index is zero so a new <code>item</code> is prepended to the child elements of <code>purchaseOrder</code>. When the <code>repeat</code> is non-empty, the new <code>item</code> is added after the node currently indexed by repeat <code>R</code>.

<div class="exampleInner">

 ...
 <xforms:instance>
    <purchaseOrder xmlns="">
         <subtotal/>
         <tax/>
         <total/>
    </purchaseOrder>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
        ...
        <item>
            <product/>
            <quantity/>
            <unitcost/>
            <price/>
        </item>
        ...
     </prototypes>
 </xforms:instance>
 ...
 <repeat nodeset="/purchaseOrder/item" id="R">
    ...
 </repeat>
 ...
 <xforms:trigger>
   <xforms:label>Add to purchase order</xforms:label>
   <xforms:action ev:event="DOMActivate>
     <xforms:insert context="/purchaseOrder" nodeset="item" at="index('R')" origin="instance('prototypes')/item"/>
     <xforms:setfocus control="R"/>
   </xforms:action>
 </xforms:trigger>
 

</div></div><div class="exampleOuter"><div class="exampleHead">Insert and Read-Only Content</div><div class="exampleInner">

 <model xmlns:my="http://example.org">
   <instance>
     <my:data>
       <my:name>
         <my:first-name>John</my:first-name>
         <my:last-name>Doe</my:last-name>
       </my:name>
       <my:address>
         <my:street>123 Main St.</my:street>
         <my:city>Smallville</my:city>
       </my:address>
     </my:data>
   </instance>
 
   <bind nodeset="/my:data/my:name/" readonly="true()"/>
   <bind nodeset="/my:data/my:address/my:street" readonly="true()"/>
 
   <action ev:event="xforms-model-construct-done">
       <insert id="I1" nodeset="my:name/*" ... />
       <insert id="I2" nodeset="my:address/my:street" at="1" >
   </action>
 </model>

</div>

Insert I1 fails because it attempts to insert into the content of a readonly node (<code>my:name</code>). Insert I2 succeeds even though the insert location is a readonly node because the new node is placed as a sibling into the content of the parent, which is not readonly.

</div>

See [[#The delete Element|The delete Element]] for an example that uses <code>insert</code> and <code>delete</code> to make a <code>repeat</code> that always shows at least one repeat item. See Appendix [[#Patterns for Data Mutations|Patterns for Data Mutations]] for numerous further usage patterns for <code>sevalue</code>, <code>insert</code> and <code>delete</code>.

</div><div class="div2">

===<span id="action-delete">The delete Element</span>===

This action deletes one or more nodes from instance data.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Node Set Binding]]

Special Attributes:

; context
: Author-optional attribute containing an XPath expression evaluated using the in-scope evaluation context. If the <code>model</code> attribute is present, then it is processed as described in [[#Evaluation Context|Evaluation Context]] before evaluating this attribute. The Node Set Binding is required unless this attribute is present. The result of the XPath expression is used to override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then the <code>delete</code> action is terminated with no effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context node, and the context position and size are set to 1. By adjusting the in-scope evaluation context, this attribute affects the evaluation of subsequent attributes that may appear on <code>delete</code>, including <code>if</code>, <code>while</code>, and <code>nodeset</code>.
; at
: Author-optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to determine the <code>delete location</code>. If the Node Set Binding node-set is empty, then this attribute is ignored.

Processing for the <code>delete</code> action is as follows:

# The <code>delete context</code> is determined. It is set to the in-scope evaluation context, possibly overridden by the <code>context</code> attribute if that attribute is present. The <code>delete</code> action is terminated with no effect if the <code>delete context</code> is the empty node-set.
# The Node Set Binding node-set is determined. If a <code>bind</code> attribute is present, it directly determines the Node Set Binding node-set. If a <code>nodeset</code> attribute is present, it is evaluated within the <code>delete context</code> to determine the Node Set Binding node-set. The behavior of the <code>delete</code> action is undefined if the Node Set Binding node-set contains nodes from more than one <code>instance</code>. The <code>delete</code> action is terminated with no effect if the Node Set Binding is expressed and the Node Set Binding node-set is the empty node-set. Otherwise, the Node Set Binding is not expressed, so the Node Set Binding node-set is set equal to the delete context node with a position and size of 1.
# The <code>delete location</code> is determined. If the <code>at</code> attribute is not specified, there is no <code>delete location</code>. Otherwise, the <code>delete location</code> is determined by evaluating the XPath expression specified by the <code>at</code> attribute as follows:
## The evaluation context node is the first node in document order from the Node Set Binding node-set, the context size is the size of the Node Set Binding node-set, and the context position is <code>1</code>.
## The return value is processed according to the rules of the XPath function <code>round()</code>. For example, the literal <code>1.5</code> becomes <code>2</code>, and the literal <code>'string'</code> becomes <code>NaN</code>.
## If the result is in the range 1 to the Node Set Binding node-set size, then the <code>delete location</code> is equal to the result. If the result is non-positive, then the <code>delete location</code> is <code>1</code>. Otherwise, if the result is <code>NaN</code> or exceeds the Node Set Binding node-set size, the <code>delete location</code> is the Node Set Binding node-set size.
# If there is no <code>delete location</code>, each node in the Node Set Binding node-set is deleted, except if the node is a readonly node, a namespace node, a root node, or the root document element of an instance, then that particular node is not deleted. Otherwise, if there is a <code>delete location</code>, the node at the <code>delete location</code> in the Node Set Binding node-set is deleted, except if the node is the root document element of an instance or has a readonly parent node, then that node is not deleted. The delete action is terminated with no effect if no node is deleted.
# The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
# The <code>delete</code> action is successfully completed by dispatching the <code>xforms-delete</code> event with appropriate context information.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]] by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.

</div>

Examples:

<div class="exampleOuter"><div class="exampleHead">Using <code>delete</code> and <code>insert</code> to Maintain a Non-empty repeat <code>repeat</code></div>

In this example, the <code>trigger</code> is not in the <code>repeat</code>. When it is activated, the indexed <code>item</code> in the repeat is first deleted. Next, if that was the last <code>item</code>, then a new prototypical <code>item</code> is inserted so that the <code>repeat</code> does not become empty. The focus is then sent back to the <code>repeat</code> from the <code>trigger</code>.

<div class="exampleInner">

 ...
 <xforms:trigger>
   <xforms:label>Delete from purchase order</xforms:label>
   <xforms:action ev:event="DOMActivate">
     <xforms:delete context="/purchaseOrder" nodeset="item" at="index('R')"/>
     <xforms:insert context="/purchaseOrder" if="not(item)"
                    nodeset="item" origin="instance('prototypes')/item"/>
     <xforms:setfocus control="R"/>
   </xforms:action>
 </xforms:trigger>
 

</div><div class="note">

'''Note:'''

The form author could have written <code>nodeset="/purchaseOrder/item"</code> in the <code>delete</code> action, but the <code>context</code> attribute was added for consistency with the <code>insert</code> action.

</div></div><div class="exampleOuter"><div class="exampleHead">Delete and Read-Only Content</div><div class="exampleInner">

 <model xmlns:my="http://example.org">
   <instance>
     <my:data>
       <my:name>
         <my:first-name>John</my:first-name>
         <my:last-name>Doe</my:last-name>
       </my:name>
       <my:address>
         <my:street>123 Main St.</my:street>
         <my:city>Smallville</my:city>
       </my:address>
     </my:data>
   </instance>
 
   <bind nodeset="/my:data/my:name/" readonly="true()"/>
   <bind nodeset="/my:data/my:address/my:street" readonly="true()"/>
 
   <action ev:event="xforms-model-construct-done">
       <delete id="D1" nodeset="my:name/*" ... />
       <delete id="D2" nodeset="my:address/my:street" at="1" >
       <delete id="D3" nodeset="my:address" at="1" >
   </action>
 </model>

</div>

Delete D1 fails because it attempts to delete from the content of a readonly node (<code>my:name</code>). Delete D2 succeeds even though the node to delete is readonly because the node is not being changed, but rather removed from the content of the parent, which is not readonly. Delete D3 succeeds even though it contains a readonly node because a node can be deleted if its parent is not readonly, and node deletion includes deletion of its attributes and content, regardless of whether or not the attributes or content nodes are readonly.

</div>

See Appendix [[#Patterns for Data Mutations|Patterns for Data Mutations]] for numerous further usage patterns for <code>sevalue</code>, <code>insert</code> and <code>delete</code>.

</div><div class="div2">

===<span id="action-setindex">The setindex Element</span>===

This XForms Action begins by invoking the [[#action-deferred-update-behavior|deferred update behavior]]. This action then marks a specific item as current in a repeating sequence (within [[#The repeat Element|The repeat Element]]).

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; repeat
: Required reference to a repeating element.
; index
: Required XPath expression that evaluates to a 1-based offset into the sequence. The evaluation context is determined in the same manner as the evaluation context for a Single-Node Binding (see [[#Evaluation Context|Evaluation Context]]).

If the selected index is 0 or less, an <code>xforms-scroll-first</code> event is dispatched and the index is set to 1. If the selected index is greater than the index of the last repeat item, an <code>xforms-scroll-last</code> event is dispatched and the index is set to that of the last item. If the index evaluates to NaN the action has no effect.

<div class="note">

'''Note:'''

The IDREF from the <code>repeat</code> attribute may not uniquely identify the desired [[#ui-repeat|repeat]] if the <code>repeat</code> element bearing the matching ID resides within the content of another <code>repeat</code>. The general method described in [[#Resolving ID References in XForms|Resolving ID References in XForms]] is used to determine the desired run-time repeat object.

</div><div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]] by performing deferred update in its initialization and by setting the deferred update flags for recalculate, revalidate and refresh.

</div></div><div class="div2">

===<span id="action-toggle">The toggle Element</span>===

This XForms Action begins by invoking the [[#action-deferred-update-behavior|deferred update behavior]]. This action then selects one possible case from an exclusive list of alternatives in a <code>switch</code>.

This action performs the following:

# Dispatches an <code>xforms-deselect</code> event to the currently selected <code>case</code> in the <code>switch</code> containing the identified <code>case</code>.
# Adjusts the <code>selected</code> states (not the attribute values) on the affected cases to reflect the new state of the <code>switch</code> containing the identified <code>case</code>.
# Dispatches an <code>xform-select</code> event to the <code>case</code> just selected.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; case
: Author-optional reference to a <code>case</code> element. The [[#ui-case|case]] to select is specified by this attribute or by the child element [[#action-toggle-case|case]].

The <code>case</code> to be selected by the <code>switch</code> is identified by IDREF either by the attribute <code>case</code> or by a child [[#action-toggle-case|case]] element. If no <code>case</code> element contains the given identifier, then this action has no effect.

<div class="note">

'''Note:'''

Whether the IDREF is obtained from the <code>case</code> attribute or element, the IDREF may not uniquely identify the desired [[#ui-case|case]] if the <code>case</code> element bearing the matching ID resides in a repeating construct such as element <code>repeat</code>. The general method described in [[#Resolving ID References in XForms|Resolving ID References in XForms]] is used to determine the desired run-time case object.

</div><div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]] by performing deferred update in its initialization.

</div><div class="div3">

====<span id="action-toggle-case">The case Element Child of the toggle Element</span>====

This section defines a child element of <code>toggle</code> named <code>case</code> that is an alternate means of providing the identity of a [[#ui-case|case]] element to select with a [[#ui-switch|switch]].

Element: <code>case</code>

Common attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the [[#ui-case|case]] identity, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The [[#ui-case|case]] to be selected by the <code>toggle</code> action is given by the <code>case</code> attribute or the <code>case</code> element. If both are given, the element takes precedence. Due to the addition of the element, the <code>case</code> attribute is no longer required, but either the <code>case</code> attribute or the <code>case</code> element must appear. The <code>case</code> element can provide the identity of a [[#ui-case|case]] with either its string content or the <code>value</code> attribute. If both are given, then the <code>value</code> attribute takes precedence.

<div class="exampleOuter"><div class="exampleInner">

 <toggle>
 <case value="concat('case_', ../addressBlockType)"/>
 </toggle>

</div></div></div></div><div class="div2">

===<span id="action-setfocus">The setfocus Element</span>===

This XForms Action begins by invoking the [[#action-deferred-update-behavior|deferred update behavior]]. This action then dispatches an <code>xforms-focus</code> event ([[#The xforms-focus Event|The xforms-focus Event]]) to the element identified by attribute <code>control</code> or child element <code>control</code>.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; control
: Author-optional reference to a [[#def-form-control|form control]]. The form control is specified by this attribute or by the child element [[#action-setfocus-control|control]].

The identity of the element to which the <code>setfocus</code> action dispatches <code>xforms-focus</code> is given by the <code>control</code> attribute or the [[#action-setfocus-control|control]] element. If no such element contains the given identifier, then this action has no effect.

<div class="note">

'''Note:'''

Whether the IDREF is obtained from the <code>control</code> attribute or element, the IDREF may not uniquely identify the desired form control if the element bearing the matching ID resides in a repeating construct such as element <code>repeat</code>. The general method described in [[#Resolving ID References in XForms|Resolving ID References in XForms]] is used to determine the desired form control.

</div><div class="note">

'''Note:'''

Changing the focus to a form control within a repeat object may cause one or more repeat index values to be changed as described in Section [[#User Interface Interaction|User Interface Interaction]].

</div><div class="div3">

====<span id="action-setfocus-control">The control Element Child of the setfocus Element</span>====

This section defines a child element of <code>setfocus</code> named <code>control</code> that is an alternate means of providing the element that receives the <code>xforms-focus</code> event.

Element: <code>control</code>

Common attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the desired element identifier, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The identity of the element to which the <code>setfocus</code> action dispatches <code>xforms-focus</code> is given by the <code>control</code> attribute or the <code>control</code> element. If both are given, the element takes precedence. Due to the addition of the element, the <code>control</code> attribute is no longer required, but either the <code>control</code> attribute or the <code>control</code> element must appear. The <code>control</code> element can provide the desired element identifier with either its string content or the <code>value</code> attribute. If both are given, then the <code>value</code> attribute takes precedence.

<div class="exampleOuter"><div class="exampleInner">

 <setfocus>
 	<control value="concat('input_', ../paymentType)"/>
 </setfocus>

</div></div></div></div><div class="div2">

===<span id="action-dispatch">The dispatch Element</span>===

This action dispatches an XML Event to a specific target element. Two kinds of event can be dispatched:

# Predefined XForms events (i.e., xforms-''event-name''), in which case the <code>bubbles</code> and <code>cancelable</code> attributes are ignored and the standard semantics as defined in [[#Processing Model|Processing Model]] apply.
# An event created by the XForms author with no predefined XForms semantics and as such not handled by default by the XForms Processor.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; name
: Author-optional attribute for specifying the name of the event to dispatch.
; targetid
: Author-optional attribute for specifying the reference to the event target.
; delay
: Author-optional attribute that indicates the minimum number of milliseconds to delay dispatching of the event to the target. The default is the empty string, which indicates no delay.
; bubbles
: Author-optional attribute containing a boolean indicating if this event bubbles—as defined in <nowiki>[</nowiki>[[#ref-dom2-events |DOM2 Events]]<nowiki>]</nowiki>. The default value is <code>true</code> for a custom event. For predefined events, this attribute has no effect.
; cancelable
: Author-optional attribute containing a boolean indicating if this event is cancelable—as defined in <nowiki>[</nowiki>[[#ref-dom2-events |DOM2 Events]]<nowiki>]</nowiki>. The default value is <code>true</code> for a custom event. For predefined events, this attribute has no effect.

The event to be dispatched is given by the <code>name</code> attribute or the [[#The name Child Element|name]] child element. Due to the addition of the <code>name</code> element, the <code>name</code> attribute is not required, but either the <code>name</code> attribute or the <code>name</code> element must appear. If the event name is not specified or empty string, then this action has no effect.

The element to which the event is to be dispatched is identified by the <code>targetid</code> attribute or the [[#The targetid Child Element|targetid]] child element. Due to the addition of the <code>targetid</code> element, the <code>targetid</code> attribute is not required, but this action has no effect unless the target identifier is specified by the element or attribute. For backwards compatibility with documents created for earlier versions of the specification, the processor of the <code>dispatch</code> element [[#intro-reading|may]] allow the attribute named <code>target</code> and the child element <code>target</code> to be used. The attribute and element named <code>target</code> provide exactly the same behaviors as the <code>targetid</code> attribute and element, except that the <code>target</code> attribute and element are ignored if the <code>dispatch</code> element also bears a <code>targetid</code> attribute or contains a <code>targetid</code> child element.

<div class="note">

'''Note:'''

Whether the IDREF is obtained from the <code>targetid</code> attribute or <code>targetid</code> element, the IDREF may not uniquely identify the desired target object if the element bearing the matching ID resides in a repeating construct such as element <code>repeat</code>. The general method described in [[#Resolving ID References in XForms|Resolving ID References in XForms]] is used to determine the desired target object.

</div>

The event may be dispatched immediately or after a specified non-negative number of milliseconds of delay. The event delay is specified the <code>delay</code> attribute or by the child element [[#The delay Child Element|delay]]. If the delay is not specified or if the given value does not conform to <code>xsd:nonNegativeInteger</code>, then the event is dispatched immediately as the result of the <code>dispatch</code> action. Otherwise, the specified event is added to the delayed event queue unless an event with the same name and target element already exists on the delayed event queue. The <code>dispatch</code> action has no effect if the event delay is a non-negative integer and the specified event is already in the delayed event queue.

<div class="note">

'''Note:'''

Since an element bearing a particular ID may be repeated, the delayed event queue may contain more than one event with the same name and target IDREF. It is the name and the target '''run-time element''' that must be unique.

</div>

If a run-time element is destroyed, then any delayed events targeted at that element are removed from the delayed event queue. A run-time element may be destroyed for a number of reasons, including shutdown of the form or removal of form controls associated by a <code>repeat</code> with an instance data node that is destroyed.

As soon as possible after the specified delay in milliseconds has elapsed, the event is removed from the delayed event queue and then dispatched. In the same manner used to handle user-generated events or the completion of an asynchronous submission, the dispatch and processing of delayed events is done without interrupting the processing of another event and its event handlers.

<div class="note">

'''Note:'''

Because the delayed event is first removed from the delayed event queue and then dispatched, a handler for a given event may dispatch the event again with a delay. This can be used to perform simple polling and asynchronous looping operations. Moreover, the [[#action-conditional|if]] attribute can be applied to the <code>dispatch</code> action to decide when to discontinue the polling or looping based on a setting in instance data.

</div><div class="div3">

====<span id="action-dispatch-name">The name Child Element</span>====

This section defines a new child element of <code>dispatch</code> that provides an alternate means of specifying the name of the event to dispatch.

Element: <code>name</code>

Common attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the event name, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The event name of the <code>dispatch</code> action is given by the <code>name</code> attribute or the <code>name</code> element. If both are given, the element takes precedence. The <code>name</code> element can provide the event name with either its string content or the <code>value</code> attribute. If both are given, then the <code>value</code> attribute takes precedence.

</div><div class="div3">

====<span id="action-dispatch-targetid">The targetid Child Element</span>====

This section defines a new child element of <code>dispatch</code> that provides an alternate means of specifying the target of the event to be dispatched.

Element: <code>targetid</code>

Common attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the event target, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The event target of the <code>dispatch</code> action is given by the <code>targetid</code> attribute or the <code>targetid</code> element. If both are given, the element takes precedence. The <code>targetid</code> element can provide an IDREF for the event target with either its string content or the <code>value</code> attribute. If both are given, then the <code>value</code> attribute takes precedence.

</div><div class="div3">

====<span id="action-dispatch-delay">The delay Child Element</span>====

This section defines a new child element of <code>dispatch</code> that provides an alternate means of specifying the delay imposed on the event to be dispatched.

Element: <code>delay</code>

Common attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the event delay, the result of the expression is processed as if by call to the XPath <code>string</code> function. If the result does not conform lexically to <code>xsd:nonNegativeInteger</code>, then the result of empty string is used. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The event delay of the <code>dispatch</code> action is given by the <code>delay</code> attribute or the <code>delay</code> element. If both are given, the element takes precedence. The <code>delay</code> element can provide the delay with either its string content or the <code>value</code> attribute. If both are given, then the <code>value</code> attribute takes precedence.

</div></div><div class="div2">

===<span id="action-rebuild">The rebuild Element</span>===

This action causes the default processing of <code>xforms-rebuild</code> to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the <code>xforms-rebuild</code> event). This action results in the XForms Processor rebuilding any internal data structures used to track computational dependencies among instance data nodes —see [[#The xforms-rebuild Event|The xforms-rebuild Event]].

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; model
: Author-optional XForms Model selector, as defined in [[#Single-Node Binding Attributes|Single-Node Binding Attributes]]. If this attribute is omitted, then the default is the <code>model</code> associated with the in-scope evaluation context node.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]].

</div></div><div class="div2">

===<span id="action-recalculate">The recalculate Element</span>===

This action causes the default processing of <code>xforms-recalculate</code> to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the <code>xforms-recalculate</code> event). As a result, instance data nodes whose values need to be recalculated are updated as specified in the processing model—see [[#The xforms-recalculate Event|The xforms-recalculate Event]].

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; model
: Author-optional XForms Model selector, as defined in [[#Single-Node Binding Attributes|Single-Node Binding Attributes]]. If this attribute is omitted, then the default is the <code>model</code> associated with the in-scope evaluation context node.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]].

</div></div><div class="div2">

===<span id="action-revalidate">The revalidate Element</span>===

This action causes the default processing of <code>xforms-revalidate</code> to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the <code>xforms-revalidate</code> event). This results in the instance data being revalidated as specified by the processing model—see [[#The xforms-revalidate Event|The xforms-revalidate Event]].

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; model
: Author-optional XForms Model selector, as defined in [[#Single-Node Binding Attributes|Single-Node Binding Attributes]]. If this attribute is omitted, then the default is the <code>model</code> associated with the in-scope evaluation context node.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]].

</div></div><div class="div2">

===<span id="action-refresh">The refresh Element</span>===

This action causes the default processing of <code>xforms-refresh</code> to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the <code>xforms-refresh</code> event). This action results in the XForms user interface being ''refreshed'', and the presentation of user interface controls being updated to reflect the state of the underlying instance data—see [[#The xforms-refresh Event|The xforms-refresh Event]].

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; model
: Author-optional XForms Model selector, as defined in [[#Single-Node Binding Attributes|Single-Node Binding Attributes]]. If this attribute is omitted, then the default is the <code>model</code> associated with the in-scope evaluation context node.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]].

</div></div><div class="div2">

===<span id="action-reset">The reset Element</span>===

This action initiates reset processing by dispatching an <code>xforms-reset</code> event to the specified <code>model</code>. Processing of event <code>xforms-reset</code> is defined in the processing model—see [[#The xforms-reset Event|The xforms-reset Event]].

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; model
: Author-optional XForms Model selector, as defined in [[#Single-Node Binding Attributes|Single-Node Binding Attributes]]. If this attribute is omitted, then the default is the <code>model</code> associated with the in-scope evaluation context node.

<div class="note">

'''Note:'''

This action affects [[#action-deferred-updates|deferred updates]].

</div></div><div class="div2">

===<span id="action-load">The load Element</span>===

This action traverses the specified link.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single-Node Binding]] (author-optional)

Special Attributes:

; resource
: Author-optional attribute. Link to an external resource to load.
; show
: Author-optional link behavior specifier. The allowed values are "replace" and "new". If this attribute is missing, a default value of "replace" is assumed.

The URI specifying the link to traverse may be pointed to by the Single Node Binding attributes, if given, or by the <code>resource</code> attribute or the [[#The resource Element child of load|resource]] child element. Individually, the Single Node Binding, <code>resource</code> element and <code>resource</code> attribute are not required. If none are given, the action has no effect. If the Single Node Binding is present and does not select an instance data node, then this action has no effect. If the Single Node Binding is given in addition to one of the <code>resource</code> attribute or <code>resource</code> element, then the action has no effect.

The URI obtained in this manner is treated as a link to an external resource, defined as an <nowiki>[</nowiki>[[#ref-xlink-1.0 |XLink 1.0]]<nowiki>]</nowiki> link between the <code>load</code> element and the remote resource indicated. No XLink <code>actuate</code> value is defined, since control of actuation is defined by XML Events. The XLink <code>show</code> value depends on the <code>show</code> attribute.

The link indidicated by the URI obtained above is traversed. If the link traversal fails, then an implementation-specific means of conveying the link traversal failure occurs. Otherwise, processing for the document (or portion of the document) reached by traversing the link is specified by the <code>show</code> attribute. The following are the possible values for the <code>show</code> attribute and the corresponding processing behaviors:

; new
: The document is loaded into a new presentation context, e.g., a new window. Form processing in the original window continues.
; replace
: The document is loaded into the current window. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document.

<div class="div3">

====<span id="action-load-resource">The resource Element child of load</span>====

When it appears as the first child element of <code>load</code>, the <code>resource</code> element provides the URI of the link, overriding the <code>resource</code> attribute. As stated above, the <code>load</code> action has no effect if both a <code>resource</code> and a Single Node Binding are given. This element allows the URI used by the <code>load</code> to be dynamically calculated based on instance data.

Common Attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the URI, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The URI to be used by the <code>load</code> can be specified with either the <code>value</code> attribute or the string content of the <code>resource</code> element. If both are specified, then the <code>value</code> attribute takes precedence. If the <code>load</code> does not have a <code>resource</code> element as its first child, then the URI is obtained from the <code>resource</code> attribute or the Single Node Binding, if given.

</div></div><div class="div2">

===<span id="action-send">The send Element</span>===

This action initiates submit processing by dispatching an <code>xforms-submit</code> event. Processing of event <code>xforms-submit</code> is defined in the processing model—see [[#The xforms-submit Event|The xforms-submit Event]].

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]]

Special Attributes:

; submission
: Author-optional attribute containing a reference to a <code>submission</code> element. If this attribute is given but does not identify a <code>submission</code> element, then the <code>send</code> action has no effect. If this attribute is omitted, then the first <code>submission</code> in document order from the <code>model</code> associated with the in-scope evaluation context is used.

</div><div class="div2">

===<span id="action-message">The message Element</span>===

This action encapsulates a message to be displayed to the to the user.

Common Attributes: [[#structure-attrs-common|Common]], [[#action-xmlevents|Events]], [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Node Binding]] (author-optional)

Special Attributes:

; level
: Author-optional attribute containing a message level identifier, one of ("ephemeral"|"modeless"|"modal"|[[#def-QNameButNotNCName|QNameButNotNCName]]). The default is "modal" if the attribute is not specified. This specification does not define behavior for [[#def-QNameButNotNCName|QNameButNotNCName]] values.

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, inline text.

The user interface for the <code>message</code> action is considered to be created at the time the action occurs. If the message is obtained from the inline content of the <code>message</code> action, then the output of any <code>output</code> controls in the <code>message</code> content is determined based on the instance data available when the <code>message</code> action occurs. For example, the following example displays the message <code>Hello, world!</code> as the form starts up:

<div class="exampleInner">

 <model>
      <instance>
          <data xmlns="">
              <name>John</name>
          </data>
      </instance>
 
      <action ev:event="xforms-ready">
          <setvalue ref="name">world</setvalue>
          <message level="modal">Hello, <output ref="name"/>!</message>
   ...</action>
 </model>

</div>

In this example, the message includes the latest user input even though other form controls not in the <code>message</code> action are not guaranteed to be updated until the end of the <code>xforms-refresh</code> event processing:

<div class="exampleInner">

 <input ref="birthday">
      <label>Enter birthday:</label>
      <message ev:event="xforms-invalid"><output ref="."/> isn't a valid birthday</message>
 </input>

</div><div class="note">

'''Note:'''

Due to deferred update behavior, if a <code>message</code> action is preceded in an action sequence by other actions that change instance nodes, and the message references nodes that are computationally dependent on the changed nodes, then the form author should invoke the <code>recalculate</code> action before the <code>message</code> action. Moreover, if the computational dependencies involved nodes that were inserted or deleted, then the form author should invoke <code>rebuild</code> prior to the <code>recalculate</code>.

</div>

A graphical browser might render a modal message as follows:

<div class="exampleInner">

 <model>
   <message level="modal" ev:event="xforms-ready">This is not a drill!</message>
   ...
 </model>

</div>

[[Image:ui-input-with-alert.png|An alert popup, with a helpful error message.]]

A modeless message is the foundation for displaying a <code>help</code> message, which a graphical browser might render as follows:

<div class="exampleInner">

 <secret ref="/login/password">
   <label>Password</label>
   <help>Have you forgotten your password? Simply call 1-900-555-1212 and have
         a major credit card handy.</help>
 </secret>

</div>

[[Image:ui-password-with-help.png|A password entry form control, with a popup window below, displaying instructions for retrieving a forgotten password]]

An ephemeral message is the foundation for displaying a <code>hint</code> message, which a graphical browser might render as follows:

<div class="exampleInner">

 <input ref="po/address/street1">
   <label>Street</label>
   <hint>Please enter the number and street name</hint>
 </input>

</div>

[[Image:ui-input-with-hint.png|An average-looking text entry form control, with a mouse pointer visible and a tooltip below, reading 'Please enter the number and street name']]

</div><div class="div2">

===<span id="action-conditional">Conditional Execution of XForms Actions</span>===

The <code>if</code> attribute can be added to any XForms action. It contains an <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> expression that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is converted to a <code>boolean</code> as if converted with the <code>boolean()</code> function defined by the <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> specification. If the converted result of the expression evaluates to <code>false</code>, then the action is not performed. If the converted result is <code>true</code>, then the action is performed.

If this attribute is applied to an XForms <code>action</code> element and the converted result of evaluation is <code>false</code>, then all of the actions within the <code>action</code> element are omitted from the execution of the XForms action sequence that invoked the <code>action</code> element. If the result is <code>true</code>, then the contained actions are performed according to the normal processing rules such as deferred update behavior and applicability of conditional and iterative attributes.

<div class="note">

'''Note:'''

In actions <code>insert</code> and <code>delete</code>, the attribute <code>context</code> is evaluated before the <code>if</code> attribute.

</div><div class="exampleOuter"><div class="exampleHead">Automatic Focus Advancement</div>

The <code>setfocus</code> action in each input control is executed only if the node bound to the control is a number of a particular length. The exacting form author could perform further validity tests.

<div class="exampleInner">

 
 ...
 <input ref="areaCode" id="AreaCodeControl" incremental="true">
 	<label>Area Code</label>
 	<setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/>
 </input>
 <input ref="exchange" id="ExchangeControl" incremental="true">
 	<label>Exchange</label>
 	<setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/>
 </input>
 <input ref="local" id="LocalControl" incremental="true">
 	<label>Local</label>
 	<setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/>
 </input>
 ...

</div></div><div class="exampleOuter"><div class="exampleHead">Handling Focus for Empty Repeats</div>

The trigger that performs a delete conditionally sets the focus to a control outside of the repeat if the repeat becomes empty due to the deletion. The <code>setfocus</code> is called first because the <code>delete</code> removes the context node.

<div class="exampleInner">

 
 ...
 <trigger id="InsertControl">
 	<label>Insert Row</label>
 	<action ev:event="DOMActivate">
 		<insert context="purchaseOrder/lines" nodeset="line"
 				at="index('PurchaseOrderRepeat')" origin="instance('prototype')"/>
 		<setfocus control="PurchaseOrderRepeat"/>
 	</action>
 </trigger>
 <repeat nodeset="purchaseOrder/lines/line" id="PurchaseOrderRepeat">
 	...
 	<trigger>
 		<label>Delete Row</label>
 		<action ev:event="DOMActivate">
 			<setfocus control="InsertControl" if="last()=1"/>
 			<delete  nodeset="../line" at="index('PurchaseOrderRepeat')"/>
 		</action>
 	</trigger>
 	...
 </repeat>

</div></div></div><div class="div2">

===<span id="action-iterated">Iteration of XForms Actions</span>===

The <code>while</code> attribute can be added to any XForms action. It contains an <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> expression that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is converted to a <code>boolean</code> as if converted with the <code>boolean()</code> function defined by the <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> specification. If the converted result of the expression is <code>true</code>, then the XForms action is performed and then the expression is re-evaluated. The XForms action is executed repeatedly until the converted result of the expression evaluates to <code>false</code>.

If this attribute is applied to an XForms <code>action</code> element, then the sequence of XForms actions in its content are executed repeatedly once for each time the immediately preceding evaluation of the expression yields a result of <code>true</code>.

When XForms actions are iteratively executed, they are still subject to the normal action processing rules such as deferred update and applicability of conditional and iterative attributes.

An XForms action may be executed zero times due to this attribute. Furthermore, if an action bears this attribute and the <code>if</code> attribute, then the expressions of both attributes must evaluate to <code>true</code> before each iterative execution of the action.

<div class="note">

'''Note:'''

In actions <code>insert</code> and <code>delete</code>, the attribute <code>context</code> is evaluated before the <code>while</code> attribute. Therefore, <code>context</code> is re-evaluated before each iteration of the actions controlled by the <code>while</code> attribute.

</div><div class="exampleOuter"><div class="exampleHead">Summing Selected Results</div>

Counter and accumlator variables are created in instance data to sum a selection of values chosen by the user

<div class="exampleInner">

 
 <trigger>
    <label>Get Sum</label>
    <action ev:event="DOMActivate">
       <setvalue ref="instance('temps')/counter" value="1"/>
       <setvalue ref="instance('temps')/accumulator" value="0"/>
       <action while="instance('temps')/counter <= count(/some/nodes)">
          <setvalue ref="instance('temps')/accumulator"
                    value=". + instance('default')/some/nodes[number(instance('temps')/counter)]"
                    if="boolean-from-string(/some/nodes[number(instance('temps')/counter)]/@selected)"/>
          <setvalue ref="instance('temps')/counter" value=". + 1"/>
       </action>
    </action>
 </trigger>

</div></div></div><div class="div2">

===<span id="action-other">Actions from Other Modules</span>===

Of the action handlers detailed in this chapter, XForms defines some to be part of the XForms Switch and Repeat modules: [[#The toggle Element|The toggle Element]] and [[#The setindex Element|The setindex Element]].

</div></div><div class="div1">

==<span id="submit">The XForms Submission Module</span>==

XForms is designed to gather [[#def-instance-data|instance data]], serialize it into an external representation, and submit it with a protocol. XForms defines a set of options for serialization and submission. The following sections define the processing of instance data for submission, and the behavior for the serialization and submission options.

<div class="div2">

===<span id="submit-submission-element">The submission Element</span>===

The <code>submission</code> element represents declarative instructions on what to submit, and how.

{| summary="listing of XForms submission element attributes and content model" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Overview of Attributes
! rowspan="1" colspan="1" | Overview of Content Model
|-
| rowspan="1" colspan="1" | submission
| rowspan="1" colspan="1" |
<blockquote>

[[#structure-attrs-common|Common]]<br />ref ([[#def-binding-expression|binding-expression]])<br />bind (xsd:IDREF)<br />resource (xsd:anyURI)<br />action (xsd:anyURI) [deprecated]<br />mode ("asynchronous"|"synchronous")<br />method ("post"|"get"|"put"|"delete"|"multipart-post"|"form-data-post"|"urlencoded-post"|Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]<nowiki>|</nowiki>[[#def-QNameButNotNCName|QNameButNotNCName]])<br />validate (xsd:boolean)<br />relevant (xsd:boolean)<br />serialization ("application/xml"|"application/x-www-form-urlencoded"|"multipart/related"|"multipart/form-data"|"none")<br />version (xsd:NMTOKEN)<br />indent (xsd:boolean)<br />mediatype (xsd:string)<br />encoding (xsd:string)<br />omit-xml-declaration (xsd:boolean)<br />standalone (xsd:boolean)<br />cdata-section-elements (QNameList)<br />replace ("all"|"instance"|"text"|"none" | [[#def-QNameButNotNCName|QNameButNotNCName]])<br />instance (xsd:IDREF)<br />targetref (nodeset XPath Expression)<br />separator (';' | '&')<br />includenamespaceprefixes (xsd:NMTOKENS)

</blockquote>
| rowspan="1" colspan="1" |
([[#submit-resource-elem|resource]] | [[#submit-method-elem| method]] | [[#submit-header| header]])*, [[#action-content-set|Action]]<nowiki>*</nowiki>
|}

Below is a more detailed decription of each attribute whose name and datatype information appears above.

Common Attributes: [[#structure-attrs-common|Common]]

Special Attributes:

; resource
: Attribute indicating the destination URI for submitting instance data. This attribute is not author-optional unless the destination URI is provided by the <code>resource</code> element, which can dynamically specify the URI based on instance data, or the <code>action</code> attribute. This attribute should be used in place of the <code>action</code> attribute. Behavior of relative URIs in links is determined by the host language, although <nowiki>[</nowiki>[[#ref-xml-base |XML Base]]<nowiki>]</nowiki> processing is strongly recommended.
; action
: Deprecated author-optional attribute indicating the destination URI for submitting instance data. Behavior of relative URIs in links is determined by the host language, although <nowiki>[</nowiki>[[#ref-xml-base |XML Base]]<nowiki>]</nowiki> processing is strongly recommended. Due to the addition of the <code>resource</code> attribute, this attribute is deprecated and optional. However, the destination URI must be specified by this attribute or by either the <code>resource</code> attribute or the <code>resource</code> element.
; ref
: Author-optional selector [[#def-binding-expression|binding expression]] enabling submission of a portion of the instance data. The selected node, and all descendants, are selected for submission. The default value is "/".
; bind
: Author-optional reference to a <code>bind</code> element. When present, the binding reference on this attribute is used in preference to any binding reference from the <code>ref</code> attribute.
; mode
: Author-optional attribute defaulting to "asynchronous" and with legal values of "synchronous" and "asynchronous". This attribute controls whether or not the submission response processing is performed as part of the default processing of event <code>xforms-submit</code>. An asynchronous submission can complete default processing for this event before the submission response is received; in this case, submission response is processed once it is completely received asynchronously. For a "synchronous" submission, the submission response is received and processed during the default processing of event <code>xforms-submit</code>.
; method
: Author-optional attribute specifying the protocol operation to be used to transmit the serialized instance data. There is no default value because either the attribute <code>method</code> or the element <code>method</code> must be specified. See Section [[#Submission Options|Submission Options]] for information on how this attribute affects the default serialization of instance data and the HTTP method <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki>.
; validate
: Author-optional boolean attribute that indicates whether or not the data validation checks of the submission are performed. The default value is "false" if the value of <code>serialization</code> is "none" and "true" otherwise.
; relevant
: Author-optional boolean attribute that indicates whether or not the relevance pruning of the submission is performed. The default value is "false" if the value of <code>serialization</code> is "none" and "true" otherwise.
; serialization
: Author-optional attribute that controls how and whether to serialize instance data as part of the submission. The default value of this attribute is based on the submission <code>method</code> as described in Section [[#Submission Options|Submission Options]]. If the attribute value is "none", then instance data is not serialized as part of the submission. This can be useful for requests that either require no data or that have the data already gathered in the URI.<div class="note">'''Note:'''Setting <code>serialization</code> to "none" will also have the default effect of preventing relevance pruning and validation. However, the author is free to override this by setting <code>relevant</code> and/or <code>validate</code> attributes to "true".</div>
; version
: Author-optional attribute specifying the <code>version</code> of XML to be serialized. The default is "1.0".
; indent
: Author-optional attribute specifying whether the serializer should add extra white space nodes for readability. The default is "false".
; mediatype
: Author-optional attribute specifying the mediatype for XML serialization of instance data. Authors should ensure that the type specified is compatible with the data being submitted, such as <code>application/xml</code> for posted XML data. The default is "application/xml".<div class="note">'''Note:'''This attribute does not affect serialization and cannot be used to override the <code>serialization</code> attribute. It is only used to provide additional information about the submission data serialization when the serialization is <code>application/xml</code>. For example, this attribute could be used to indicate that the content type of the XML serialization is <code>text/xml</code>.</div>
; encoding
: Author-optional attribute specifying an encoding for serialization. The default is "UTF-8".
; omit-xml-declaration
: Author-optional attribute specifying whether to omit the XML declaration on the serialized instance data. The default value is "false".
; standalone
: Author-optional attribute specifying whether to include a standalone declaration in the serialized XML.If the <code>omit-xml-declaration</code> attribute has the value <code>true</code>, then this attribute is ignored. Otherwise, if this attribute is omitted, then the XML declaration does not include a standalone document declaration, and if this attribute is specified, then the XML declaration includes a standalone document declaration with the same value as this attribute.
; cdata-section-elements
: Author-optional attribute specifying element names to be serialized with CDATA sections. The default is empty string.
; replace
: Author-optional attribute specifying how the information returned after submit should be applied. In the absence of this attribute, "all" is assumed. The legal values are "all", "instance", "text" and "none".
; instance
: Author-optional attribute specifying the instance to replace when the <code>replace</code> attribute value is "instance". When the attribute is absent, then the default is the instance that contains the submission data. An xforms-binding-exception ([[#The xforms-binding-exception Event|The xforms-binding-exception Event]]) occurs if this attribute does not indicate an instance in the same model as the submission.
; targetref
: Author-optional attribute containing an XPath expression that indicates the target node for data replacement. The in-scope evaluation context of the <code>submission</code> element is used to evaluate the expression. If <code>replace</code> is "instance", then the target node is replaced by the submission result. If <code>replace</code> is "text", then the content of the target node is replaced by the submission result. For other values of the <code>replace</code> attribute, this attribute is ignored. By default, the target node is the document element of the instance indicated by the <code>instance</code> attribute.
; separator
: Author-optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is '&'. To express the default, character entity encoding is used: <code>separator='&amp;'</code>.
; includenamespaceprefixes
: Author-optional attribute providing control over namespace serialization. If absent, all namespace nodes present in the instance data are considered for serialization. If present, specifies list of namespace prefixes to consider for serialization, in addition to those visibly utilized. As in [[#Exc-C14N|Exc-C14N]] <nowiki>[</nowiki>[[#ref-Exc-C14N |Exc-C14N]]<nowiki>]</nowiki>, the special value <code><nowiki>#default</nowiki></code> specifies the default namespace.

The following examples show how various options on element <code>submission</code> can affect serialization as <code>application/xml</code>. Given the following XForms fragment:

<div class="exampleInner">

 <xforms:model xmlns:xforms="http://www.w3.org/2002/xforms"
               xmlns:my="http://ns.example.org/2003">
   <xforms:instance>
     <qname xmlns="">my:sample</qname>
   </xforms:instance>
   <xforms:submission method="post" resource="..."/>
 </xforms:model>

</div>

Note that the <code>includenamespaceprefixes</code> attribute is not present, which causes all namespace nodes to be serialized, resulting in the following serialized instance data:

<div class="exampleInner">

 <qname xmlns:xforms="http://www.w3.org/2002/xforms"
        xmlns:my="http://ns.example.org/2003">my:sample</qname>

</div>

In particular, note that the XForms namespace has been serialized. To prevent this example from including the unneeded XForms namespace while maintaining the needed <code>my</code> prefix, <code>includenamespaceprefixes="my"</code> must be added to the submission element. When this attribute is present, the author takes responsibility to list all namespace prefixes not visibly utilized by the submitted instance data.

The following attributes correspond (in spelling, processing, and default values) to attributes on the <code>output</code> element of <nowiki>[</nowiki>[[#ref-xslt |XSLT 1.0]]<nowiki>]</nowiki>, with the exception of using <code>xsd:boolean</code> to replace <code>"yes"|"no"</code><nowiki>:</nowiki>

<blockquote>

version<br />indent<br />encoding<br />omit-xml-declaration<br />cdata-section-elements

</blockquote><div class="note">

'''Note:'''

The following XSLT attributes have no counterpart in XForms:

<blockquote>

doctype-system<br />doctype-public

</blockquote></div>

The table below provides an overview of the child elements of the XForms <code>submission</code> element, including their attributes and content models. Elements defined in the XForms Actions module are also allowed in the content model of <code>submission</code>.

{| summary="listing of child elements of the XForms submission element, and their attributes and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Overview of Attributes
! rowspan="1" colspan="1" | Overview of Content Model
|-
| rowspan="1" colspan="1" | resource
| rowspan="1" colspan="1" | value (string XPath Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" | method
| rowspan="1" colspan="1" | value (string XPath Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" | header
| rowspan="1" colspan="1" | nodeset (nodeset XPath Expression)
| rowspan="1" colspan="1" | name, value+
|-
| rowspan="1" colspan="1" |
[[#action-content-set|Action]]
| rowspan="1" colspan="1" | various
| rowspan="1" colspan="1" | various
|}

</div><div class="div2">

===<span id="submit-evt-submit">The xforms-submit Event</span>===

Target: <code>submission</code>

Bubbles: Yes

Cancelable: Yes

Context Info: None

Under no circumstances can more than a single concurrent submit process be under way for a particular XForms submission. From the start of the default action of <code>xforms-submit</code> for a <code>submission</code>, until immediately before <code>xforms-submit-done</code> or <code>xforms-submit-error</code> is dispatched to that <code>submission</code>, the default action for subsequent <code>xforms-submit</code> events dispatched to that <code>submission</code> is to dispatch <code>xforms-submit-error</code> to that submission with context information containing an <code>error-type</code> of <code>submission-in-progress</code>.

Otherwise, the default action for this event results in the following steps:

# The data model is updated based on some of the flags defined for [[#action-deferred-updates|deferred updates]].. Specifically, if the deferred update <code>rebuild</code> flag is set for the <code>model</code> containing this <code>submission</code>, then the rebuild operation is performed without dispatching an event to invoke the operation. Then, if the deferred update <code>recalculate</code> flag is set for the <code>model</code> containing this <code>submission</code>, then the recalculate operation is performed without dispatching an event to invoke the operation. This sequence of operations affects the [[#action-deferred-update-behavior|deferred update behavior]] by clearing the deferred update flags associated with the operations performed.
# If the binding attributes of <code>submission</code> indicate an empty nodeset or a node other than an element or an instance document root node, then submission processing is stopped after dispatching event <code>xforms-submit-error</code> with context information containing an <code>error-type</code> of <code>no-data</code>. Otherwise, the binding attributes of <code>submission</code> indicate a node of instance data.
# The indicated node and all nodes for which it is an ancestor are selected. If the attribute <code>relevant</code> is <code>true</code>, whether by default or declaration, then any selected node which is not relevant as defined in [[#The relevant Property|The relevant Property]] is deselected (pruned). If all instance nodes are deselected, then submission processing is stopped after dispatching event <code>xforms-submit-error</code> with context information containing an <code>error-type</code> of <code>no-data</code>.
# If the attribute <code>validate</code> is <code>true</code>,whether by default or declaration, then all selected instance data nodes are checked for validity according to the definition in [[#The xforms-revalidate Event|The xforms-revalidate Event]] (no notification events are marked for dispatching due to this operation). Any selected instance data node that is found to be invalid stops submission processing after dispatching event <code>xforms-submit-error</code> with context information containing an <code>error-type</code> of <code>validation-error</code>.
# The [[#submit-method|submission method]] is determined.
# The [[#submit-resource|submission resource]] is determined. If the resource is not specified, then submission processing stops after dispatching even <code>xforms-submit-error</code> with context information containing an <code>error-type</code> of <code>resource-error</code>.
# If the <code>serialization</code> attribute value is <code>"none"</code>, then the submission data serialization is the empty string. Otherwise, the submission data serialization is determined as follows. The event <code>xforms-submit-serialize</code> is dispatched. If the <code>submission-body</code> property of the event is changed from the initial value of empty string, then the content of the <code>submission-body</code> property string is used as the <code>submission data serialization</code>. Otherwise, the <code>submission data serialization</code> consists of a serialization of the selected instance data according to the rules stated in [[#Submission Options|Submission Options]].
# The <code>submission headers</code> are determined using the header entries produced by the <code>header</code> element(s) in the submission and the <code>mediatype</code> attribute or its default.
# The submission is performed based on the <code>submission headers</code>, [[#submit-method|submission method]], [[#submit-resource|submission resource]], and <code>submission data serialization</code>. The exact rules of submission are based on the URI scheme and the [[#submit-method|submission method]], as defined in [[#Submission Options|Submission Options]].

<div class="note">

'''Note:'''

A <code>submission</code> with no resource specification can be used to test validity of data. If the selected data is invalid, then the <code>xforms-submit-error</code> has an <code>error-type</code> of <code>validation-error</code>. If the selected data is valid, then the <code>xforms-submit-error</code> has an <code>error-type</code> of <code>resource-error</code>.

</div>

If the <code>mode</code> of the <code>submission</code> is <code>asynchronous</code>, then default processing for this event ends after the above steps, and submission processing is resumed once the response from the submission is returned. In the same manner used to handle user-generated events or the dispatch and processing of delayed events, the processing of the asynchronous submission response is done without interrupting the processing of any other event and its event handlers. If the <code>mode</code> of the <code>submission</code> is <code>synchronous</code>, then the XForms processor suspends user interaction with all form controls of the document and action processing is blocked within the default processing for this event until the response from the submission is returned.

The response returned from the submission is applied as follows:

* For a success response including a body, when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>all</code>", the event <code>xforms-submit-done</code> may be dispatched with appropriate context information, and submit processing concludes with entire containing document being replaced with the returned body.
* For a success response including a body of an XML media type (as defined by the content type specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>), when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>instance</code>", the response is parsed as XML. If the parse fails, then submission processing concludes after dispatching <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>parse-error</code>. However, if the XML parse succeeds, then instance data replacement is performed according to the rules specified in [[#Replacing Data with the Submission Response|Replacing Data with the Submission Response]]. This operation may fail for a number of reasons, including if processing of the <code>targetref</code> attribute yields a readonly node (if <code>replace="text"</code>) or a node that either has a readonly parent or is not an element (if <code>replace="instance"</code>). In this case, submission ends after dispatching event <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>target-error</code>. Otherwise, the instance data replacement succeeds. Submission processing then concludes after dispatching <code>xforms-submit-done</code> with appropriate context information.
* For a success response including a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>), when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>instance</code>", nothing in the document is replaced and submission processing concludes after dispatching <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>resource-error</code>.
* For a success response including a body of an XML media type (as defined by the content type specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>) or a text media type (as defined by a content type of <code>text/*</code>), when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>text</code>", the response is encoded as text. Then, the content replacement is performed according to the rules specified in [[#Replacing Data with the Submission Response|Replacing Data with the Submission Response]]. If the processing of the <code>targetref</code> attribute (including its default) fails, then the submission processing concludes after dispatching <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>target-error</code>. Otherwise, submission processing then concludes after dispatching <code>xforms-submit-done</code> with appropriate context information.
* For a success response including a body that is both a non-XML media type (i.e. with a content type not matching any of the specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>) and a non-text type (i.e. with a content type not matching <code>text/*</code>), when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>text</code>", nothing in the document is replaced and submission processing concludes after dispatching <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>resource-error</code>.
* For a success response including a body, when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>none</code>", submission processing concludes after dispatching <code>xforms-submit-done</code> with appropriate context information.
* For a success response not including a body, submission processing concludes after dispatching <code>xforms-submit-done</code> with appropriate context information.
* Behaviors of other possible values for attribute <code>replace</code> are not defined in this specification.
* For an error response, when the value of the <code>replace</code> attribute on element <code>submission</code> is "<code>all</code>", either the document is replaced with an implementation-specific indication of an error or submission processing concludes after dispatching <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>resource-error</code>.
* For an error response, when the value of the <code>replace</code> attribute on element <code>submission</code> is not "<code>all</code>", nothing in the document is replaced, and submission processing concludes after dispatching <code>xforms-submit-error</code> with appropriate context information, including an <code>error-type</code> of <code>resource-error</code>.

In addition to initiating a submission with its default processing, XForms actions can also provide handlers for the <code>xforms-submit</code> event to peform tasks such as data preparation.

Example:

<div class="exampleOuter"><div class="exampleHead">Preparing data for submission</div><div class="exampleInner">

 <submission resource="http://example.com/searchDoctors" method="post" ref="instance('doctorSearchParams')"
             replace="instance" targetref="instance('doctorList')" >
     <action ev:event="xforms-submit">
         <setvalue ref="diagnosis" value="instance('patientRecord')/malady"/>
         <setvalue ref="city" value="instance('patientRecord')/city"/>
     </action>
 </submission>

</div>

The schema for the doctor search service requires certain portions of the patient record in order to provide a list of specialists who could treat the patient. The server-side module may perform database searches for doctors with the required specialties as well as implement business rules such as providing doctors that are within an acceptable distance of the given city. The resulting list is provided to a separate instance so it can be presented to the user for selection or used in subsequent availability searches.

</div></div><div class="div2">

===<span id="submit-evt-submit-serialize">The xforms-submit-serialize Event</span>===

Dispatched at the beginning of <code>submission</code> serialization (see [[#The xforms-submit Event|The xforms-submit Event]]).

Target: <code>submission</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-compute-exception event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | submission-body
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | A document element node with a QName of <code>submission-body</code>. The node initially contains an empty string. Event handlers can write data into the node. If the string value of this node is non-empty, then the string value is used in the submission in lieu of the default instance data serialization.
|}

<div class="note">

'''Note:'''

The <code>submission-body</code> property is a string, but the <code>event()</code> function encapsulates the string in a text node so that the string can be modified by the <code>setvalue</code> action, which sets a value into a node determined by its Single Node Binding.

</div><div class="note">

'''Note:'''

Since the <code>submission-body</code> is a string, this feature may be used to submit non-XML data.

</div>

Default Action: If the event context <code>submission-body</code> property string is empty, then no operation is performed so that the <code>submission</code> will use the normal serialization data (see [[#The xforms-submit Event|The xforms-submit Event]]). Otherwise, if the event context <code>submission-body</code> property string is non-empty, then the serialization data for the <code>submission</code> is set to be the content of the <code>submission-body</code> string.

Example:

<div class="exampleOuter"><div class="exampleHead">Submitting plain text</div><div class="exampleInner">

 <submission resource="http://example.com/greeter" method="post" mediatype="text/plain">
     <setvalue ev:event="xforms-submit-serialize" ref="event('submission-body')" value="my/text"/>
 </submission>

</div>

The string value of the element <code>my/text</code> is placed into the node representing the submission body, so that is the text posted by the submission. In this example, the result returned by the submission replaces the document. This feature could be used to submit plain text, but it could also be used to allow a document to submit its serialization rather than just submitting instance data.

</div></div><div class="div2">

===<span id="submit-evt-submit-done">The xforms-submit-done Event</span>===

Dispatched as an indication of: successful completion of a submission process

Target: <code>submission</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-submit-done event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | resource-uri
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | The submission resource URI that succeeded (xsd:anyURI)
|-
| rowspan="1" colspan="1" | response-status-code
| rowspan="1" colspan="1" | number
| rowspan="1" colspan="1" | The protocol return code of the success response, or <code>NaN</code> if the submission did not receive a success response.
|-
| rowspan="1" colspan="1" | response-headers
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | Zero or more elements, each one representing a content header in the success response received by the submission. The returned node-set is empty if the submission did not receive a response or if there were no headers. Each element has a local name of <code>header</code> with no namespace URI and two child elements, <code>name</code> and <code>value</code>, whose string contents are the name and value of the header, respectively.
|-
| rowspan="1" colspan="1" | response-reason-phrase
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | The protocol response reason phrase of the success response. The string is empty if the submission did not receive a response or if the response did not contain a reason phrase.
|}

Default Action: None; notification event only.

Example:

<div class="exampleOuter"><div class="exampleHead">Submission Sequencing</div><div class="exampleInner">

 <submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record">
     <send ev:event="xforms-submit-done" submission="chargeForRecord"/>
 </submission>
 <submission id="chargeForRecord" resource="https://example.com/chargeForRecord" method="get" serialization="none" replace="none"/>

</div>

The default instance data is submitted as the search criteria for a desired record. Only upon successful completion of the submission is a second submission performed to charge the user's account for the record.

</div></div><div class="div2">

===<span id="submit-evt-submit-error">The xforms-submit-error Event</span>===

Dispatched as an indication of: failure of a submission process

Target: <code>submission</code>

Bubbles: Yes

Cancelable: No

Context Info:

{| summary="Event context properties for xforms-submit-error event" border="1"
! rowspan="1" colspan="1" | Property
! rowspan="1" colspan="1" | Type
! rowspan="1" colspan="1" | Value
|-
| rowspan="1" colspan="1" | error-type
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | One of the following: <code>submission-in-progress</code>, <code>no-data</code>, <code>validation-error</code>, <code>parse-error</code>, <code>resource-error</code>, <code>target-error</code>.
|-
| rowspan="1" colspan="1" | resource-uri
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | The submission resource URI that failed (xsd:anyURI)
|-
| rowspan="1" colspan="1" | response-status-code
| rowspan="1" colspan="1" | number
| rowspan="1" colspan="1" | The protocol return code of the error response, or <code>NaN</code> if the failed submission did not receive an error response.
|-
| rowspan="1" colspan="1" | response-headers
| rowspan="1" colspan="1" | node-set
| rowspan="1" colspan="1" | Zero or more elements, each one representing a content header in the error response received by a failed submission. The returned node-set is empty if the failed submission did not receive an error response or if there were no headers. Each element has a local name of <code>header</code> with no namespace URI and two child elements, <code>name</code> and <code>value</code>, whose string contents are the name and value of the header, respectively.
|-
| rowspan="1" colspan="1" | response-reason-phrase
| rowspan="1" colspan="1" | string
| rowspan="1" colspan="1" | The protocol response reason phrase of the error response. The string is empty if the failed submission did not receive an error response or if the error response did not contain a reason phrase.
|-
| rowspan="1" colspan="1" | response-body
| rowspan="1" colspan="1" | object (string or node-set)
| rowspan="1" colspan="1" |
When the error response specifies an XML media type as defined by <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>, the response body is parsed into an XML document and the root element of the document is returned. If the parse fails, or if the error response specifies a text media type (starting with <code>text/</code>), then the response body is returned as a string. Otherwise, an empty string is returned.
|}

Default Action: None; notification event only.

Example:

<div class="exampleOuter"><div class="exampleHead">Reporting a Submission Error</div><div class="exampleInner">

 <submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record">
     <message ev:event="xforms-submit-error">A submission error (<output value="event('error-type')"/>) occurred.</message>
 </submission>

</div>

The default instance data is submitted as the search criteria for a desired record. Only upon successful completion of the submission is a second submission performed to charge the user's account for the record.

</div></div><div class="div2">

===<span id="submit-resource">The Submission Resource</span>===

The <code>submission resource</code> is the URI for the submission. It is of type <code>xsd:anyURI</code>.

In XForms 1.0, the URI for submission was provided by the <code>action</code> attribute. For consistency, form authors should now use the attribute <code>resource</code> of type <code>xsd:anyURI</code>, which deprecates the <code>action</code> attribute. If both <code>action</code> and <code>resource</code> are present, then the <code>resource</code> attribute takes precedence.

The <code>resource</code> element provides the submission URI, overriding the <code>resource</code> attribute and the <code>action</code> attribute. If a <code>submission</code> has more than one <code>resource</code> child element, the first <code>resource</code> element child must be selected for use. Individually, the <code>resource</code> element, the <code>resource</code> attribute and the <code>action</code> attribute are not required. However, one of the three is mandatory as there is no default submission resource.

<div class="div3">

====<span id="submit-resource-elem">The resource Element</span>====

The <code>resource</code> element allows the URI used for a submission to be dynamically calculated based on instance data.

Common Attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the URI, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The URI to be used by the <code>submission</code> can be specified with either the <code>value</code> attribute or the string content of the <code>resource</code> element. If both are specified, then the <code>value</code> attribute takes precedence. If the <code>submission</code> does not have a <code>resource</code> child element, then the submission URI is obtained from the <code>resource</code> attribute or the <code>action</code> attribute.

Example:

<div class="exampleOuter"><div class="exampleHead">Submitting the default instance to a location determined dynamically from an instance</div><div class="exampleInner">

 <submission method="post">
     <resource value="instance('params')/anyURI"/>
 </submission>

</div></div></div></div><div class="div2">

===<span id="submit-method">The Submission Method</span>===

The <code>submission method</code> indicates the submission protocol operation to be performed.

The submission method may be specified by the <code>method</code> attribute. The <code>submission</code> element can have a child element named <code>method</code>, which overrides the submission method setting obtained from the <code>method</code> attribute if both are specified. If more than one <code>method</code> element is given, the first occurrence in document order must be selected for use. Individually, the <code>method</code> element and the <code>method</code> attribute are not required. However, one of the two is mandatory as there is no default submission method.

<div class="div3">

====<span id="submit-method-elem">The method Element</span>====

The <code>method</code> element allows the submission method to be dynamically calculated based on instance data.

Common Attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the method, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

Content: PCDATA

The method to be used by the <code>submission</code> can be specified with either the <code>value</code> attribute or the string content of the <code>method</code> element. If both are specified, then the <code>value</code> attribute takes precedence. If the <code>submission</code> does not have a <code>method</code> child element, then the submission method is obtained from the <code>method</code> attribute.

</div></div><div class="div2">

===<span id="submit-header">The header Element</span>===

The <code>header</code> element can be used to contribute information to the preamble of a submission in a manner appropriate to the protocol. The <code>submission</code> element can contain zero or more <code>header</code> child elements. Each produces zero or more header entries containing a name, a value, and a combination. The entries are provided to the submission protocol in the specified order. It is the responsibility of the submission protocol implementation to combine the entries and to serialize the result into submission protocol headers. Accordingly, entries may be re-ordered, combined, or otherwise altered in accordance with the specific protocol implementation requirements.

Common Attributes: None

Special Attributes:

; nodeset
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. One or more header entries are generated for each node selected by this attribute.
; combine
: Author-optional attribute defaulting to "append" and with legal values of "append", "prepend", and "replace". This attribute controls the method of combination for entries produced by this element <code>header</code> with other entries produced by other <code>header</code> elements. This attribute and its default also provide information for the protocol implementation, which may use some or all of the information to combine XForms submission headers with headers provided by the user agent.

Content: (<code>name</code>, <code>value</code>+) | (<code>value</code>+, <code>name</code>)

If the <code>header</code> element does not contain a <code>nodeset</code> attribute, then one header entry is created for each <code>value</code> element. If the <code>header</code> element contains a <code>nodeset</code> attribute, then for each selected node, one header entry is created for each <code>value</code> element. The name and value of the header entry are obtained from the required child elements <code>name</code> ([[#The name Element|The name Element]]) and <code>value</code> ([[#The value Element|The value Element]]). If the name obtained from the <code>name</code> element is the empty string, then the header entry is omitted.

The header entry order is determined as follows:

# document order of <code>header</code> elements
# node order of nodes in <code>nodeset</code> attribute
# document order of <code>value</code> elements

The application of this order information to header serialization is determined by the submission protocol.

If a <code>header</code> element defines the <code>Content-type</code> header, then this setting overrides a <code>Content-type</code> set by the <code>mediatype</code> attribute.

In the case of a multipart submission, the header entries are combined with those for the first part of the submission.

Example:

<div class="exampleOuter"><div class="exampleHead">Setting the Accept header</div>

In the example below, the submission request uses the <code>header</code> element to replace the user agent's existing value of the HTTP Accept header with <code>application/sparql-results+xml</code>.

<div class="exampleInner">

 <submission id="loadConcepts"
             resource="http://example.com/taxonomy/concepts" method="get"
             ref="instance('conceptsList')" replace="instance">
   <header combine="replace">
     <name>Accept</name>
     <value>application/sparql-results+xml</value>
   </header>
 </submission>

</div></div><div class="div3">

====<span id="submit-header-name">The name Element</span>====

When the <code>name</code> element appears as a child of element <code>header</code>, it is used to specify the name of a header entry to be provided to the submission protocol.

Common Attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the header name, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

The header entry name may be given by the string content of the <code>name</code> element, or by the result of the <code>value</code> attribute. If both are given, the result from the <code>value</code> attribute takes precedence. If the resulting name is the empty string, then the entry is considered to be void, and it is not supplied to the submission protocol.

</div><div class="div3">

====<span id="submit-header-value">The value Element</span>====

When the <code>value</code> element appears as a child of element <code>header</code>, it is used to specify the value component of a header entry to be supplied to the submission protocol to be added to the preamble of a submission. The <code>value</code> element may be used more than once in a given element <code>header</code>, in which case each value produces a new header entry.

Common Attributes: None

Special Attributes:

; value
: Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the header entry value, the result of the expression is processed as if by call to the XPath <code>string</code> function. An empty string is used if the XPath evaluation fails.

The header entry value may be given by the string content of the <code>value</code> element, or by the result of the <code>value</code> attribute. If both are given, the result from the <code>value</code> attribute takes precedence.

<div class="note">

'''Note:'''

The XPath <code>string</code> function combines multiple nodes by concatenating them into a string separated with spaces. As a result, a header value specified by a <code>value</code> element nodeset containing multiple nodes may not be properly serialized in a submission protocol preamble. To assure proper delivery of individual header items to the submission protocol, restrict use of XPath expressions producing nodesets for element <code>header</code> with attribute <code>nodeset</code>, where each node will produce its own separate header entry, and use expressions resulting in only a single node in element <code>value</code>.

</div></div></div><div class="div2">

===<span id="submit-options">Submission Options</span>===

The XForms Model specifies a <code>submission</code> element containing the following attributes and child elements that affect serialization and submission. This section summarizes the behaviors for the allowable values of these attributes and child elements, and presents subsections that define the behavior for submission and serialization.

* the [[#submit-resource|submission resource]]
* the [[#submit-method|submission method]]
* the <code>header</code> elements

For the submission protocol obtained from the URI scheme in the [[#submit-resource|submission resource]], XForms normatively defines a binding to HTTP/1.1 <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki>.

<div class="note">

'''Note:'''

Other bindings, in particular to the URI scheme "mailto:" may, and the schemes "https:" and "file:" should, be supported. Bindings to these schemes are not normatively defined in XForms. Implementations that choose to provide a binding to these schemes should pay particular attention to privacy and security concerns. Within the "http:" and "https:" schemes, form creators are encouraged to follow the finding of the W3C Technical Architecture Group on when to use the GET method: <nowiki>[</nowiki>[[#ref-tag7 |TAG Finding 7]]<nowiki>]</nowiki>

</div>

The [[#submit-method|submission method]] determines the default data serialization format, and both the [[#submit-method|submission method]] and the URI scheme in the [[#submit-resource|submission resource]] determine the submission protocol operation, according to the following table:

{| summary="Form Serialization and Submission Behaviors" border="1"
! rowspan="1" colspan="1" | URI scheme
! rowspan="1" colspan="1" |
[[#submit-method|Submission Method]]
! rowspan="1" colspan="1" | Default Serialization
! rowspan="1" colspan="1" | Submission Protocol Operation
|-
| rowspan="1" colspan="1" | http https mailto
| rowspan="1" colspan="1" | "post"
| rowspan="1" colspan="1" | <code>application/xml</code>
| rowspan="1" colspan="1" | HTTP POST or equivalent
|-
| rowspan="1" colspan="1" | http https file
| rowspan="1" colspan="1" | "get"
| rowspan="1" colspan="1" | <code>application/x-www-form-urlencoded</code>
| rowspan="1" colspan="1" | HTTP GET or equivalent
|-
| rowspan="1" colspan="1" | http https file
| rowspan="1" colspan="1" | "delete"
| rowspan="1" colspan="1" | <code>application/x-www-form-urlencoded</code>
| rowspan="1" colspan="1" | HTTP DELETE or equivalent
|-
| rowspan="1" colspan="1" | http https file
| rowspan="1" colspan="1" | "put"
| rowspan="1" colspan="1" | <code>application/xml</code>
| rowspan="1" colspan="1" | HTTP PUT or equivalent
|-
| rowspan="1" colspan="1" | http https mailto
| rowspan="1" colspan="1" | "multipart-post"
| rowspan="1" colspan="1" | <code>multipart/related</code>
| rowspan="1" colspan="1" | HTTP POST or equivalent
|-
| rowspan="1" colspan="1" | http https mailto
| rowspan="1" colspan="1" | "form-data-post"
| rowspan="1" colspan="1" | <code>multipart/form-data</code>
| rowspan="1" colspan="1" | HTTP POST or equivalent
|-
| rowspan="1" colspan="1" | http https mailto
| rowspan="1" colspan="1" | "urlencoded-post"
| rowspan="1" colspan="1" | <code>application/x-www-form-urlencoded</code>
| rowspan="1" colspan="1" | HTTP POST or equivalent
|-
| rowspan="1" colspan="1" | (any)
| rowspan="1" colspan="1" |
Any other [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]
| rowspan="1" colspan="1" | <code>application/xml</code>
| rowspan="1" colspan="1" |
As given by the [[#submit-method|Submission Method]]
|-
| rowspan="1" colspan="1" | (any)
| rowspan="1" colspan="1" |
[[#def-QNameButNotNCName|QNameButNotNCName]]
| rowspan="1" colspan="1" | implementation-defined
| rowspan="1" colspan="1" | implementation-defined
|}

<div class="note">

'''Note:'''

Foreign-namespaced attribute values are allowed in the [[#submit-method|Submission Method]], but no behavior is defined by XForms.

</div><div class="div3">

====<span id="submit-get">The get Submission Method</span>====

This submit method represents HTTP GET or the equivalent concept. The serialized form data is delivered as part of the URI that is requested during the submit process.

This method is not suitable for submission of forms that are intended to change state or cause other actions to take place at the server. See <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki> for recommended uses of HTTP GET.

The URI is constructed as follows:

* The submit URI is examined. If it does not already contain a <code>?</code> (question mark) character, one is appended. If it does already contain a question mark character and the serialized form data is non-empty, then a separator character from the attribute <code>separator</code> is appended.
* The serialized form data, if any, is appended to the URI.

No message body is sent with the request.

Examples:

<div class="exampleOuter"><div class="exampleHead">Simple search submission</div><div class="exampleInner">

 <submission resource="http://example.com/search" method="get"/>

</div>

After doing relevance and validity checking on the data, the leaf nodes of the default instance are submitted asynchronously, encoded as a URL (<code>application/x-www-form-urlencoded</code>), to <code>http://example.com/search</code>. The result replaces the whole page.

</div><div class="exampleOuter"><div class="exampleHead">Reading from a local file</div><div class="exampleInner">

 <submission resource="file:data.xml" method="get" serialization="none" replace="instance" instance="data" />

</div>

Replaces the instance 'data' with the content of the file data.xml. Serialization, and its associated validity and relevance processing, is not needed. See the corresponding example for saving a file in Section [[#The put Submission Method|The put Submission Method]]. The user agent may restrict file access to a user-specific and domain-specific security zone in local storage.

</div></div><div class="div3">

====<span id="submit-post">The post, multipart-post, form-data-post, and urlencoded-post Submission Methods</span>====

These submit methods represent HTTP POST or the equivalent concept (such as a mail message). The serialized form data is delivered as the message body.

Examples:

<div class="exampleOuter"><div class="exampleHead">Posting instance data</div><div class="exampleInner">

 <submission resource="https://example.com/jsp/orders" method="post" ref="/purchaseOrder" />

</div>

Submits the XML for a purchase order to a secure server order processing system.

</div><div class="exampleOuter"><div class="exampleHead">Simple posted login</div><div class="exampleInner">

 <submission resource="http://example.com/login" method="urlencoded-post"/>

</div>

After doing relevance pruning and validity checking on the login data, the leaf nodes of the default instance are submitted asynchronously in the posted data, encoded based on the <code>application/x-www-form-urlencoded</code> serialization, to <code>http://example.com/login</code>. The result replaces the whole page.

</div></div><div class="div3">

====<span id="submit-put">The put Submission Method</span>====

This submit method represents HTTP PUT or the equivalent concept (such as writing to a local file). The serialized form data is delivered as the message body.

Example:

<div class="exampleOuter"><div class="exampleHead">Saving to a local file</div><div class="exampleInner">

 <submission resource="file:data.xml" ref="instance('data')" method="put" validate="false" relevant="false" replace="none" />

</div>

Saves the instance 'data' to the file data.xml without validation checking and relevance pruning. See the corresponding example for reading from a local file in Section [[#The get Submission Method|The get Submission Method]]. The user agent may restrict file access to a user-specific and domain-specific security zone in local storage.

</div></div><div class="div3">

====<span id="submit-delete">The delete Submission Method</span>====

This submit method represents HTTP DELETE or the equivalent concept (such as deleting a local file). The serialized form data is delivered in the same manner as the [[#submit-get|get]] submission method (see [[#The get Submission Method|The get Submission Method]]).

</div><div class="div3">

====<span id="serialize-xml">Serialization as application/xml</span>====

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 capable of submission of binary content.

The steps for serialization are as follows:

# An XML document is produced following the rules of the XML output method defined in <nowiki>[</nowiki>[[#ref-xslt |XSLT 1.0]]<nowiki>]</nowiki> section 16 and 16.1, using the values supplied as attributes of the <code>submission</code> element.
## Handling of namespace nodes: The default behavior is that every namespace node is serialized according to the rules of the XML output method, so that at least one namespace declaration appears in the serialized XML for each in-scope namespace. Additional inherited namespaces are declared on the root element of the serialized XML. If, however, attribute <code>includenamespaceprefixes</code> on element <code>submission</code> is present, then all namespace declarations not visibly utilized in the instance data (as defined in <nowiki>[</nowiki>[[#ref-Exc-C14N |Exc-C14N]]<nowiki>]</nowiki>) and the default namespace if it is empty are excluded from the root element serialization, unless the corresponding namespace prefix is listed in the <code>includenamespaceprefixes</code> attribute. The special value <code><nowiki>#default</nowiki></code> represents the default namespace.
## Mediatype: By default, the mediatype of the serialized XML instance is <code>application/xml</code>, but can be changed to a compatible type using element <code>submission</code> attribute <code>mediatype</code>. Authors should ensure that the type specified is compatible with <code>application/xml</code>.

</div><div class="div3">

====<span id="serialize-multipart">Serialization as multipart/related</span>====

This format is intended for integration of XForms into environments that involve large amounts of binary data where the inclusion of the data as <code>xsd:base64Binary</code> or <code>xsd:hexBinary</code> is undesirable.

In this format, XML instance data is serialized as one part of the <nowiki>[</nowiki>[[#ref-rfc-2387 |RFC 2387]]<nowiki>]</nowiki> <code>multipart/related</code> message, using the rules as described in [[#Serialization as application/xml|Serialization as application/xml]]. Binary content from <code>xsd:anyURI</code> instance nodes populated by the <code>upload</code> (see [[#The upload Element|The upload Element]]) control is serialized in separate parts of the <nowiki>[</nowiki>[[#ref-rfc-2387 |RFC 2387]]<nowiki>]</nowiki> <code>multipart/related</code> message.

This format follows the rules of <code>multipart/related</code> MIME data streams for in <nowiki>[</nowiki>[[#ref-rfc-2387 |RFC 2387]]<nowiki>]</nowiki>, with specific requirements of this serialization listed below:

* <code>multipart/related</code> message header requirements:
** Must contain a <code>type</code> parameter of the mediatype of the serialized XML instance.
** Must contain a <code>start</code> parameter referring to the Content-ID first body part (root).
* First body part (root) requirements:
** Must have <code>Content-Type</code> parameter of the type specified by the <code>submission</code> <code>mediatype</code> attribute.
** Content is serialized by the rules at [[#Serialization as application/xml|Serialization as application/xml]].
* Subsequent part requirements:
** One part for each node with a datatype of <code>xsd:anyURI</code> populated by <code>upload</code> with:
*** A <code>Content-Type</code> header that represents the type of the attachment if known, otherwise <code>application/octet-stream</code>.
*** A <code>Content-Transfer-Encoding</code> header.
*** A <code>Content-ID</code> header whose value matches the URI in the associated instance data node.
*** The binary content associated with the URI, serialized according to the <code>Content-Transfer-Encoding</code> heading.

<div class="exampleOuter"><div class="exampleHead">multipart/related</div><div class="exampleInner">

 <submission method="multipart-post" resource="http://example.com/photo" />

</div>

Submits the instance data in <code>multipart/related</code>, along with the selected file as an attachment.

<div class="exampleInner">

 POST /photo HTTP/1.0
 Host: example.com
 Content-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>"
 Content-Length: xxx
 
 --f93dcbA3
 Content-Type: application/xml; charset=UTF-8
 Content-ID: <980119.X53GGT@example.com>
 
 <?xml version="1.0"?>
 <uploadDocument>
   <title>My Proposal</title>
   <author>E. X. Ample</author>
   <summary>A proposal for a new project.</summary>
   <notes image="cid:980119.X17AXM@example.com">(see handwritten region)</notes>
   <keywords>project proposal funding</keywords>
   <readonly>false</readonly>
   <filename>image.png</filename>
   <content>cid:980119.X25MNC@example.com</content>
 </uploadDocument>
 --f93dcbA3
 Content-Type: image/png
 Content-Transfer-Encoding: binary
 Content-ID: <980119.X25MNC@example.com>
 
 ...Binary data here...
 --f93dcbA3
 Content-Type: image/png
 Content-Transfer-Encoding: binary
 Content-ID: <980119.X17AXM@example.com>
 
 ...Binary data here...
 --f93dcbA3--

</div></div></div><div class="div3">

====<span id="serialize-form-data">Serialization as multipart/form-data</span>====

This format is for legacy compatibility to permit the use of XForms clients with <nowiki>[</nowiki>[[#ref-rfc-2388 |RFC 2388]]<nowiki>]</nowiki> servers. This method is suitable for the persistence of binary content. Contextual path information, attribute values, namespaces and namespace prefixes are not preserved. As a result, different elements might serialize to the same name.

<div class="note">

'''Note:'''

Existing HTML user agents fail to encode special characters (such as double quotes) and non-ASCII characters in the <code>Content-Disposition: form-data</code> <code>name</code> and <code>filename</code> parameters. Since this serialization method is supported for legacy applications only, new applications should use <code>application/xml</code> or <code>multipart/related</code>.

</div>

This format follows the rules for <code>multipart/form-data</code> MIME data streams in <nowiki>[</nowiki>[[#ref-rfc-2388 |RFC 2388]]<nowiki>]</nowiki>, with specific requirements of this serialization listed below:

* Each element node is visited in document order, except non-relevant elements are skipped if the <code>relevant</code> setting of the <code>submission</code> is <code>true</code>.
* Each visited element that has no child element nodes (i.e., each leaf element node) is selected for inclusion, including those that have no value (no text node).
* Element nodes selected for inclusion are encoded as <code>Content-Disposition: form-data</code> MIME parts as defined in <nowiki>[</nowiki>[[#ref-rfc-2388 |RFC 2388]]<nowiki>]</nowiki>, with the <code>name</code> parameter being the element local name.
* Element nodes of any datatype populated by <code>upload</code> also have a <code>Content-Disposition</code> <code>filename</code> parameter, if the filename is available.
* Element nodes of any datatype populated by <code>upload</code> are serialized as the specified binary content. In the case of <code>xsd:anyURI</code> and derived types, the serialization content is obtained from the URI. For <code>xsd:base64Binary</code>, <code>xsd:hexBinary</code>, and derived types, the serialization content is obtained by decoding the element string value.
* Element nodes of any datatype not populated by <code>upload</code> are serialized as the string value of the element (the concatenation of all text node children, or empty string if the element has no text node children).
* The <code>Content-Type</code> must be <code>text/plain</code> except for <code>xsd:anyURI</code>, <code>xsd:base64Binary</code>, <code>xsd:hexBinary</code>, and derived types, in which case the header represents the media type of the attachment if known, otherwise <code>application/octet-stream</code>. If a character set is applicable, the <code>Content-Type</code> may have a <code>charset</code> parameter.

Example:

<div class="exampleOuter"><div class="exampleHead">multipart/form-data</div><div class="exampleInner">

 <submission method="form-data-post" resource="http://example.com/photo" />

</div>

Submits the instance data in <code>multipart/form-data</code>, along with the selected file as a part.

<div class="exampleInner">

 POST /photo HTTP/1.0
 Host: example.com
 Content-Type: multipart/form-data; boundary=AaB03x
 Content-Length: xxx
 
 --AaB03x
 Content-Disposition: form-data; name="document"; filename="b.txt"
 Content-Type: text/plain; charset=iso-8859-1
 This is a file.
 It has two lines.
 --AaB03x
 Content-Disposition: form-data; name="title"
 A File
 --AaB03x
 Content-Disposition: form-data; name="summary"
 This is my file
 file test
 --AaB03x--

</div></div></div><div class="div3">

====<span id="serialize-urlencode">Serialization as application/x-www-form-urlencoded</span>====

This format represents an extension of the <nowiki>[</nowiki>[[#ref-xhtml-1.0 |XHTML 1.0]]<nowiki>]</nowiki> form content type <code>application/x-www-form-urlencoded</code> with specific rules for encoding non-ASCII and reserved characters.

This format is not suitable for the persistence of binary content. Therefore, it is recommended that forms capable of containing binary content use another serialization method.

The steps for serialization are as follows:

# Each element node is visited in document order, except non-relevant elements are skipped if the <code>relevant</code> setting of the <code>submission</code> is <code>true</code>. Each visited element that has no child element nodes (i.e., each leaf element node) is selected for inclusion, including those that have no value (no text node). Note that attribute information is not preserved.
# Element nodes selected for inclusion are encoded as <code>EltName=value</code>, where <code><nowiki>=</nowiki></code> is a literal character, <code>EltName</code> represents the element local name, and <code>value</code> represents the string value of the element (the concatenation of all text node children, or empty string if the element has no text node children). The separator character {sep} from the <code>separator</code> attribute on <code>submission</code> is used between pairs of encoded name/value pairs, e.g. <code>EltName1=value1{sep}EltName2=value2{sep}EltName3=value3</code>. Note that contextual path information is not preserved, nor are namespaces or namespace prefixes. As a result, different elements might serialize to the same name.
#* The encoding of <code>EltName</code> and <code>value</code> are as follows: space characters are replaced by <code>+</code>, and then non-ASCII and reserved characters (as defined by <nowiki>[</nowiki>[[#ref-rfc-2396 |RFC 2396]]<nowiki>]</nowiki> as amended by subsequent documents in the IETF track) are escaped by replacing the character with one or more octets of the UTF-8 representation of the character, with each octet in turn replaced by <code>%HH</code>, where <code>HH</code> represents the uppercase hexadecimal notation for the octet value and <code>%</code> is a literal character. Line breaks are represented as "CR LF" pairs (i.e., <code>%0D%0A</code>).
# All such encodings are concatenated, maintaining document order.

Example:

<div class="exampleOuter"><div class="exampleHead">application/x-www-form-urlencoded</div><div class="exampleInner">

 GivenName=Ren%C3%A9

</div>

This format consists of simple name-value pairs.

<div class="exampleInner">

 <PersonName title="Mr">
   <GivenName>René</GivenName>
 </PersonName>

</div>

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.

</div></div></div><div class="div2">

===<span id="submit-data-replacement">Replacing Data with the Submission Response</span>===

The <code>submission</code> element allows an author-optional attribute named <code>targetref</code>. The attribute value is interpreted as a [[#def-binding-expression|binding expression]] to which the first node rule is applied to obtain a '''replacement target node''' for the submission response. This attribute is ignored unless the value of the <code>replace</code> attribute is "instance" or "text".

For backwards compatibility with documents created for earlier versions of the specification, the processor of the <code>submission</code> element [[#intro-reading|may]] allow the author-optional attribute named <code>target</code> to be used. The <code>target</code> attribute provides exactly the same behaviors as the <code>targetref</code> attribute except that the <code>target</code> attribute is ignored if the <code>submission</code> element also bears a <code>targetref</code> attribute.

The default replacement target node is the document element node of the instance identified by the <code>instance</code> attribute, which is equal to the default instance of the model if not specified. The evaluation context for this attribute is the in-scope evaluation context for the <code>submission</code> element, except the context node is modified to be the document element of the instance identified by the <code>instance</code> attribute if it is specified.

This attribute is evaluated only once a successful submission response has been received and if the <code>replace</code> attribute value is "instance" or "text". The first node rule is applied to the result.

The processing of the <code>targetref</code> attribute (and its default) is considered to have failed if the result is any of the following:

* an empty nodeset
* a readonly node, if <code>replace="text"</code>
* a non-element, if <code>replace="instance"</code>
* a node whose parent is readonly, if <code>replace="instance"</code>

If the processing of the <code>targetref</code> attribute fails, then submission processing ends after dispatching the event <code>xforms-submit-error</code> with an <code>error-type</code> of <code>target-error</code>.

If the <code>replace</code> attribute contains the value "<code>text</code>" and the submission response conforms to an XML mediatype (as defined by the content type specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>) or a text media type (as defined by a content type specifier of <code>text/*</code>), then the response data is encoded as text and replaces the content of the replacement target node.

If the <code>replace</code> attribute contains the value "<code>instance</code>" and the submission response conforms to an XML mediatype (as defined by the content type specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>) and the XML parse of the submission response succeeds, then the XML obtained from the submission response is used to replace the target node. The XML in the response may have comment and processing instruction nodes before and after the document element. These nodes are discarded if the replacement target node is not the document element of an instance. Otherwise, those processing instructions and comments replace any processing instructions and comments that previously appeared outside of the document element of the instance being replaced.

In the case of text replacement of the content of the replacement target node, the replacement is performed by the XForms Action <code>setvalue</code> ([[#The setvalue Element|The setvalue Element]]). In the case of instance node replacement, the replacement is performed by an XForms action that performs some combination of node insertion and deletion operations that are performed by the <code>insert</code> action ([[#The insert Element|The insert Element]]) and the <code>delete</code> action ([[#The delete Element|The delete Element]]). If the <code>submission</code> has a <code>mode</code> of "<code>asynchronous</code>", then the text replacement action or the instance node replacement action is an outermost action handler, so the [[#action-deferred-update-behavior|deferred update behavior]] occurs at the end of the action. If the <code>mode</code> is "<code>synchronous</code>", then the text replacement action or the instance node replacement action is not outermost since occurs during the default processing of <code>xforms-submit</code>, so the appropriate [[#action-deferred-update-behavior|deferred update flags]] are set based on whether the action was a <code>setvalue</code> or whether it performed a series of <code>insert</code> and <code>delete</code> actions.

<div class="note">

'''Note:'''

In an asynchronous submission, the deferred update behavior ensures that the user interface is up to date with the latest calculated values before the <code>xforms-submit-done</code> event is dispatched. In a synchronous submission, the calculated values dependent on replaced text or data nodes can be made available to actions in the <code>xforms-submit-done</code> handler by first invoking the <code>recalculate</code> action. A sequence of synchronous submissions performed with successive <code>send</code> actions can avoid refreshing the user interface until after the completion of the last <code>send</code> action.

</div>

Examples:

<div class="exampleOuter"><div class="exampleHead">Replacing a subtree of instance data</div><div class="exampleInner">

 <submission resource="http://example.com/jsp/prefill" method="post" ref="name" replace="instance" targetref="address"/>

</div>

This submission would be invoked after the user enters a value for <code>name</code>. Based on the name given, a simple server-side database lookup is performed to get a last known address. The <code>address</code> element is replaced with the result, prefilling part of the form for the user.

</div><div class="exampleOuter"><div class="exampleHead">Replacing text in an instance</div><div class="exampleInner">

 <submission resource="http://example.com/postalCodeSearch" method="get" ref="address" replace="text" targetref="address/postalCode"/>

</div>

The address information is past to a postal code search service that returns a textual result, which is placed into the <code>postalCode</code> element.

</div><div class="exampleOuter"><div class="exampleHead">Submission and Read-Only Content</div><div class="exampleInner">

 <model xmlns:my="http://example.org">
   <instance>
     <my:data>
       <my:name>
         <my:first-name>John</my:first-name>
         <my:last-name>Doe</my:last-name>
       </my:name>
       <my:address>
         <my:street>123 Main St.</my:street>
         <my:city>Smallville</my:city>
       </my:address>
     </my:data>
   </instance>
 
   <bind nodeset="/my:data/my:name/" readonly="true()"/>
   <bind nodeset="/my:data/my:address/my:street" readonly="true()"/>
 
   <submission id="S1" targetref="my:name" replace="instance" method="post" resource="..."/>
   <submission id="S2" targetref="my:name/my:first-name" replace="instance" method="post" resource="..."/>
 
   <submission id="S3" targetref="my:name/my:first-name" replace="text" method="post" resource="..."/>
   <submission id="S4" targetref="my:address/my:street" replace="text" method="post" resource="..."/>
 </model>

</div>

Submission S1 succeeds because a readonly node (<code>my:name</code>) can be replaced if its parent is not readonly. Submission S2 fails because a node (<code>my:first-name</code>) cannot be replaced if its parent is readonly. Submission S3 fails because the content of a readonly node cannot be replaced, even if it is readonly due to inheritance. Submission S4 failse because the content of a readonly node cannot be replaced, even if the node's parent is not readonly.

</div></div><div class="div2">

===<span id="SOAP">Integration with SOAP</span>===

This section describes the integration of XForms submission with <nowiki>[</nowiki>[[#ref-soap-11 |SOAP 1.1]]<nowiki>]</nowiki> and <nowiki>[</nowiki>[[#ref-soap-12 |SOAP 1.2]]<nowiki>]</nowiki>

<div class="div3">

====<span id="SOAP-envelope">Representation of SOAP Envelope</span>====

The single-node binding of the <code>submission</code> element refers to the XML data to be submitted. In the case of a SOAP submission, the instance data includes the SOAP envelope and related SOAP tags.

<div class="note">

'''Note:'''

The form author may choose to store the data payload in one instance and copy the data to the submission instance containing the SOAP envelope as part of an <code>xforms-submit</code> event handler. The form author is responsible for declaring the appropriate model item properties on both instances (e.g. the <code>relevant</code> declarations).

</div></div><div class="div3">

====<span id="SOAP-mediatype">Indicating a SOAP submission</span>====

For a SOAP submission, the <code>mediatype</code> attribute of the <code>submission</code> [[#intro-reading|must]] be set to the MIME type of <code>application/soap+xml</code>. The form author may append <code>charset</code> and <code>action</code> MIME parameters.

<div class="note">

'''Note:'''

The <code>action</code> MIME parameter has no effect unless the submission <code>method</code> is "post" because the GET method implies no SOAP processing by the receiving SOAP node.

</div><div class="note">

'''Note:'''

SOAP 1.1 does not support the HTTP GET operation.

</div></div><div class="div3">

====<span id="SOAP-HTTP-Binding">SOAP HTTP Binding</span>====

The <code>method</code> attribute of the <code>submission</code> [[#intro-reading|must]] be set to <code>get</code> or <code>post</code> in order to access the SOAP HTTP binding.

If <code>method="get"</code>, then the SOAP response message exchange pattern is used. The HTTP headers [[#intro-reading|must]] contain the Accept parameter with a value conforming to the following properties:

* [[#intro-reading|must]] begin with <code>application/soap+xml</code>
* If the submission <code>mediatype</code> contains a <code>charset</code> MIME parameter, then it is appended to the <code>application/soap+xml</code> MIME type. Otherwise, a <code>charset</code> MIME parameter with same value as the <code>encoding</code> attribute (or its default) is appended to the <code>application/soap+xml</code> MIME type.
* No other MIME parameters from the <code>mediatype</code> are copied to the <code>application/soap+xml</code> MIME type
* The <code>q</code> MIME parameter [[#intro-reading|must not]] be specified in the <code>application/soap+xml</code> MIME type so that the default quality of 1 is used.

If <code>method="post"</code>, then the SOAP request-response message exchange pattern is used. For SOAP 1.2, the current submission behavior of using the <code>mediatype</code> attribute value as the value of the <code>Content-type</code> parameter in the HTTP headers is sufficient. If the instance data being submitted has as its root element node a SOAP envelope in the SOAP 1.1 namespace (<code>http://schemas.xmlsoap.org/soap/envelope/</code>), then:

* the <code>Content-type</code> HTTP header is changed to <code>text/xml</code>
* the <code>charset</code> MIME parameter is appended . The charset parameter value from the <code>mediatype</code> attribute is used if it is specified. Otherwise, the value of the <code>encoding</code> attribute (or its default) is used.
* if the <code>action</code> MIME parameter appears in the <code>mediatype</code> then a SOAPAction HTTP header is added and given a value equal to the content of the <code>action</code> MIME parameter

<div class="note">

'''Note:'''

XForms 1.1 does not support the SOAP email binding, so method="post" with a <code>mailto:</code> scheme results in an <code>xforms-submit-error</code> event before any submit processing message is dispatched.

</div><div class="note">

'''Note:'''

XForms 1.1 does not support the SOAP 1.1 binding to the HTTP Extension Framework.

</div>

Example:

<div class="exampleOuter"><div class="exampleHead">Consuming a SOAP 1.1 Request-Response Web Service</div><div class="exampleInner">
 <xforms:model xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://www.webservice.net">
    <xforms:instance id="data">
        <data xmlns="">
            <city>Victoria</city>
            <country>Canada</country>
            <weather>Mostly sunny and cool. High 12C. Low 3C.</weather>
        </data>
    </xforms:instance>
 
    <xforms:instance id="GetWeatherSoapIn">
 	  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 		 <soap:Body>
 			<GetWeather xmlns="http://www.webservice.net">
 			   <CityName>Victoria</CityName>
 			   <CountryName>Canada</CountryName>
 			</GetWeather>
 		 </soap:Body>
 	  </soap:Envelope>
    </xforms:instance>
    <xforms:instance id="GetWeatherSoapOut">
 	  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 		 <soap:Body>
 			<GetWeatherResponse xmlns="http://www.webservice.net">
 			   <GetWeatherResult>Mostly sunny and cool. High 12C. Low 3C.</GetWeatherResult>
 			</GetWeatherResponse>
 		 </soap:Body>
 	  </soap:Envelope>
    </xforms:instance>
 
    <xforms:submission id="GetWeather" resource="http://www.webservice.net/getweather.asmx" method="post"
         ref="instance('GetWeatherSoapIn')" mediatype="application/soap+xml; action=http://www.webservice.net/GetWeather"
         replace="instance" instance="GetWeatherSoapOut">
         <xforms:action ev:event="xforms-submit">
             <xforms:setvalue ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CityName"
                              value="instance('data')/city"/>
             <xforms:setvalue ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CountryName"
                              value="instance('data')/country"/>
         </xforms:action>
         <xforms:action ev:event="xforms-submit-done">
             <xforms:setvalue ref="instance('data')/weather"
                              value="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeatherResponse/tns:GetWeatherResult"/>
         </xforms:action>
    </xforms:submission>
 </xforms:model>
 
 <xforms:input ref="city">
    <xforms:label>City </xforms:label>
    <xforms:send ev:event="xforms-value-changed" submission="GetWeather"/>
 </xforms:input>
 <xforms:input ref="country">
    <xforms:label>Country </xforms:label>
    <xforms:send ev:event="xforms-value-changed" submission="GetWeather"/>
 </xforms:input>
 <xforms:output ref="weather">
    <xforms:label>The weather forecast is </xforms:label>
 </xforms:output>
</div>

This form accepts input of a city name and country name from the user. When the user changes either value, the 'GetWeather' web service is initiated. On <code>xforms-submit</code>, the user input is copied into the request envelope. When the web service submission result is received, the <code>xforms-submit-done</code> handler copies the weather forecast from the response envelope to the data instance.

The submission and the request and response instances correspond to the web service definition below:

<div class="exampleInner">

 <wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
      xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
      xmlns:tns="http://www.webservice.net" targetNamespace="http://www.webservice.net">
   <wsdl:types>
     <xs:schema elementFormDefault="qualified" targetNamespace="http://www.webservice.net">
       <xs:element name="GetWeather">
         <xs:complexType>
           <xs:sequence>
             <xs:element minOccurs="0" maxOccurs="1" name="CityName" type="xs:string" />
             <xs:element minOccurs="0" maxOccurs="1" name="CountryName" type="xs:string" />
           </xs:sequence>
         </xs:complexType>
       </xs:element>
       <xs:element name="GetWeatherResponse">
         <xs:complexType>
           <xs:sequence>
             <xs:element minOccurs="0" maxOccurs="1" name="GetWeatherResult" type="xs:string" />
           </xs:sequence>
         </xs:complexType>
       </xs:element>
       ...
   </wsdl:types>
 
   <wsdl:message name="GetWeatherSoapIn">
     <wsdl:part name="parameters" element="tns:GetWeather" />
   </wsdl:message>
   <wsdl:message name="GetWeatherSoapOut">
     <wsdl:part name="parameters" element="tns:GetWeatherResponse" />
   </wsdl:message>
   ...
   <wsdl:portType name="GetWeatherSoap">
     <wsdl:operation name="GetWeather">
       <wsdl:input message="tns:GetWeatherSoapIn" />
       <wsdl:output message="tns:GetWeatherSoapOut" />
     </wsdl:operation>
     ...
   </wsdl:portType>
   ...
   <wsdl:binding name="GetWeatherSoap" type="tns:GetWeatherSoap">
     <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
     <wsdl:operation name="GetWeather">
       <soap:operation soapAction="http://www.webservice.net/GetWeather" style="document" />
       <wsdl:input>
         <soap:body use="literal" />
       </wsdl:input>
       <wsdl:output>
         <soap:body use="literal" />
       </wsdl:output>
     </wsdl:operation>
     ...
   </wsdl:binding>
 
   <wsdl:service name="GetWeatherService">
     <wsdl:port name="GetWeatherSoap" binding="tns:GetWeatherSoap">
       <soap:address location="http://www.webservice.net/getweather.asmx" />
     </wsdl:port>
     ...
   </wsdl:service>
 </wsdl:definitions>

</div></div></div><div class="div3">

====<span id="SOAP-response">Handling the SOAP Response</span>====

The XForms processor [[#intro-reading|must]] handle client authorization and redirection.

SOAP faults (400 and 500 level errors) are handled in the same manner as underlying HTTP errors, which is to say that an <code>xforms-submit-error</code> event is dispatched.

On successful completion, the results are consumed according to the XForms submission process, culminating in an <code>xforms-submit-done</code> event. The form author may capture this event and copy data from the target instance that receives the returned SOAP envelope to other instances that are designed to carry only data.

</div></div></div><div class="div1">

==<span id="conform">Conformance</span>==

<div class="div2">

===<span id="conform-desc-documents">Conforming XForms Documents</span>===

All XForms Containing Documents must conform to the following specifications, except as qualified below:

* <nowiki>[</nowiki>[[#ref-xml-1.0 |XML 1.0]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xml-names |XML Names]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>

XForms elements are typically inserted into a containing document in multiple places. The root element for each individual fragment of XForms [[#intro-reading|must]] be <code>model</code>, a [[#elems-form-controls|core form control]], <code>group</code>, <code>repeat</code>, or <code>switch</code>. Individual XForms fragments [[#intro-reading|must]] be schema-valid according to the Schema for XForms ([[#Schema for XForms (Non-Normative)|Schema for XForms]]), except that the host language [[#intro-reading|may]] add elements of its own namespace to the content models of the following elements: <code>group</code>, <code>repeat</code>, <code>case</code>, <code>label</code>, <code>help</code>, <code>hint</code>, <code>alert</code> and <code>message</code>. .

A [[#def-host-language|host language]] [[#intro-reading|may]] introduce additional conformance requirements.

</div><div class="div2">

===<span id="conform-desc-generators">Conforming XForms Generators</span>===

XForms generators [[#intro-reading|should]] generate conforming XForms documents.

</div><div class="div2">

===<span id="xforms-base-tech">Base Technologies for XForms Processors</span>===

The following are base technologies for XForms. An [[#def-xforms-processor|XForms Processor]] therefore [[#intro-reading|must]] conform to the following specifications, except as qualified below:

* <nowiki>[</nowiki>[[#ref-xml-1.0 |XML 1.0]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xml-names |XML Names]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki>
* <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> (not all aspects are [[#intro-reading|required]])
* <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>

</div><div class="div2">

===<span id="conform-levels">Conformance Levels</span>===

XForms is a generalized XML processing language. Therefore, the XForms specification is intended for implementation on hardware platforms of all sizes, from tiny hand-held devices to high-powered servers. This section describes two main levels of conformance that are useful in varied scenarios.

<div class="div3">

====<span id="conform-levels-model">XForms Model</span>====

This conformance level is distinguished by the processor's <code>property()</code> function returning a string beginning with <code>"model"</code> for the <code>conformance-level</code> property.

An XForms <code>model</code> can contain or reference XML schemas, XForms <code>instance</code> elements, XForms <code>bind</code> elements, XForms <code>submission</code> elements, and XForms actions. XForms <code>submission</code> elements can also contain XForms actions.

An <span id="conform-model-processor">'''XForms Model Processor'''</span> is a reduced functionality [[#def-xforms-processor|XForms Processor]] with required, recommended and optional features described in this section.

An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|must]] support all attributes of the <code>model</code> element. The processor [[#intro-reading|must]] support the valid attributes and content of the <code>instance</code> element, and it [[#intro-reading|should]] support the notification events <code>xforms-insert</code> and <code>xforms-delete</code>. The processor [[#intro-reading|must]] support all attributes, content and other aspects of <code>bind</code> elements, except <code>p3ptype</code> support is [[#intro-reading|optional]]. The processor [[#intro-reading|must]] fully support <nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki>, including all XForms extension functions (though the <code>index()</code> function [[#intro-reading|may]] return <code>1</code> if the processor has no information about the identified <code>repeat</code> element). The processor [[#intro-reading|must]] make available the automatic schema datatype information defined by XForms. The processor [[#intro-reading|must]] be able to parse inline and external declared XML schema and consume their schema datatype information <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>, and the processor [[#intro-reading|should]] consume all schema information available where appropriate in the XForms processing model. An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|may]] (and hence may not) support user interface creation and refresh behaviors described for <code>model</code> processing. An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|must]] support action handlers for the events <code>xforms-model-construct-done</code>, <code>xforms-ready</code>, <code>xforms-link-exception</code> and <code>xforms-version-exception</code>. The processor [[#intro-reading|may]] support action handlers for the <code>xforms-refresh</code> event, and it [[#intro-reading|should]] support all other events targetted at <code>model</code> elements. The support for attributes and elements of <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> is described below in the description of the support for XForms Actions.

An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|should]] support the [[#The XForms Submission Module|XForms Submission module]]. If it does, then all attributes, child elements, behaviors and events [[#intro-reading|must]] be supported except as follows. The support for attributes and elements of <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> on action handlers for submission events is described below in the description of the support for XForms Actions. All [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName] submission methods [[#intro-reading|should]] be supported, and the following methods [[#intro-reading|must]] be supported: <code>get</code>, <code>post</code>, <code>put</code>, <code>delete</code>, and <code>urlencoded-post</code>. The <code>mode</code> attribute [[#intro-reading|should]] be supported; at least one of asynchronous or synchronous submission [[#intro-reading|must]] be supported. The <code>http</code> submission scheme [[#intro-reading|must]] be supported. The <code>https</code> and <code>file</code> schemes [[#intro-reading|should]] be supported. Other schemes [[#intro-reading|may]] be supported such as <code>mailto</code> or <code>ftp</code>. XForms-defined submission headers [[#intro-reading|may]] be combined with those from the user agent in the manner specified by the <code>combine</code> attribute.

An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|must]] support the following actions: <code>action</code>, <code>insert</code>, <code>delete</code>, <code>setvalue</code>, <code>reset</code>, <code>rebuild</code>, <code>recalculate</code>, <code>revalidate</code>, and <code>dispatch</code>. The processor [[#intro-reading|should]] support <code>send</code> and <code>load</code>. The processor [[#intro-reading|may]] support <code>refresh</code>, <code>setindex</code>, <code>setfocus</code>, <code>toggle</code>, and <code>message</code>. For every supported action, the processor [[#intro-reading|must]] support all local attributes defined for the action, including conditional and iteration attributes. An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|must]] support the attribute <code>ev:event</code> so that XForms action handlers can appear as children of either the target elements of the events they handle or ancestors of those elements. The processor [[#intro-reading|should]] support the attribute <code>ev:target</code> so action handlers can identify the events targetted at a particular descendant of the action handler's parent element (e.g. the <code>xforms-insert</code> or <code>xforms-delete</code> event on a particular <code>instance</code> of the <code>model</code>). The processor [[#intro-reading|may]] support all other features of <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki>.

</div><div class="div3">

====<span id="conform-levels-full">XForms Full</span>====

This conformance level is distinguished by the processor's <code>property()</code> function returning a string beginning with <code>"full"</code> for the <code>conformance-level</code> property.

An '''XForms Full Processor''' is an [[#def-xforms-processor|XForms Processor]] consisting of a conforming [[#conform-model-processor|XForms Model Processor]] along with the following additional required, recommended and optional features:

* The processor [[#intro-reading|must]] support user interface creation and refresh behaviors described for <code>model</code> processing.
* The processor [[#intro-reading|must]] support all [[#elems-form-controls|core form controls]], including all of their attributes and child elements.
* The processor [[#intro-reading|must]] support the actions <code>refresh</code>, <code>setfocus</code>, and <code>message</code>.
* The processor [[#intro-reading|should]] support the [[#ui-group-module|XForms Group Module]]. If the processor does not support this module and a <code>group</code> element is encountered during user interface initialization, then the processor [[#intro-reading|must]] terminate processing after dispatching [[#evt-bindingException|xforms-binding-exception]].
* The processor [[#intro-reading|should]] support the <code>toggle</code> action and the [[#ui-switch-module|XForms Switch Module]]. If the processor does not support this module and a <code>switch</code> element is encountered during user interface initialization, then the processor [[#intro-reading|must]] terminate processing after dispatching [[#evt-bindingException|xforms-binding-exception]].
* The processor [[#intro-reading|should]] support the <code>setindex</code> action and the [[#ui-repeat-module|XForms Repeat Module]], except that support of the <code>repeat-*</code> attributes is [[#intro-reading|optional]]. If the processor does not support this module and a <code>repeat</code> element is encountered during user interface initialization, then the processor [[#intro-reading|must]] terminate processing after dispatching [[#evt-bindingException|xforms-binding-exception]].
* The processor [[#intro-reading|should]] support all interaction and notification events targetted at basic form controls, <code>group</code>, <code>switch</code>, <code>repeat</code>, and their descendant elements (e.g. <code>case</code> and <code>item</code>).
* The processor [[#intro-reading|may]] support the Extension module.

</div></div></div><div class="div1">

==<span id="terms">Glossary Of Terms</span>==

; <span id="def-binding">Binding</span>
: [Definition<nowiki>: A "binding" connects an instance data node to a form control or to a model item property by using a binding expression as a locator.] </nowiki>
; <span id="def-binding-expression">Binding expression</span>
: [Definition<nowiki>: An </nowiki><nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> expression used in a binding.]
; <span id="def-compound-document">Compound Document</span>
: A <nowiki>[</nowiki>[[#ref-cdrf-1.0 |CDRF 1.0]]<nowiki>]</nowiki> Compound Document is a document that combines multiple document formats either by reference, by inclusion or both.
; <span id="def-computed-expression">Computed expression</span>
: [Definition<nowiki>: An </nowiki><nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> expression used by model item properties such as relevant and calculate to include dynamic functionality in XForms.]
; <span id="def-containing-document">Containing document</span>
: [Definition<nowiki>: A specific document, for example an XHTML document, in which one or more <model> elements are found.] </nowiki>
; <span id="def-datatype">Datatype</span>
: [Definition<nowiki>: From XML Schema </nowiki><nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki><nowiki>: A 3-tuple, consisting of a) a set of distinct values, called its value space, b) a set of lexical representations, called its lexical space, and c) a set of facets that characterize properties of the value space, individual values or lexical items.] </nowiki>
; <span id="def-facet">Facet</span>
: [Definition<nowiki>: From XML Schema </nowiki><nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki><nowiki>: A single defining aspect of a value space. Generally speaking, each facet characterizes a value space along independent axes or dimensions.] </nowiki>
; <span id="def-first-node-rule">First node rule</span>
: NONREF [Definition<nowiki>: When a UI Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set is used.]</nowiki>
; <span id="def-form-control">Form control</span>
: [Definition<nowiki>: An XForms user interface control that serves as a point of user interaction (a </nowiki>[[#Core Form Controls|core form control]]) or as a container for other form controls (a [[#Container Form Controls|container form control]]).]
; <span id="def-host-language">Host language</span>
: [Definition<nowiki>: An XML vocabulary, such as XHTML, into which XForms is embedded.] </nowiki>
; <span id="def-instance-data">Instance data</span>
: [Definition<nowiki>: An internal tree representation of the values and state of all the instance data nodes associated with a particular form.] </nowiki>
; <span id="def-instance-data-node">Instance data node</span>
: [Definition<nowiki>: An </nowiki><nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> node from the instance data.]
; <span id="def-lax-schema-processing">Lax schema processing</span>
: [Definition<nowiki>: From XML Schema </nowiki><nowiki>[</nowiki>[[#ref-xschema-1 |XML Schema part 1]]<nowiki>]</nowiki><nowiki>: For an element or attributes Schema validity to be assessed, then the applicable schema must provide a definition of the item. If not, Schema validation makes no contribution to the validity test for the item.]</nowiki>
; <span id="def-lexical-space">Lexical space</span>
: [Definition<nowiki>: From XML Schema </nowiki><nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki><nowiki>: A lexical space is the set of valid literals for a datatype.] The XML serialization that may occur during submission expresses the instance data using lexical space literals.</nowiki>
; <span id="def-model-binding-expression">Model Binding expression</span>
: [Definition<nowiki>: An </nowiki><nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> expression used in the <code>nodeset</code> attribute of a <code>bind</code> element in an XForms model. Often, a <code>bind</code> also declares [[#def-computed-expression|computed expressions]] for model item properties of the nodes. ]
; <span id="def-model-item">Model item</span>
: [Definition<nowiki>: An instance data node with associated constraints.] </nowiki>
; <span id="def-model-item-property">Model item property</span>
: [Definition<nowiki>: An XForms-specific annotation to an instance data node.] </nowiki>
; <span id="def-non-relevant-form-control">Non-relevant Form Control</span>
: [Definition<nowiki>: A form control satisfying at least one of the </nowiki>[[#form-control-non-relevance-conditions|form control non-relevance conditions]].]
; <span id="def-QNameButNotNCName">QNameButNotNCName</span>
: [Definition<nowiki>: A </nowiki>[http://www.w3.org/TR/REC-xml-names/#NT-QName QName] that is not an [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName]. In 2006, the W3C named this a [http://www.w3.org/TR/REC-xml-names/#NT-PrefixedName PrefixedName]. ]
; <span id="def-relevant-form-control">Relevant Form Control</span>
: [Definition<nowiki>: A form control satisfying none of the </nowiki>[[#form-control-non-relevance-conditions|form control non-relevance conditions]].]
; <span id="def-schema-constraint">Schema constraint</span>
: [Definition<nowiki>: A restriction, applied to form data, based on XML Schema datatypes.] </nowiki>
; <span id="def-strict-schema-processing">Strict schema processing</span>
: [Definition<nowiki>: From XML Schema </nowiki><nowiki>[</nowiki>[[#ref-xschema-1 |XML Schema part 1]]<nowiki>]</nowiki><nowiki>: If the applicable schema does not provide a definition for an element or attribute, then Schema validation marks the item as invalid.]</nowiki>
; <span id="def-ui-binding-expression">UI Binding Expression</span>
: [Definition<nowiki>: An </nowiki><nowiki>[</nowiki>[[#ref-xpath-1.0 |XPath 1.0]]<nowiki>]</nowiki> expression used in binding a [[#def-form-control|form control]] to the instance.]
; <span id="def-valid">Valid node</span>
: [Definition<nowiki>: An instance data node is valid if and only if the constraint model item property is true, the value is non-empty if the required model item property is true, and the node satisfies all applicable XML Schema definitions (including those associated byt the type model item property, by </nowiki><code>xsi:type</code> or by an external or inline schema).]
; <span id="def-value-space">Value space</span>
: [Definition<nowiki>: From XML Schema </nowiki><nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki><nowiki>: A set of values for a given datatype. Each value in the value space of a datatype is denoted by one or more literals in its lexical space.] </nowiki>
; <span id="def-versionList">versionList</span>
: [Definition<nowiki>: A list (</nowiki><nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>) with an atomic datatype (<nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>) of [[#def-versionNumber|versionNumber]].]
; <span id="def-versionNumber">versionNumber</span>
: [Definition<nowiki>: A string consisting of a non-zero digit (1 to 9) followed by zero or more digits (0 to 9), then a period character (.), and then one or more digits (0-9). A version number is derived from string by restriction based on the following pattern value (excluding the quote marks): </nowiki><code>"[1-9]\d*\.\d+"</code>.]
; <span id="def-xforms-model">XForms Model</span>
: [Definition<nowiki>: The non-visible definition of an XML form as specified by XForms. The XForms Model defines the individual model items and constraints and other run-time aspects of XForms.] </nowiki>
; <span id="def-xforms-processor">XForms Processor</span>
: [Definition<nowiki>: A software application or program that implements and conforms to the XForms specification.] </nowiki>

</div><div class="back"><div class="div1">

==References==

<div class="div2">

===Normative References===

; Exc-C14N
: [http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/ <cite id="Exc-C14N">Exclusive XML Canonicalization Version 1.0</cite>], J. Boyer, D. Eastlake 3rd, J. Reagle, 2002. W3C Recommendation available at http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/.
; HMAC
: [http://www.ietf.org/rfc/rfc2104.txt <cite id="ref-hmac">RFC 2104 - HMAC: Keyed-Hashing for Message Authentication</cite>], H. Krawczyk, M. Bellare, R. Canetti, 1997. Available at http://www.ietf.org/rfc/rfc2104.txt
; Luhn Patent
: <cite id="ref-luhn">Computer for Verifying Numbers</cite>, H. P. Luhn, U.S. Patent 2,950,048, 1960.
; MD5
: [http://www.ietf.org/rfc/rfc1321.txt <cite id="ref-md5">RFC 1321: The MD5 Message-Digest Algorithm</cite>], R. Rivest, 1992. Available at http://www.ietf.org/rfc/rfc1321.txt
; RFC 2119
: [http://www.ietf.org/rfc/rfc2119.txt <cite id="ref-rfc-2119">RFC 2119: Key words for use in RFCs to Indicate Requirement Levels</cite>], S. Bradner, 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
; RFC 2387
: [http://www.ietf.org/rfc/rfc2387.txt <cite id="ref-rf-2387">RFC 2387: The MIME Multipart/Related Content-type</cite>], E. Levinson, 1998. Available at: http://www.ietf.org/rfc/rfc2387.txt.
; RFC 2388
: [http://www.ietf.org/rfc/rfc2388.txt <cite id="ref-rfc-2388">RFC 2388: Returning Values from Forms: multipart/form-data</cite>], L. Masinter, 1998. Available at: http://www.ietf.org/rfc/rfc2388.txt.
; RFC 2396
: [http://www.ietf.org/rfc/rfc2396.txt <cite id="ref-rfc-2396">RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax</cite>], T. Berners-Lee, R. Fielding, L. Masinter, 1998. Available at: http://www.ietf.org/rfc/rfc2396.txt.
; RFC 2616
: [http://www.ietf.org/rfc/rfc2616.txt <cite id="ref-rfc-2616">RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1</cite>], R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee,1999. Available at: http://www.ietf.org/rfc/rfc2616.txt.
; RFC 2822
: [http://www.ietf.org/rfc/rfc2822.txt <cite id="ref-rfc-2822">RFC 2822: Internet Message Format</cite>], P. Resnick, 2001. Available at: http://www.ietf.org/rfc/rfc2822.txt.
; RFC 3023
: [http://www.ietf.org/rfc/rfc3023.txt <cite id="ref-rfc-3023">RFC 3023: XML Media Types</cite>], M Murata, S. St. Laurent, D. Kohn, 2001. Available at: http://www.ietf.org/rfc/rfc3023.txt.
; SHA2
: [http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf <cite id="ref-sha2">SECURE HASH STANDARD. FIPS PUB 180-2</cite>], August 2002. Available at http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
; SOAP 1.1
: [http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ <cite id="ref-soap-11">Simple Object Access Protocol (SOAP) 1.1 </cite>], D. Box, D. Ehnebuske, G. Kakivaya, A. Layman, N. Mendelsohn, H. F. Nielsen, S. Thatte, D. Winer, 2000. Available at: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
; SOAP 1.2
: [http://www.w3.org/TR/2007/REC-soap12-part1-20070427/ <cite id="ref-soap-12">SOAP Version 1.2 Part 1: Messaging Framework</cite>], M. Gudgin, M. Hadley, N. Mendelsohn, J.-J. Moreau, H. F. Nielsen, A. Karmarkar, Y. Lafon, 2007. Available at: http://www.w3.org/TR/2007/REC-soap12-part1-20070427/.
; Unicode Collation Algorithm
: [http://www.unicode.org/unicode/reports/tr10/ <cite id="ref-unicode-collation">Unicode Technical Standard #10, Unicode Collation Algorithm</cite>], Available at: http://www.unicode.org/unicode/reports/tr10/.
; XHTML Modularization
: [http://www.w3.org/TR/2008/REC-xhtml-modularization-20081008 <cite id="ref-xhtml-mod">XHTML Modularization 1.1</cite>], D. Austin, S. Peruvemba, S. McCarron, M. Ishikawa, M. Birbeck, 2008. W3C Recommendation available at http://www.w3.org/TR/2008/REC-xhtml-modularization-20081008.
; XML Base
: [http://www.w3.org/TR/2009/REC-xmlbase-20090128/ <cite id="ref-xml-base">XML Base (Second Edition)</cite>], J. Marsh, R. Tobin, 2009. W3C Recommendation available at: http://www.w3.org/TR/2009/REC-xmlbase-20090128/.
; XML Events
: [http://www.w3.org/TR/2003/REC-xml-events-20031014/ <cite id="ref-xml-events">XML Events - An events syntax for XML</cite>], Steven Pemberton, T. V. Raman, Shane P. McCarron, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-xml-events-20031014/.
; XHTML 1.0
: [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ <cite id="ref-xhtml-1.0">XHTML 1.0: The Extensible HyperText Markup Language - A Reformulation of HTML 4 in XML 1.0</cite>], Steven Pemberton, et al., 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-xhtml1-20020801/.
; XML 1.0
: [http://www.w3.org/TR/2006/REC-xml-20060816/ <cite id="ref-xml-1.0">Extensible Markup Language (XML) 1.0 (Fourth Edition)</cite>], Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml-20060816/
; XML Names
: [http://www.w3.org/TR/2006/REC-xml-names-20060816/ <cite id="ref-xml-names">Namespaces in XML (Second Edition)</cite>], Tim Bray, Dave Hollander, Andrew Layman, and Richard Tobin, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml-names-20060816/.
; XPath 1.0
: [http://www.w3.org/TR/1999/REC-xpath-19991116 <cite id="ref-xpath-1.0">XML Path Language (XPath) Version 1.0</cite>], James Clark, Steve DeRose, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xpath-19991116.
; XML Schema part 1
: [http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/ <cite id="ref-xschema-1">XML Schema Part 1: Structures</cite>], Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.
; XML Schema part 2
: [http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/ <cite id="ref-xschema-2">XML Schema Part 2: Datatypes</cite>], Paul V. Biron, Ashok Malhotra, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
; XSLT 1.0
: [http://www.w3.org/TR/1999/REC-xslt-19991116 <cite id="ref-xslt">XSL Transformations (XSLT) Version 1.0</cite>], James Clark, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xslt-19991116.

</div><div class="div2">

===Informative References===

; Algorithms
: <cite id="ref-art">The Art of Computer Programming: Volume 1 Fundamental Algorithms</cite>, D. E. Knuth, Addison-Wesley, Reading, MA. 1968. Third edition, 1997. ISBN:0-2018-9683-4.
; AUI97
: <cite id="ref-AUI97">Auditory User Interfaces--Toward The Speaking Computer</cite>, T. V. Raman, Kluwer Academic Publishers, 1997. ISBN:0-7923-9984-6.
; CDRF 1.0
: [http://www.w3.org/TR/2007/CR-CDR-20070718/ <cite id="ref-cdrf-1.0">Compound Document by Reference Framework 1.0</cite>], Timur Mehrvarz, Lasse Pajunen, Julien Quint, and Daniel Applequist, 2007. W3C Candidate Recommendation available at: http://www.w3.org/TR/2007/CR-CDR-20070718/.
; CSS2
: [http://www.w3.org/TR/1998/REC-CSS2-19980512/ <cite id="ref-css2">Cascading Style Sheets, level 2 (CSS2) Specification</cite>], Bert Bos, Håkon Wium Lie, Chris Lilley, Ian Jacobs, 1998. W3C Recommendation available at: http://www.w3.org/TR/1998/REC-CSS2-19980512/.
; DDJ-ArrayDoubling
: <cite id="ref-ddj">Resizable Arrays, Heaps and Hash Tables</cite>, John Boyer, Doctor Dobb's Journal, CMP Media LLC, January 1998 Issue.
; DOM2 Core
: [http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/ <cite id="ref-dom2-core">Document Object Model (DOM) Level 2 Core Specification</cite>], Tom Pixley, 2000. W3C Recommendation available at: http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/.
; DOM2 Events
: [http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/ <cite id="ref-dom2-events">Document Object Model (DOM) Level 2 Events Specification</cite>], Tom Pixley, 2000. W3C Recommendation available at: http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/.
; EXSLT
: [http://www.exslt.org <cite id="ref-exslt">EXSLT Web site</cite>]. Available at http://www.exslt.org.
; ODF 1.1
: [http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1-html/OpenDocument-v1.1.html <cite id="ref-odf-1.1">NOTREF Open Document Format for Office Applications (OpenDocument) v1.1</cite>], Patrick Durusau, Michael Brauer, and Lars Oppermann (editors), 2007. OASIS Standard available at: http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1-html/OpenDocument-v1.1.html.
; P3P 1.0
: [http://www.w3.org/TR/2002/REC-P3P-20020416/ <cite id="ref-p3p-1.0">The Platform for Privacy Preferences 1.0 (P3P1.0) Specification</cite>], Lorrie Cranor, Marc Langheinrich, Massimo Marchiori, Martin Presler-Marshall, Joseph Reagle, 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-P3P-20020416/.
; RELAXNG
: [http://www.relaxng.org/spec-20011203.html <cite id="ref-RELAXNG">RELAXNG Specification</cite>], James Clark, MURATO Makoto, 2001. OASIS Committee Specification available at: http://www.relaxng.org/spec-20011203.html.
; RELAXNG Compact
: [http://www.relaxng.org/compact-20021121.html <cite id="ref-RELAXNG-Compact">RELAXNG Compact Syntax</cite>], James Clark, 2002. OASIS Committee Specification available at: http://www.relaxng.org/compact-20021121.html.
; SVG 1.1
: [http://www.w3.org/TR/2003/REC-SVG11-20030114/ <cite id="ref-svg-1.1">SVG 1.1</cite>], Jon Ferraiolo, FUJISAWA Jun, Dean Jackson, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-SVG11-20030114/.
; TAG Finding 7
: [http://www.w3.org/2001/tag/doc/whenToUseGet-20040321 <cite id="ref-tag7">TAG Finding: URIs, Addressability, and the use of HTTP GET</cite>], Ian Jacobs, 2004. Available at: http://www.w3.org/2001/tag/doc/whenToUseGet-20040321
; Unicode Script Names
: [http://unicode.org/iso15924/iso15924-codes.html <cite id="ref-unicode-script-names">ISO 15924: Codes for the representation of names of scripts</cite>], Available at: http://unicode.org/iso15924/iso15924-codes.html.
; UAAG 1.0
: [http://www.w3.org/TR/UAAG10/ <cite id="ref-uaag-1.0">User Agent Accessibility Guidelines 1.0</cite>], Ian Jacobs, Jon Gunderson, Eric Hansen, 2002. Working Draft available at http://www.w3.org/TR/UAAG10/.
; Unicode Scripts
: [http://www.unicode.org/unicode/reports/tr24/ <cite id="ref-unicode-scripts"> Script Names</cite>], Mark Davis, 2001. Unicode Technical Report #24 available at http://www.unicode.org/unicode/reports/tr24/.
; XForms 1.0
: [http://www.w3.org/TR/2007/REC-xforms-20071029/ <cite id="ref-xforms-1.0">XForms 1.0 Third Edition</cite>], John Boyer, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xforms-20071029/.
; XForms Basic
: [http://www.w3.org/TR/2003/CR-xforms-basic-20031014/ <cite id="ref-xformsbasic">NOTREF XForms Basic Profile</cite>], Micah Dubinko, T. V. Raman, 2003. W3C Candidate Recommendation available at: http://www.w3.org/TR/2003/CR-xforms-basic-20031014/.
; XLink 1.0
: [http://www.w3.org/TR/2001/REC-xlink-20010627/ <cite id="ref-xlink-1.0">XML Linking Language (XLink) Version 1.0</cite>], Steve DeRose, Eve Maler, David Orchard, 2001. W3C Recommendation available at: http://www.w3.org/TR/2001/REC-xlink-20010627/.
; XPath 2.0
: [http://www.w3.org/TR/2007/REC-xpath20-20070123/ <cite id="ref-xpath-2.0">XML Path Language (XPath) 2.0</cite>], Anders Berglund, Scott Boag, Don Chamberlin, Mary F. Fernández, Michael Kay, Jonathan Robie, and Jérôme Siméon, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xpath20-20070123/.
; XML Schema part 0
: [http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/ <cite id="ref-xschema-0">XML Schema Part 0: Primer Second Edition</cite>], David C. Fallside and Priscilla Walmsley, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/.

</div></div><div class="div1">

==Patterns for Data Mutations==

This appendix provides several usage patterns for the <code>setvalue</code>, <code>insert</code> and <code>delete</code> actions that perform various kinds of mutations of instance data elements and attributes.

<div class="div2">

===Prepend Element Copy===

Pattern: '''<insert context="'''''parent of new element'''''" origin="'''''element to copy'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is used so that this pattern will work whether or not the parent element is empty.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Prepend a new, empty </nowiki><code>person</code> element into a list of <code>people</code>
<div class="exampleInner">

 <xforms:insert context="people" origin="instance('prototypes')/person"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
    <data xmlns="">
        <people>
            <person>
                <name>Jane Doe</name>
            </person>
        </people>
    </data>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name/>
         </person>
     </prototypes>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
    <data xmlns="">
        <people>
            '''<font size="larger"><person></font>'''
                '''<font size="larger"><name/></font>'''
            '''<font size="larger"></person></font>'''
            <person>
                <name>Jane Doe</name>
            </person>
        </people>
    </data>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name/>
         </person>
     </prototypes>
 </xforms:instance>

</div></div></div><div class="div2">

===Append Element Copy===

Pattern: '''<insert context="'''''parent of new element'''''" nodeset="*" origin="'''''element to copy'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is used so that this pattern will work whether or not the parent element is empty.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Append a new, empty </nowiki><code>person</code> element into a list of <code>people</code>
<div class="exampleInner">

 <xforms:insert context="people" nodeset="person" origin="instance('prototypes')/person"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
    <data xmlns="">
        <people>
            <person>
                <name>Jane Doe</name>
            </person>
        </people>
    </data>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name/>
         </person>
     </prototypes>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
    <data xmlns="">
        <people>
            <person>
                <name>Jane Doe</name>
            </person>
            '''<font size="larger"><person></font>'''
                '''<font size="larger"><name/></font>'''
            '''<font size="larger"></person></font>'''
        </people>
    </data>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name/>
         </person>
     </prototypes>
 </xforms:instance>

</div></div></div><div class="div2">

===Duplicate Element===

Pattern: '''<insert nodeset="'''''exact element to duplicate'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact element to duplicate, so <code>nodeset</code> is used. If the element does not exist, the operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Duplicate the selected element and place it as a following sibling</nowiki>
<div class="exampleInner">

 <xforms:insert nodeset="paragraph[2]"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <document xmlns="">
         <header>Lorem ipsum</header>
         <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
         <paragraph>Primis abhorreant delicatissimi ..</paragraph>
         <header>Lorem ipsum</header>
         <header>Lorem ipsum</header>
     </document>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <document xmlns="">
         <header>Lorem ipsum</header>
         <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
         <paragraph>Primis abhorreant delicatissimi ...</paragraph>
         '''<font size="larger"><paragraph>Primis abhorreant delicatissimi ...</paragraph></font>'''
         <header>Lorem ipsum</header>
         <header>Lorem ipsum</header>
     </document>
 </xforms:instance>

</div></div></div><div class="div2">

===Set Attribute===

Pattern: '''<insert context="'''''container element receiving attribute'''''" origin="'''''attribute to copy'''''"/>'''

<div class="note">

'''Note:'''

The <code>nodeset</code> attribute is not used because this pattern cannot indicate an exact attribute sibling of the attribute being inserted. This is true not only because attribute order is not guaranteed but also because the attribute being inserted may already exist, in which case the existing attribute is replaced. The <code>context</code> attribute is used when it is necessary to indicate the parent of the node being inserted.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Create or replace an attribute with a copy of a given attribute</nowiki>
<div class="exampleInner">

 <xforms:insert context="item[2]" origin="../item[1]/@rating"/>
 <xforms:insert context="item[3]" origin="../item[1]/@rating"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="23" rating="classified"/>
         <item key="42"/>
         <item key="68" rating="unknown"/>
     </items>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="23" rating="classified"/>
         <item key="42" '''<font size="larger">rating="classified"</font>'''/>
         <item key="68" rating="'''<font size="larger">classified</font>'''"/>
     </items>
 </xforms:instance>

</div></div></div><div class="div2">

===Remove Element===

Pattern: '''<delete nodeset="'''''exact element to remove'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact element to remove, so <code>nodeset</code> is used. If the element does not exist, the operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Remove </nowiki><code>item</code> element in case it exists
<div class="exampleInner">

 <xforms:delete nodeset="item[2]"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <shoppingcart xmlns="">
         <item>
             <product>SKU-0815</product>
             <quantity>1</quantity>
             <unitcost>29.99</unitcost>
             <price>29.99</price>
         </item>
         '''<font size="larger"><item></font>'''
             '''<font size="larger"><product>SKU-4711</product></font>'''
             '''<font size="larger"><quantity>3</quantity></font>'''
             '''<font size="larger"><unitcost>7.49</unitcost></font>'''
             '''<font size="larger"><price>22.47</price></font>'''
         '''<font size="larger"></item></font>'''
     </shoppingcart>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <shoppingcart xmlns="">
         <item>
             <product>SKU-0815</product>
             <quantity>1</quantity>
             <unitcost>29.99</unitcost>
             <price>29.99</price>
         </item>
     </shoppingcart>
 </xforms:instance>

</div></div></div><div class="div2">

===Remove Attribute===

Pattern: '''<delete nodeset="'''''exact attribute to remove'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact attribute to remove, so <code>nodeset</code> is used. If the attribute does not exist, the operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Remove </nowiki><code>rating</code> attribute in case it exists
<div class="exampleInner">

 <xforms:delete nodeset="item/@rating"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="23" '''<font size="larger">rating="classified"</font>'''/>
     </items>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="23"/>
     </items>
 </xforms:instance>

</div></div></div><div class="div2">

===Remove Nodeset===

Pattern: '''<delete nodeset="'''''nodeset to remove'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate a nodeset to remove, so <code>nodeset</code> is used. If the nodeset does not exist, the operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Remove </nowiki><code>track</code> nodeset in case it exists
<div class="exampleInner">

 <xforms:delete nodeset="track"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <playlist xmlns="">
         <name>Music for Airports</name>
         '''<font size="larger"><track id="382"/></font>'''
         '''<font size="larger"><track id="461"/></font>'''
         '''<font size="larger"><track id="629"/></font>'''
     </playlist>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <playlist xmlns="">
         <name>Music for Airports</name>
     </playlist>
 </xforms:instance>

</div></div></div><div class="div2">

===Copy Nodeset===

Pattern: '''<insert context="'''''parent of new nodeset'''''" nodeset="*" origin="'''''nodeset to copy'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is used so that this pattern will work whether or not the parent element is empty.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Append a </nowiki><code>person</code> nodeset into a list of <code>people</code>
<div class="exampleInner">

 <xforms:insert context="people" nodeset="person" origin="instance('prototypes')/person"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <data xmlns="">
         <people/>
     </data>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name>Jane Doe</name>
         </person>
         <person>
             <name>John Doe</name>
         </person>
         <person>
             <name>Joe Sixpack</name>
         </person>
     </prototypes>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <data xmlns="">
         <people>
             '''<font size="larger"><person></font>'''
                 '''<font size="larger"><name>Jane Doe</name></font>'''
             '''<font size="larger"></person></font>'''
             '''<font size="larger"><person></font>'''
                 '''<font size="larger"><name>John Doe</name></font>'''
             '''<font size="larger"></person></font>'''
             '''<font size="larger"><person></font>'''
                 '''<font size="larger"><name>Joe Sixpack</name></font>'''
             '''<font size="larger"></person></font>'''
         </people>
     </data>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name>Jane Doe</name>
         </person>
         <person>
             <name>John Doe</name>
         </person>
         <person>
             <name>Joe Sixpack</name>
         </person>
     </prototypes>
 </xforms:instance>

</div></div></div><div class="div2">

===Copy Attribute List===

Pattern: '''<insert context="'''''exact element receiving attribute list'''''" origin="'''''attribute list to copy'''''"/>'''

<div class="exampleOuter">

'''Operation'''<nowiki>: Copy attribute list from one </nowiki><code>item</code> to another

<div class="exampleInner">

 <xforms:insert context="item[2]" origin="../item[1]/@*"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="0" rating="classified"/>
         <item/>
     </items>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="0" rating="classified"/>
         <item '''<font size="larger">key="0" rating="classified"</font>'''/>
     </prototypes>
 </xforms:instance>

</div></div></div><div class="div2">

===Replace Element===

Pattern: '''<insert nodeset="'''''exact element to replace'''''" origin="'''''element to copy'''''"/>''' '''<delete nodeset="'''''exact element to replace'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact element to replace, so <code>nodeset</code> is used. If the element does not exist, both insert and delete operation will have no effect.

</div><div class="exampleOuter">

'''Operation'''<nowiki>: Replace a </nowiki><code>person</code> element by copying a new one and removing the old one

<div class="exampleInner">

 <xforms:insert nodeset="person[1]" origin="instance('prototypes')/person"/>
 <xforms:delete nodeset="person[1]"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <people xmlns="">
         <person>
             <name>John Doe</name>
         </person>
     </people>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name/>
         </person>
     </prototypes>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <people xmlns="">
         <person>
             '''<font size="larger"><name/></font>'''
         </person>
     </people>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <person>
             <name/>
         </person>
     </prototypes>
 </xforms:instance>

</div></div></div><div class="div2">

===Replace Attribute===

Pattern: '''<setvalue ref="'''''exact attribute to replace'''''" value="'''''attribute to copy'''''"/>'''

<div class="note">

'''Note:'''

If the attribute does not exist, the operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Replace an attribute with the copy of a given attribute</nowiki>
<div class="exampleInner">

 <xforms:setvalue ref="item[2]/@key" value="../../item[1]/@key"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance >
     <items xmlns="">
         <item key="0"/>
         <item key="4711"/>
     </items>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance >
     <items xmlns="">
         <item key="0"/>
         <item '''<font size="larger">key="0"</font>'''/>
     </items>
 </xforms:instance>

</div></div></div><div class="div2">

===Replace Instance with Insert===

Pattern: '''<insert nodeset="'''''root node of instance to replace'''''" origin="'''''element to copy'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an instance root node to replace, so <code>nodeset</code> is used. Since an instance cannot be empty, <code>nodeset</code> will always be non-empty. Insert implements special handling for instance root nodes, thus a delete operation is not necessary.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Replace instance root node with an empty </nowiki><code>shoppingcart</code> element
<div class="exampleInner">

 <xforms:insert nodeset="." origin="instance('prototypes')/shoppingcart"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <shoppingcart xmlns="">
         '''<font size="larger"><item></font>'''
             '''<font size="larger"><product>SKU-0815</product></font>'''
             '''<font size="larger"><quantity>1</quantity></font>'''
             '''<font size="larger"><unitcost>29.99</unitcost></font>'''
             '''<font size="larger"><price>29.99</price></font>'''
         '''<font size="larger"></item></font>'''
         '''<font size="larger"><item></font>'''
             '''<font size="larger"><product>SKU-4711</product></font>'''
             '''<font size="larger"><quantity>3</quantity></font>'''
             '''<font size="larger"><unitcost>7.49</unitcost></font>'''
             '''<font size="larger"><price>22.47</price></font>'''
         '''<font size="larger"></item></font>'''
     </shoppingcart>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <shoppingcart/>
     </prototypes>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <shoppingcart xmlns=""/>
 </xforms:instance>
 
 <xforms:instance>
     <prototypes xmlns="">
         <shoppingcart/>
     </prototypes>
 </xforms:instance>

</div></div></div><div class="div2">

===Move Element===

Pattern: '''<insert context="'''''new parent of element'''''" nodeset="*" origin="'''''exact element to move'''''"/>''' '''<delete nodeset="'''''exact element to move'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is used for insert so that this pattern will work whether or not the new parent element is empty. For delete the <code>nodeset</code> attribute is used instead because this pattern assumes the ability to indicate an exact element to move. If the element to be moved does not exist, both insert and delete operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Copy an existing element to a new parent and remove the original</nowiki>
<div class="exampleInner">

 <xforms:insert context="playlist[2]" nodeset="track" origin="../playlist[1]/track[2]"/>
 <xforms:delete nodeset="playlist[1]/track[2]"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <library xmlns="">
         <playlist>
             <name>Music for Airports</name>
             <track id="382"/>
             '''<font size="larger"><track id="461"/></font>'''
             <track id="629"/>
         </playlist>
         <playlist>
             <name>Lullabies</name>
             <track id="251"/>
             <track id="331"/>
         </playlist>
     </library>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <library xmlns="">
         <playlist>
             <name>Music for Airports</name>
             <track id="382"/>
             <track id="629"/>
         </playlist>
         <playlist>
             <name>Lullabies</name>
             <track id="251"/>
             <track id="331"/>
             '''<font size="larger"><track id="461"/></font>'''
         </playlist>
     </library>
 </xforms:instance>

</div></div></div><div class="div2">

===Move Attribute===

Pattern: '''<insert context="'''''exact element receiving attribute'''''" origin="'''''exact attribute to move'''''"/>''' '''<delete nodeset="'''''exact attribute to move'''''"/>'''

<div class="note">

'''Note:'''

If the attribute to be moved does not exist, both insert and delete operation will have no effect.

</div><div class="exampleOuter">
'''Operation'''<nowiki>: Copy an existing attribute to a new element and remove the original</nowiki>
<div class="exampleInner">

 <xforms:insert context="item[2]" origin="../item[1]/@rating"/>
 <xforms:delete nodeset="item[1]/@rating"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="23" '''<font size="larger">rating="classified"</font>'''/>
         <item key="42"/>
     </items>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <items xmlns="">
         <item key="23"/>
         <item key="42" '''<font size="larger">rating="classified"</font>'''/>
     </items>
 </xforms:instance>

</div></div></div><div class="div2">

===Insert Element into Non-Contiguous, Heterogeneous Nodeset===

Pattern: '''<insert nodeset="'''''non-contiguous, heterogeneous nodeset'''''" origin="'''''element to copy'''''" at="'''''insert location'''''"/>'''

<div class="note">

'''Note:'''

The <code>context</code> attribute is not used because it adheres to the first node rule and therefore would not allow to select a non-contiguous nodeset. The <code>nodeset</code> attribute is used instead to select a nodeset consisting of nodes with different names and different parents. The parent of the new node is the same as the parent of the insert location node selected by the combination of <code>nodeset</code> and <code>at</code>.

</div><div class="exampleOuter">

'''Operation'''<nowiki>: Copy an existing element into a non-contiguous, heterogeneous nodeset at a specified position</nowiki>

<div class="exampleInner">

 <xforms:insert nodeset="chapter/*" origin="instance('prototypes')/paragraph" at="7" position="before"/>

</div>

'''Data Before Operation'''

<div class="exampleInner">

 <xforms:instance>
     <document xmlns="">
         <chapter>
             <header>Lorem ipsum</header>
             <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
             <diagram>Exemplum 1</diagram>
             <diagram>Exemplum 2</diagram>
             <paragraph>Primis abhorreant delicatissimi ...</paragraph>
         </chapter>
         <chapter>
             <header>Lorem ipsum</header>
             <diagram>Exemplum 3</diagram>
         </chapter>
     </document>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <chapter/>
         <header/>
         <paragraph/>
         <diagram/>
     </prototypes>
 </xforms:instance>

</div>

'''Data After Operation'''

<div class="exampleInner">

 <xforms:instance>
     <document xmlns="">
         <chapter>
             <header>Lorem ipsum</header>
             <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
             <diagram>Exemplum 1</diagram>
             <diagram>Exemplum 2</diagram>
             <paragraph>Primis abhorreant delicatissimi ...</paragraph>
         </chapter>
         <chapter>
             <header>Lorem ipsum</header>
             '''<font size="larger"><paragraph/></font>'''
             <diagram>Exemplum 3</diagram>
         </chapter>
     </document>
 </xforms:instance>
 
 <xforms:instance id="prototypes">
     <prototypes xmlns="">
         <chapter/>
         <paragraph/>
         <diagram/>
     </prototypes>
 </xforms:instance>

</div></div></div></div><div class="div1">

==Recalculation Sequence Algorithm==

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

Following is the default handling for a <code>recalculate</code> action. Action <code>recalculate</code> is defined in [[#The recalculate Element|The recalculate Element]].

# A master dependency directed graph is created as detailed in [[#Details on Creating the Master Dependency Directed Graph|Details on Creating the Master Dependency Directed Graph]].
# To provide consistent behavior, implementations must reduce the number of vertices to be processed by computing a pertinent dependency subgraph consisting only of vertices and edges that are reachable from nodes that require recomputation. This is detailed in [[#Details on Creating the Pertinent Dependency Subgraph|Details on Creating the Pertinent Dependency Subgraph]]. Note that on a first recomputation (such as on form load), the pertinent dependency subgraph will be the same as the master dependency directed graph.
# A topological sort is performed on the vertices of the pertinent dependency subgraph, resulting in an order of evaluation in which each vertex is evaluated only after those vertices on which it depends and before all vertices which depend on it. The topological sort algorithm is discussed at <nowiki>[</nowiki>[[#ref-art |Algorithms]]<nowiki>]</nowiki>.
# The <code>recalculate</code> process completes.

<div class="div2">

===Details on Creating the Master Dependency Directed Graph===

The master dependency directed graph can be considered an array with one record for each vertex, each having the following fields:

<blockquote>

'''InstanceNode'''<nowiki>: a reference to the associated instance data node</nowiki><br />'''type'''<nowiki>: indicates the aspect of the instance node represented by the vertex (the text content or a model item property such as readOnly or required)</nowiki><br />'''depList'''<nowiki>: a list of vertices that refer to this vertex</nowiki><br />'''in-degree'''<nowiki>: the number of vertices on which this vertex depends</nowiki><br />'''visited'''<nowiki>: a flag used to ensure vertices are not added to a subgraph multiple times</nowiki><br />'''index'''<nowiki>: an association between vertices in the master dependency directed graph and a subgraph</nowiki>

</blockquote>

The <code>depList</code> for each vertex is assigned based on the referenced XML nodes of instance nodes, which are obtained by parsing the computed expression bound to the node (e.g., by calculate, relevant, readonly, or required). Any expression violating any Binding Expression Constraint causes an exception ([[#The xforms-compute-exception Event|The xforms-compute-exception Event]]), terminating the <code>recalculate</code> process.

Specifically, the <code>depList</code> for a vertex <code>v</code> is assigned to be the vertices other than <code>v</code> whose computational expressions reference <code>v</code> (described below). Vertex <code>v</code> is excluded from its own <code>depList</code> to allow self-references to occur without causing a circular reference exception.

A computational expression appearing in a <code>calculate</code> attribute controls the text content (value) of one or more instance nodes. A vertex exists for each instance node to represent the expression in the context of the node. Likewise, computational expressions for model item properties such as <code>readOnly</code> and <code>required</code> are applied to one or more instance nodes, and vertices are created to represent such expressions in the context of each applicable node. The computational expression of each vertex must be examined to determine the XML nodes to which it refers. Any expression violating any Binding Expression Constraint causes an exception ([[#The xforms-compute-exception Event|The xforms-compute-exception Event]]), terminating the <code>recalculate</code> process. A computation expression refers to a vertex <code>v</code> if a subexpression indicates the InstanceNode for <code>v</code> and <code>v</code> represents the instance node text content (its value). In this version of XForms, model item properties such as <code>readOnly</code> and <code>required</code> cannot be referenced in an expression.

</div><div class="div2">

===Details on Creating the Pertinent Dependency Subgraph===

If all calculations must be performed, which is the case on form load, then the pertinent dependency subgraph is simply a duplicate of the master dependency directed graph. If the recalculation algorithm is invoked with a list of changed instance data nodes since the last recalculation, then the pertinent dependency subgraph is obtained by exploring the paths of edges and vertices in the computational dependency directed graph that are reachable from each vertex in the change list. The method of path exploration can be depth first search, a suitable version of which appears in the pseudo-code below.

<div class="exampleOuter"><div class="exampleHead">Sample Algorithm to Create the Pertinent Dependency Subgraph</div>

This algorithm creates a pertinent dependency subgraph <code>S</code> from a list of changed instance data nodes <code>L<sub>c</sub></code>. Variables such as <code>v</code> and <code>w</code> represent vertices in the master dependency directed graph. The same variables ending with <code>S</code> indicate vertices in the pertinent dependency subgraph <code>S</code>.

<div class="exampleInner">
<pre>
 // Use depth-first search to explore master digraph subtrees rooted at
 // each changed vertex. A 'visited' flag is used to stop exploration
 // at the boundaries of previously explored subtrees (because subtrees
 // can overlap in directed graphs).
 for each vertex ''r'' in ''Lc''
   if ''r'' is not visited
   {
     Push the pair (NIL, ''r'') onto a stack
     while the stack is not empty
     {
       (''v'', ''w'') = pop dependency pair from stack
       if ''w'' is not visited
       {
         Set the visited flag of ''w'' to true
         Create a vertex ''wS'' in S to represent ''w''
         Set the index of ''w'' equal to the array location of ''wS''
         Set the index of ''wS'' equal to the array location of ''w''
         Set the InstanceNode of ''wS'' equal to the InstanceNode of ''w''
         Set the type of ''wS'' equal to the type of ''w''
         For each dependency node ''x'' of ''w''
           Push the pair (''w'', ''x'') onto the stack
       }
       else Obtain ''wS'' from index of ''w''
       if ''v'' is not NIL
       {
         Obtain ''vS'' from index of ''v''
         Add dependency node for ''wS'' to ''vS''
         Increment inDegree of ''wS''
       }
     }
   }
 
 // Now clear the visited flags set in the loop above
 for each vertex ''vS'' in S
 {
   Obtain ''v'' from index of ''vS''
   Assign false to the visited flag of ''v''
 }
</pre>
</div></div>

Note that the number of vertices and dependency nodes in the pertinent dependency subgraph is not known beforehand, but a method such as array doubling (see <nowiki>[</nowiki>[[#ref-ddj |DDJ-ArrayDoubling]]<nowiki>]</nowiki>) can be used to ensure that building the subgraph is performed in time linear in the size of <code>S</code>.

</div><div class="div2">

===Details on Computing Individual Vertices===

The following steps process vertices, resulting in a recalculated form:

# A vertex with inDegree of 0 is selected for evaluation and removed from the pertinent dependency subgraph. In the case where more than one vertex has inDegree zero, no particular ordering is specified. If the pertinent dependency subgraph contains vertices, but none have an inDegree of 0, then the calculation structure of the form has a loop, and an exception ([[#The xforms-compute-exception Event|The xforms-compute-exception Event]]) must be thrown, terminating processing.
# If the vertex corresponds to a computed item, computed expressions are evaluated as follows:
## <code>calculate</code><nowiki>: If the value of the model item changes, the corresponding instance data is updated and the dirty flag is set.</nowiki>
## <code>relevant</code>, <code>readonly</code>, <code>required</code>, <code>constraint</code><nowiki>: If any or all of these computed properties change, the new settings are placed into effect for associated form controls.</nowiki>
# For each vertex in the <code>depList</code> of the removed vertex, decrement the inDegree by 1.
# If no vertices remain in the pertinent dependency subgraph, then the calculation has successfully completed. Otherwise, repeat this sequence from step 1.

</div><div class="div2">

===Example of Calculation Processing===

For example, consider six vertices <code>a</code>, <code>b</code>, <code>v</code>, <code>w</code>, <code>x</code>, and <code>y</code>. Let <code>a</code> and <code>b</code> represent the text content of instance nodes that will be set by a binding from user input controls. Let <code>v</code> and <code>w</code> be vertices representing the calculated value and the validity property of a third instance node <code>c</code>. These vertices would result from a <code>bind</code> element <code>B</code> with <code>calculate</code> and <code>constraint</code> attributes and a <code>nodeset</code> attribute that indicates <code>c</code>. Suppose that the value of <code>c</code> is the product of <code>a</code> and <code>b</code> and that the value is only valid if it does not exceed 100. Likewise, suppose <code>x</code> and <code>y</code> are vertices representing the calculated value and the validity property of a fourth instance node <code>d</code>. Let the value of <code>d</code> be the sum of <code>a</code> and <code>b</code>, and let <code>d</code> be valid if the value does not exceed 20. The figure below depicts the dependency digraph for this example.

[[Image:depdigraph.gif|Dependency graph]]

Vertices <code>a</code> and <code>b</code> have edges leading to <code>v</code> and <code>x</code> because these vertices represent the calculate expressions of <code>c</code> and <code>d</code>, which reference <code>a</code> and <code>b</code> to compute their product and sum, respectively. Similarly, <code>v</code> and <code>x</code> have directed edges to <code>w</code> and <code>y</code>, respectively, because <code>w</code> and <code>y</code> represent the <code>constraint</code> expressions of <code>c</code> and <code>d</code>, which reference the values of <code>c</code> and <code>d</code> to compare them with boundary values.

If <code>a</code> and <code>b</code> are initially equal to 10, and the user changes <code>a</code> to 11, then it is necessary to first recalculate <code>v</code> (the value of <code>c</code>) then recalculate <code>w</code> (the validity property of the value of <code>c</code>). Likewise, <code>x</code> (the value of <code>d</code>) must be recalculated before recalculating <code>y</code> (the validity property of the value of <code>d</code>). In both cases, the validity of the value does not change to <code>false</code> until after the new product and sum are computed based on the change to <code>a</code>. However, there are no interdependencies between <code>v</code> and <code>x</code>, so the product and sum could be computed in either order.

The pertinent subgraph excludes <code>b</code> and only vertex <code>a</code> has in-degree of zero. The vertex <code>a</code> is processed first. It is not a computed vertex, so no recalculation occurs on <code>a</code>, but its removal causes <code>v</code> and <code>x</code> to have in-degree zero. Vertex <code>v</code> is processed second. Its value changes to 121, and its removal drops the in-degree of vertex <code>w</code> to zero. Vertex <code>x</code> is processed next, changing value to 21. When <code>x</code> is removed, its neighbor <code>y</code> drops to in-degree zero. The fourth and fifth iterations of this process recalculate the validity of <code>w</code> and <code>y</code>, both of which change to false.

</div></div><div class="div1">

==Privacy Considerations==

<div class="div2">

===Using P3P with XForms===

P3P privacy policies may be associated with any forms transmitted over HTTP that have URIs associated with them. In the future, mechanisms may be specified for associating P3P policies with content transmitted over other protocols.

P3P allows for policies to be associated with an individual URI or a set of URIs. By associating a separate policy with each URI a site can declare a very precise policy that addresses exactly what data is collected with a particular HTTP request and how that data will be used. However, site management is substantially easier for many sites if they declare a single policy that covers many URIs, or even their entire Web presence.

The P3P specification specifies several methods for referencing a P3P policy reference file, which in turn associates P3P policies with URIs and cookies. XForms can be P3P enabled using any of the methods that are appropriate for the Web site in which they are embedded. Some special considerations regarding forms are addressed in the P3P Specification. <nowiki>[</nowiki>[[#ref-p3p-1.0 |P3P 1.0]]<nowiki>]</nowiki>

Different P3P policies may be applied to the representation of a form embedded in a containing document to that which is associated with the data submitted via that form. If the form representation is served from a different server than the form is submitted to, it is likely that separate P3P policy reference files and policies will be needed. Typically the form representation causes only ''clickstream'' data (as defined in <nowiki>[</nowiki>[[#ref-p3p-1.0 |P3P 1.0]]<nowiki>]</nowiki> section 5.6.4) to be transferred, while a form submission causes much more data to be transferred.

</div></div><div class="div1">

==Input Modes (Non-Normative)==

The attribute <code>inputmode</code> provides a ''hint'' to the user agent to select an appropriate input mode for the text input expected in an associated form control. The input mode may be a keyboard configuration, an input method editor (also called front end processor) or any other setting affecting input on the device(s) used.

Using <code>inputmode</code>, the author can give hints to the agent that make form input easier for the user. Authors should provide <code>inputmode</code> attributes wherever possible, making sure that the values used cover a wide range of devices.

<div class="div2">

===inputmode Attribute Value Syntax===

The value of the <code>inputmode</code> attribute is a white space separated list of tokens. Tokens are either sequences of alphabetic letters or absolute URIs. The later can be distinguished from the former by noting that absolute URIs contain a ':'. Tokens are case-insensitive. All the tokens consisting of alphabetic letters only are defined in this specification, in [[#List of Tokens|List of Tokens]] (or a successor of this specification).

This specification does not define any URIs for use as tokens, but allows others to define such URIs for extensibility. This may become necessary for devices with input modes that cannot be covered by the tokens provided here. The URI should dereference to a human-readable description of the input mode associated with the use of the URI as a token. This description should describe the input mode indicated by this token, and whether and how this token modifies other tokens or is modified by other tokens.

</div><div class="div2">

===User Agent Behavior===

Upon entering an empty form control with an <code>inputmode</code> attribute, the user agent should select the input mode indicated by the <code>inputmode</code> attribute value. User agents should not use the <code>inputmode</code> attribute to set the input mode when entering a form control with text already present. To set the appropriate input mode when entering a form control that already contains text, user agents should rely on platform-specific conventions.

User agents should make available all the input modes which are supported by the (operating) system/device(s) they run on/have access to, and which are installed for regular use by the user. This is typically only a small subset of the input modes that can be described with the tokens defined here.

<div class="note">

'''Note:'''

Additional guidelines for user agent implementation are found at <nowiki>[</nowiki>[[#ref-uaag-1.0 |UAAG 1.0]]<nowiki>]</nowiki>.

</div>

The following simple algorithm is used to define how user agents match the values of an <code>inputmode</code> attribute to the input modes they can provide. This algorithm does not have to be implemented directly; user agents just have to behave as if they used it. The algorithm is not designed to produce "obvious" or "desirable" results for every possible combination of tokens, but to produce correct behavior for frequent token combinations and predictable behavior in all cases.

First, each of the input modes available is represented by one or more lists of tokens. An input mode may correspond to more than one list of tokens; as an example, on a system set up for a Greek user, both "greek upperCase" and "user upperCase" would correspond to the same input mode. No two lists will be the same.

Second, the <code>inputmode</code> attribute is scanned from front to back. For each token <var>t</var> in the <code>inputmode</code> attribute, if in the remaining list of tokens representing available input modes there is any list of tokens that contains <var>t</var>, then all lists of tokens representing available input modes that do not contain <var>t</var> are removed. If there is no remaining list of tokens that contains <var>t</var>, then <var>t</var> is ignored.

Third, if one or more lists of tokens are left, and they all correspond to the same input mode, then this input mode is chosen. If no list is left (meaning that there was none at the start) or if the remaining lists correspond to more than one input mode, then no input mode is chosen.

<div class="exampleOuter">

Example: Assume the list of lists of tokens representing the available input modes is: {"cyrillic upperCase", "cyrillic lowerCase", "cyrillic", "latin", "user upperCase", "user lowerCase"}, then the following <code>inputmode</code> values select the following input modes: "cyrillic title" selects "cyrillic", "cyrillic lowerCase" selects "cyrillic lowerCase", "lowerCase cyrillic" selects "cyrillic lowerCase", "latin upperCase" selects "latin", but "upperCase latin" does select "cyrillic upperCase" or "user upperCase" if they correspond to the same input mode, and does not select any input mode if "cyrillic upperCase" and "user upperCase" do not correspond to the same input mode.

</div></div><div class="div2">

===List of Tokens===

Tokens defined in this specification are separated into two categories: ''Script tokens'' and ''modifiers''. In <code>inputmode</code> attributes, script tokens should always be listed before modifiers.

<div class="div3">

====Script Tokens====

Script tokens provide a general indication of the set of characters that is covered by an input mode. In most cases, script tokens correspond directly to <nowiki>[</nowiki>[[#ref-unicode-scripts |Unicode Scripts]]<nowiki>]</nowiki>. However, this neither means that an input mode has to allow input for all the characters in the script, nor that an input mode is limited to only characters from that specific script. As an example, a "latin" keyboard doesn't cover all the characters in the Latin script, and includes punctuation which is not assigned to the Latin script.

The script tokens that are allowed are listed in <nowiki>[</nowiki>[[#ref-unicode-script-names |Unicode Script Names]]<nowiki>]</nowiki>, "codes for the representations of scripts". The allowable values are those listed in the column "Property Value Alias" with the underscore character (_) removed, and excluding the two values "Common", and "Unknown". At the time of writing, these values are:

* <code>Arabic</code>
* <code>Armenian</code>
* <code>Balinese</code>
* <code>Bengali</code>
* <code>Bopomofo</code>
* <code>Braille</code>
* <code>Buginese</code>
* <code>Buhid</code>
* <code>CanadianAboriginal</code>
* <code>Carian</code>
* <code>Cherokee</code>
* <code>Coptic</code>
* <code>Cuneiform</code>
* <code>Cypriot</code>
* <code>Cyrillic</code>
* <code>Deseret</code>
* <code>Devanagari</code>
* <code>Ethiopic</code>
* <code>Georgian</code>
* <code>Glagolitic</code>
* <code>Gothic</code>
* <code>Greek</code>
* <code>Gujarati</code>
* <code>Gurmukhi</code>
* <code>Han</code>
* <code>Hangul</code>
* <code>Hanunoo</code>
* <code>Hebrew</code>
* <code>Hiragana</code>
* <code>Kannada</code>
* <code>Katakana</code>
* <code>KatakanaOrHiragana</code>
* <code>KayahLi</code>
* <code>Kharoshthi</code>
* <code>Khmer</code>
* <code>Lao</code>
* <code>Latin</code>
* <code>Lepcha</code>
* <code>Limbu</code>
* <code>LinearB</code>
* <code>Lycian</code>
* <code>Lydian</code>
* <code>Malayalam</code>
* <code>Mongolian</code>
* <code>Myanmar</code>
* <code>NewTaiLue</code>
* <code>Nko</code>
* <code>Ogham</code>
* <code>OlChiki</code>
* <code>OldItalic</code>
* <code>OldPersian</code>
* <code>Oriya</code>
* <code>Osmanya</code>
* <code>PhagsPa</code>
* <code>Phoenician</code>
* <code>Rejang</code>
* <code>Runic</code>
* <code>Saurashtra</code>
* <code>Shavian</code>
* <code>Sinhala</code>
* <code>Sundanese</code>
* <code>SylotiNagri</code>
* <code>Syriac</code>
* <code>Tagalog</code>
* <code>Tagbanwa</code>
* <code>TaiLe</code>
* <code>Tamil</code>
* <code>Telugu</code>
* <code>Thaana</code>
* <code>Thai</code>
* <code>Tibetan</code>
* <code>Tifinagh</code>
* <code>Ugaritic</code>
* <code>Vai</code>
* <code>Yi</code>

Seven other values are allowed:

{| summary="a list of additional allowed values for the inputmode attribute" border="2" frame="border" frame="border"
! rowspan="1" colspan="1" | Input Mode Token
! rowspan="1" colspan="1" | Comments
|-
| rowspan="1" colspan="1" | <code>ipa</code>
| rowspan="1" colspan="1" | International Phonetic Alphabet
|-
| rowspan="1" colspan="1" | <code>hanja</code>
| rowspan="1" colspan="1" | Subset of 'han' used in writing Korean
|-
| rowspan="1" colspan="1" | <code>kanji</code>
| rowspan="1" colspan="1" | subset of 'han' used in writing Japanese
|-
| rowspan="1" colspan="1" | <code>math</code>
| rowspan="1" colspan="1" |
mathematical symbols and related characters, representing the <nowiki>[</nowiki>[[#ref-unicode-script-names |Unicode Script Names]]<nowiki>]</nowiki> code "Zmth"
|-
| rowspan="1" colspan="1" | <code>simplifiedHanzi</code>
| rowspan="1" colspan="1" |
representing the <nowiki>[</nowiki>[[#ref-unicode-script-names |Unicode Script Names]]<nowiki>]</nowiki> code "Hans"
|-
| rowspan="1" colspan="1" | <code>traditionalHanzi</code>
| rowspan="1" colspan="1" |
representing the <nowiki>[</nowiki>[[#ref-unicode-script-names |Unicode Script Names]]<nowiki>]</nowiki> code "Hant"
|-
| rowspan="1" colspan="1" | <code>user</code>
| rowspan="1" colspan="1" | special value denoting the 'native' input of the user according to the system environment
|}

</div><div class="div3">

====Modifier Tokens====

Modifier tokens can be added to the scripts they apply in order to more closely specify the kind of characters expected in the form control. Traditional PC keyboards do not need most modifier tokens (indeed, users on such devices would be quite confused if the software decided to change case on its own; CAPS lock for upperCase may be an exception). However, modifier tokens can be very helpful to set input modes for small devices.

{| summary="list of modifier tokens for attribute inputmode" border="2" frame="border" frame="border"
! rowspan="1" colspan="1" | Input Mode Token
! rowspan="1" colspan="1" | Comments
|-
| rowspan="1" colspan="1" | <code>lowerCase</code>
| rowspan="1" colspan="1" | lowercase (for bicameral scripts)
|-
| rowspan="1" colspan="1" | <code>upperCase</code>
| rowspan="1" colspan="1" | uppercase (for bicameral scripts)
|-
| rowspan="1" colspan="1" | <code>titleCase</code>
| rowspan="1" colspan="1" | title case (for bicameral scripts): words start with an upper case letter
|-
| rowspan="1" colspan="1" | <code>startUpper</code>
| rowspan="1" colspan="1" | start input with one uppercase letter, then continue with lowercase letters
|-
| rowspan="1" colspan="1" | <code>digits</code>
| rowspan="1" colspan="1" | digits of a particular script (e.g. inputmode='thai digits')
|-
| rowspan="1" colspan="1" | <code>symbols</code>
| rowspan="1" colspan="1" | symbols, punctuation (suitable for a particular script)
|-
| rowspan="1" colspan="1" | <code>predictOn</code>
| rowspan="1" colspan="1" | text prediction switched on (e.g. for running text)
|-
| rowspan="1" colspan="1" | <code>predictOff</code>
| rowspan="1" colspan="1" | text prediction switched off (e.g. for passwords)
|-
| rowspan="1" colspan="1" | <code>halfWidth</code>
| rowspan="1" colspan="1" | half-width compatibility forms (e.g. Katakana; deprecated)
|}

</div></div><div class="div2">

===Relationship to XML Schema pattern facets===

User agents may use information available in an XML Schema pattern facet to set the input mode. Note that a pattern facet is a hard restriction on the lexical value of an instance data node, and can specify different restrictions for different parts of the data item. Attribute <code>inputmode</code> is a soft hint about the kinds of characters that the user may most probably start to input into the form control. Attribute <code>inputmode</code> is provided in addition to pattern facets for the following reasons:

# The set of allowable characters specified in a pattern may be so wide that it is not possible to deduce a reasonable input mode setting. Nevertheless, there frequently is a kind of characters that will be input by the user with high probability. In such a case, <code>inputmode</code> allows to set the input mode for the user's convenience.
# In some cases, it would be possible to derive the input mode setting from the pattern because the set of characters allowed in the pattern closely corresponds to a set of characters covered by an <code>inputmode</code> attribute value. However, such a derivation would require a lot of data and calculations on the user agent.
# Small devices may leave the checking of patterns to the server, but will easily be able to switch to those input modes that they support. Being able to make data entry for the user easier is of particular importance on small devices.

</div><div class="div2">

===Examples===

<div class="exampleOuter">
This is an example of  the user interface markup for  a form for user input in Japanese. .
<div class="exampleInner">
<pre>
 <xf:input ref="name" inputmode="kanji">
    <xf:label>Family name:</xf:label>
 </xf:input>
 
 <xf:input ref="nameKana" inputmode="katakana">
    <xf:label>Family name in kana:</xf:label>
 </xf:input>
 
 <xf:input ref="given" inputmode="kanji">
    <xf:label>Given name:</xf:label>
 </xf:input>
 
 <xf:input ref="givenKana" inputmode="katakana">
    <xf:label>Given name in kana:</xf:label>
 </xf:input>
 
 <xf:input ref="email" inputmode="latin lowerCase">
    <xf:label>Email:</xf:label>
 </xf:input>
 
 <xf:input ref="phone" inputmode="latin digits">
    <xf:label>Telephone:</xf:label>
 </xf:input>
 
 <xf:textarea ref="comments" inputmode="user predictOn">
    <xf:label>Comments:</xf:label>
 </xf:textarea>
 
 <xf:submit submission="sendit">
    <xf:label>Send It</xf:label>
 </xf:submit>
</pre>
</div></div></div></div><div class="div1">

==Schema for XForms (Non-Normative)==

The XML Schema for XForms, which has a target namespace <code>http://www.w3.org/2002/xforms</code>, is located at http://www.w3.org/MarkUp/Forms/2007/XForms-11-Schema.xsd.

The RELAXNG (<nowiki>[</nowiki>[[#ref-RELAXNG |RELAXNG]]<nowiki>]</nowiki>, <nowiki>[</nowiki>[[#ref-RELAXNG-Compact |RELAXNG Compact]]<nowiki>]</nowiki>) Schema for XForms, which includes the target namespace <code>http://www.w3.org/2002/xforms</code> as well as the version suitable for import to a host language namespace, is located at http://www.w3.org/MarkUp/Forms/2007/XForms-11-RELAXNG.zip.

<div class="div2">

===Schema for XML Events===

This XML Schema for XML Events is referenced by the XML Schema for XForms, and located at [http://www.w3.org/TR/2003/REC-xml-events-20031014/#a_schema_attribs  http://www.w3.org/TR/2003/REC-xml-events-20031014/#a_schema_attribs].

</div></div><div class="div1">

==XForms and Styling (Non-Normative)==

This informative section provides a broad outline of new and existing CSS features needed to style XForms content. A future Recommendation from the CSS Working Group will fully develop the specification of these features.

<div class="div2">

===Pseudo-classes===

A CSS pseudo-class is used to select elements for styling based on information that lies outside of the document tree or that cannot be expressed using the other selectors.

{| summary="suggested pseudo-classes for styling forms" border="1"
! rowspan="1" colspan="1" | Name
! rowspan="1" colspan="1" | Defined in:
! rowspan="1" colspan="1" | Relationship to XForms
|-
| rowspan="1" colspan="1" | <code><nowiki>:enabled</nowiki></code> & <code><nowiki>:disabled</nowiki></code>
| rowspan="1" colspan="1" | [CSS3]
| rowspan="1" colspan="1" |
Selects any form control that is [[#def-relevant-form-control|relevant]] or [[#def-non-relevant-form-control|non-relevant]] (respectively).
|-
| rowspan="1" colspan="1" | <code><nowiki>:required</nowiki></code> & <code><nowiki>:optional</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Selects any core form control bound to a node with the model item property <code>required</code> evaluating to true or false (respectively).
|-
| rowspan="1" colspan="1" | <code><nowiki>:valid</nowiki></code> & <code><nowiki>:invalid</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Selects any core form control bound to a node that is currently valid or invalid (respectively), as defined by XForms.
|-
| rowspan="1" colspan="1" | <code><nowiki>:read-only</nowiki></code> & <code><nowiki>:read-write</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Selects any core form control bound to a node with the model item property <code>readonly</code> evaluating to true or false (respectively).
|-
| rowspan="1" colspan="1" | <code><nowiki>:out-of-range</nowiki></code> & <code><nowiki>:in-range</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Selects any core form control bound to a node that contains a value the form control is not or is capable of rendering, (respectively).
|-
| rowspan="1" colspan="1" | <code><nowiki>:value-empty</nowiki></code> & <code><nowiki>:value-non-empty</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Selects any core form control bound to a node whose content is the empty string or not the empty string (respectively).
|}

This list is not exhaustive; other pseudo-classes may be defined.

</div><div class="div2">

===Pseudo-elements===

Pseudo-elements are abstractions about the document tree beyond those specified by the document language. Pseudo-elements do not appear in the DOM; they are used only for purposes of styling.

{| summary="suggested pseudo-elements for styling forms" border="1"
! rowspan="1" colspan="1" | Name
! rowspan="1" colspan="1" | Defined in:
! rowspan="1" colspan="1" | Relationship to XForms
|-
| rowspan="1" colspan="1" | <code><nowiki>::value</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Represents the "active" area of a form control excluding the label; this corresponds in HTML to <code>input</code> and other form control elements. This pseudo-element is a child of the form control element, and appears immediately after the required <code>label</code> element.
|-
| rowspan="1" colspan="1" | <code><nowiki>::repeat-item</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Represents a single item from a repeating sequence. Its position is as a parent to all the elements in a single repeating item. Each <code><nowiki>::repeat-item</nowiki></code> is associated with a particular instance data node, and is affected by the model item properties (e.g. '<code>relevant</code>') found there, as the related style properties will cascade to the child elements.
|-
| rowspan="1" colspan="1" | <code><nowiki>::repeat-index</nowiki></code>
| rowspan="1" colspan="1" | TBD
| rowspan="1" colspan="1" | Represents the current item of a repeating sequence. Its position is as a parent of all the elements in the index repeating item (and as a child to the <code><nowiki>::repeat-item</nowiki></code> pseudo-element), thus any style declarations applying to this pseudo-element override those on the parent <code><nowiki>::repeat-item</nowiki></code>.
|}

This list is not exhaustive; other pseudo-elements may be defined.

</div><div class="div2">

===Examples===

The following examples collects together styling recommendations from this document, expressing them with a CSS notation. Throughout the examples, the following namespace declaration is assumed:

<div class="exampleInner">

 
 @namespace xf url('http://www.w3.org/2002/xforms');
 

</div>

From [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]]<nowiki>: "All form controls, including </nowiki>[[#Container Form Controls|container form controls]], should have an inline layout by default... By default, [[#def-repeat-item|repeat items]] should have a block layout." Hence, if the display property is not set via CSS, it should default to the following:

<div class="exampleInner">

 <nowiki>
 xf|input:enabled, xf|secret:enabled, xf|textarea:enabled, xf|output:enabled,
 xf|upload:enabled, xf|range:enabled, xf|trigger:enabled, xf|submit:enabled,
 xf|select:enabled, xf|select1:enabled { display: inline; }
 xf|output:enabled { display: inline; }
 xf|group:enabled, xf|switch:enabled { display: inline; }
 xf|repeat:enabled { display: inline; }
 ::repeat-item:enabled { display:block; }
     </nowiki>

</div>

From [[#The relevant Property|The relevant Property]]<nowiki>: "Typically, non-relevant content is not presented, or it may be styled as disabled." If the display property is not set via CSS, it should default to the following:</nowiki>

<div class="exampleInner">

 <nowiki>
 xf|input:disabled, xf|secret:disabled, xf|textarea:disabled,
 xf|output:disabled, xf|upload:disabled, xf|range:disabled,
 xf|trigger:disabled, xf|submit:disabled, xf|select:disabled,
 xf|select1:disabled
 {
   display: none;
 }
 
 xf|output:disabled { display: none; }
 xf|group:disabled, xf|switch:disabled { display: none; }
 ::repeat-item:disabled { display: none; }
     </nowiki>

</div>

Below is an example of how a form author can override the default display:none styling of :disabled. Note that the implementation must also implement the behavior of not accepting user input in the disabled control.

<div class="exampleInner">

 
 xf|input.authorization:disabled {
    display: inline; background-color: #bbbbbb
 }
 

</div>

From [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]]<nowiki>: "The readonly form control should render in a way which indicates that entering or changing the value is not allowed." Below is an example of one way to indicate this information. CSS does not have a way to provide readonly behavior, so this example merely changes the background color. An implementation could use this style by default, and an author would only need to use styling to override the default.</nowiki>

<div class="exampleInner">

 
 xf|input:enabled:readonly::value
 {
   display: inline; background-color: #888888
 }
 

</div>

From [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]]<nowiki>: "Except as noted, relevant form controls must distinguish rendering between being bound to a required node versus a non-required node. Exceptions are form controls that do not directly render the string value of the bound node (including trigger and the container form controls)." Below is an example styling form controls bound to required nodes with a soft yellow background. An implementation could use this style by default, and an author would only need to use styling to override the default.</nowiki>

<div class="exampleInner">

 
 xf|input:enabled:required, xf|secret:enabled:required,
 xf|textarea:enabled:required, xf|output:enabled:required,
 xf|upload:enabled:required, xf|range:enabled:required,
 xf|trigger:enabled:required, xf|submit:enabled:required,
 xf|select:enabled:required, xf|select1:enabled:required
 {
    background-color: #FFFFD0
 }
 

</div>

From [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]]<nowiki>: Relevant form controls must distinguish rendering between valid and "invalid states. Control of this behavior should be made available to stylesheets." Below is an example styling input controls bound to non-empty but invalid nodes with a reddish background. An implementation could use this style by default, and an author would only need to use styling to override the default.</nowiki>

<div class="exampleInner">

 
 xf|input:enabled:invalid:value-non-empty {
    background-color: #ff8080;
 }
 

</div>

From [[#Implementation Requirements Common to All Form Controls|Implementation Requirements Common to All Form Controls]]<nowiki>: "Relevant form controls must indicate when the bound instance data contains a value or content that the form control is not capable of rendering. Control of this behavior should be made available to stylesheets". In this example, select, select1, and range controls bound nodes whose values are not presentable by the controls are styled with in red. An implementation could use this style by default, and an author would only need to use styling to override the default.</nowiki>

<div class="exampleInner">

 
 xf|select1:enabled:out-of-range, xf|select1:enabled:out-of-range,
 xf|range:enabled:out-of-range {
   color: red;
 }
 

</div></div></div><div class="div1">

==Complete XForms Examples (Non-Normative)==

This section presents complete XForms examples. These and additional examples are maintained at [http://www.w3.org/MarkUp/Forms/2002/Examples/ http://www.w3.org/MarkUp/Forms/2002/Examples].

<div class="div2">

===XForms in XHTML===
<div class="exampleInner">

 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:my="http://commerce.example.com/payment" xml:lang="en">
  <head>
    <title>XForms in XHTML</title>
    <model xmlns="http://www.w3.org/2002/xforms" schema="payschema.xsd">
      <instance>
        <my:payment as="credit">
          <my:cc />
          <my:exp />
        </my:payment>
      </instance>
      <submission action="http://www.example.com/buy.rb" method="post" id="s00" />
      <bind nodeset="my:cc" relevant="../@as='credit'" required="true()" />
      <bind nodeset="my:exp" relevant="../@as='credit'" required="true()" />
    </model>
  </head>
  <body>
    ...
    <group xmlns="http://www.w3.org/2002/xforms">
        <select1 ref="@as">
          <label>Select Payment Method</label>
          <item>
              <label>Cash</label>
              <value>cash</value>
              <message level="modeless" ev:event="xforms-select">
              Please do not mail cash.</message>
          </item>
          <item>
              <label>Credit</label>
              <value>credit</value>
          </item>
        </select1>
        
        <input ref="my:cc">
          <label>Credit Card Number</label>
          <alert>Please specify a valid credit card number
            (use spaces or hyphens between digit groups)</alert>
        </input>
        
        <input ref="my:exp">
          <label>Expiration Date</label>
        </input>
        
        <submit submission="s00">
          <label>Buy</label>
        </submit>
    </group>
    ...
  </body>
 </html>
</div>

Schema file <code>payschema.xsd</code><nowiki>:</nowiki>

<div class="exampleInner">

 <!-- payschema.xsd -->
 <xs:schema xmlns:my="http://commerce.example.com/payment" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://commerce.example.com/payment" elementFormDefault="qualified">
 
  <xs:element name="payment">
    <xs:complexType>
      <xs:sequence minOccurs="0" maxOccurs="unbounded">
        <xs:choice>    
          <xs:element ref="my:cc" />
          <xs:element ref="my:exp" />
        </xs:choice>
      </xs:sequence>
      <xs:attribute name="as" type="my:paymentAs" />
    </xs:complexType>
  </xs:element>
  <xs:element name="cc" type="my:cc" />
  <xs:element name="exp" type="xsd:gYearMonth" />
 
  <xs:simpleType name="cc">
     <xs:restriction base="xsd:string"> 
       <xs:minLength value="12" /> 
       <xs:maxLength value="19" /> 
       <xs:pattern value="[0-9]+" /> 
     </xs:restriction> 
  </xs:simpleType>
 
  <xs:simpleType name="paymentAs">
    <xs:restriction base="xsd:string">
      <xs:enumeration value="cash" />
      <xs:enumeration value="credit" />
    </xs:restriction>
  </xs:simpleType>
 </xs:schema>
</div>

===Editing Hierarchical Bookmarks Using XForms===

<div class="exampleInner">

 <html xmlns="http://www.w3.org/2002/06/xhtml2" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:my="http://commerce.example.com/payment" xmlns:ev="http://www.w3.org/2001/xml-events" xml:lang="en">
  <head>
    <style type="text/css">
      xforms|input.editField {
       font-weight:bold; font-size:20px; width:500px
      }
      xforms|label.sectionLabel {
        font-weight:bold; color:white; background-color:blue
      }
      xforms|submit {
        font-family: Arial; font-size: 20px; font-style: bold; color: red
      }
    </style>
    <title>Editing Hierarchical Bookmarks In X-Smiles </title>
    <xforms:model id="bookmarks" version="1.1">
      <xforms:instance resource="bookmarks.xml" />
      <xforms:submission id="s01" method="post" action="http://examples.com/" />
    </xforms:model>
  </head>
  <body>
    <xforms:repeat nodeset="section" id="repeatSections">
      <xforms:input ref="@name" class="editField">
        <xforms:label class="sectionLabel">Section</xforms:label>
      </xforms:input>
 <!-- BOOKMARK REPEAT START -->
      <xforms:repeat nodeset="bookmark" id="repeatBookmarks">
        <xforms:input ref="@name">
          <xforms:label>Bookmark name</xforms:label>
        </xforms:input>
        <xforms:input ref="@href">
          <xforms:label>URL</xforms:label>
        </xforms:input>
      </xforms:repeat>
    </xforms:repeat>
    &lt;p>
 <!-- INSERT BOOKMARK BUTTON -->
      <xforms:trigger id="insertbutton">
        <xforms:label>Insert bookmark</xforms:label>
        <xforms:insert nodeset="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" position="after" ev:event="DOMActivate" />
      </xforms:trigger>
 <!-- DELETE BOOKMARK BUTTON -->
      <xforms:trigger id="delete">
        <xforms:label>Delete bookmark</xforms:label>
        <xforms:delete nodeset="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" ev:event="DOMActivate" />
      </xforms:trigger>
    &lt;/p>
    &lt;p>
 <!-- INSERT SECTION BUTTON -->
      <xforms:trigger id="insertsectionbutton">
        <xforms:label>Insert section</xforms:label>
        <xforms:insert nodeset="section" at="index('repeatSections')" position="after" ev:event="DOMActivate" />
      </xforms:trigger>
 <!-- DELETE SECTION BUTTON -->
      <xforms:trigger id="deletesectionbutton">
        <xforms:label>Delete section</xforms:label>
        <xforms:delete nodeset="section" at="index('repeatSections')" ev:event="DOMActivate" />
      </xforms:trigger>
    &lt;/p>
 <!-- SUBMIT BUTTON -->
    <xforms:submit submission="s01">
      <xforms:label>Save</xforms:label>
      <xforms:hint>Click to submit</xforms:hint>
    </xforms:submit>
  </body>
 </html>
</div>

Initial instance file <code>bookmarks.xml</code><nowiki>:</nowiki>

<div class="exampleInner">
 <!--This is the bookmarks.xml file -->
 <bookmarks>
  <section name="main">
    <bookmark href="http://www.example.com/xforms.xml" name="Main page" />
  </section>
  <section name="demos">
    <bookmark href="http://www.example.com/demo/images.fo" name="images" />
    <bookmark href="http://www.example.com/demo/xf-ecma.xml" name="ecma" />
    <bookmark href="http://www.example.com/demo/sip.fo" name="sip" />
  </section>
  <section name="XForms">
    <bookmark href="file:///C/source/xmlevents.xml" name="XML events" />
    <bookmark href="file:///C/source/model3.xml" name="model3" />
    <bookmark href="file:///C/source/repeat.fo" name="repeat" />
  </section>
 </bookmarks>
</div>

===Survey Using XForms and SVG===

The following example shows one possible way of integrating XForms with <nowiki>[</nowiki>[[#ref-svg-1.1 |SVG 1.1]]<nowiki>]</nowiki>. Note that the complete set of rules for integrating XForms and SVG are not fully specified at the time this specification was published. Future versions of the XForms, SVG, or other W3C specifications might define more complete rules for integrating XForms and SVG which might not be compatible with the example below.

Note that the example below does not use SVG's <code>switch</code> and <code>requiredExtensions</code> features, which are commonly used in conjunction with <code>foreignObject</code>.

<div class="exampleInner">
 <!-- <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
     "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -->
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
      xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:ev="http://www.w3.org/2001/xml-events" 
      xmlns:s="http://example.com/survey" width="700px" height="600px" viewBox="0 0 700 600">
  <defs>
    <polygon id="bullet" points="-30,-30, -10,-10, -20,10" fill="#007138" />
    <xforms:model id="form1" schema="surveyschema.xsd">
      <xforms:instance id="instance1">
        &lt;s:survey xmlns="http://example.com/survey">
          &lt;s:drink>none</s:drink>
          &lt;s:espressoPrefs>
            &lt;s:numberPerWeek>0</s:numberPerWeek>
            &lt;s:sugar>0</s:sugar>
            &lt;s:lemon>Always</s:lemon>
          </s:espressoPrefs>
        </s:survey>
      </xforms:instance>
      <xforms:submission id="submit1" method="post" action="http://www.example.org/surveyhandler" />
    </xforms:model>
  </defs>
  <title>Espresso survey</title>
  <desc>Sample SVG and XForms - espresso customer survey</desc>
  <g>
    <text x="50" y="70" font-size="40" font-family="Arial Black, sans-serif" font-weight="900">Customer Survey: Espresso</text>
    <g font-family="Arial, Helvetica, sans-serif" font-size="18">
      <foreignObject x="80" y="150" width="250" height="40">
        <xforms:select1 appearance="minimal" model="form1" ref="s:drink">
          <xforms:label>
            <g transform="translate(80, 140)">
              <use xlink:href="#bullet" />
              <text>Your usual coffee drink is:</text>
            </g>
          </xforms:label>
          <xforms:item>
            <xforms:label>Rich, dark espresso</xforms:label>
            <xforms:value>espresso</xforms:value>
          </xforms:item>
          <xforms:item>
            <xforms:label>Creamy cappuccino</xforms:label>
            <xforms:value>cappuccino</xforms:value>
          </xforms:item>
          <xforms:item>
            <xforms:label>Long, milky latte</xforms:label>
            <xforms:value>latte</xforms:value>
          </xforms:item>
          <xforms:item>
            <xforms:label>Don't like coffee!</xforms:label>
            <xforms:value>none</xforms:value>
          </xforms:item>
        </xforms:select1>
      </foreignObject>
      <foreignObject x="80" y="240" width="250" height="40">
        <xforms:range model="form1" start="0" end="30" step="5" ref="s:espressoPrefs/s:numberPerWeek">
          <xforms:label>
            <g transform="translate(80, 230)">
              <use xlink:href="#bullet" />
              <text>Shots of espresso per week:</text>
            </g>
          </xforms:label>
        </xforms:range>
      </foreignObject>
      <foreignObject x="80" y="350" width="250" height="40">
        <xforms:select model="form1" ref="s:espressoPrefs/s:sugar">
          <xforms:label>
            <g transform="translate(80, 340)">
              <use xlink:href="#bullet" />
              <text>Sugar?</text>
            </g>
          </xforms:label>
          <xforms:item>
            <xforms:label>Yes</xforms:label>
            <xforms:value>X</xforms:value>
          </xforms:item>
        </xforms:select>
      </foreignObject>
      <foreignObject x="80" y="420" width="250" height="90">
        <xforms:select1 appearance="full" model="form1" ref="s:espressoPrefs/s:lemon">
          <xforms:label>
            <g transform="translate(80, 410)">
              <use xlink:href="#bullet" />
              <text>Lemon?</text>
            </g>
          </xforms:label>
          <xforms:item>
            <xforms:label>Required for the full experience</xforms:label>
            <xforms:value>Always</xforms:value>
          </xforms:item>
          <xforms:item>
            <xforms:label>Whatever</xforms:label>
            <xforms:value>Indifferent</xforms:value>
          </xforms:item>
          <xforms:item>
            <xforms:label>Keep that citrus to yourself</xforms:label>
            <xforms:value>Never</xforms:value>
          </xforms:item>
        </xforms:select1>
      </foreignObject>
    </g>
    <use xlink:href="#bullet" x="101" y="64" transform="scale(7,3)" />
    <foreignObject y="150" x="500" height="60" width="100">
      <xforms:submit model="form1">
        <xforms:label>Send survey</xforms:label>
      </xforms:submit>
    </foreignObject>
    <!--- keep the graphics data out of this example listing -->
    <image xlink:href="espresso.svg" x="400" y="230" width="280" height="270" />
  </g>
 </svg>
</div>

<div class="div1">

{{:Acknowledgements}}

==Production Notes (Non-Normative)==

This document was encoded in the XMLspec DTD v2.6. The XML sources were transformed using diffspec and xmlspec stylesheets, version 2.6. The XML Schema portion of the Appendix was rendered into HTML with the [http://www.informatik.hu-berlin.de/~obecker/XSLT/ xmlverbatim XSLT] stylesheet (used with permission). The primary tool used for editing was XMLSpy. The XML was transformed using the XSLT processor in Java 6. The editor(s) use the W3C CVS repository and the W3C IRC server for collaborative authoring.

</div></div>
</div>