View source for XForms 2.0

 __NUMBEREDHEADINGS__
{{TR|title=XForms 2.0}}
<div id='editors'>
; Editors:
: Erik Bruchez, Orbeon
: Alain Couthures, agence XML
: Steven Pemberton, CWI

</div>
<div id='pasteditors'>
; Past Editors:
: Nick Van den Bleeken, Inventive Designers
: John M. Boyer, IBM
: Leigh L. Klotz, Jr., Xerox
</div>
<div style="font-weight:bold;">Abstract</div>
<div id='abstract'>XForms is an XML markup for a new generation of applications on the Web. XForms is not primarily a free-standing document type, but is intended for integrating into other markup languages, such as <nowiki>[</nowiki>[[#ref-xhtml-1.0|XHTML]]<nowiki>]</nowiki>, <nowiki>[</nowiki>[[#ref-odf-1.1|ODF]]<nowiki>]</nowiki> or <nowiki>[</nowiki>[[#ref-svg-1.1|SVG]]<nowiki>]</nowiki>. An XForms-based application gathers and processes data using an architecture that separates presentation, purpose and content; processing of data occurs 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 component reuse, fosters strong data type validation, eliminates unnecessary round-trips to the server, offers device independence and accessibility, and reduces the need for scripting.

XForms 2.0 moves to using XPath 2.0 and higher, which adds new facilities and functions; adds Attribute Value Templates, allowing dynamic data values to be used in attributes; allows labels, hints, help, and alert texts to be expressed as attributes as well as elements; adds custom functions and variables, model-based switch and repeat,  and defines consuming and submitting JSON and CSV instance data.
 </div>
<div style="font-weight:bold;">Status of this Document</div>
<div>{{status|xforms}}</div>
<p>Please send any comments for this version to [mailto:public-xformsusers@w3.org public-xformsusers@w3.org].</p>

[http://www.w3.org/Consortium/Legal/ipr-notice#Copyright Copyright] &copy; 2010-2024 [http://www.w3.org/ W3C]<sup>&reg;</sup> ([http://www.csail.mit.edu/ MIT], [http://www.ercim.eu/ 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 XForms</span>==

Web applications and ecommerce have sparked the demand for rich interactions and XForms is a response to this, providing a declarative platform-independent language for online interaction.

The original version of XForms was purely about forms, and followed HTML fairly closely in what it could do. However, thanks to XForms' generality, it was quickly realised that it was capable of far more than only forms if certain parts were further generalised. And so was born XForms 1.1, that allowed not only forms to be created, but certain types of applications as well, that you would not normally consider as being a form. XForms 2.0 continues this process of generalization.

For a list of the differences between XForms 2.0 and 1.1, see the [[#version-diffs|appendix]].

<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 implementors; however, it is not intended as a tutorial. The specification is organized as follows:

; Sections 1 and 2
: An introduction outlining the design principles and giving a brief tutorial.
; Sections 3 and up
: XForms definition.
; Appendixes
: An XML Schema description of XForms, references, examples, and other useful information.

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

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

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

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

<blockquote>

'''xforms:''' The XForms namespace, <code>http://www.w3.org/2002/xforms</code> (see [[#structure-namespace|Namespace for XForms]])<br />
'''html:''' The XHTML namespace, <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 />
'''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="example" title="item">
 Example Item
</div>

References to external documents appear as follows: <nowiki>[</nowiki>[[#ref-xml-events |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>

{{EditorialNote|title=Editorial Note Name|date=2011-08-31|desc=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>

==Introduction to XForms==

XForms was originally designed for handling forms on the web. Forms helped to kick off the web as an interactive medium and for e-commerce, with tasks such as searching, shopping, reading and writing email, editing documents online, configuring hardware, and banking.

XForms has been designed to improve such interactivity. Issues addressed included authoring, reuse, internationalization, accessibility, usability, data structuring, client-side checking, device independence, support of common use cases and reduced reliance on scripting.

Properties of XForms include:

* '''Data is separated from the markup of the controls.''' This not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse, since the essential part is no longer irretrievably bound to the page it is used in.
* '''Controls say what they do, not how they look.''' This gives the designer more control, makes it easier to deploy to multiple devices, and aids accessibility.
* '''Data can be checked client-side'''. This speeds up interaction since it reduces the need for round trips to the server for validation, and reduces server-side processing.
* '''Structured, typed data is supported'''. This allows integration in existing data pipelines without the data having to be transformed first. Although XML is the principal format for this, formats like JSON and CSV are also supported.
* '''Declarative specification is used'''. The details of the data, including calculation, are defined using declarative markup, rather than scripting, making forms smaller, more tractable (through static analysis), and easier to produce. Experience has shown that this significantly reduces production times and costs.
* '''Calculations are done spreadsheet-style'''. This means that calculations are always up to date, and the user doesn't have to press a 'recalculate' button having changed a value.
* '''Data and markup are fully integrated'''. For instance, as the user enters an address it can be displayed in its final form on the page itself; data imported from an external source can be easily displayed; and as the data changes it is updated on the page. It also means that it is easy to produce an internationalized version of a form, by importing labels in different languages.

<div class="div2">

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

An application in XForms has a section that describes the data being manipulated, called  the [[#structure-abstract|Model]], which includes the data, types, constraints, and relationships with other data values, and another section that describes how the data is manipulated.
Consider a simple case like this:

[[Image:intro.png|screen shot of an example form]]

It is clear that we are asking for the method of payment being used, and if a credit card, its number and expiration date.

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

 <model>
    <instance>
       <payment xmlns="">
          <amount/>
          <method/>
          <number/
          <expiry/>
       </payment>
    </instance>
    <submission resource=<nowiki>"https://example.com/submit"</nowiki> method="post"/>
 </model>

This simply says that we are collecting four 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>resource</code> attribute.  XForms defines a device-neutral set of [[#def-form-control|controls]] suitable for general-purpose use. The controls are ''bound'' to the data in the model using the <code>ref</code> attribute on the controls. This markup would appear within the  <code>&lt;body&gt;</code> of an XHTML document:

 Please pay: <output ref="amount"/>
 <select1 ref="method" label="Payment Method">
    <item label="Cash">cash</item>
    <item label="Credit">cc</item>
 </select1>
 <input ref="number" label="Card Number"/>
 <input ref="expiry" label="Expiration Date"/>
 <submit label="Submit"/>

There are some things worth noting here:

* The user interface is not hard-coded to use radio buttons, or any other style of input. Different devices (such as voice browsers) can render the concept of "select one" as appropriate, small-screen devices can use drop-down menus, while larger-screen devices can use radio buttons.
* Controls always have labels directly associated with them &mdash; a feature designed to enhance accessibility.

The fact that you can bind controls to the model like this simplifies integration with other ''host languages'', since any control markup may be used to bind to the model.

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

===<span id="concepts-submitted-data">Submitted Data</span>===

The data collected can directly be submitted as XML data. In the example, the submitted data might look like this:

 <payment>
    <amount>99.00</amount>
    <method>cc</method>
    <number>1235467789012345</number>
    <expiry>2025-12</expiry>
 </payment>

but it is also possible to submit data in URL-encoded style, such as

 <nowiki>https://example.com/submit?amount=99.00&amp;method=cc&amp;number=1235467789012345&amp;expiry=2025-12</nowiki>

This is done by changing the <code>method</code> attribute on [[#submit-submission-element|the <code>submission</code> element]] to

 <submission resource=<nowiki>"https://example.com/submit"</nowiki> '''method="get"'''/>

<div class="div2">

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

Processing keeps track of the state of the values entered through the instance data; this data can be initially empty as in the example above, or may be (partially) initialized with values, for instance:

 &lt;instance&gt;
   &lt;payment xmlns=""&gt;
     &lt;amount&gt;99.99&lt;/amount&gt;
     &lt;method&gt;cc&lt;/method&gt;
     &lt;number/&gt;
     &lt;expiry/&gt;
   &lt;/payment&gt;
 &lt;/instance&gt;

Data may be also initialised from external sources. For instance, for a control to fill in a country, the data for the countries of the world can be obtained from an external resource:

 &lt;instance id="c" src="countries.xml"/&gt;

If the countries data looks like this:

 &lt;countries xml:lang="en"&gt;
   &lt;country code="AF"&gt;Afghanistan&lt;/country&gt;
   &lt;country code="AX"&gt;Åland Islands&lt;/country&gt;
   &lt;country code="AL"&gt;Albania&lt;/country&gt;
   &lt;country code="DZ"&gt;Algeria&lt;/country&gt;
   &lt;country code="AS"&gt;American Samoa&lt;/country&gt;
   ...

then a suitable <code>select1</code> control could use this as follows:

 &lt;select1 ref="land" label="Country"&gt;
   &lt;itemset ref="instance('c')/country" label="{.}" value="@code"/&gt;
 &lt;/select1&gt;

This means that the country data is no longer hard-wired, but can be sourced from a single file for the whole site, and is easily updated when necessary.

Binding expressions in XForms use <nowiki>[</nowiki>[[#ref-xpath-2.0|XPath]]<nowiki>]</nowiki>, including the use of the <code>@</code> character to refer to attributes, as seen here.

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

===<span id="concepts-calculate">Calculating Values</span>===

Values can be calculated dynamically from other values as they change.

For instance, if we add to the example above two values for the unit price of an item, and how many are being ordered:

 &lt;payment xmlns=""&gt;
   &lt;unitprice&gt;99.99&lt;/unitprice&gt;
   &lt;howmany/&gt;
   &lt;amount/&gt;
   &lt;method/&gt;
   &lt;number/&gt;
   &lt;expiry/&gt;
 &lt;/payment&gt;

then we can add a calculation to calculate the total amount from these two:

 &lt;bind ref="amount" calculate="../unitprice * ../howmany" /&gt;

Whenever either of those two values is changed, the total amount is automatically updated.

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

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

Data can be checked for validity as the values are entered.

In the absence of specific information, all values are considered strings, but values can be assigned other types. For instance in the
example, datatypes representing an integer, and a decimal type for
representing monetary values can be used:

 &lt;bind ref="howmany" type="integer"/&gt;
 &lt;bind ref="amount" type="decimal"/&gt;

but there is also a data type that represents a credit card, accepting
between 14 and 18 digits:

 &lt;bind ref="number" type="card-number"/&gt;

It is possible to add dynamic constraints to a value. For instance, if you
want to restrict how many items are bought:

 &lt;bind ref="howmany" constraint=". lt 10" /&gt;

which would prevent more than 9 items being ordered. There is also a
function for checking that a credit card number is valid:

 &lt;bind ref="number" constraint="is-card-number(.)"/&gt;

Values can also be checked that they match a particular pattern:

 &lt;bind ref="expiry" constraint="matches(., '^[0-9][0-9]/(0[1-9]|1[012])$'"/>

The data cannot be submitted until all constraints are met, and input
controls bound to data not matching their constraints are typically marked
specially (how they are marked is controllable by stylesheets). You can also
include a message to be displayed should the constraints not be met:

 &lt;input ref="howmany" label="Number" alert="Must be a whole number less than 10"/&gt;

 &lt;input ref="expiry" label="Expiry date" alert="Format YY/MM"/&gt;
</div><div class="div2">

===<span id="concepts-relevance"> Relevance and Required Values</span>===

In the example, the values for <code>number</code> and
<code>expiry</code> are only relevant if the credit card option is chosen for
<code>method</code>, but are required in that case. This is expressed as
follows:

 &lt;bind ref="number"
       type="card-number"
       relevant="../method='cc'"
       required="true()"/&gt;
 &lt;bind ref="expiry"
       relevant="../method='cc'"
       required="true()"/&gt;

Processors have the option of graying out controls bound to
non-relevant values, or of making them non-visible, and this is controllable using style sheets.

Putting it all together, the model would look like this:

 &lt;model&gt;<nowiki>
   &lt;instance&gt;
     &lt;payment xmlns=""&gt;
       &lt;unitprice&gt;99.99&lt;/unitprice&gt;
       &lt;howmany/&gt;
       &lt;amount/&gt;
       &lt;method/&gt;
       &lt;number/&gt;
       &lt;expiry/&gt;
     &lt;/payment&gt;
   &lt;/instance&gt;
   &lt;bind ref="howmany" type="integer" constraint=". lt 10"/&gt;
   &lt;bind ref="amount" type="decimal" calculate="../unitprice * ../howmany" /&gt;
   &lt;bind ref="number"
         type="card-number"
         relevant="../method='cc'"
         required="true()"
         constraint="is-card-number(.)"/&gt;
   &lt;bind ref="expiry" relevant="../method='cc'" required="true()"
         constraint="matches(., '^[0-9][0-9]/(0[1-9]|1[012])$'"/&gt;
   &lt;submission resource="https://example.com/submit" method="post"/&gt;
 &lt;/model&gt;</nowiki>

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

===<span id="concepts-avt">Attribute Values</span>===

Values can be displayed using the <code>output</code> element, but they can also be injected into ''attributes'', using ''attribute value templates'' (AVTs). These are marked with braces "{" and "}". Any part of an attribute may be replaced.

For instance, with

 &lt;output ref="total" class="{if (. ge 0) then 'positive' else 'negative'}" /&gt;

a style sheet can then have two rules, one for class
<code>positive</code>, and one for <code>negative</code>, for instance coloring
the output red if it is negative:

 .positive {color: black}
 .negative {color: red}

or putting brackets around negative values:

 .negative::before {content: "("}
 .negative::after {content: ")"}

All attributes support AVTs with the exception of attributes that are already expressions, and a small number  of structural attributes. These are marked in the descriptions of the attributes.
</div><div class="div2">

===<span id="concepts-multiple">Multiple Models per Document</span>===
A single document may contain multiple data models. 
In that case controls need to identify which <code>model</code> element
contains the data they use by using
an <code>id</code> attribute on the <code>model</code> element, 
and a <code>model</code> attribute on the control alongside the <code>ref</code> attribute.
If no <code>model</code> attribute is used, the first model in the document is referred to.

For instance, adding an opinion poll to the example:

 &lt;model&gt;<nowiki>
   &lt;instance&gt;
     ...payment instance data...
   &lt;/instance&gt;
   &lt;submission resource="https://example.com/submit" method="post"/&gt;
 &lt;/model&gt;
 
 &lt;model id="poll"&gt;
   &lt;instance&gt;
     &lt;data xmlns=""&gt;
       &lt;helpful/&gt;
     &lt;/data&gt;
   &lt;/instance&gt;
   &lt;submission resource="..."/&gt;
 &lt;/model&gt;</nowiki>

Then the controls can identify which model they use:

 &lt;select1 ref="helpful" model="poll" label="How useful is this page to you?"&gt;
   &lt;item value="0" label="Not at all helpful"/&gt;
   &lt;item value="1" label="Barely helpful"/&gt;
   &lt;item value="2" label="Somewhat helpful"/&gt;
   &lt;item value="3" label="Very helpful"/&gt;
 &lt;/select1&gt;
 
 &lt;submit model="poll" label="Submit"/&gt;

More 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 documents consist of two parts: one or more ''models'' that contain data, data properties, and relationships, and a ''user interface'' that contains controls bound to the data in the models. How these two parts are contained in a document depends on the ''host language''.

===Host languages===

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 versions of XHTML <nowiki>[</nowiki>[[#ref-xhtml-1.0 |XHTML 1.0]]<nowiki>]</nowiki>. As such, it is the integration of XForms with the [[#def-host-language|host language]] that defines exactly where in a document the XForms constructs may go; however, XForms may also be used standalone with the [[#structure-form-element|form element]].

The definition of XForms is done as a small number of ''modules''. Each module represents a separable part of the functionality of XForms that could if needed be used independently in some host integration.

The <span id="structure-namespace">namespace URI for XForms</span>, used for distinguishing which elements are from XForms and which from the host language, is <code>http://www.w3.org/2002/xforms</code>. 

<div class="example" title="XForms used in combination with XHTML 1.0">
 <html <nowiki>xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="http://www.w3.org/1999/xhtml"</nowiki>>
 <head>
     <title>Input</title>
     '''<model <nowiki>xmlns="http://www.w3.org/2002/xforms"</nowiki>>
         '''<instance>
             '''&lt;data xmlns="">
                 '''<name/>
             '''&lt;/data>
         '''</instance>
     '''</model>
 </head>
 <body>
     '''<group xmlns=<nowiki>"http://www.w3.org/2002/xforms"</nowiki>>
         '''<input ref="name" label="Your name"/>'''<h:br/>
         '''Hello <output ref="name"/>!
     '''</group>
 </body>
 </html>
</div>
</div>

===<span id="structure-form-element">The form Element</span>===
 
Although XForms can be embedded in host languages such as XHTML, ODF, or SVG, the <code>form</code> element is available to enclose the elements of an XForm, either as a root element or embedded in another language.
<div class="desc">

Common Attributes: [[#structure-attrs-common|Common]], [[#attrs-ui-common|UI Common]]

Content:Content: ([[#structure-model|model]]|[[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*

</div>
 
<div class="example" title="form element"> 
 <form xmlns="http://www.w3.org/2002/xforms">
   <label>Date</label>
   <model>
      <instance>
         <date xmlns=""><today/></date>
      </instance>
   </model>
   <bind ref="today" calculate="local-date()"/>
   <output ref="today"/>
 </form>
</div>

===<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 and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#structure-extension|extension]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]
| rowspan="1" colspan="1" | ANY
|}

<div class="div3">

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

The optional <code>extension</code> element 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.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]

Content: ANY
</div>
<div class="example" title="Attaching RDF metadata to a control">
 <input ref="dataset/user/email" id="email-input" label="Your email address">
   <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 class="div1">

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

Core attributes are groups of attributes that are applicable widely over the language, and not restricted to a single element.

<div class="div3">

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

The Common Attribute Collection applies to every element.

; ''anyAttribute''
: Foreign attributes are allowed on all elements; their meaning is defined by the namespace that they come from. For instance, a web-based XForms implementation might allow <code>html:autocomplete</code> attributes on input controls. Processors must ignore unrecognized foreign-namespaced attributes. <div class="note"> '''Note:''' The [[#action-xmlevents|XML Events attributes]] are foreign attributes and therefore allowed on any element that includes the [[#structure-attrs-common|Common]] attributes. This specification lists both [[#structure-attrs-common|Common]] and [[#action-xmlevents| Events]] attributes on Actions for reading convenience, since authors are most likely to place [[#action-xmlevents |Events]] attributes on the actual event handler elements.</div>

;class
: An optional list of names that can be matched by CSS class selectors.

;dir
: Allows the author to specify the direction of the element's text content. This direction affects the display of characters as defined in Unicode Standard Annex #9: The Bidirectional Algorithm [UAX9], and defines directional properties of text as defined by CSS [CSS]. The default value of this attribute is <code>auto</code>. Possible values are:
* auto: The directionality is determined by the directionality of the first character in the text that has directionality.
* ltr: Left-to-right text. The effect of this attribute is defined by the CSS2 rule:
 *[dir="ltr"] { unicode-bidi: embed; direction: ltr}
* rtl: Right-to-left text. The effect of this attribute is defined by the CSS2 rule:
 *[dir="rtl"] { unicode-bidi: embed; direction: rtl}
* lro: Left-to-right override. The effect of this attribute is defined by the CSS2 rule:
 *[dir="lro"] { unicode-bidi: bidi-override; direction: ltr}
* rlo: Right-to-left override. The effect of this attribute is defined by the CSS2 rule:
 *[dir="rlo"] { unicode-bidi: bidi-override; direction: rtl}

Example

 The Hebrew word for "Hebrew" is &lt;span xml:lang="he">&#x5e2;&#x5d1;&#x5e8;&#x5d9;&#x5ea;&lt;/span>,
 but since Hebrew letters have intrinsic right-to-left directionality,
 I had to type the word starting from the letter "&#x5e2;",
 i.e. &lt;span xml:lang="he" dir="lro">&#x5e2;&#x5d1;&#x5e8;&#x5d9;&#x5ea;&lt;/span>.

; id [not AVT]
: An optional attribute of type <code>xs:ID</code>. Assigns an identity to the containing element; see the section on [[#idref-resolve|resolving IDs in XForms]]. <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.</div> 

;<nowiki>xml:lang</nowiki>
: An optional specification of the natural language of the element content as defined in <nowiki>[</nowiki>[[#ref-xml-lang |Language Identification in XML]]<nowiki>]</nowiki>.

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

===<span id="structure-attrs-evaluation">Evaluation Attributes</span>===

The Evaluation Attribute Collection specifies the evaluation context for bindings. See [[#Evaluation Context|Evaluation Context]] for details.

; <span id="structure-attrs-model">model</span> [not AVT]
: An optional Model selector. Specifies the <code>ID</code> of a Model to be associated with this element. This attribute is ignored if a <code>bind</code> attribute is also present. If a <code>model</code> attribute refers to something other than a <code>model</code> element, an [[#evt-bindingError|xforms-binding-error]] is dispatched to the element with the attribute. Rules for determining the context Model are described in the section on [[#Evaluation Context|Evaluation Context]]. 

; <span id="structure-attrs-context">context</span>
: An optional expression used to override the default [[#in-scope-evaluation-context|in-scope evaluation context]] for a binding or expression. This attribute has no meaning when a <code>bind</code> attribute is present. If the <code>model</code> attribute is present, then it is processed first. Processing is described in [[#Evaluation Context|Evaluation Context]].
</div>
<div class="div3">

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

These attributes bind an element such as a control to data, using a [[#def-binding-expression|binding expression]]; such data values are referred to as '''bound values'''. Typically controls will bind to instance data nodes, but they can bind to any sort of item (such as atomic values like integer, date, or string atomic values). Atomic values always have the <code>readonly</code> property.
; bind [not AVT]
: Reference to the ID of a <code>bind</code> element. If there is no matching <code>bind</code> element, an [[#The xforms-binding-error Event|xforms-binding-error]] is dispatched to the element that the <code>bind</code> attribute is on.
; ref
: [[#def-binding-expression|Binding expression]]: ignored if a <code>bind</code> attribute is present.
; <span class="deprecated">nodeset (deprecated)</span>
: <span class="deprecated">Synonym for the <code>ref</code> attribute: ignored if a <code>ref</code> attribute is present. In this specification, at any time the <code>ref</code> attribute is mentioned, it should be read to include <code>nodeset</code> where applicable.</span>

In this specification, when an element is declared to have a (item or sequence) binding, then it is required unless the description for the element explicitly states that it is optional.

When a binding is required, one of <code>ref</code> or <code>bind</code> is required:
* When <code>bind</code> is used, the items are determined by the referenced <code>bind</code> element. 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 item is determined by evaluating the expression as specified in the [[#def-expression-module|expression module]] in the [[#in-scope-evaluation-context|in-scope evaluation context]].

When a binding is defined as a <span id="structure-attrs-single-node">'''Single Item Binding'''</span> then the
'''First-item rule'''<nowiki> is applied: if a binding selects a sequence of size greater than 1, the first item in the sequence is used.</nowiki>

When a binding is defined as being to simpleContent then this excludes binding to element nodes that have element children. See [[#ui-processing|Implementation Requirements Common to All Controls]] for user interface processing rules common to all controls.

The binding attributes may be used in other XML vocabularies to bind custom user interface controls to
instance data. As an example, the <code>bind</code> attribute might be used with XHTML 1.x user interface controls:

<div class="example" title="XForms Binding In XHTML 1.x User Interface Controls">
 <html:input type="text" name="..." xforms:bind="fn"/>
</div>

</div><div class="div3">
===<span id="structure-attrs-properties">Property Attributes</span>===
These attributes add metadata about the values referenced by a binding.

Properties are bound to instance data nodes with a [[#structure-attrs-nodeset|binding]]. The combination of an [[#def-instance-data-node|instance data node]] and its properties is called a '''<span id="def-model-item">model item</span>'''.

Some model item properties define '''inheritance rules''', in which case the Processor combines the '''local value''', which is applied from the binding, with the '''inherited value''', which is the combination of values from ancestor nodes in the instance data.

Some properties are '''computed''': the [[#rpm|processing model]] describes when and how the calculation is performed.

If [[#Model Item Properties|Model Item Properties]] are attached to atomic values, or nodes that don't belong to an instance, an [[#evt-bindingError|xforms-binding-error]] is dispatched to the element with the binding. {{EditorialNote|title=Properties of atomic values | date=2024-05-02|desc=Is this still so?.}}

Most, but not all, properties may be assigned multiple times to a node using different bindings (for instance two bindings to the same node, each specifying a constraint). An [[#The_xforms-binding-error_Event|xforms-binding-error]] is dispatched to any element that has a binding that applies disallowed properties twice to the same node. 

{| border="1"
|-
! property
! computed
! value
! default
! inherits
! combination
|-
| [[#model-prop-type|type]]
| no
| xs:QName
| xf:string
| no
| all have to be true
|-
| [[#model-prop-constraint|constraint]]
| yes
| boolean expression
| true
| no
| all have to be true
|-
| [[#model-prop-relevant|relevant]]
| yes
| boolean expression
| true
| yes
| all have to be true
|-
| [[#model-prop-required|required]]
| yes
| boolean expression
| false
| no
| one has to be true
|-
| [[#model-prop-readonly|readonly]]
| yes
| boolean expression
| false (unless the value is calculated, then true)
| yes
| one has to be true
|-
| [[#model-prop-whitespace|whitespace]]
| no
| preserve, remove, trim, collapse, normalize.
| preserve
| no
| not allowed
|-
| [[#model-prop-type|label]]
| no
| string
| none
| no
| not allowed
|-
| [[#model-prop-help|help]]
| no
| string
| none
| no
| not allowed
|-
| [[#model-prop-hint|hint]]
| no
| string
| none
| no
| not allowed
|-
| [[#model-prop-alert|alert]]
| no
| string
| none
| no
| one allowed per type and constraint
|}

;<span id="model-prop-type">type</span>
:associates a datatype with a node, contributing to the [[#validity|validity]] of the node.

The value must reference a datatype (as defined in <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>) defined in an applicable XML Schema, or an XForms predefined type. The datatype can be obtained from a simpleType definition or a simpleContent definition from a complexType. The namespace context of the <code>bind</code> element is used to resolve the namespace.

The datatype is associated with the node, as defined in [[#ref-xpath-data-model|XPath Data Model]]. It can be applied to both elements and attributes, but not to instance nodes that contain child elements.

<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, it is not applicable to a <code>type</code> model item property.
</div>
;constraint
:specifies extra [[#validity|validity]] conditions for instance data.
If the expression fails to evaluate or evaluates to <code>false</code>, the associated data node is not valid (the converse is not necessarily true). 

This property contributes to the validity of a node; the effect of validity on controls is described in the section on [[#ui-processing|Implementation Requirements Common to All Controls]]. This property does not prevent controls and Actions from setting invalid values into data nodes.
;<span id="model-prop-relevant">relevant</span>
:whether an instance node is available to the user interface and to submission.

If the expression fails to evaluate, the property is set to <code>false</code>.

If any ancestor node of the bound node is non-relevant, the bound node is also non-relevant; otherwise, this property determines relevance.

This property indicates whether <span id="def-enabled">the instance data node is available for use by controls in the user interface and for submission</span>. For instance, when paying by cash, a credit card number is not relevant. 

Relevance affects visibility, focus, and navigation order of controls bound to a node: see the section on [[#form-control-non-relevance-conditions|Availability]] for details.

<div class="note">
'''Note:''' A control must have a Single Item 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>
;<span id="model-prop-required">required</span>
:whether a value may be empty or not, contributing to the [[#validity|validity]] of the node.

If the expression fails to evaluate, the property is set to <code>true</code>.

This property indicates whether <span id="def-required">the instance data node must be non-empty</span>. A value is non-empty if it would have a length greater than zero if converted to <code>string</code>.

Controls bound to a required node should indicate that they are required. This property does not prevent controls and Actions from setting empty strings into data nodes, and has no defined effect on visibility, focus, or navigation order. Authors should ensure that controls bound to <code>required</code> data are visible. 
;<span id="model-prop-readOnly">readonly</span>
:whether the node content is restricted from being changed.

If the expression fails to evaluate, the property is set to <code>true</code>.

If any ancestor node of the bound node is <code>readonly</code>, the bound node is also <code>readonly</code>; otherwise, this property determines whether it is.

This property indicates whether <span id="def-readonly">changes are allowed to the content of the bound instance data node from constructs other than the model item property system</span> (i.e. other than a <code>calculate</code>). Instance mutations performed by <code>submission</code>, 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.

Controls bound to readonly instance data do not receive input focus, and should indicate that entering or changing the value is not allowed. The <code>readonly</code> model item property does not affect visibility.

;<span id="model-prop-whitespace">whitespace</span>
:how whitespace is treated when a node receives a new value

Whitespace is any character defined as whitespace ("WSpace=Y", "WS") in the Unicode Character Database <nowiki>[</nowiki>[[#ref-unicode-character-database |Unicode Character Database]]<nowiki>]</nowiki>.

The <code>whitespace</code> property is processed during a [[#model-recalculate|recalculate]].

Permitted values are:
* <code>preserve</code>: all whitespace is preserved,
* <code>remove</code>: all whitespace is removed,
* <code>trim</code>: all whitespace from the beginning and end of the string is removed,
* <code>collapse</code>: each occurrence of multiple whitespace is replaced with a single space character (0x20),
* <code>normalize</code>: a combination of 'trim' and 'collapse'.

;<span id="model-prop-label">label</span>
:associates a label text with a node.

Controls without a label element or attribute must make the label property text available to the user as part of the control. If a control has its own label element or attribute, that text is used instead.
;<span id="model-prop-help">help</span>
:associates a help text with a node.

Controls without a help element or attribute must make the help property text available to the user when requested. If a control has its own help element or attribute, that text is used instead.

;<span id="model-prop-hint">hint</span>
:associates a hint text with a node
Controls without a hint element or attribute must make the hint property text available to the user when requested. If a control has its own hint element or attribute, that text is used instead.

;<span id="model-prop-alert">alert</span>
:associates an alert text with type and constraint properties of a binding.

A control bound to a node that fails to match its type and constraint properties must make an alert text available to the user: if the control has an alert element or attribute, that text is used; otherwise, if the type property or constraint that has failed has an alert property associated with it, that text is used; otherwise an implementation-dependent text may be used.
</div><div class="div3">

===The <span id="structure-attrs-value">value</span> and <span id="structure-attrs-mediatype">mediatype</span> Attributes===
The <code>value</code> attribute is used by elements to evaluate an expression; some elements that carry it also carry the <code>mediatype</code> attribute that indicates how to interpret the resulting value.

;value
:An expression. If the result is to be used as a string, then the result of the expression is processed as if by a call to the string conversion function as described in the expression module; an empty string is used if the evaluation fails. If the element has PCDATA content, then the result of the expression overrides that content.

;mediatype
:Optional string specifying the mediatype to use for interpreting the value, according to the format specified for the HTTP Accept: header in <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki>. It is the author's responsibility to ensure that the type specified is compatible with the value. The default is to treat the value as text.</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-linkError| xforms-link-error]] to the <code>model</code> associated with the element that bears the Linking Attributes Collection for the failed link.

</div><div class="div3">
===<span id="avts">Attribute Value Templates</span>===
All attributes except those that are already expressions and those that explicitly disallow AVTs can contain Attribute Value Templates.

An attribute value template consists of an alternating sequence of fixed parts and variable parts. A variable part consists of an expression enclosed in braces ({}). A fixed part may contain any characters, except that a left brace must be written as {<!-- dummy comment -->{ and a right brace must be written as }}. An expression within a variable part may contain an unescaped brace within a StringLiteral or within a comment.

Adding attribute value template support to [[#def-host-language|host language]] attributes is recommended, but should be defined in the [[#def-host-language|host language]] integration specification.

====<span id="avt-evaluation">AVT Evaluation</span>====

An attribute value template is evaluated by concatenating the evaluations of the fixed and variable parts:
* a fixed part: any double brace ({<!-- dummy comment -->{ or }}) is replaced by the corresponding single brace.
* a variable part: the enclosed expression is evaluated as a string, using the [[#element-evaluation-context|element evaluation context]].

An [[#evt-expressionError|xforms-expression-error]] is dispatched to the element containing the expression in the following cases:
* an unescaped left curly bracket appears in a fixed part, without a matching right curly bracket;
* an unescaped right curly bracket occurs in a fixed part;
* the expression contained between matching curly brackets is not syntactically correct;
* a dynamic error occurs during the concatenation of the parts, for example if the sequence contains an element with a complex content type (which cannot be atomized).

Braces are not treated specially in attributes that cannot contain an attribute value template.

Attribute value templates are evaluated when necessary: on a control, they are evaluated on [[#model-refresh|refresh]]; on an action, when it is executed.

{{SpecNote|The following non-normative list of attributes do '''not''' support AVTs: <code>functions</code>, <code>schema</code> and <code>version</code> on <code>model</code>; <code>signature</code> on <code>function</code>; <code>src</code> and <code>resource</code> on <code>instance</code>; <code>type</code> on <code>bind</code>; <code>id</code>.}}

<div class="example" title="Attribute value template in class attribute">
 <output ref="total" class="{if (. ge 0) then 'positive' else 'negative'}"/>
</div>

<div class="example" title="Attribute value template on load action">
 <load resource="/forms/detail/{instance('document-instance')/document/id}"/>

When <code><load></code> is executed, the resource attribute is evaluated. The result is the concatenation of /forms/detail/ and of the result of the expression within braces. If the id element pointed to contains the string C72E5, the resource attribute would take the value:
 /forms/detail/C72E5
</div>

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

==<span id="structure-abstract">The Model</span>==

This module defines storing and describing the data to be used.

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 and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#structure-model|model]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], functions (QNameList)[not AVT], schema (list of xs:anyURI)[not AVT], version ([[#def-versionList|xforms:versionList]])[not AVT]
| rowspan="1" colspan="1" |
([[#The_function_Element|function]] | [[#structure-model-instance|instance]] | xs:schema | [[#submit|submission]] | [[#structure-bind-element|bind]] | [[#action-content-set|Action]])*
|-
| rowspan="1" colspan="1" |
[[#structure-model-instance|instance]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], src (xs:anyURI)[not AVT], resource (xs:anyURI) [not AVT], response-mediatype (xs:string) [not AVT]
| rowspan="1" colspan="1" | ANY
|-
| rowspan="1" colspan="1" |
[[#structure-bind-element|bind]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], ref ([[#def-model-binding-expression|model-binding-expression]]), nodeset ([[#def-model-binding-expression|model-binding-expression]] [deprecated]), [[#model-prop-type|type]] (Type), [[#model-prop-constraint|constraint]] (Boolean expression), [[#model-prop-relevant|relevant]] (Boolean expression), [[#model-prop-required|required]] (Boolean expression), [[#model-prop-readOnly|readonly]] (Boolean expression), [[#model-prop-calculate|calculate]] (Expression), [[#model-prop-whitespace|whitespace]] ("preserve"* | "remove" |  "trim" | "collapse" | "normalize")
| rowspan="1" colspan="1" | bind*
|-
| rowspan="1" colspan="1" |
[[#structure-shared-element|shared]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Item Binding]]? 
| rowspan="1" colspan="1" | [[#action-content-set|Action]]*
|-
| [[#The_function_Element|function]]
| [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], signature[not AVT], override?
| <nowiki>(var*, result)?</nowiki>
|-
| [[#The_result_element|result]]
| [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], value (expression)
| PCDATA
|-
|[[#structure-var-element|var]]
|[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], name (QName), value (expression)
| PCDATA
|}

Elements defined in the Actions module 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.

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 is a container for the data to be used. There is no restriction on the number of <code>model</code> elements in a document.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]]

Special Attributes:

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

The XML Schema definitions for a namespace are determined to be '''applicable''' to instance nodes based on an instance XML Schema validation episode initialized to [[#def-lax-schema-processing|lax processing]]. When an element lacks an XML Schema declaration, the XML Schema specification defines as implementation-optional the recursive checking of children and attributes. For XForms, this recursive checking is required. XML Schema processing for a node with matching XML 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 [not AVT]
: Optional list of versions with a default value of empty string and legal values defined by the datatype [[#def-versionList|xforms:versionList]]. Examples are <code>"1.0"</code>,  <code>"1.1"</code> and <code>"1.1 2.0"</code>. On the default <code>model</code>, if one or more versions are indicated by this attribute then an XForms Processor must support at least one of the listed language versions of XForms; otherwise, the Processor dispatches the event [[#evt-versionError|xforms-version-error]] to the <code>model</code>. If the Processor supports more than one of the language versions indicated or if the version setting is empty, then the Processor must execute the XForms content using the highest 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 Processor, then the Processor dispatches the event [[#evt-versionError|xforms-version-error]] to the default <code>model</code>.
Content: ([[#The_function_Element|function]] | [[#structure-model-instance|instance]] | xs:schema | [[#submit|submission]] | [[#structure-bind-element|bind]] | [[#action-content-set|Action]])*
</div>

<div class="example" title="a simple model">
 <model>
     <instance>
         &lt;data xmlns="">
             <name/>
         &lt;/data>
     </instance>
 </model>
</div>

<div class="example" title="specifying a schema">
 <model id="Person" schema="MySchema.xsd">
   <instance resource=<nowiki>"https://example.com/cgi-bin/get-instance"</nowiki>/>
 </model>
</div>

<div class="example" title="handling an xforms-version-error">
 <model>
   <message level="modal" ev:event="xforms-version-error">
     <output value="event('error-message')"/>
   </message>
   ...
 </model>
 ...
 <model id="m2" version="2.0">
   ...
 </model>

Since the <code>version</code> attribute is not specified on the <code>model</code>, the 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="example" title="Differing but Compatible Version Settings">
 <model version="1.0 2.0">
   ...
 </model>
 ...
 <model id="m2">
   ...
 </model>

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 class="div3">

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

This element contains instance data, which can be updated during processing.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]]

Special Attributes:

; src [not AVT]
: Optional link to externally defined initial instance data.
; resource [not AVT]
: Optional link to externally defined initial instance data.
; response-mediatype [not AVT]
: Optional mediatype, used to override the mediatype reported by the external resource.

Content: ANY
</div>
The data for the instance is obtained from the link in the <code>src</code> attribute, if present and successful, otherwise from the inline content of the <code>instance</code> element if present, and otherwise from the link in the <code>resource</code> attribute.

The resulting document is converted to an [[#ref-xpath-data-model|XPath Data Model]] and associated with the instance element.

Processors must at all times keep the data consistent with the constraints imposed by the XPath Data Model. For instance, since consecutive text nodes are not permitted, if a text node is inserted as a sibling to another text node, or a comment node between two text nodes is deleted, the two text nodes must be concatenated into a single text node; similarly, since empty text nodes are not permitted, they must be removed.

Processors must preserve all data relevant to the XPath data model during processing and serialization, including processing instructions, comment nodes and whitespace.

<div class="note">'''Note:''' The difference between the <code>src</code> and <code>resource</code> attributes is the precedence over inline content, and that <code>src</code> uses the inline content as a fallback if the link fails.</div>

<div class="example" title="An instance initialized from inline data">
 <instance>
   &lt;screen xmlns="">
     <height>1024</height>
     <width>1920</width>
   &lt;/screen>
 </instance>
</div>

<div class="example" title="Instances initialized from an external resource">
 <instance resource=<nowiki>"https://example.org/templates/a1.xml"</nowiki>/>
 <instance resource=<nowiki>"https://example.org/docs/letter.abw"
          response-mediatype="application/xml"</nowiki>/>
 <instance resource=<nowiki>"https://example.org/site/index.html
          response-mediatype="application/xhtml+xml"</nowiki>/>
</div>

<div class="example" title="Inline content used as fallback">
 <instance src="saveddata.xml">
   &lt;game xmlns="">
      <score>0</score>
      <attempts>0</attempts>
   </game>
 </instance>
</div>

====<span id="initialize-instance-internal">Creating instance data from inline content</span>====

Instance data is obtained from  inline content as follows:

# A detached copy of the single child element of the <code>instance</code> element is created and placed within a new document node. The copied element becomes the ''root element'' of a new XML document.
# Ancestor namespace nodes that are referenced by prefixes of elements and attributes in the instance data are copied to the detached root element. (Note that this is a change from previous versions of XForms, where ''all'' ancestor namespaces were copied.)

If creation of the XPath data model from inline content fails (for example because the <code>instance</code> element has more than one child element or none):

# The instance data is formed by creating an XPath data model consisting of a single document node without a root element.
# An [[#evt-linkError| xforms-link-error]] is dispatched to the relevant <code>model</code> element with a <code>resource-uri</code> indicating a fragment identifier URI reference (including the leading # mark) for an identified internal instance, or empty string for an unidentified internal instance. If the event is not canceled, processing halts (this is the default action for [[#evt-linkError| xforms-link-error]]). If the event is canceled, processing continues.

<div class="example" title="No namespaces copied">
 <xh:html
   xmlns:xh=<nowiki>"http://www.w3.org/1999/xhtml"</nowiki>
   xmlns:xf=<nowiki>"http://www.w3.org/2002/xforms"</nowiki>
   xmlns:foo=<nowiki>"http://example.org/foo"</nowiki>
   xmlns:bar=<nowiki>"http://example.org/bar"></nowiki>
   <xh:head>
     <xf:model>
       <xf:instance>
         <form>
           <first-name/>
         </form>
       </xf:instance>
     </xf:model>
   </xh:head>
 </xh:html>

Resulting data model
 <form>
   <first-name/>
 </form>
</div>
<div class="example" title="Namespaces in use are copied">
 <xh:html
   xmlns:xh=<nowiki>"http://www.w3.org/1999/xhtml"</nowiki>
   xmlns:xf=<nowiki>"http://www.w3.org/2002/xforms"</nowiki>
   xmlns:foo=<nowiki>"http://example.org/foo"</nowiki>
   xmlns:bar=<nowiki>"http://example.org/bar"></nowiki>
   <xh:head>
     <xf:model>
       <xf:instance>
         <form>
           <foo:first-name/>
           <last-name bar:baz=""/>
         </form>
       </xf:instance>
     </xf:model>
   </xh:head>
 </xh:html>

Resulting data model

 <form xmlns:foo=<nowiki>"http://example.org/foo"</nowiki>
       xmlns:bar=<nowiki>"http://example.org/bar"</nowiki>>
   <foo:first-name/>
   <last-name bar:baz=""/>
 </form>
</div>
<div class="example" title="Shadowed namespace prefix is not copied">
 <xh:html
   xmlns:xh=<nowiki>"http://www.w3.org/1999/xhtml"</nowiki>
   xmlns:xf=<nowiki>"http://www.w3.org/2002/xforms"</nowiki>
   xmlns:foo=<nowiki>"http://example.org/foo"</nowiki>
   xmlns:bar=<nowiki>"http://example.org/bar"</nowiki>>
   <xh:head>
     <xf:model>
       <xf:instance>
         <form>
           <foo:bar xmlns:foo=<nowiki>"http://dummy.org/foo"</nowiki>/>
         </form>
       </xf:instance>
     </xf:model>
   </xh:head>
 </xh:html>

Resulting data model

 <form>
   <foo:bar xmlns:foo=<nowiki>"http://dummy.org/foo"</nowiki>/>
 </form>
</div>
<div class="example" title="Namespace prefixes not used in element and attribute names are not copied">
 <xh:html<nowiki>
   xmlns:xh="http://www.w3.org/1999/xhtml"
   xmlns:xf="http://www.w3.org/2002/xforms"
   xmlns:foo="http://example.org/foo"
   xmlns:bar="http://example.org/bar"></nowiki>
   <xh:head>
     <xf:model>
       <xf:instance>
         <form xmlns:baz=<nowiki>"http://example.org/baz"</nowiki>>
           <expression value="foo:a/bar:b/baz:c"/>
         </form>
       </xf:instance>
     </xf:model>
   </xh:head>
 </xh:html>

Resulting data model

 <form xmlns:baz=<nowiki>"http://example.org/baz"</nowiki>>
   <expression value="foo:a/bar:b/baz:c"/>
 </form>

In this case, if the namespace declarations are needed, they should be placed in the instance data:

 <xh:html<nowiki>
   xmlns:xh="http://www.w3.org/1999/xhtml"
   xmlns:xf="http://www.w3.org/2002/xforms"
   xmlns:foo="http://example.org/foo"
   xmlns:bar="http://example.org/bar"></nowiki>
   <xh:head>
     <xf:model>
       <xf:instance>
         <form<nowiki>
           xmlns:foo="http://example.org/foo"
           xmlns:bar="http://example.org/bar"
           xmlns:baz="http://example.org/baz"></nowiki>
           <expression value="foo:a/bar:b/baz:c"/>
         </form>
       </xf:instance>
     </xf:model>
   </xh:head>
 </xh:html>

Resulting data model

 <form<nowiki>
   xmlns:foo="http://example.org/foo"
   xmlns:bar="http://example.org/bar"
   xmlns:baz="http://example.org/baz"></nowiki>
   <expression value="foo:a/bar:b/baz:c"/>
 </form>
</div>
</div>

====<span id="initialize-instance-external">Creating instance data from external resources</span>====

Although inline instance values are created from XML markup, there is no requirement that external sources be XML, just that they be converted to an [[#ref-xpath-data-model|XPath Data Model]] internally.

If the external resource is not an XML format, it should be parsed as if a one-to-one mapping had been applied to the original to produce an equivalent XML document which is then used to produce the XPath Data Model. The one-to-one mapping is defined per format. Two format mappings are given below, but implementors are encouraged to add others, and report on their experiences.

A requirement on such a mapping is that it should only require simple and obvious XPath expressions to access the data. It is not necessary to be able to map all possible XML onto the external data type, but it is required to be able to map all possible values of the external data to XML, and then back again.

For every mediatype accepted for external sources by the processor, the processor must provide an equivalent serialization using the <code>serialization</code> attribute of [[#submit-submission-element|the <code>submission</code> element]].

If the link to the external data cannot be traversed, or it can be traversed, but an XPath data model cannot be created from the resource:
* If the link is specified by the <code>src</code> attribute, and the instance has inline content, that inline content is used to create the instance data, and an [[#submit-evt-submit-error|xforms-submit-error]] with a <code>resource-uri</code> of the link that failed is dispatched to the containing model;
* otherwise, the instance data is formed by creating an XPath data model consisting of a single document node without a root element, and an [[#evt-linkError|xforms-link-error]] with a <code>resource-uri</code> of the link that failed is dispatched to the containing model. If the event is not canceled, processing halts (this is the default action for [[#evt-linkError|xforms-link-error]]); if it is canceled, processing continues.

Otherwise the instance data is formed by creating an XPath data model of the linked resource as described below, and an [[#submit-evt-submit-done|xforms-submit-done]] with a <code>resource-uri</code> of the link is dispatched to the containing model.

The conversion of external data to an XPath data model is used both for initializing instances, and for [[#submission-response|processing the data returned by submissions]].

=====<span id="external-xml">External XML values</span>=====

If the external resource is an XML format (i.e. with a content type matching any of the specifiers in <nowiki>[</nowiki>[[#ref-rfc-3023 |RFC 3023]]<nowiki>]</nowiki>), then an XPath data model is created as defined in <nowiki>[</nowiki>[[#ref-xpath-data-model|XDM]]].

=====<span id="external-json">External JSON values</span>=====
If the external resource is a JSON value <nowiki>[</nowiki>[[#ref-json|JSON]]]<nowiki>[</nowiki>[[#mediatypes|Media Types]]], a root element <code><json/></code> is created whose content is the transformation of the JSON value. Each JSON value is treated as follows:

* A number is copied across, and an attribute <code>type="number"</code> is added to its containing element.
* true and false are copied across, and an attribute <code>type="boolean"</code> is added to its containing element.
* null produces empty content, and an attribute <code>type="null"</code> is added to its containing element.
* The content of a string is copied across.  Escaped characters are transformed as necessary; characters and escapes that have no equivalent XML character (\b, \f, and characters of the form \uxxxx less than \u0020, except for \u0009, \u000A, and  \u000D) are transformed by adding \uE000 to them.
* An object is transformed by adding an attribute <code>type="object"</code> to its containing element, and transforming each of the object's members, if any.
** Each name/value member is encoded as an XML element whose name is the name of the member, and whose content is the transformation of the value part of the member. If any character of the element name is not an allowable XML name character, or is ":", the character is replaced with an underscore "_"; if the first character of the element name is not an allowable XML name start character, or is ":", then an underscore "_" is prepended to the name. In either case, an attribute <code>name</code> is added to the element, with the value of the original name of the element, with  characters treated as with strings.
* A (non-anonymous) array is transformed by adding an attribute <code>type="array"</code> to its containing element, and transforming each of the array's elements, if any, each contained in an element called "_".
* An anonymous array (either at the top level, or itself an element of an array), is transformed by creating an element with the name "_", and an attribute <code>type="array"</code>, and then transforming each of the array's elements, if any, each contained in an element called "_".

This format can be serialized back to JSON with a [[#submit-submission-element|<code>submission</code> element]] with a <code>serialization</code> attribute value of "application/json". Elements not in the default namespace and unknown attributes are ignored when serialising to JSON.

<div class="example" title="various transformations">

{| class="wikitable"
|-
! JSON !! Transformation !! Example selector
|-
| {"given": "Mark", "family": "Smith"} ||
 <json type="object">
    <given>Mark</given>
    <family>Smith</family>
 </json>
|given
|-
| {"name": "Mark", "age": 21} ||
 <json type="object">
    <name>Mark</name>
    <age type="number">21</age>
 </json>
|age
|-
| {"selected": true} ||
 <json type="object">
    <selected type="boolean">true</selected>
 </json>
|selected
|-
| {"cities": ["Amsterdam", "Paris", "London"]} ||
 <json type="object">
   <cities type="array">
     <_>Amsterdam</_>
     <_>Paris</_>
     <_>London</_>
   </cities>
 </json>
|cities/_[1]
|-
| {"load": [0.31, 0.33, 0.32]} ||
 <json type="object">
   <load type="array">
     <_ type="number">0.31</_>
     <_ type="number">0.33</_>
     <_ type="number">0.32</_>
   </load>
 </json>
|load/_[1]
|-
| {"father": {"given": "Mark", "family": "Smith"}, "mother": {"given": "Mary", "family": "Smith"}} ||
 <json type="object">
   <father type="object">
      <given>Mark</given>
      <family>Smith</family>
   </father>
   <mother type="object">
      <given>Mary</given>
      <family>Smith</family>
   </mother>
 </json>
|mother/given
|-
| {"p": null} ||
 <json type="object"><p type="null"/></json>
|p
|-
| {"p": ""} ||
 <json type="object"><p/></json>
|p
|-
| {"p": []} ||
 <json type="object"><p type="array"/></json>
|p
|-
| {"p": {}} ||
 <json type="object"><p type="object"/></json>
|p
|-
| {"$v": 0} ||
 <json type="object">
    <_v name="$v" type="number">0</_v>
 </json>
|*[@name="$v"]
|-
| {"1": "one"} ||
 <json type="object"><_1 name="1">one</_1></json>
|*[@name="1"]
|-
| 3 ||
 <json type="number">3</json>
|.
|-
| "Disconnected" ||
 <json>Disconnected</json>
|.
|-
| ["red", "green", "blue"] ||
 <json type="array">
   <_>red</_>
   <_>green</_>
   <_>blue</_>
 </json>
|_[1]
|-
| {"g": [["a", "b", "c"], ["d", "e"]]} ||
 <json type="object">
  <g type="array">
    <_ type="array">
      <_>a</_>
      <_>b</_>
      <_>c</_>
    </_>
    <_ type="array">
      <_>d</_>
      <_>e</_>
    </_>
  </g>
 </json>
|g/_[1]/_[1]
|-
| {} ||
<json type="object"/>
|.
|-
| [] ||
<json type="array"/>
|.
|-
| "" ||
<json/>
|.
|}

</div>

Note that the mapping is designed to be round-trippable, to allow as natural as possible selectors, and to easily support structural additions and deletions; the <code>type</code> attributes are only necessary to distinguish ambiguous representations on serialization, and have no further effect on processing.

</div>

<div class="div4">

=====<span id="external-csv">External CSV values</span>=====
When an XForms Processor receives a CSV value <nowiki>[</nowiki>[[#ref-csv|CSV]]], it treats it as follows:

* A root element <code><csv/></code> is created whose content is the transformation of the CSV value.
* If the first row of the external value contains labels (marked by the <code>header</code> parameter of the mediatype), then that row appears in the transformed content, enclosed by an <code>&lt;h&gt;</code> element. Each value of the headers row is enclosed by an element: if the value consists only XML name characters, that is the name of the element, otherwise non-matching characters are replaced by the underscore character "_"; if the first character may not start an XML name, an underscore is prepended.
* Each (subsequent) row is enclosed in an <code>&lt;r&gt;</code> element.
* If the first row of the external value contained labels, then each value of subsequent rows is surrounded by an element consisting of the transformed name from the respective header as defined above.
* If the first row of the CSV value did not contain headers, then each value is surrounded by a <code>&lt;v&gt;</code> element.

This format can be serialized back to CSV with a [[#submit-submission-element|<code>submission</code> element]] with a <code>serialization</code> attribute value of "text/csv", with optional charset and header parameters <nowiki>[</nowiki>[[#ref-csv|CSV]]]. When no header parameter is supplied, it has the same effect as <code>header=absent</code>.

<div class="example" title="various transformations">
{| class="wikitable"
|-
! CSV !! Transformation
|-
|
 Year, Result
 2011, 143
 2012, 457
   ||
 <csv>
   <r><Year>2011</Year><Result>143</Result></r>
   <r><Year>2012</Year><Result>457</Result></r>
 </csv>
|-
|
 2011, "Jan, Mar"
 2012, "Feb, Apr"
 ||
 <csv>
   <r><v>2011</v><v>Jan, Mar</v></r>
   <r><v>2012</v><v>Feb, Apr</v></r>
 </csv>
|-
|
 Name, Hex value
 Red, #f00
 Green, #0f0
 Blue, #00f
 ||
 <csv>
   <h><Name>Name</Name><Hex_value>Hex value</Hex_value></h>
   <r><Name>Red</Name><Hex_value>#f00</Hex_value></r>
   <r><Name>Green</Name><Hex_value>#0f0</Hex_value></r>
   <r><Name>Blue</Name><Hex_value>#00f</Hex_value></r>
 </csv>
|}
</div>

<div class="example" title="selectors">
 <repeat ref="r"><output ref="Name"/></repeat>
 <output ref="r[1]/Year"/>
 <input ref="r[1]/v[3]">...
 <output ref="r[2]/Hex_value"/>
</div>

</div>

<div class="div4">

=====<span id="external-other">Other External values</span>=====

No other types of external values are normatively defined in this specification; however implementors are encouraged to accept other types of values, and report on experiences for possible future inclusion. Transformations should be chosen to make selectors as natural as possible. As an example, a VCARD:

 BEGIN:VCALENDAR<nowiki>
 METHOD:PUBLISH
 PRODID:-//Example/ExampleCalendarClient//EN
 VERSION:2.0
 BEGIN:VEVENT
 ORGANIZER:mailto:a@example.com
 DTSTART:19970701T200000Z
 DTSTAMP:19970611T190000Z
 SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
 UID:0981234-1234234-23@example.com
 END:VEVENT
 END:VCALENDAR</nowiki>

could be transformed to

 <VCALENDAR><nowiki>
   <METHOD>PUBLISH</METHOD>
   <PRODID>-//Example/ExampleCalendarClient//EN</PRODID>
   <VERSION>2.0</VERSION>
   <VEVENT>
     <ORGANIZER>mailto:a@example.com</ORGANIZER>
     <DTSTART>19970701T200000Z</DTSTART>
     <DTSTAMP>19970611T190000Z</DTSTAMP>
     <SUMMARY>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</SUMMARY>
     <UID>0981234-1234234-23@example.com</UID>
   </VEVENT>
 </VCALENDAR></nowiki>
</div>
</div>
<div class="div3">

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

The <code>bind</code> element associates properties with values in instance data.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]

Special Attributes:

; ref
: Optional [[#def-model-binding-expression|model binding expression]] that selects the items on which to operate. If the attribute is omitted, the default is the [[#in-scope-evaluation-context|in-scope evaluation context]].
; nodeset [deprecated]
: A synonym for <code>ref</code>.  Ignored if attribute <code>ref</code> is present.
; [[#model-prop-type|type]] [not AVT]
: Optional type. Default is xf:string.
; [[#model-prop-constraint|constraint]]
: Optional boolean expression. Default is true.
; [[#model-prop-relevant|relevant]]
: Optional boolean expression. Default is true.
; [[#model-prop-required|required]]
: Optional boolean expression. Default is false.
; [[#model-prop-readOnly|readonly]]
: Optional boolean expression. Default is false.
; [[#model-prop-calculate|calculate]]
: Optional expression. Default is no calculated expression.
; [[#model-prop-whitespace|whitespace]]
: Optional string with allowable values "preserve", "remove", "trim", "collapse", and "normalize". Default is "preserve". 
; [[#model-prop-label|label]]
: Optional text with no default.
; [[#model-prop-hint|hint]]
: Optional text with no default.
; [[#model-prop-help|help]]
: Optional text with no default.
; [[#model-prop-alert|alert]]
: Optional text with no default.

Content: bind*
</div>
If the <code>model</code> attribute is used, and doesn't reference the parent model, an [[#The xforms-binding-error Event|xforms-binding-error]] is dispatched to the <code>bind</code> element.

If the bind has a <code>ref</code> attribute, it is evaluated in the [[#in-scope-evaluation-context|in-scope evaluation context]] to give a sequence of items; otherwise the in-scope evaluation context gives the sequence.

For each item in the sequence, model item properties are applied according to the remaining attributes on the <code>bind</code> element (see [[#Model Item Properties|Model Item Properties]] for details). 

When <code>bind</code> has an attribute of type <code>xs:ID</code>, that ID is associated with the selected sequence.

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

<div class="example" title="binds">
 <bind ref="today" type="date"/>
 <bind ref="color" readonly="../variant='basic'"/>
 <bind ref="state" required="../country='USA'"/>
 <bind ref="state" relevant="../country='USA'"/>
 <bind ref="total" calculate="../number * ../unitprice"/>
 <bind ref="height" constraint=". > 0"/>
 <bind ref="creditcard" whitespace="remove"/>
 <bind ref="a" label="Age"/>
 <bind ref="username" help="If you can't remember your username, call the help desk on extension 3000"/>
 <bind ref="h" hint="height in centimeters"/>
 <bind ref="i" type="integer" alert="must be a whole number"/>
 <bind ref="c">
       <bind calculate="../a + ../b"/>
 </bind>
 <bind ref="c">
       <bind context=".." calculate="a + b"/>
 </bind>
 <bind ref="instance('admin')">
       <bind ref="submitted" type="boolean"/>
       <bind ref="finished" relevant="../submitted=true()"/>
 </bind>
 <bind ref="count">
       <bind type="integer" alert="must be a whole number"/>
       <bind constraint=". > 0" alert="must be greater than zero"/>
 </bind>
</div>

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

Model item properties are properties bound to instance data nodes with [[#The bind Element|the <code>bind</code> element]]. The combination of an [[#def-instance-data-node|instance data node]] and its properties is called a '''<span id="def-model-item">model item</span>'''.

Some model item properties define '''inheritance rules''', in which case the Processor combines the '''local value''', which is applied from a <code>bind</code> element, with the '''inherited value''', which is the combination of values from ancestor nodes in the instance data.

Some model item properties are '''computed''': the [[#rpm|processing model]] describes when and how the calculation is performed.

If [[#Model Item Properties|Model Item Properties]] are attached to atomic values, or nodes that don't belong to an instance, an [[#evt-bindingError|xforms-binding-error]] is dispatched to the element with the binding.

Most properties may be assigned multiple times to a node using different bind elements (for instance two binds to the same node, each specifying a constraint). However, an [[#The_xforms-binding-error_Event|xforms-binding-error]] is dispatched to any bind that applies a <code>calculate</code> or <code>whitespace</code> property twice to the same node. Multiple bindings are combined so that all have to be true, or that at least one has to be true, according to the following table:

{| border="1"
|-
! property
! combination
|-
| type
| all have to be true
|-
| constraint
| all have to be true
|-
| relevant
| all have to be true
|-
| required
| one has to be true
|-
| readonly
| one has to be true
|-
| calculate
| not allowed
|-
| whitespace
| not allowed
|-
| label
| not allowed
|-
| help
| not allowed
|-
| hint
| not allowed
|-
| alert
| one allowed per type and constraint
|}

<div class="example" title="combination">

 &lt;bind ref="action" readonly="../status='accepted'"/>
 &lt;bind ref="action" readonly="../status='rejected'"/>

has the same effect as

 &lt;bind ref="action" readonly="../status='accepted' or ../status='rejected'"/>
</div>
The following sections list the model item properties available.
<div class="div3">

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

This property associates a datatype with an instance node, contributing to the [[#validity|validity]] of a node.
<div class="desc">
Computed Expression: No.

Legal Values: An <code>xs:QName</code>.

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

Inheritance Rules: does not inherit.
</div>
The value must reference a datatype (as defined in <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>) defined in an applicable XML Schema, or an XForms predefined type. The datatype can be obtained from a simpleType definition or a simpleContent definition from a complexType. The namespace context of the <code>bind</code> element is used to resolve the namespace.

The datatype is associated with the node, as defined in [[#ref-xpath-data-model|XPath Data Model]]. It can be applied to both elements and attributes, but not to instance nodes that contain child elements.

<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, it is not applicable to a <code>type</code> model item property.
</div>
<div class="example" title="simple usage">
 <bind ref="count" type="integer"/>
 <bind ref="today" type="date"/>
</div>
<div class="example" title="simple schema usage">
 <nowiki><model xmlns="http://www.w3.org/2002/xforms">
    <schema xmlns="http://www.w3.org/2001/XMLSchema">
       <simpleType name="PIN">
          <restriction base="xsd:string">
             <pattern value="[0-9]{4}"/>
          </restriction>
       </simpleType>
    </schema>

    <instance>
       <data xmlns="">
          <pin-code/>
       </data>
    </instance>

    <bind ref="pin-code" type="PIN"/>
 </model></nowiki>
</div>
<div class="example" title="using schema types">
 <nowiki><model xmlns:ex="http://example.org">
 
   <schema targetNamespace="http://example.org" xmlns="http://www.w3.org/2001/XMLSchema">
     <simpleType name="Currency">
       <restriction base="xs:string">
         <enumeration value="USD"/>
         <enumeration value="EUR"/>
       </restriction>
     </simpleType>
 
     <complexType name="Price">
       <simpleContent>
         <extension base="xs:decimal">
           <attribute name="currency" type="ex:Currency" use="optional" default="USD"/>
         </extension>
       </simpleContent>
     </complexType>
   </schema>
 
   <instance>
     &lt;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>
     &lt;/data>
   </instance>
 
   <bind ref="ex:simpleType/ex:price" type="decimal"/>
   <bind ref="ex:complexType/ex:price" type="ex:Price"/>
   <bind ref="ex:complexType/ex:price[3]/@currency" type="ex:Currency"/>
 
 </model></nowiki>
</div>
</div>
<div class="div3">

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

This property describes whether the node content is restricted from changing.
<div class="desc">
Computed Expression: Yes.

Legal Values: Any boolean expression.

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

Inheritance Rules: If any ancestor node of the bound node is <code>readonly</code>, this value is also <code>readonly</code>. Otherwise, the local value is used.
</div>

If the expression fails to evaluate, the property is set to <code>true</code>.

This property indicates whether <span id="def-readonly">changes are allowed to the content of the bound instance data node from constructs other than the model item property system</span> (i.e. other than a <code>calculate</code>). Instance mutations performed by <code>submission</code>, 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.

Controls bound to readonly instance data do not receive input focus, and should indicate that entering or changing the value is not allowed. The <code>readonly</code> model item property does not affect visibility.

<div class="example" title="simple usage">
 <instance>
   <person xmlns="">
     <name>Roland</name>
     <id>2015000123</id>
   </person>
 </instance>
 <bind ref="id" readonly="true()"/>
</div>

<div class="example" title="computed value">
 <bind ref="color" readonly="../version='basic'"/>
</div>

<div class="example" title="Setting a default value">
This example illustrates overriding the default <code>readonly</code> setting on calculated nodes.
 <model>
   <instance>
     &lt;data xmlns="">&lt;/data>
   </instance>
   <bind ref="/data" readonly="false()" calculate="choose(.=<nowiki>''</nowiki>, 'default', .)"/>
 <model>
The <code>calculate</code> is executed on any recalculate, including initialization, so the value is initially 'default'. If the user makes changes to the value, the calculate is re-evaluated, so that if an empty value is entered, <code>data</code> will be set back to 'default'.
</div>
</div>
<div class="div3">

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

This property describes whether a value may be empty or not, contributing to the [[#validity|validity]] of a node.
<div class="desc">
Computed Expression: Yes.

Legal Values: Any <code>boolean</code> expression.

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

Inheritance Rules: does not inherit.
</div>

If the expression fails to evaluate, the property is set to <code>true</code>.

This property indicates whether <span id="def-required">the instance data node must be non-empty</span>. A value is non-empty if it would have a length greater than zero if converted to <code>string</code>.

Controls bound to a required node should indicate that they are required. This property does not prevent controls and Actions from setting empty strings into data nodes, and has no defined effect on visibility, focus, or navigation order. Authors should ensure that controls bound to <code>required</code> data are visible. 

<div class="example" title="required">
 <instance>
    <address xmlns="">
       <street/>
       <street2/>
       <city/>
       <state/>
       <country/>
    </address>
 </instance>
 <bind ref="street" required="true()"/>
 <bind ref="city" required="true()"/>
 <bind ref="state" required="../country='USA'"/>

Here, <code>street2</code> and <code>country</code> are optional, and <code>state</code> is only required if <code>country</code> has the value <code>'USA'</code>.
</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.

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>, the element still has to be non-empty.
</div>
</div><div class="div3">

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

This property indicates whether an instance node is available to the user interface and to submission.
<div class="desc">
Computed Expression: Yes.

Legal Values: Any boolean expression.

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

Inheritance Rules: If any ancestor node of the bound node is non-relevant, this value is also non-relevant. Otherwise, the local value is used. 
</div>

If the expression fails to evaluate, the property is set to <code>false</code>.

This property indicates whether <span id="def-enabled">the instance data node is available for use by controls in the user interface and for submission</span>. For instance, when paying by cash, a credit card number is not relevant. 

Relevance affects visibility, focus, and navigation order of controls bound to a node: see the section on [[#form-control-non-relevance-conditions|Availability]] for details.

<div class="note">
'''Note:''' A control must have a Single Item 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="example" title="relevant">
 <instance>
   <order xmlns="">
     <item>
       <amount/>
       <discount>10</discount>
     </item>
   </order>
 </instance>
 <bind ref="item/discount" readonly="true()" relevant="../amount > 1000"/>
This indicates that the discount is relevant only when the order amount is greater than 1000.
</div></div><div class="div3">

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

Instance values may be computed from other values, for example, the sum of a series of values, or the amount of tax to be paid on an order.  This property calculates a value for the associated node.
<div class="desc">
Computed Expression: Yes.

Legal Values: Any expression.

Default Value: none.

Inheritance Rules: does not inherit.
</div>

If the evaluation succeeds, the result is converted to <code>string</code> and stored as the value content of the associated data node. If the evaluation fails, the value content is set to the empty sequence.

<div class="example" title="calculate">
 <instance>
   <order xmlns="">
     <item>
       <amount/>
       <discount/>
     </item>
   </order>
 </instance>
 <bind
   ref="item/discount"
   calculate="../amount * 0.1"
   relevant="../amount > 1000"/>

Here, a discount of 10% is calculated when the order amount is greater than 1000.
</div>
</div><div class="div3">

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

This property specifies extra [[#validity|validity]] conditions for instance data.
<div class="desc">
Computed Expression: Yes.

Legal Values: Any boolean expression.

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

Inheritance Rules: does not inherit.
</div>

If the expression fails to evaluate or evaluates to <code>false</code>, the associated data node is not valid (the converse is not necessarily true). 

This property contributes to the validity of a node; the effect of validity on controls is described in the section on [[#ui-processing|Implementation Requirements Common to All Controls]]. This property does not prevent controls and Actions from setting invalid values into data nodes.

<div class="example" title="constraint">
 <instance>
   <range xmlns="">
     <from/>
     <to/>
   </range>
 </instance>
 <bind ref="to" constraint=". > ../from"/>

This indicates that the value of <code>to</code> must be greater than that of <code>from</code>.
</div>
<div class="example" title="pattern matching">
 <bind ref="pin-code" constraint="matches(., '^\d{4}$')"/>
This checks if the value of <code>pin-code</code> matches 4 digits. This could also be done by writing a schema that defines a type that has the same effect (see [[#model-prop-type|The Type Property]] for the equivalent example).
</div>
<div class="example" title="constraining number of items">
 <instance>
     <wishes xmlns="">
         <blank><wish/></blank>
     </wishes>
 </instance>
 <bind ref="wish" constraint="count(../wish) &amp;lt; 4"/>

 <repeat ref="wish">
     <input ref="." label="What is your wish?">
         <alert>You can't have more than 3 wishes!</alert>
     </input>
 </repeat>
 <trigger label="Make a wish">
     <insert ev:event="DOMActivate" ref="wish" origin="/wishes/blank/wish"/>
 </trigger>
This makes ''all'' wishes invalid if there are more than 3. To make only the excess wishes invalid, you can use
 <bind ref="wish" constraint="position() &amp;lt; 4"/>
</div>
</div><div class="div3">

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

This property specifies how whitespace is treated when a node receives a new value.
<div class="desc">
Computed Expression: No.

Legal Values: <code>preserve</code>, <code>remove</code>, <code>trim</code>, <code>collapse</code>, <code>normalize</code>.

Default Value: <code>preserve</code>.

Inheritance Rules: does not inherit.
</div>
When a node receives a new value, this property controls how whitespace is treated:

;<code>preserve</code>
: all whitespace is preserved,
;<code>remove</code>
: all whitespace is removed,
;<code>trim</code>
: all whitespace from the beginning and end of the string is removed,
;<code>collapse</code>
: each occurrence of multiple whitespace is replaced with a single space character (0x20),
;<code>normalize</code>
: a combination of 'trim' and 'collapse'.

Whitespace is any character defined as whitespace ("WSpace=Y", "WS") in the Unicode Character Database <nowiki>[</nowiki>[[#ref-unicode-character-database |Unicode Character Database]]<nowiki>]</nowiki>.

The <code>whitespace</code> property is processed during a [[#model-recalculate|recalculate]].

<div class="example" title="whitespace">
 <instance>
    <payment xmlns="">
       <amount/>
       <name/>
       <cardnumber/>
    </payment>
 </instance>
 <bind ref="amount" type="decimal"/>
 <bind ref="name" whitespace="normalize"/>
 <bind ref="cardnumber" type="card-number" constraint="is-card-number(.)"
       whitespace="remove"/>

Here, the <code>whitespace</code> properties indicate that when a value is input for <code>name</code>, the leading and trailing whitespace will be removed, and all other consecutive sequences of whitespace will be collapsed to a single space, and that if a credit card number is input with embedded whitespace, that whitespace will be removed. For the <code>amount</code> value, by default whitespace is preserved &mdash; however XML rules specify that leading and trailing whitespace does not affect validity of numbers: see the section on whitespace normalization during validation in <nowiki>[</nowiki>[[#ref-xschema-1 |XML Schema Part 1]]<nowiki>]</nowiki>.
</div>
</div>

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

This property associates a label text with an instance data node. It may be expressed either with an attribute on bind or with a label element as a child of bind.
<div class="desc">
Computed Expression: No.

Legal Values: Any string.

Default Value: None.

Inheritance Rules: does not inherit.
</div>
Controls without a label element or attribute must make the label property text available to the user as part of the control. If a control has its own label element or attribute, that text is used instead.

<div class="example" title="label property">
 <bind ref="p" label="Percentage"/>

 <bind ref="co2">
     <label>CO<h:sub>2</h:sub></label>
 </bind>
</div>

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

This property associates a help text with an instance data node. It may be expressed either with an attribute on bind or with a help element as child of bind.
<div class="desc">
Computed Expression: No.

Legal Values: Any string.

Default Value: None.

Inheritance Rules: does not inherit.
</div>
Controls without a help element or attribute must make the help property text available to the user when requested. If a control has its own help element or attribute, that text is used instead.

<div class="example" title="help property">
 <bind ref="cvv" label="Security Code" help="The 3-digit code on the back of your card is your CVV number/Card Security Code."/>

 <bind ref="/login/password" label="Password">
   <help>Have you forgotten your password? Simply call 1-900-555-1212 and have
         a major credit card handy.</help>
 </bind>
</div>

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

This property associates a hint text with an instance data node. It may be expressed either with an attribute on bind or with a hint element as child of bind.
<div class="desc">
Computed Expression: No.

Legal Values: Any string.

Default Value: None.

Inheritance Rules: does not inherit.
</div>
Controls without a hint element or attribute must make the hint property text available to the user when requested. If a control has its own hint element or attribute, that text is used instead.
<div class="example" title="hint property">
 <bind ref="creditcard" type="card-number" label="Credit card" constraint="is-card-number(.)"
       alert="Incorrect card number" hint="16 digits, spaces allowed" whitespace="remove"/>
 
 <bind ref="expires" label="Expires" constraint="matches(., '^dd/0d|dd/1[12]$')" alert="Format must be YY/MM">
    <hint appearance="minimal">YY/MM</hint>
 </bind>
</div>

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

This property associates an alert text with type and constraint properties of a binding. It may be expressed either with an attribute on bind or as an alert element as child of bind.
<div class="desc">
Computed Expression: No.

Legal Values: Any string.

Default Value: None.

Inheritance Rules: does not inherit.
</div>
This property associates an alert text with a type property or constraint property of a binding, or both. 

A control bound to a node that fails to match its type and constraint properties must make an alert text available to the user:
If the control has an alert element or attribute, that text is used;
otherwise, if the type property or constraint that has failed has an alert property associated with it, that text is used;
otherwise an implementation-dependent text may be used.

<div class="example" title="alert property">
 <bind ref="a" type="integer" alert="Must be an integer"/>

 <bind ref="a" type="integer">
       <alert><h:strong>Must</h:strong> be an integer"</alert>
 </bind> 

 <bind ref="b" constraint=". ne 0" alert="May not be zero"/>
 
 <bind ref="c" type="integer" constraint=". ge 0 and . le 100" alert="Must be an integer between 0 and 100"/>

 <bind ref="c" label="Percentage" type="integer" alert="Must be integer">
      <bind constraint=". ge 0 and . le 100" alert="Must be between 0 and 100"/>
 </bind>
 
 <bind ref="c" label="Percentage" type="integer" alert="Must be integer">
      <bind constraint=". ge 0 and . le 100">
           <alert><h:strong>Must</h:strong> be between 0 and 100</alert>
      </bind>
 </bind>

 <bind ref="d" label="{instance('messages')/divisor}">
      <bind type="integer"      alert="{instance('messages')/integer}"/>
      <bind constraint=". ne 0" alert="{instance('messages')/zero}"/>
 </bind>
 
 <bind ref="birth" label="Year of birth" type="integer">
      <bind constraint=". ge 1900" alert="Year must be after 1900"/>
      <bind constraint=". le ../thisyear" alert="Year can be at most {../thisyear}"/>
 </bind>
 
 <bind ref="death" label="Year of death" type="integer">
      <bind constraint=". ge 1900"        alert="Year must be after 1900"/>
      <bind constraint=". le ../thisyear" alert="Year can be at most {../thisyear}"/>
      <bind constraint=". ge ../birth"    alert="Year of death must be after year of birth ({../birth})"/>
 </bind>
 
 <bind id="age" ref="age" label="Age at death" type="integer" calculate="../death-../birth">
      <bind constraint=". ge 0"   alert="Age must be greater than or equal to zero"/>
      <bind constraint=". lt 130" alert="No one has ever lived to be that age!"/>
 </bind>
</div>

===<span id="structure-shared-element">The shared Element</span>===
Specifies the data to be shared by this form when embedded with a [[#ui-control|<code>control</code>]] element in another form, and allows communication with events between the two.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-single-node|Single Item Binding]] (optional)

Special Attributes:

; initial [not AVT]
: Optional attribute specifying how the shared data must be initialized. Allowable values are "local" and "external". The default is "local".

Content: [[#action-content-set|Action]]*

Data Binding Restrictions: This element can only be bound to a single element, of any type.
</div>

If this form is not embedded in another, this element has no effect.

If it is embedded, this element specifies which data element if any is to be shared and synchronised with the embedding form, and provides a communication point for use with the [[#action-signal|<code>signal</code>]] action.

If the element has a binding:

* It is evaluated, and must evaluate to a single element, and the control element that caused the current form to be embedded must also have a binding that similarly evaluates to a single element, otherwise an [[#evt-bindingError|xforms-binding-error]] is dispatched to the <code>shared</code> element.
* If the element has an <code>initial</code> attribute that evaluates to <code>external</code>, the attributes and content including all children of the referenced element in the embedding form replace those of the referenced element in the embedded form,
* otherwise, the attributes and content including all children of the referenced element in the embedded form replace those of the referenced element in the embedding form.
* After initialisation, the referenced elements are kept synchronised: a change in one is reflected in a change in the other.

If the <code>shared</code> element does not have a binding, the <code>control</code> element used to embed the current form must not have a binding and no data is shared.

<div class="example" title="Sharing an element (and its children)">
 <shared ref="data"/>
</div>
<div class="example" title="using a bind">
 <shared bind="sharing"/>
</div>
<div class="example" title="initializing from the embedding XForm">
 <shared ref="collection/a" initial="external"/>
</div>
<div class="example" title="no data shared">
 <shared/>
</div>
<div class="example" title="no data shared, listening for a restart event">
 <shared>
   <action ev:event="restart">
      <setvalue ref="score">0</setvalue>
   </action>
 </shared>
</div>

===<span id="validity">Validity</span>===

An instance node is '''valid''' if 
* the value is empty and not <code>required</code>, 
or 
* the value satisfies all applicable types, and all applicable <code>constraint</code> model item properties evaluate to <code>true()</code>.

Applicable types include those associated by the <code>type</code> model item property, by an external or an inline XML Schema, and by <code>xsi:type</code>.

Validity affects the rendering of values, and submission; the effect of validity on controls is described in the section on [[#ui-processing|Implementation Requirements Common to All Controls]]. It does not prevent controls and Actions from setting data nodes to values that do not match their types.

===<span id="model-processing">Model Processing</span>===

====<span id="model-initialization">Model Initialization</span>====

The XML Schemas, if any, are loaded. If an error occurs while attempting to access or process a remote document, an [[#evt-linkError|xforms-link-error]] is dispatched to the model: if the event is canceled, processing continues as if the XML Schema had not been linked in the first place; otherwise processing halts (which is the default action for [[#evt-linkError|xforms-link-error]]).

For each <code>instance</code> element an XPath data model is constructed as described in [[#The instance Element|The instance Element]] section.

An [[#model-update|update]] is then done for this model. (A [[#model-refresh|refresh]] is not performed since the user interface has not yet been initialized.)

====<span id="model-ui-initialize">User Interface Initialization</span>====
After all models have been initialized, the controls in the user interface are connected to the data in the models.

For each control:
* The user interface for the control is created.
* If the control has a binding, it is evaluated; if the result is an empty sequence then the control is initially disabled; if the result is an atomic value, the control is initially [[#model-prop-readOnly|readonly]].
* The control is initialized with its value and model item properties (valid, required, readonly and relevant).
* For a <code>repeat</code>, it is initialized as described in [[#repeat-initialization|repeat initialization]].

</div>

====<span id="expr-dependencies">Dependencies</span>====

As a result of bindings within a model, instance values can depend on each other in various ways; for instance, a value may by calculated from other values with a <code>calculate</code> property, or may be constrained by other values using a <code>constraint</code> property.

At fixed points during processing, if the structure of an instance has changed (due to insert or delete actions, or being replaced after a submit), or values within an instance have changed, the model is ''updated''.

An update may involve as necessary a ''[[#model-rebuild|rebuild]]'' of dependencies if the structure has changed, a ''[[#model-recalculate|recalculate]]'' of new values of dependent items, and a ''[[#model-revalidate|revalidate]]'', to check the validity of the new values.

An update is followed by a ''[[#model-refresh|refresh]]'' of the user interface with the new values.

Note that updates are triggered by a change to a value or structure within an instance; this means that values that only depend on values external to the model are not automatically updated when the external values change. In particular functions without parameters such as <code>index()</code>, <code>case()</code>, and <code>now()</code> do not trigger a recalculate when their values change. For <code>index</code> it is preferable to use the <code>indexref</code> attribute on <code>repeat</code> and for <code>case</code> the <code>ref</code> attribute on <code>select</code>.

Although some processes in this specification are described as if all expressions in a model or the user interface are re-evaluated every time there is a change, implementations are of course at liberty to optimize this, as long as the result is the same.

Although rebuild, recalculate, revalidate, and refresh are described as separate steps, since they always occur in sequence, implementations are at liberty to combine them into a lesser number of steps.

An expression '''references''' a node of instance data if the node is selected during the evaluation of the expression, even if it is subsequently excluded from further participation in the expression evaluation (for example by a filter expression).
(The selection mechanism is defined in the [[#def-expression-module|expression module]].)

A [[#def-computed-expression|computed expression]] is '''dependent''' on an instance node if it references it and uses its character content (rather than just referencing for navigation);
any other expression is dependent on an instance node if it just references it.

<div class="example" title="References and Non-References">

Consider the following expression:

 continent[@name='Europe']/country[@name='France']/capital

applied to the following instance:

 &lt;instance>
    &lt;data xmlns="">
       &lt;'''continent name'''="Europe">
          &lt;'''country name'''="UK">
             &lt;capital>London&lt;/capital>
          &lt;/country>
          &lt;area>10&lt;/area>
       &lt;/continent>
       &lt;'''continent name'''="Asia">
          &lt;country name="Japan">
             &lt;capital>Tokyo&lt;/capital>
          &lt;/country>
          &lt;area>45&lt;/area>
       &lt;/continent>
    &lt;/data>
 &lt;/instance>

Both <code>continent</code> elements are referenced since both are matched, and the <code>name</code> attribute on each is referenced during the evaluation of the filter. The filter rejects the second <code>continent</code> element, but the element and its attribute have still been referenced.

The <code>country</code> element in the first <code>continent</code> is referenced, but not the one in the second <code>continent</code> since expression evaluation did not proceed beyond the filter expression that rejected the second <code>continent</code> element.

While performing the test for element <code>country</code>, observe that the expression evaluator may visit all the children of the first <code>continent</code> element. However, an element is not referenced if it is only visited but fails the test. In this case, the test is for <code>country</code>, which the <code>area</code> element fails. Therefore, <code>area</code> is not referenced.

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

Element <code>capital</code> is not considered to be referenced by this expression. Although a test for <code>capital</code> appears in the expression, the evaluation of the expression did not proceed due to the rejection of <code>country</code> by the filter expression.

Finally, note that an expression can reference many nodes even if its final result is the empty sequence (as in this case).
</div>
<div class="example" title="Explicit Rebuild">

Consider the following example:

 &lt;model>
   &lt;instance>
     &lt;data xmlns="">
       &lt;continent name="Europe">
         &lt;country name="UK">
           &lt;capital>London&lt;/capital>
         &lt;/country>
         &lt;area>10&lt;/area>
       &lt;/continent>
       &lt;continent name="Asia">
         &lt;country name="Japan">
           &lt;capital>Tokyo&lt;/capital>
         &lt;/country>
         &lt;area>45&lt;/area>
       &lt;/continent>
       &lt;selected-country>UK&lt;/selected-country>
     &lt;/data>
   &lt;/instance>
 
   &lt;bind
     ref="selected-country"
     id="selected-country"/>
 
   &lt;bind
     ref="continent/country"
     id="all-countries"/>
 
   &lt;bind
     ref="continent/country[@name = ../../selected-country]"
     id="current-country"/>
 
 &lt;/model>
 
  &lt;select1 bind="selected-country" label="Select country">
   &lt;itemset bind="all-countries" label="{@name}" value="@name"/>
   &lt;rebuild ev:event="xforms-value-changed"/>
 &lt;/select1>
 
 &lt;group bind="current-country" label="Country details">
   &lt;output ref="@name" label="Country name"/>
   &lt;output ref="capital" label="Country capital"/>
 &lt;/group>

When the user changes the value of the selection control, the expectation is that the information relative to the selected country shows below.

However, the <code>current-country</code> bind does not refresh upon the selection control's change of value. This means that the form doesn't behave as
intuitively expected. In order to fix this, an explicit <code>rebuild</code> action runs when the value of the control changes. Subsequently, all
model binds are up to date, and when the user interface refreshes the correct country details show.

</div>
<!-- Not needed
=====Dynamic Dependencies=====
The references of an expression may be altered by insertion of instance nodes since the new nodes may be referenced by the expression if it is re-evaluated. Similarly, the references of an expression may be altered by deletion of instance nodes that are being referenced by the expression.

An expression is '''dynamically dependent''' on an instance node if its set of references is altered by inserting, deleting or changing the value of the instance node.

An instance node is a '''dynamic dependency''' for an expression if the expression is dynamically dependent on the instance node. If an expression contains a dynamic dependency and the XForms Processor is maintaining dependency lists for the category of the expression, then changing the dynamic dependency implies a change to the dependency lists of instance nodes referenced by the expression.

The computational dependency data structure described in [[#model-recalculate|recalculate]] 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 rebuilt 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.

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

====<span id="action-deferred-updates">Updates</span>====
Updates of a model are done after a user or action handler has caused a change to an instance.

Updates are not done while an action handler is being processed, but only after the termination of the [[#action-outermost-action|outermost action handler]].

An <span id="action-outermost-action">'''outermost action handler'''</span> is an action that is activated when the Processor is not executing any other action handlers.

An <span id="action-inner-action">'''inner action handler'''</span> is an action that is activated while the Processor is already executing an 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 by an action handler.

<div class="note">

'''Note:'''

Since the Processor is not executing an outermost action handler at the time that it performs an update, event handlers for events dispatched during the resulting refresh are new outermost action handlers.

</div>

Since some XForms actions require the model to be in a consistent state either before or after their processing, they ensure that the model is up-to-date at the appropriate moment. These points are described in the relevant descriptions of the actions.

====<span id="model-rebuild">Rebuild</span>====
A rebuild considers each [[#structure-bind-element|<code>bind</code>]] element in the model, re-computes the model item properties, rebuilds the implicit computational dependency structures, and prepares for a full recalculate.

====<span id="model-recalculate">Recalculate</span>====
All computed expressions in the model are identified:

* An expression is bound either to the value or to a model item property of one or more instance nodes; each combination of an 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.

* A compute may '''reference''' (or '''refer to''') an instance node, in which case the value of the instance node is '''referenced'''. 

* All computes that directly reference an instance node are its '''dependants'''; excluded are references to the current node's value in <code>calculate</code> expressions (such an instance node does not take itself as a dependent). 

* A compute is '''computationally dependent''' on an instance node if there is a path of dependants 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 through a series of <code>calculate</code> expressions.

At the start of a recalculate, there is a, possibly empty, list ''L'' of instance nodes whose values may have been changed, e.g., by user input or by a <code>setvalue</code> action.

* All nodes in ''L'', if any, and nodes that are computationally dependent on nodes in ''L'' must be recalculated.
* Only a single recalculation of each compute that is computationally dependent on elements in ''L'' may be performed.
* A compute must be recalculated before any computes that are computationally dependent on the instance node associated with it.
* If a compute is computationally dependent on an element in ''L'' and part of a circular dependency, then an [[#evt-computeError|xforms-compute-error]] must be dispatched to the model element.

When a compute is recalculated, the expression is evaluated using the evaluation context of the model binding expression that the compute comes from, as defined for computed expressions in [[#Evaluation Context|Evaluation Context]]. 

If any node value changes as a result of a <code>calculate</code> constraint, and if the resulting node has a [[#model-prop-whitespace|<code>whitespace</code>]] property, that property must be immediately applied to the value.

<div class="note">
'''Note:''' The [[#Recalculation Sequence Algorithm|Recalculation Sequence Algorithm]] describes one possible method for achieving the recalculation behavior.
</div>
<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 ref="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 ref="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>

====<span id="model-revalidate">Revalidate</span>====
All instance data nodes in all <code>instance</code> elements in the <code>model</code> are checked for [[#validity|validity]].

====<span id="model-update">Update</span>====
All instance data nodes in all <code>instance</code> elements in the <code>model</code> are updated by doing a [[#model-rebuild|rebuild]], [[#model-recalculate|recalculate]], and [[#model-revalidate|revalidate]] as necessary.

====<span id="model-refresh">Refresh</span>====
All [[#UI Expressions|UI Expressions]] are re-evaluated as necessary, and the user interface is updated to reflect the state of the model, including:
* current values,
* model item properties: validity, relevance, read-write, and requiredness,
* the proper number of, and content for, repeat objects and itemset items.

Notification events are dispatched, in no defined order:
* If a bound value has become non-relevant since the last refresh, the <code>xforms-disabled</code> event is dispatched to the value's bound controls; if a bound value has become relevant, the <code>xforms-enabled</code> event is dispatched.
* If a bound value has changed since the last refresh, then the <code>xforms-value-changed</code> event is dispatched to the value's enabled bound controls.
* If any other model item properties of a bound value have changed since the last refresh, the appropriate notification events (<code>xforms-optional</code>/<code>xforms-required</code>, <code>xforms-readwrite</code>/<code>xforms-readonly</code>, <code>xforms-valid</code>/<code>xforms-invalid</code>) are dispatched to the value's enabled bound controls.
* The events <code>xforms-out-of-range</code> and <code>xforms-in-range</code> must also be dispatched as appropriate to enabled controls.

Finally an <code>[[#evt-refresh-done|xforms-refresh-done]]</code> event is dispatched to the default model.

==<span id="expr-eval">Expressions</span>==

Expressions appear in attributes throughout XForms. They can be split into two kinds: 
* bindings, that identify locations whose content may or may not be changed by the attached element; and 
* value expressions, that supply values for use by the attached element.

They can further be classified according to when they are evaluated:
* on bind elements (where bindings are called ''model item bindings'', and other expressions are called ''computed expressions''): evaluated during [[#model-initialization|model initialization]] and [[#model-recalculate|recalculate]]; 
* on controls and their contained elements excluding Actions (where bindings are called UI bindings, and all expressions including bindings are called <span id="UI_Expressions">UI expressions</span>): evaluated during [[#model-ui-initialize|user interface initialization]] and [[#model-refresh|refresh]];
* on Actions and [[#submit-submission-element|the <code>submission</code> element]]: evaluated on activation by an event;
* in Attribute Value Templates (AVTs): evaluated whenever the containing element is processed.

At the time of evaluation, an expression must be syntactically correct, the namespaces it uses must be in scope, and the functions and variables it uses must be defined; otherwise one of the following events is dispatched:
* for a bind element, [[#evt-bindingError|xforms-binding-error]],
* for an action, [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>expression-error</code>,
* for other elements, [[#evt-expressionError|xforms-expression-error]]. 

If the evaluation of an expression fails, for whatever reason, including type errors:
* for a calculate expression, the result is the empty sequence;
* for other bind computed expressions (which are all boolean valued), the result is the opposite of the default for that property;
* for all other expressions, an [[#evt-expressionError|xforms-expression-error]] is dispatched to the element containing the expression.

<div class="Note">Note: To allow for forward compatibility, this specification is written to permit the use of different expression languages. However only one is used in XForms 2.0, XPath 2.0 as defined in [[XPath_Expressions_Module|XForms 2.0: XPath Expressions Module]].
</div>

<div class="div2">

===<span id="expr-typed-values">Typed Values</span>===

Types in XForms are principally used to check the validity of strings  
provided as values to nodes; however, the types can also be used when  
evaluating expressions using nodes.

The XForms processor should therefore  
provide the typed values of nodes to the expression evaluator, and not  
just the strings. This includes expressions evaluated during a [[#model-recalculate|recalculate]], even though a [[#model-revalidate|revalidate]] has not yet occurred.

When the result of evaluating an expression is described as being converted to some type, this is done as described in the [[#def-expression-module|expression module]].

<div class="example" title="typed values">
This example illustrates the difference between evaluating with and without types. If the typed values are passed, then the two times <code>00:00:00</code> and <code>24:00:00</code> are recognized as being equal. However, if the two values are just passed as strings, they are not found to be equal.

 <nowiki><model>
    <instance>
       <data xmlns="">
          <t>00:00:00</t>
          <t>24:00:00</t>
       </data>
    </instance>
    <bind ref="t" type="time"/>
 </model>
 
 <output value="choose(t[1] = t[2], 'typed', 'untyped')"/></nowiki>
</div>
</div>

===Evaluation Context===

All expressions are evaluated in an '''evaluation context''', which consists of a ''context item'', a ''size'', and a ''position''. In general, the context item is some element of a sequence, the size is the size of that sequence, and the position is the position of the context item within the sequence.

====<span id="initial-evaluation-context">Initial evaluation context</span>====

An element inherits an initial evaluation context from its ancestor elements; if the element has a <code>model</code> attribute, and the inherited context item is not from that model, then the initial evaluation context is the default context from the referenced model.

For elements with no ancestor, the initial evaluation context is the default context item of the element's default model, with a size and position of one:
* the default model for an element is its containing model, if any, and otherwise the textually first model in the document;
* the default context item of a model is the top-level document element node of the textually first instance of the model.

====<span id="in-scope-evaluation-context">In-scope evaluation context</span>====

If the element has a <code>context</code> attribute, that attribute is evaluated in the initial evaluation context, giving the in-scope evaluation context; otherwise the initial evaluation context is used for the in-scope evaluation context.

====<span id="element-evaluation-context">Element evaluation context</span>====

Unless otherwise stated, all expressions (including those in AVTs) in an element are evaluated in the element evaluation context:

* if the element has no binding, the in-scope evaluation context is used for the element evaluation context;
* if the element has a <code>ref</code> attribute, the attribute is evaluated in the in-scope context to give the element evaluation context;
* if it has a <code>bind</code> attribute, the element evaluation context of the referenced bind element is used.

If a binding is declared as a '''Single Item Binding''', the size of the context and its position are both set to 1; otherwise it is a '''Sequence Binding''', and uses the evaluated size and position.

For sequence bindings, an occurrence of the original binding element is also generated for each of the items in the sequence, with a dynamic evaluation context that has a context item of the item of the sequence for which the occurrence was generated, a size of the size of the sequence, and a position of the position of the generated item in the sequence.

The element evaluation context is then inherited by any contained elements as their initial evaluation context.

<div class="note">
'''Note''': the <code>context()</code> function returns the context item of an element's in-scope evaluation context, while the <code>position()</code> and <code>last()</code> functions return the context position and size respectively of the element evaluation context, and the dot selector <code>"."</code> returns its context item.

So the following would output <code>2 1 2 3</code>:
 <instance><nowiki>
    <data xmlns="">
       <a><b>1</b</a>
       <b>2</b>
       <b>3</b>
    </data></nowiki>
 </instance>
  ...
 <output         value="b"/> ⇒ 2
 <output ref="a" value="b"/> ⇒ 1
 <output ref="a" value="context()/b"/> ⇒ 2
 <output         value="b[last()]"/> ⇒ 3
</div>

<div class="example" title="evaluation context">
 <model id="m"><nowiki>
    <instance>
       <data xmlns="">
          <a>1</a>
       </data>
    </instance>
 </model>
 <model id="n">
    <instance>
       <data xmlns="">
          <a>2</a>
          <a>3</a>
          <b>4</b>
       </data>
    </instance>
 </model>
 <model id="p">
    <instance>
       <data xmlns="">
          <a><b>5</b></a>
          <b>6</b>
       </data>
    </instance></nowiki>
 </model>

 <output ref="a"/> ⇒ 1
 <output model="n" ref="a"/> ⇒ 2
 <output model="p" ref="a" value="b"/> ⇒ 5
 <output model="p"         value="b"/> ⇒ 6
 <group model="p" ref="a">
    <output ref="b"/> ⇒ 5
 </group>
 <group model="p" ref="a">
    <output context=".." ref="b"/> ⇒ 6
 </group>
 <group model="p">
    <output ref="b"/> ⇒ 6
 </group>
 <group model="p">
    <output model="n" ref="b"/> ⇒ 4
 </group>

</div></div>

<div class="div2">

=== Functions ===

The extra functions available in expressions above those available from XPath are described in the [[XPath Expressions Module]]. The list here gives an overview.

==== Math functions ====

double [[XPath Expressions Module#fn-avg | avg]](node()*)<br/>
The arithmetic average of the nodes.

double [[XPath Expressions Module#fn-min | min]](node()*)<br/>
Minimum (numeric) value.

double [[XPath Expressions Module#fn-max | max]](node()*)<br/>
Maximum (numeric) value.

double [[XPath Expressions Module#fn-power | power]]($base as double, $exponent as double)<br/>
The first argument raised to the power of the second.

double [[XPath Expressions Module#fn-random | random]](boolean?)<br/>
A uniformly distributed pseudorandom number ≥ 0.0 and < 1.0.

==== String functions ====

integer [[XPath Expressions Module#fn-compare | compare]](string, string)<br/>
Lexicographic comparison of the two Unicode strings, returning -1 (less than), 0 (equal) or +1 (greater than).

==== Card Number functions ====

boolean [[XPath Expressions Module#fn-is-card-number | is-card-number]](string?)<br/>
Whether the string (or context item if absent) is a valid (credit-card) number.

==== Date and time functions ====

date [[XPath Expressions Module#fn-local-date | local-date]]()<br/>
The current date in the user agent time zone.

dateTime [[XPath Expressions Module#fn-local-dateTime | local-dateTime]]()<br/>
The current date and time in the user agent time zone.

string [[XPath Expressions Module#fn-now | now]]()<br/>
The current date and time in UTC.

numeric [[XPath Expressions Module#fn-days-from-date | days-from-date]](string)<br/>
Number of days since 1970 of the given date.

string [[XPath Expressions Module#fn-days-to-date | days-to-date]](double)<br/>
The date of those number of days since 1970.

double [[XPath Expressions Module#fn-seconds-from-epoch | seconds-from-epoch]](string)<br/>
double [[XPath Expressions Module#fn-seconds-from-dateTime | seconds-from-dateTime]](string)<br/>
The number of seconds since 1970 of the given date and time. The seconds-from-dateTime function is only for backwards compatibility: use seconds-from-epoch for preference.

string [[XPath Expressions Module#fn-seconds-to-dateTime | seconds-to-dateTime]](double)<br/>
The date and time of that many seconds since 1970.

string [[XPath Expressions Module#fn-adjust-dateTime-to-timezone | adjust-dateTime-to-timezone]](string)<br/>
Takes a date and time (possibly in a different timezone) and returns it adjusted to the local timezone.

numeric [[XPath Expressions Module#fn-seconds | seconds]](string)<br/>
Returns a duration of days, hours, minutes and seconds as the number of seconds.

numeric [[XPath Expressions Module#fn-months | months]](string)<br/>
Returns a duration of years and months as the number of months.

==== URI functions ====

anyURI [[XPath Expressions Module#fn-location-uri | location-uri]]()<br/>
The URI from which the current document has been loaded.

string* [[XPath Expressions Module#fn-location-param | location-param]](string)<br/>
The current location URL's parameter values for the given name.

string? [[XPath Expressions Module#fn-uri-scheme | uri-scheme]](string)<br/>
string? [[XPath Expressions Module#fn-uri-scheme-specific-part | uri-scheme-specific-part]](string, boolean)<br/>
string? [[XPath Expressions Module#fn-uri-authority | uri-authority]](string, boolean)<br/>
string? [[XPath Expressions Module#fn-uri-user-info | uri-user-info]](string, boolean)<br/>
string? [[XPath Expressions Module#fn-uri-host | uri-host]](string)<br/>
integer? [[XPath Expressions Module#fn-uri-port | uri-port]](string)<br/>
string? [[XPath Expressions Module#fn-uri-path | uri-path]](string, boolean)<br/>
string? [[XPath Expressions Module#fn-uri-query | uri-query]](string, boolean)<br/>
string? [[XPath Expressions Module#fn-uri-fragment | uri-fragment]](string, boolean)<br/>
Returns the respective sub-part of the given URI.

string* [[XPath Expressions Module#fn-uri-param-names | uri-param-names]](string)<br/>
The names of the parameters used in the given URI.

string* [[XPath Expressions Module#fn-uri-param-values | uri-param-values]](string, string)<br/>
The value(s) in the given URI of the given parameter name.

==== Utility functions ====

item() [[XPath Expressions Module#fn-current | current]]()<br/>
The current context item.

item() [[XPath Expressions Module#fn-context | context]](string?)<br/>
The current in-scope evaluation context item.

boolean [[XPath Expressions Module#fn-boolean-from-string | boolean-from-string]](string)<br/>
"true" and "1" return <code>true</code>, all other strings return <code>false</code>.

integer [[XPath Expressions Module#fn-count-non-empty | count-non-empty]](node()*)<br/>
The number of non-empty nodes.

item()* [[XPath Expressions Module#fn-eval | eval]](string)<br/>
Evaluates the string as an expression in the current context.

item()* [[XPath Expressions Module#fn-eval-in-context | eval-in-context]](string, node()*)<br/>
Evaluates the string as an expression in the given context.

item()* [[XPath Expressions Module#fn-choose | choose]](boolean, item()*, item()*)<br/>
If the first parameter is <code>true</code>, returns the second parameter, and otherwise the third. [Deprecated]

==== Cryptographic functions ====

string [[XPath Expressions Module#fn-digest | digest]]($data as string, $algo as string, $encoding as string?)<br/>
The hash value of the data string.

string [[XPath Expressions Module#fn-hmac | hmac]]($secret as string, $data as string, $algo as string, $encoding as string?)<br/>
A cryptographic encoding of the data string.

==== Model functions ====

element()? [[XPath Expressions Module#fn-instance | instance]](string?)<br/>
The identified instance data.

node()* [[XPath Expressions Module#fn-bind | bind]](string)<br/>
The nodes associated with the identified <code>bind</code> element.

boolean [[XPath Expressions Module#fn-valid | valid]](item*?) <br/>
boolean [[XPath Expressions Module#fn-valid | valid]](item*, boolean, boolean?)<br/>
Whether the selected items are ''valid''. By default recurses through the elements, and non-relevant items are ignored. The booleans control this default.

boolean [[XPath Expressions Module#fn-relevant | relevant]](item*?)<br/>
boolean [[XPath Expressions Module#fn-readonly | readonly]](item*?)<br/>
boolean [[XPath Expressions Module#fn-required | required]](item*?)<br/>
Whether the selected items are, respectively, ''relevant'', ''read-only'', or ''required''.

==== Controls functions ====

numeric [[XPath Expressions Module#fn-index | index]](string)<br/>
The value of the repeat index for the identified repeat.

string? [[XPath Expressions Module#fn-case | case]](string)<br/>
Returns the ID of the selected case for the identified switch.

==== Event functions ====

item()* [[XPath Expressions Module#fn-event | event]](string)<br/>
Returns the specified context information of the current event.

string? [[XPath Expressions Module#fn-property | property]](string)<br/>
Returns details of the implementation.

==== XML manipulation functions ====

element() [[XPath Expressions Module#fn-element | element]]($qname as anyAtomicType, $content as item()*)<br/>
Constructs an element from string values.

attribute() [[XPath Expressions Module#fn-attribute | attribute]]($qname as anyAtomicType, $value as anyAtomicType?)<br/>
Constructs an attribute.

element()? [[XPath Expressions Module#fn-parse | parse]](string, string?)<br/>
Parses a string, and returns the resulting node.

string [[XPath Expressions Module#fn-serialize | serialize]](item*, $params?)<br/>
String serialization of the items. [NOTE: same as XPath 3.0]

element()* [[XPath Expressions Module#fn-id | id]](string*, node()*?)<br/>
element()* [[XPath Expressions Module#fn-id | id]](node()*, node()*?)<br/>
The elements in the given data identified by the given IDs. [Deprecated]

=== Extension Functions===

XForms documents may use additional functions beyond those defined in the document and by the expression language. A number of useful community extensions are defined at [[#ref-exslt| [EXSLT]]]. 

The names of any extension functions used in a document should be declared in the <code>functions</code> attribute on the <code>model</code> element. When the document is loaded the processor must check that those functions are available. If any are not, an [[#evt-computeError|xforms-compute-error]] must be dispatched to the <code>model</code> element. If that event is not canceled, processing halts (this is the default action for [[#evt-computeError|xforms-compute-error]]). If the event is canceled, processing continues. 

If an expression uses an extension function for which the processor does not have an implementation, on evaluation an appropriate event ([[#evt-expressionError|xforms-expression-error]], [[#evt-bindingError|xforms-binding-error]], or [[#evt-actionError|xforms-action-error]]) must be dispatched to the containing element.

<div class="example" title="extension function">
 <model functions="math:sin">
    <instance>
       &lt;data xmlns="">
          <length/>
          <angle/>
          <height/>
       &lt;/data>
    </instance>
    <bind ref="length | angle | height" type="double"/>
    <bind ref="height" calculate="../length * math:sin(../angle)"/>
 </model>
</div>

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

=== <span id="structure-var-element">The var element</span> ===
The <code>var</code> element declares a local variable. A variable is a mapping between a name and a value. The value of a variable is any sequence of nodes and/or atomic values, as defined in the XPath Data Model <nowiki>[</nowiki>[[#ref-xpath-data-model|XDM]]].
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Special Attributes:

; name
: Required attribute containing the name of the variable. The value of the <code>name</code> attribute is a QName. The scope of the variable is defined in the Variable Scope section below.

Content: PCDATA
</div>
A value is obtained by evaluating the <code>value</code> attribute if present, and otherwise from the inline text. The result is made available as a variable to expressions for which the variable is in scope.

A variable can occur either as a child of an <code>action</code> element or anywhere a control can appear.

{{SpecNote|Variables under the <code>model</code> element are not supported except within nested <code>action</code> elements. Behavior for such variables may be specified in the future based on implementation experience.}}

===== Variable Evaluation =====

If a variable is a child of an <code>action</code> element, its value is updated after the previous child action or variable has been invoked or evaluated, and before the following child action or variable is invoked or evaluated. Such a variable is evaluated exactly once for each execution of the content of the <code>action</code> element.

{{SpecNote|This means that if the action is repeated with the <code>iterate</code> or <code>while</code> attribute, the variable is re-evaluated as well during each execution.}}

Variables outside of actions behave as if they are updated by [[#model-refresh|refresh]] in the order they are defined.

{{SpecNote|A variable holds '''references''' to all the nodes the <code>value</code> expression returns (if any). Deleting nodes from an instance with a <code>delete</code> action does '''not''' remove those nodes from the value of the variable until the variable is re-evaluated. Similarly, changes to predicates of the <code>value</code> expression by actions don't update the value of the variable.}}

===== Variable Scope =====
For any variable, there is a region (more specifically, a set of element nodes) of the form within which the variable is visible. The set of variables in scope for an expression consists of those variables that are visible at the point in the form where the expression occurs.

Variable scoping is '''lexical''': a variable defined by a <code>var</code> element is visible for all following sibling nodes and their descendants. The variable is not visible for the <code>var</code> element itself.

Variable shadowing is not allowed: if a variable is declared with a name that is already in scope at the point of the new variable declaration, an [[#evt-bindingError|xforms-binding-error]] is dispatched to the <code>var</code> element.

{{SpecNote|This is unlike XSLT, which discourages but allows shadowing.}}

<div class="example" title="Variable declared and used within an action">
 <trigger label="Show">
   <action ev:event="DOMActivate">
     <var name="message" value="instance('message')"/>
     <message ref="$message"/>
   </action>
 </trigger>
</div>
<div class="example" title="Variable declared outside an action and used within the action">
 <var name="message" value="instance('message')"/>
 <trigger label="Show">
   <message ev:event="DOMActivate" ref="$message"/>
 </trigger>
</div>
<div class="example" title="Variable declared within an action with the iterate attribute">
 <action iterate="items/item">
   <var name="current-item" value="."/>
   <insert context="$current-item" origin="xforms:element('label'), xforms:element('value')"/>
 </action>
</div>
<div class="example" title="Variable used by a control binding">
 <var name="binding" value="quantity"/>
 <input ref="$binding" label="Quantity"/>
</div>
<div class="example" title="Variable used by a control label or itemset">
 <var name="items" value="items/item"/>
 <select ref="my-item" label="Item">
   <itemset ref="$items" label="{name}" value="value"/>
 </select>
</div>
<div class="example" title="Inline value">
 <nowiki><var name="message">Your document has been saved.</var></nowiki>
</div>
<div class="example" title="Use of context/model attribute">
 <var
   name="first-name"
   model="my-model"
   context="instance('member')"
   value="first-name"/>
</div>
<div class="example" title="Lexical scoping">
 <var name="paging" value="instance('paging')"/>
 <group>
   <var name="total"      value="$paging/@total"/>
   <var name="page-size"  value="$paging/@page-size"/>
   <var name="page-count" value="($total + $page-size - 1) idiv $page-size"/>
   <output value="$page-count" label="Number of pages"/>
 </group>
</div>

</div>

<div class="div3">

=== The function Element ===

Defines a function that can be called from any expression within the document that is associated with the model in which the function is defined.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]

Special Attributes:

; signature [not AVT]
: The signature (name, parameters and return type) of the function.

;override
: Optional string specifying if this function overrides previously declared functions. Allowable values are <code>true</code> and <code>false</code>, with a default of <code>true</code>.

;type
: Optional MIME type specifying the implementation language of the function. The default is the default expression language of the form. Other supported languages are implementation-dependent. The function definition is ignored if the language is not supported or if the function element contains mixed content.

Content: ([[#structure-var-element|var]]*, [[#The_result_element|result]])?
</div>
A <code>function</code> element can only appear as a top-level element in a model.
<div class="note">
'''Note:'''
The Working Group is considering allowing the definition of custom functions outside of the model in a future version of the specification, but is waiting for implementation experience first.
</div>

A custom function is included in the in-scope functions of the static context for all expressions associated with the model that contains the function definition, unless
* the <code>override</code> attribute has the value "no" and there is already a function with the same name and arity in the in-scope functions.
* the custom function tries to override a built-in function.

The value of the <code>signature</code> attribute defines the name, parameters and return type of the function. See [[#Function signature syntax|Function signature syntax]] for more information about the function signature.

The function that is executed as the result of a function call is identified by searching the in-scope functions of the static context for a function whose name and arity match those of the function call.

<div class="note">
'''Note:'''
Functions are not polymorphic. Although the function call mechanism allows two functions to have the same name and different arity, it does not allow them to be distinguished by the types of their arguments.
</div>

The result of a function is a sequence of atomic values and/or nodes. If the result type of the function is specified with the <code>as</code> attribute, the result value of the function as specified by the function body is converted to the required type (specified using a SequenceType, as defined in [[#ref-xpath-2.0|XPath 2.0]]), using the function conversion rules. It is a type error if this conversion fails. If the <code>as</code> attribute is omitted, the calculated result is used as supplied, and no conversion takes place.

<div class="example" title="sum of products">
 <function signature="my:sumproduct($p as xs:decimal*, $q as xs:decimal*) as xs:decimal">
   sum(for $i in 1 to count($p) return $p[$i]*$q[$i])
 </function>
</div>

<div class="example" title="Fibonacci">
 <function signature="my:fibonacci($n as xs:integer) as xs:integer">
   <var name="sqrt5" value="math:sqrt(5)"
   <result value="(math:power(1+$sqrt5, $n) - math:power(1-$sqrt5, $n)) div (math:power(2, $n) * $sqrt5)"/>
 </function>
</div>

<div class="example" title="JavaScript, with fallback">
 <function signature="my:summation($p as xs:decimal*) as xs:decimal" override="no" type="text/javascript">
   ...
 </function>

 <function signature="my:summation($p as xs:decimal*) as xs:decimal" override="no">
   sum($p)
 </function>

The second definition of the my:summation function doesn't override the first definition because the <code>override</code> attribute is set to <code>no</code> (even though the expanded QName and the arity of the functions are the same).
</div>

==== Function signature syntax ====
The <code>signature</code> attribute  of the <code>function</code> element has the following syntax:

{| border="0" cellpadding="2" cellspacing="0"
| CustomFunctionSignature
| ::=
| <code>FunctionName "(" ParamList? ")" ("as" SequenceType)?</code>
|-
| FunctionName
| ::=
| [[#def-PrefixedName|<code>PrefixedName</code>]]
|-
| ParamList
| ::=
| <code>Param ("," Param)*</code>
|-
| Param
| ::=
| <code>"$" QName TypeDeclaration?</code>
|-
| TypeDeclaration
| ::=
| <code>"as" SequenceType</code>
|}

The function name is a QName but not an NCName. This means that a form author cannot add functions to the default function namespace.

The parameter list defines the formal arguments to the function. When the function is called using a function call in an expression, the first argument supplied is assigned to the first parameter, the second argument supplied is assigned to the second parameter, and so on.

The type declaration defines the required type of the parameter. The rules for converting the values of the actual arguments supplied in the function call to the types required by each parameter are defined in [XPath 2.0]. The rules that apply are those for the case where XPath 1.0 compatibility mode is set to false.

If the value of a parameter to a custom function cannot be converted to the required type, a type error is signaled.

If the type declaration is omitted, no conversion takes place and any value is accepted.

[ERR] It is a static error if two parameters of a custom function have the same name.

{{SpecNote|Optional parameters are not allowed.}}

<div class="example" title="function with name my:foo that has no arguments and returns an xs:integer">
 my:foo() as xs:integer
</div>
<div class="example" title="function with name my:sumproduct that takes two sequences of xs:decimal and returns an xs:decimal">
 my:sumproduct($p as xs:decimal*, $q as xs:decimal*) as xs:decimal
</div>

==== Function body ====

The function body contains the implementation of the function as text content, following the syntax of the function's implementation language.

Alternatively, when the function's implementation language is the same as the expression language of the form, the function body can be specified with an optional sequence of <code>var</code> elements followed by a single <code>result</code> element specifying the function's result.

'''Note:''' This in particular allows writing more readable custom functions with XPath 1.0 and XPath 2.0, which do not natively support variables.

The implementation of the function should be stable (calling the same function twice within an execution scope with the same arguments returns the same result) and should not change any instance data, nor should it change the internal state of the form (e.g.: should not change the repeat index) or processor.

====  Function body evaluation context ====

Within the body of a custom function, the evaluation focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a non-recoverable dynamic error ([err:XPDY0002] as defined in [[#ref-xpath-2.0|XPath 2.0]])

The variables in scope for the function body include all variables representing the function parameters, as well as all variables that are in scope where the custom function is defined.

'''Note:''' Function parameter names can shadow variables that would otherwise be in scope for the function body.

Expressions within the function body may refer to instance data by using the instance() function.

Any static or dynamic error occurring while evaluating the value of a <code>var</code> element within the <code>body</code> element propagates to the expression calling the function.

==== The result element ====
The optional <code>result</code> element is used inside a <code>function</code> element to produce the result of the function.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
If any <code>var</code> element is present under the <code>function</code> element, this element is required. Otherwise, it is optional.

A value is obtained by evaluating the value attribute if present, and otherwise from the inline text; this is used as the result of the function.

Any static or dynamic error occurring while evaluating the <code>value</code> attribute propagates to the expression calling the function.

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

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

This section defines the standard datatypes available. They are in-scope without the inclusion of an XML Schema.

<div class="div2">

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

All XML Schema 1.0 [[#def-datatype|datatype]]s are supported except for <code>xs:ENTITY</code>, <code>xs:ENTITIES</code>, and <code>xs:NOTATION</code>. The concepts of [[#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>. 

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

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

The following types are defined in the XForms namespace. They can be used without a namespace prefix when the XForms namespace is the default.

====Built-in primitive and derived types====

For ease of authoring, the following XForms types are defined as having a lexical space identical to the corresponding XML Schema datatype.

Built-in primitive types:

<blockquote>

string, boolean, decimal, double, float, date, time, dateTime, duration, dayTimeDuration, yearMonthDuration, QName, anyURI, gDay, gMonthDay, gMonth, gYearMonth, gYear, base64Binary, hexBinary

</blockquote>

Built-in derived types:

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

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

'''Note:'''

Type <code>duration</code> does not support a total ordering. Using <code>dayTimeDuration</code> or <code>yearMonthDuration</code> is preferable.
</div>

====Absolute IRI type====

This type represents an absolute IRI, a subset of IRI as defined in <nowiki>[</nowiki>[[#ref-rfc-3987|RFC 3987]]<nowiki>]</nowiki>

The type is defined as the following lexical space (the pattern has been split over lines for slightly improved readability, but should be a single line):

 <xs:simpleType name="absoluteIRI">
   <xs:restriction base="xs:string">
     <pattern value="[a-zA-Z][a-zA-Z0-9\+\.\-]*://
                     ((%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:_~\-])*@)?
                     ([a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;]([a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;-]*[a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;])*
                   (\.[a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;]([a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;-]*[a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;])*)*
                     |(\[([0-9a-fA-F]{0,4}:){0,6}(([0-9a-fA-F]{0,4}:[0-9a-fA-F]{0,4})|([0-9]{1,3}\.){3}[0-9]{1,3})\]))
                     (:[0-9]*)?
                     (/(%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:@_~\-])*)*
                    (\?(%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:@_~\-/\?])*)?
                     (#(%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:@_~\-/\?])*)?"/>
    </xs:restriction>
 </xs:simpleType>

<div class="note">
To help understand the above rather complex pattern, here is a more informal description:

 absoluteIRI: scheme :// user? host port? path? query? fragment?

 scheme: letter letgit*
 letter: [a-zA-Z]
 letgit: [a-zA-Z0-9+.-]
                          Example: http

 user:   uch* @
 uch:    enc | iletter | punct
                          Example: user05:pw12345@

 host:   domain (.domain)* | ipv6
 domain: iletter (iletterm* iletter)*
 iletterm: iletter | "-"
                          Example: www.w3.org

 IPv6:   [ (h4:){0,6} ((h4:h4)|ipv4) ]
 h4:     h{0,4}
 h:      [0-9a-fA-F]
                          Example: [2001:db8:1::8a2e:370:7334]

 ipv4:   d3.d3.d3.d3
 d3:     [0-9]{1,3}
                          Example: 192.168.0.1

 port:   : digit*
 digit:  [0-9]
                          Example: :80

 path:   segment+
 segment: / pch*
 pch:    enc | iletter | punct | @
                          Example: /2002/xforms/index.xhtml

 query:  ? qfch*
 qfch:   enc | iletter | punct | [/?@]
                          Example: ?q=test

 fragment: # qfch*
                          Example: #toc

 iletter: [a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;]
 enc:    %[0-9A-F][0-9A-F]
 punct:  [.!$&amp;'()*+,;=:_~-]
</div>

<div class="example" title="absoluteIRI">
 <nowiki>http://www.w3.org/</nowiki>
 <nowiki>http://www.w3.org/2002/xforms</nowiki>
 <nowiki>https://école.fr.example.org/élève.xhtml</nowiki>
 <nowiki>irc://irc.w3.org:6665/#forms</nowiki>
 <nowiki>http://search.example.org?q=☺</nowiki>
 <nowiki>https://zh.wikipedia.org/wiki/Wikipedia:关于中文维基百科/en</nowiki>
 <nowiki>https://www.石川.日本/雅康#mimasa</nowiki>
 <nowiki>ssh://user@host.example.com:2222</nowiki>
 <nowiki>ftp://anonymous@example.net:4916/;type=d</nowiki>
</div>

====HTTP IRI type====
This type represents an internationalised absolute <code>http:</code> or <code>https:</code> web address, a further subset of <code>absoluteIRI</code>.

The type is defined as the following lexical space (the pattern has been split over lines for readability, but should be a single line), which is the same as that defined for <code>absoluteIRI</code>, with the scheme restricted to <code>http</code> and <code>https</code>.

 <xs:simpleType name="httpIRI">
   <xs:restriction base="xs:string">
     <pattern value="(http|https)://
                     ((%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:_~\-])*@)?
                     ([a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;]([a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;-]*[a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;])*
                   (\.[a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;]([a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;-]*[a-zA-Z0-9&amp;#xA1;-&amp;#x2FA1F;])*)*
                     |(\[([0-9a-fA-F]{0,4}:){0,6}(([0-9a-fA-F]{0,4}:[0-9a-fA-F]{0,4})|([0-9]{1,3}\.){3}[0-9]{1,3})\]))
                     (:[0-9]*)?
                     (/(%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:@_~\-])*)*
                    (\?(%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:@_~\-/\?])*)?
                     (#(%[0-9A-F][0-9A-F]|[a-zA-Z0-9&amp;#xA0;-&amp;#xEFFFD;\.!$&amp;amp;'()\*\+,;=:@_~\-/\?])*)?"/>
   </xs:restriction>
 </xs:simpleType>

<div class="example" title="httpIRI">
 <nowiki>http://www.w3.org/</nowiki>
 <nowiki>http://www.w3.org/2002/xforms</nowiki>
 <nowiki>https://www.石川.日本/雅康#mimasa</nowiki>
</div>


<div class="div3">

====<span id="dt-email">Legacy email type</span>====

This type represents an email address, as defined by the production <code>Mailbox</code> in <nowiki>[</nowiki>[[#ref-rfc-5321|RFC 5321]]<nowiki>]</nowiki>. Two uncommon features of the syntax are excluded, namely address literals, such as <code>person@[198.162.0.1]</code>, and quoted-strings, such as <code>"unusual.@.unusual"@example.com</code>. Additionally, the domain part must contain at least one dot, as recommended by ICANN <nowiki>[</nowiki>[[#ref-icann|ICANN]]<nowiki>]</nowiki>.

The type is defined as the following lexical space (the pattern has been split over lines for readability, but should be a single line):

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

<div class="note">
To help understand the above pattern, it can be split up as follows:
 email:   atoms@host
 atoms:   atom(.atom)*
 atom:    char+
 char:    [A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]
 
 host:    domain(.domain)+
 domain:  letgit(letgitm*letgit)?
 letgit:  [A-Za-z0-9]
 letgitm: [A-Za-z0-9-]
</div>

<div class="example" title="email addresses">
 editors@example.com
 ~my_mail+{nospam}$?@sub-domain.example.info
</div>

<div class="note">

'''Note:'''

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

</div>

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

====<span id="dt-iemail">International email type</span>====
This type represents an 'international' email address, as defined in <nowiki>[</nowiki>[[#ref-rfc-6531|RFC 6531]]<nowiki>]</nowiki>. This is in essence the same syntax as above, but with more characters permitted where letters are permitted. 

The type is defined as the following lexical space (the pattern has been split over lines for readability, but should be a single line):

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

<div class="example" title="international email addresses">
 editors@example.com
 ~my_mail+{nospam}$?@sub-domain.example.info
 élève@école.fr
 δοκιμή@παράδειγμα.δοκιμή
 我買@屋企.香港
 甲斐@黒川.日本
 чебурашка@ящик-с-апельсинами.рф
 संपर्क@डाटामेल.भारत
</div>

</div><div class="div3">
====<span id="dt-telephone">Telephone number type</span>====
This type represents a telephone number, based on <nowiki>[</nowiki>[[#ref-ITU|ITU E.123]]<nowiki>]</nowiki>, but adapted according to observed usage. The type allows an optional leading international code (such as <code>+33</code>), an optional bracketed area code (such as <code>(020)</code>), and a string of digits. Digits may be separated by spaces and hyphens.

The type is defined as the following lexical space (the pattern has been split over lines for readability, but should be a single line):

 <simpleType name="telephone">
    <restriction base="xsd:string">
       <pattern value="^(\(\ *\+?\ *([0-9]\ *(\-\ *[0-9]\ *)*)+\)\ *
                                    ([0-9]\ *(\-\ *[0-9]\ *)*)+)
                            |(\+?\ *([0-9]\ *(\-\ *[0-9]\ *)*)+
                              (\(\ *([0-9]\ *(\-\ *[0-9]\ *)*)+\)\ *
                                    ([0-9]\ *(\-\ *[0-9]\ *)*)+)?)[0-9]$"/>
    </restriction>
 </simpleType>

<div class="example" title="telephone numbers">
 06123456
 (020)6123456
 +31206123456
 +31 20 6123456
 +31-20-6123456
 +1(234)1234567
 +1 (234) 1234567
 +1 (234) 123-4567
 +1 (234) 123 - 4567
</div>

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

====<span id="dt-card-number">card-number type</span>====

This type represents identity, debit and credit card numbers; it is a pattern restriction on <code>xs:string</code><nowiki> to one or more digits (0 - 9).</nowiki>

 <xs:simpleType name="card-number">
   <xs:restriction base="xs:string">
     <xs:pattern value="[0-9]+"/>
   </xs:restriction>
 </xs:simpleType>

<div class="example" title="Credit Card">
To properly check a credit card number, you must not only check that it is a string of digits, but also that it is a valid card number.
The function <code>is-card-number()</code> does this, as in this example:

 <nowiki><model xmlns="http://www.w3.org/2002/xforms">
   <instance>
     <payment xmlns="">
       <amount/>
       <number/>
       <expiry/>
     </payment>
   </instance>
   <bind ref="number" type="card-number" 
         constraint="is-card-number(.)" whitespace="remove"/>
 </model></nowiki>
</div>
</div></div><div class="div3">

====<span id="dt-htmlfragment">HTMLFragment type</span>====

This type is for a value intended to be interpreted as a serialized HTML fragment. The lexical space is a <code>string</code> with no extra restrictions:

 <xs:simpleType name="HTMLFragment">
   <xs:restriction base="xs:string"/>
 </xs:simpleType>

{{SpecNote|<code>HTMLFragment</code> is a tagging datatype that can be used by the UI to provide a convenient means for entry and displaying of HTML fragments ('rich text content').}}

<div class="example" title="HTMLFragment">
 This is &lt;b&gt;rich&lt;/b&gt; text content.
</div>
</div>
<div class="div3">

====<span id="dt-listItem">listItem type</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 xs:string, except white space characters.

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

====<span id="dt-listItems">listItems type</span>====

Controls that produce simpleType list content use a <code>derived-by-list</code> datatype. The lexical space for listItems is defined by list-derivation from [[#dt-listItem| listItem]], that is to say, it consists of zero or more values of type listItem, separated by whitespace.

<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="div2">

===<span id="model-using">Applying Datatypes</span>===

Datatypes can be applied to instance data nodes in three ways:

# Through applicable XML Schema definitions (via external or an inline XML Schemas);
# By <code>xsi:type</code> attributes directly applied to instance values;
# Through a <code>type</code> model item property applied by a [[#The_bind_Element|<code>bind</code>]] element.

When multiple datatype restrictions apply to a node, the combination of all given restrictions apply. (Note that it is possible to produce a combination of restrictions that is impossible to satisfy.)

If no type constraint is provided, an instance data node defaults to type <code>xs:string</code>.

If a type name is used that does not identify an in-scope type, an [[#evt-bindingError|xforms-binding-error]] is dispatched to the relevant <code>bind</code> or <code>instance</code> element.

<div class="note">
'''Note:'''
Attributes <code>xsi:schemaLocation</code> and <code>xsi:noNamespaceSchemaLocation</code> are ignored for purposes for locating an XML Schema.
</div>

<div class="example" title="Type Constraint Using a Schema">
This declares a datatype based on <code>xs:string</code> with an additional constraining facet:
 <xs:simpleType name="password">
   <xs:restriction base="xs:string">
     <xs:minLength value="8"/>
   </xs:restriction>
 </xs:simpleType>

This datatype can then be associated with model items using <code>xsi:type</code>:

 <instance>
   <password xmlns="" xsi:type="my:password"/>
 </instance>

or <code>bind</code>:

 <instance>
   <password xmlns=""/>
 </instance>
 <bind ref="/password" type="my:password"/>
</div>
</div>

<div class="div1">

==<span id="controls">Controls</span>==

Controls allow interaction with instance data:

* They encapsulate high-level semantics by expressing the intent of the control without prescribing presentation. 
* They are declared using elements and their attributes. 
* They are bound to data using [[#structure-attrs-nodeset|binding attributes]].
* Thanks to the high-level semantics, controls are suitable for styling as aural or visual media.
* Accessibility is further aided by taking a uniform approach to features such as labels, help text, navigation, and keyboard shortcuts. 
* Internationalization issues are addressed by following the same design principles as in XHTML.

A '''[[#core-controls|core control]]''' is an element that acts as a direct point of user interaction for read, write, or read/write access to instance data. 

A '''[[#Container Controls|container control]]''' combines other controls into full user interfaces.

Each control has its own syntax and functionality; however, all share some features, which are described in this section.

===<span id="ui-common">Common attribute and content sets</span>===

The following attributes and attribute sets are common to many elements.

; Control Common
:{| id="attrs-control-common" summary="listing of XForms Common attributes on controls" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and their Content (after AVT evaluation)
|-
| rowspan="1" colspan="1" | (various)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#attrs-navigation|Navigation]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-single-node|Single Item Binding]]
|}
; appearance:

:{| id="attrs-appearance" summary="listing of XForms appearance attribute" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
|-
| rowspan="1" colspan="1" | (various)
| rowspan="1" colspan="1" |
appearance ("full"|"compact"|"minimal" | [[#def-PrefixedName|PrefixedName]])
|}
: Optional appearance hint. If absent, any suitable rendering may be used. The effect of this attribute is defined by each control that uses it. Note that a control may have up to four standard appearances: without the attribute, and with the three possible values. See for instance [[#ui-output|the output element]].

; <span id="attrs-inputmode">inputmode</span>
: Optional hint about the sort of text that is expected by the control. See [[#Input Modes (Non-Normative)|Input Modes]] for details.
; <span id="attrs-incremental">incremental</span>
: Optional boolean that determines when a bound control updates instance data. Normally, controls that only require a single interaction update the instance immediately after a change; controls that require more interaction, like text-oriented controls such as <code>textarea</code>, only update the instance once focus is moved away. When <code>false</code>, this attribute indicates that the instance data should be updated when the control loses focus; when <code>true</code>, the instance data should be updated more often, thereby generating more xforms-value-changed events &ndash; however, an implementation may buffer sequences of changes happening in quick succession, and apply them all at once. The default value for this attribute varies per control and modality, but for textual controls the default is normally <code>false</code>.
; UI Common:
:{| id="attrs-ui-common" summary="listing of XForms Common UI attributes" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and their Content (after AVT evaluation)
|-
| rowspan="1" colspan="1" | (various)
| rowspan="1" colspan="1" |
[[#ui-commonelems-label|label]] (xs:string) | [[#ui-commonelems-help|help]] (xs:string) | [[#ui-commonelems-hint|hint]] (xs:string) | [[#ui-commonelems-alert|alert]] (xs:string)
|} Controls may have label, help, hint, and alert texts associated with them, either via attributes or child elements of the control itself, or via texts associated with the bound value through the [[#tructure-bind-element|bind element]] in the model. If a text is associated in more than one way, the attribute on the control takes precedence, followed by the child element of the control, and finally the bound text in the model. The effect of these texts are described in the respective element descriptions.
; <span id="attrs-navigation">Navigation</span>
: A host language must provide a way to indicate overall navigation order among controls and other elements included in the host language, as well as keyboard or direct access navigation to specific elements. One possibility is to use a pair of attributes named <code>navindex</code> and <code>accesskey</code>, defined as follows:

; navindex
: Optional 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|control]]s are traversed. The default navigation order is specified in the section on [[#evt-next|control navigation]].
; accesskey
: Optional shortcut for moving the input focus directly to a particular [[#def-form-control|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|control]]. The user agent must provide a means of identifying the accesskeys that can be used.

This module also 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" |
[[#ui-commonelems-label|label]]|[[#ui-commonelems-help|help]]|[[#ui-commonelems-hint|hint]]|[[#ui-commonelems-alert|alert]]|[[#action-content-set|Action]]
|-
| id="elems-list-ui-common" rowspan="1" colspan="1" | '''List UI Common'''
| rowspan="1" colspan="1" | [[#ui-selection-commonelems-choices|choices]]|[[#ui-selection-commonelems-item|item]]|[[#ui-selection-commonelems-itemset|itemset]]
|-
| id="elems-form-controls" rowspan="1" colspan="1" | '''Core Controls'''
| rowspan="1" colspan="1" | [[#ui-input|input]]|[[#ui-secret|secret]]|[[#ui-textarea|textarea]]|[[#ui-output|output]]|[[#ui-upload|upload]]|[[#ui-range|range]]|[[#ui-trigger|trigger]]|[[#ui-submit|submit]]|[[#ui-select|select]]|[[#ui-select1|select1]]|[[#ui-control|control]]
|-
| id="elems-all-controls" rowspan="1" colspan="1" | '''Controls'''
| rowspan="1" colspan="1" | [[#elems-form-controls|Core Controls]]|[[#ui-group|group]]|[[#ui-switch|switch]]|[[#ui-repeat|repeat]]|[[#ui-dialog-module|dialog]]
|-
| id="elems-inline" rowspan="1" colspan="1" | '''UI Content'''
| rowspan="1" colspan="1" | [[#ui-output|output]]
|}

The [[#action|Actions]] 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>
<div class="div2">

===<span id="ui-commonelems">Common Support Elements</span>===

These are used to attach information to many controls and other elements; the information may be specified either as a child element, or as an attribute of the same name (see the [[#attrs-ui-common|UI Common]] attribute set). If both an attribute and an element of the same name are present, the attribute is used.

If specified as an attribute, the content of the attribute is the information to be used; if as a child element, the information is obtained by evaluating the <code>value</code> attribute if present, otherwise from the Single Item Binding if present, and otherwise from the inline text.

The information is rendered in the same way as by [[#ui-output|the output element]], and then displayed as described below; as a consequence they may also generate an [[#evt-output-error|xforms-output-error]].

The following table summarizes the common child elements for controls.

{| summary="listing of support elements for controls, their attributes and their content models" border="1"
! rowspan="1" colspan="1" | Support Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
! 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-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]
| 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-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]
| 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-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]
| 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-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]
| rowspan="1" colspan="1" |
(PCDATA|([[#elems-inline|UI Content]]))*
|}

<div class="div3">

====<span id="ui-commonelems-label">The label Element</span>====

Optional descriptive label for the attached control.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]

Content: (PCDATA|([[#elems-inline|UI Content]]))*
</div>
The label is made available to the user.

<div class="example" title="labels">
 <input ref="price" label="Unit Price"/>
 <input ref="price">
    <label>Unit Price</label>
 </input>
 <input ref="price" label="{instance('msg')/price}"/>
 <group>
    <label ref="intro" mediatype="text/html"/>
    ...
 </group>
</div>
</div><div class="div3">

====<span id="ui-commonelems-help">The help Element</span>====

Optional help information for a control.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]

Content: (PCDATA|([[#elems-inline|UI Content]]))*
</div>
If the user requests it, the help content is made available to the user.

Processors should choose an appropriate presentation, and should allow styling if the host language integration supports it.
By default a graphical browser should present help as an ephemeral [[#The message Element|message]].

<div class="example" title="help">
 <secret ref="/login/password" label="Password">
   <help>Have you forgotten your password? Simply call 1-900-555-1212 and have
         a major credit card handy.</help>
 </secret>

[[Image:ui-password-with-help.png|A password entry form control, with a popup window below, displaying instructions for retrieving a forgotten password]]
</div>

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

====<span id="ui-commonelems-hint">The hint Element</span>====

Optional hint information for a control.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]

Content: (PCDATA|([[#elems-inline|UI Content]]))*
</div>
If the user requests it, the hint content is made available to the user.

Processors should choose an appropriate presentation for the hint, and should allow styling if the host-language integration supports it.  By default, a presentation should be the same as an ephemeral message associated with the label.
<div class="example" title="the use of a hint">
 <input ref="po/address/street1" label="Street">
   <hint>Please enter the number and street name</hint>
 </input>
A graphical browser might render this as follows:

[[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>
With <code>appearance="minimal"</code>, a hint should be associated with the value yet distinguished from actual values.
<div class="example" title="a minimal hint">
 <group ref="registration">
   <input ref="name" label="Name:">
     <hint appearance="minimal">Last, First</hint>
   </input>
   <input ref="website" label="Website:">
     <hint appearance="minimal"><nowiki>http://</nowiki></hint>
   </input>
 </group>

A graphical browser might render this as follows:

[[Image:ui-input-with-minimal-hint.png|Two text entry form controls, one for name and another for website, with grayed-out hints 'Last, First' and 'http://' appearing in the input value text boxes.]]
</div>
</div>
<div class="div3">

====<span id="ui-commonelems-alert">The alert Element</span>====

Optional alert or error text for a control when its associated data is non-valid.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]

Content: (PCDATA|([[#elems-inline|UI Content]]))*
</div>
When a control's associated data is invalid, the alert text is made available to the user.
Processors should choose an appropriate presentation for the alert.

<div class="example" title="alert">
 <instance>
    &lt;data xmlns="">
       <number/>
    </data>
 <instance>
 <bind ref="number" type="integer" />
 ... 
 <input ref="number" label="Number" alert="Must be a whole number/>

This might be displayed with a symbol showing that the value is invalid, that if you hover over, displays the alert text:

[[Image:ui-input-with-alert.png|An average-looking text entry form control, with the value 1.5 entered and a mouse pointer hovering over an icon representing invalidity, and a tooltip below, reading 'Must be a whole number']]
</div>
</div><div class="div2">

===<span id="ui-processing">Implementation Requirements Common to All Controls</span>===

All controls must meet the implementation requirements listed in the following sections.

====Data Binding====
* If a control violates its data binding restriction, an <code>xforms-binding-error</code> must be dispatched to the control.<div class="note">'''Note: ''' Controls that read or write simpleContent produce this error whenever and as soon as they are bound to an element node that has an element child node.</div>
* Controls that write simpleContent to instance data must do so as defined by [[#The setvalue Element|the <code>setvalue</code> action]].<div class="note">'''Note: '''If a control binds to an element node, then regardless of how many child nodes the element has, the result of the control writing to it is that it has either a single non-empty text node child, or no children if the value written is the empty string.</div>
* A control that reads simpleContent instance data must do so according to the type of node it is bound to:
** The root node: an <code>xforms-binding-error</code> is dispatched to the control. 
** Element nodes: If element child nodes are present, then an <code>xforms-binding-error</code> is dispatched to the control. Otherwise, the string-value of the node is used.
** Attribute nodes: the string-value of the node is used.
** Text nodes: the string-value of the node is used.
** Namespace, processing instruction, and comment nodes: behavior is undefined and implementation-dependent.
<div class="note">'''Note: '''The simpleContent binding restriction is intended to allow controls to bind to attribute and element nodes. This specification does not prevent binding controls directly to text nodes, however doing so can yield undesirable behavior, such as a control becoming disabled if a user enters empty data. This specification also does not prevent implementers supporting binding controls directly to comment or processing instruction nodes, however the resulting behavior is implementation-dependent and may also yield undesirable behavior.</div>

====<span id="all-controls-interaction">Interaction</span>====
* At any time, at most one [[#core-controls|core control]] has the '''focus''', so that user interaction goes to that control. The focus can be changed by user interaction, by the effects of processing, or by the focus-setting events and actions [[#evt-focus|xforms-focus]], [[#evt-previous|xforms-previous]], [[#evt-next|xforms-next]], [[#action-setfocus|setfocus]], [[#action-previousfocus|previousfocus]], [[#action-nextfocus|nextfocus]].
* If a [[#container-controls|container control]] is given focus, focus goes to the first enclosed core control in navigation order that can accept focus. If there is no such control, no control has focus.
* Controls bound to a readonly value or an atomic value, must not allow the user to modify the value.
* The host language may define navigation order between controls; in the absence of a host-language-defined ordering, the next/previous control (including container controls) in document order that is capable of receiving the focus defines the navigation order. 
* Controls that are disabled, hidden, or read-only do not participate as navigable controls, and may not receive the focus. 
* The navigation order past the last control, or before the first, is undefined. Processors may cycle back to the first/last control, remove focus altogether, or do something else.

====<span id="form-control-non-relevance-conditions">Availability</span>====
Controls are '''disabled''' if any of the following apply and '''enabled''' otherwise:
* the Single Item Binding resolves to the empty sequence,
* the Single Item Binding resolves to a non-relevant instance node,
* the control is contained by a non-relevant <code>switch</code>, <code>group</code>, or <code>repeat</code> item,
* the control is contained by a non-selected <code>case</code> element of a <code>switch</code>.

When a control becomes disabled, the <code>xforms-disabled</code> event must be dispatched to it, and the control and any children must be made unavailable, removed from the navigation order, and not allowed focus. Disabled content should not be presented, or should be styled differently.

When a control becomes enabled, the control must be updated to represent the current value(s) and model item properties of its bound instance data, and made available for user interaction. The <code>xforms-enabled</code> event must be dispatched to the control, as well as the following events as appropriate: <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>.

This processing is done during a [[#model-refresh|refresh]].

<div class="note">'''Note:''' Some elements other than controls, such as actions like [[#The setvalue Element|setvalue]] and [[#The message Element|message]], and [[#submit-submission-element|the <code>submission</code> element]] also use a Single Item Binding; however, since the binding is not a [[#def-ui-binding-expression|UI binding expression]] they are not disabled when bound to a non-relevant node. Their operation may however be affected in other ways; for example, non-relevant nodes are by default excluded from the data of a submission.</div>

====Rendering====
* '''Layout''': unless otherwise specified, controls 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>). [[#def-repeat-item|Repeat items]] and [[#ui-group|groups]] have a block layout by default (e.g. a CSS styling of <code>display:block</code>).
* '''Representation''': controls that render bound data must produce a rendering that directly corresponds to the data; it is not required to match the lexical space value of the data, but should take into account the datatype of the value, appearance hints, and localization and internationalization issues such as representation of numbers and dates.
* '''Required values''': enabled controls that display a representation of the bound data must distinguish rendering between being bound to a required node versus a non-required node. Exceptions include <code>trigger</code> and the [[#container-controls|container controls]]. This rendering should be user-stylable.
* '''Validity''': enabled controls must distinguish rendering between valid and invalid states. This rendering should be user-stylable.
* '''Read-only''': controls bound to a readonly value or an atomic value should indicate that entering or changing the value is not allowed. This rendering should be user-stylable.
* <span id="def-out-of-range">'''Out-of-range'''</span>: enabled controls bound to a value that the control is unable to represent must indicate that the control is out-of-range. This rendering should be user-stylable. Whenever a control switches to or from being out-of-range, an xforms-out-of-range or xforms-in-range event must be dispatched to the control.

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

==<span id="core-controls">Core Controls</span>==

A core control is an element that acts as a direct point of user interaction and often provides read, write, or read/write access to instance data. 

{| summary="listing of XForms Core Controls, their attributes and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes  and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-input|input]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], [[#attrs-inputmode|inputmode]] (xs:string), [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-secret|secret]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], [[#attrs-inputmode|inputmode]] (xs:string), [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-textarea|textarea]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], [[#attrs-inputmode|inputmode]] (xs:string), [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-output|output]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], [[#structure-attrs-value|value]] (Expression), mediatype (xs:string)
| rowspan="1" colspan="1" |
PCDATA | ([[#ui-output-mediatype|mediatype]]? [deprecated], [[#elems-ui-common|UI Common]]*)
|-
| rowspan="1" colspan="1" |
[[#ui-upload|upload]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], accept (xs:string), mediatype (xs:string) [deprecated], [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#ui-upload-filename|filename]]?, [[#ui-upload-mediatype|mediatype]]?, [[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-range|range]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], start (xs:string), end (xs:string), step (xs:string), [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-trigger|trigger]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]]
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-submit|submit]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], submission (xs:IDREF)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-select|select]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], selection ("open" | "closed"), [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*, [[#elems-list-ui-common|List UI Common]]+, [[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-select1|select1]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], selection ("open" | "closed"), [[#attrs-incremental|incremental]] (xs:boolean)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*, [[#elems-list-ui-common|List UI Common]]+, [[#elems-ui-common|UI Common]]*
|-
| rowspan="1" colspan="1" |
[[#ui-control|control]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], resource (xs:anyURI)
| rowspan="1" colspan="1" |
[[#elems-ui-common|UI Common]]*
|}

The following table summarizes the support elements for these controls.

{| summary="listing of support elements for controls, their attributes and their content models" border="1"
! rowspan="1" colspan="1" | Support Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-upload-filename|filename]] (for [[#ui-upload|upload]])
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item 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-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#ui-output-mediatype|mediatype]] (for [[#ui-output|output]]) (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]], value (string 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]], [[#structure-attrs-evaluation|Evaluation]], label (xs:string)
| 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]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-ui-common|UI Common]], value (Expression), copy (Expression)
| rowspan="1" colspan="1" |
(value|copy), ([[#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-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]] (optional), value (Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-itemset|itemset]] (for selection controls)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-nodeset|Sequence Binding]], value (Expression), copy (Expression)
| rowspan="1" colspan="1" |
(value|copy), ([[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-selection-commonelems-copy|copy]] (for selection controls)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]]
| rowspan="1" colspan="1" | EMPTY
|}

<div class="div3">
===<span id="ui-input">The input Element</span>===

This control enables data entry in a way appropriate to the datatype of the bound node.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-inputmode|inputmode]], [[#attrs-incremental|incremental]]

Content: [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: Binds to any simpleContent (except <code>xs:base64Binary</code>, <code>xs:hexBinary</code> or any datatype derived from these) or an atomic value.
</div>
An <code>input</code> element produces some suitable rendering of the instance data it is bound to. If the control has an <code>appearance</code> attribute with a value of <code>minimal</code>, it should be displayed in a manner similar to the <code>output</code> control, otherwise, it should be displayed in a way that suggests that the value is editable.

When the element has the input focus, interaction can change that rendering; changes to the rendering cause consequent changes to the instance data it is bound to.

This control must allow entry of a lexical value for the bound datatype. Implementations should provide a convenient means for entry of value according to their datatype and take into account localization and internationalization issues such as representation of numbers and dates. For example, an <code>input</code> bound to an instance data node of type <code>date</code> might provide a calendar control to enter dates; similarly, an input control bound to type <code>boolean</code> might be rendered as a checkbox.

<div class="example" title="Simple input">
 <input ref="order/shipTo/street" label="Street"/>

A graphical browser might render this as:

[[Image:ui-input.png|An average-looking text entry control. The label, 'Street' has been aligned to the left]]
</div>
<div class="example" title="Datatype-sensitive input">
 <input ref="order/shipDate" label="Ship By"/>

A graphical browser might render this as:

[[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|upright=0.2|A calendar picker graphical widget.]]

</div>
<div class="example" title="Input with Activation">
 <input ref="/search/expr" label="Search term(s):">
   <send ev:event="DOMActivate" submission="doSearch"/>
 </input>
 
 <submit submission="doSearch" label="Search"/>

This example shows <code>input</code> and <code>submit</code> 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 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 control).

</div>

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

===<span id="ui-secret">The secret Element</span>===

This control allows input of data in a manner that hinders third parties discerning the data being input. A common use is for password entry.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-inputmode|inputmode]], [[#attrs-incremental|incremental]]

Content: [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: Binds to any simpleContent (except <code>xs:base64Binary</code>, <code>xs:hexBinary</code> or any datatype derived from these) or an atomic value.

Implementation Requirements: Implementations, including accessibility aids, must obscure the value being entered into this control. One approach is to render a "*" or similar character instead of the actual characters entered.
</div>
Except for the rendering aspects, the <code>secret</code> control behaves further as an <code>input</code> control.

<div class="example" title="Password Entry">
 <secret ref="/login/password" label="Password" 
         hint="The password you enter will not be displayed"/>

A graphical browser might render this control as follows:

[[Image:ui-secret-with-hint.png|A password entry 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>===

This control enables free-form data entry and is intended for use in entering multiline content, such as the body of an email message.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-inputmode|inputmode]], [[#attrs-incremental|incremental]]

Content: [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: Binds to any simpleContent (except <code>xs:base64Binary</code>, <code>xs:hexBinary</code> or any datatype derived from these) or an atomic value.

Implementation Requirements: Must allow entry of a lexical value for the bound datatype, including multiple lines of text. Implementations should provide a convenient means for entry of datatypes, for example, a textarea bound to an instance data node of type xforms:HTMLFragment might provide a WYSIWYG rich text editor with common word processor features.
</div>

<div class="example" title="Email Message Body">
 <textarea ref="message/body" label="Message Body:"/>

Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from any 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>===

This control renders content based on instance data.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#structure-attrs-value|value]], [[#structure-attrs-mediatype|mediatype]]

Content: PCDATA | ([[#ui-output-mediatype|mediatype]]? [deprecated], [[#elems-ui-common|UI Common]]*)

Most controls are required to have an item binding: <code>output</code> does not.

Data Binding Restrictions: Binds to any simpleContent or an atomic value.
</div>
The data to be rendered is obtained by evaluating the <code>value</code> attribute if present, or otherwise from the Single Item Binding if present, and otherwise from the inline data.

The mediatype is obtained from the <code>mediatype</code> attribute if present, or otherwise from the <code>mediatype</code> child element if any.

If a mediatype has been specified, and the data to be output is non-empty, the data is decoded or dereferenced depending on the base type of the data: an <code>xs:base64Binary</code> value is base-64 decoded, an <code>xs:hexBinary</code> value is hex-binary decoded, and an <code>xs:anyURI</code> value is treated as a URI and dereferenced. For any other type, the data is used without modification. Implementations [[#intro-conventions|should]] accept at least <code>image/*</code> and, if the host language is some version of HTML, <code>text/html</code> as possible values of <code>mediatype</code>.

The data is rendered in a suitable way taking into account the datatype of the value, the mediatype if any, the <code>appearance</code> attribute, and localization and internationalization issues such as representation of numbers and dates.

The data is rendered on XForms initialization, and re-rendered whenever there is a change in any node to which the binding or expression refers, or if the mediatype changes.

Failure to render the content [[#intro-reading|should]] result in a (non-fatal) [[#evt-output-error|xforms-output-error]]. Failure can occur for many reasons, such as:

* Data to be decoded does not conform to the format of <code>xs:base64Binary</code> or <code>xs:hexBinary</code>;
* An error dereferencing the URI in a item of or derived from type <code>xs:anyURI</code>;
* A data format error (e.g. incorrect or unsupported image format);
* An unrecognized mediatype identifier string.

<div class="note">

'''Note:'''

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.

</div>

<div class="example" title="Simple usage">
 <output ref="age" label="Age:"/>
 <output ref="age"><label>Age:</label></output>
 <output value="amount*taxrate" label="Tax:"/>
 <output class="note">Deleted</output>
</div>

<div class="example" title="Explanatory Message">
 I charged you <output ref="order/totalPrice"/>
 - and here is why:

A graphical browser might render this control as follows:

[[Image:ui-output.png|Average-looking text, reading 'I charged you 100.0 - and here is why:']]

</div>

<div class="example" title="Displaying an image from a URL">
 <output value="<nowiki>'http://tile.openstreetmap.org/10/511/340.png'</nowiki>" mediatype="image/*" />
 <output value="<nowiki>'http://{site}/{zoom}/{x}/{y}.{type}'</nowiki>" mediatype="image/*" />

The second example above can use an instance such as:
 <instance xmlns="">
    <map>
       <site>tile.openstreetmap.org</site>
       <zoom>10</zoom>
       <x>511</x>
       <y>340</y>
       <type>png</type>
    </map>
 </instance>
</div>

<div class="example" title="Displaying an image uploaded to instance data">

 <model>
   <instance>
     &lt;data xmlns="">
       <picture/>
     &lt;/data>
   </instance>
   <bind ref="picture" type="xs:base64Binary"/>
 </model>

Given the <code>model</code> above, the following controls can upload an image to instance data and display it:

 <upload ref="picture" accept="image/*" label="Press me to attach a picture"/>

 <output ref="picture" mediatype="image/*" hint="This is the image you attached to the form.">
   <message ev:event="xforms-output-error">Error attaching image data.</message>
 </output>

</div>

<div class="example" title="Output of value of type date">

 <bind ref="birthdate" type="date"/>
 ...
 <output ref="birthdate" label="Lexical:"/>
 <output ref="birthdate" appearance="full" label="Full:"/>
 <output ref="birthdate" appearance="compact" label="Compact:"/>
 <output ref="birthdate" appearance="minimal" label="Minimal:"/>

A graphical browser taking into account the <code>appearance</code> and the localization information from the host language, might present the above output controls as follows:

 Lexical: 1998-01-19 Full: 19 janvier 1998 Compact: 19 jan 98 Minimal: 19/01/1998

or as

 Lexical: 1998-01-19 Full: 19 January 1998 Compact: 19 Jan 98 Minimal: 19/01/1998

</div>
<div class="example" title="Rich text output">
 <instance id="messages">
    <messages xmlns="">
       ...
       <warning>Do &amp;lt;em>not&amp;lt;/em> pass go!</warning>
       ...
    </messages>
 </instance>

 <output ref="instance('messages')/warning" mediatype="text/html"/> 
</div>
<div class="div4">
====<span id="ui-output-mediatype">The mediatype Element (for output) (Deprecated)</span>====

Element <code>mediatype</code> (deprecated in favor of using an AVT in the <code>mediatype</code> attribute on element <code>output</code>) specifies the required mediatype to be used for output.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The mediatype to be used is obtained by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element.

<div class="example" title="mediatype">
 <mediatype value="'image/*'"/>
 <mediatype>image/*</mediatype>
 <mediatype value="../imagetype"/>
</div>

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

===<span id="ui-upload">The upload Element</span>===

This control allows files to be uploaded from the local file system, as well as accepting input from devices such as microphones, pens, scanners, and digital cameras.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-incremental|incremental]]

Special Attributes:

; accept
: Optional comma-separated list of suggested mediatypes and file extensions (including the leading period), used to determine the possible sources of data to upload. This attribute must work as described in [[#ref-html5 | [HTML5]]].
; mediatype [deprecated in favor of <code>accept</code>]
: Space-separated list of suggested mediatypes, used to determine the possible sources of data to upload.

Content: [[#ui-upload-filename|filename]]?, [[#ui-upload-mediatype|mediatype]]?, [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: This control can only be bound to datatypes <code>xs:anyURI</code>, <code>xs:base64Binary</code> or <code>xs:hexBinary</code>, or types derived by restriction from them.
</div>
When activated, this control offers the user a dialog to upload a file, or obtain data from another source, such as a camera, scanner, microphone, etc.

Implementations with a file system should support ''file upload'' &mdash; selecting a specific file. The types of files presented by default should reflect the mediatype specified by the <code>accept</code> attribute, for example defaulting to only audio file types for "audio/*".

Implementations attached to devices capable of producing data should support those devices. The devices presented by default should reflect the mediatype specified by the <code>accept</code> attribute, for example defaulting to cameras and scanners for "image/*".

Implementations which cannot support upload for the given mediatype must make this apparent to the user.

If child element <code>[[#The filename Element (for upload)|filename]]</code> is present and a filename is available, the filename of the data to upload is placed in the instance at the node indicated by the binding attributes on child element <code>filename</code>.

If child element <code>[[#The mediatype Element (for upload)|mediatype]]</code> is present and a mediatype is available, the mediatype of the data to upload is placed in the instance at the node indicated by the binding attributes on child element <code>mediatype</code>.

When bound to an instance data node of type <code>xs:base64binary</code>, <code>xs:hexBinary</code>, or a type derived by restriction thereof, the binary content is placed in the content of the node, encoded as indicated.

When bound to an instance data node of type <code>xs:anyURI</code> (or a type derived by restriction thereof), a URI is placed in the content of the node. For security reasons, the URI bound to this control must not be dereferenced without explicit user permission.  <div class="note">'''Note: '''Binary content, mediatype, and filename must be associated 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>

<div class="example" title="Uploading An Attachment">
 <upload ref="mail/attachment" accept="video/*,image/*,.txt,.pdf" label="Select attachment:">
   <filename ref="@filename"/>
   <mediatype ref="@mediatype"/>
 </upload>
</div>

<div class="example" title="Uploading An Image">
 <upload ref="mail/attachment" accept="image/*" label="Select image:">
   <filename ref="@filename"/>
   <mediatype ref="@mediatype"/>
 </upload>

A graphical browser might render this 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...]]
</div>
</div>
<div class="div4">

====<span id="ui-upload-filename">The filename Element (for upload)</span>====

This element specifies the location for the filename of the chosen binary resource, if available. For security reasons, <code>upload</code> must not take action due to any existing value of the node.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]]

Content: EMPTY

Data Binding Restrictions: Binds to any simpleContent (except xs:base64Binary, xs:hexBinary or any datatype derived from these).
</div>
<div class="example" title="Uploading an image">
The user is prompted to select an image. Depending on the type of <code>mail/attachment</code>, either the binary data of the image or a URI for it, is placed in <code>mail/attachment</code>. The corresponding 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>.

 <upload ref="mail/attachment" accept="image/*" label="Select an image to attach">
   <filename ref="@filename"/>
   <mediatype ref="@mediatype"/>
 </upload>
</div>
</div>
<div class="div4">

====<span id="ui-upload-mediatype">The mediatype Element (for upload)</span>====

This element specifies the location to place the mediatype of the chosen binary resource, if available.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]]

Content: EMPTY

Data Binding Restrictions: Binds to any simpleContent (except xs:base64Binary, xs:hexBinary or any datatype derived from these).
</div>
</div>
<div class="div3">

===<span id="ui-range">The range Element</span>===

This control allows input or selection from a sequential range of values.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-incremental|incremental]]

Special Attributes:

; start
: Optional hint for the starting bound for the range &mdash; a legal value for the underlying data. If provided, this value further refines the constraints specified by the underlying model.
; end
: Optional hint for the ending bound for the range &mdash; a legal value for the underlying data. If provided, this value further refines the constraints specified by the underlying model.
; step
: Optional delta-value to use for incrementing or decrementing the value. It must be of a type capable of expressing the difference between two legal values of the underlying data.

Content: [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: Binds to simpleContent from the following list of datatypes, or datatypes derived by restriction from them: <code>xs:duration</code>, <code>xs:date</code>, <code>xs:time</code>, <code>xs:dateTime</code>, <code>xs:gYearMonth</code>, <code>xs:gYear</code>, <code>xs:gMonthDay</code>, <code>xs:gDay</code>, <code>xs:gMonth</code>, <code>xs:float</code>, <code>xs:double</code>, and <code>xs:decimal</code>.

<div class="note">
'''Note:''' These datatypes include by derivation all of the integer datatypes (which are derived by restriction from <code>xs:decimal</code>), and all of the XForms datatypes defined in Section [[#XForms Datatypes|XForms Datatypes]] that correspond to the allowed XML Schema datatypes.
</div>
</div>
This control allows the input of a value within the restrictions specified by the 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. The upper and lower bounds and the step size should be available to the user.

If the instance data value is outside the upper or lower bounds, the control is [[#def-out-of-range|out-of-range]]. 

In graphical environments, this control could be rendered as a "slider" or "rotary control".

<div class="note">

'''Note:'''

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, 2020 through December 31, 2020.''
</div>

<div class="example" title="Picking From A Range">
 <range ref="/stats/balance" start="-2.0" end="2.0" step="0.5" label="Balance"/>

A graphical browser might render this as follows:

[[Image:ui-range.png|a slider control, from -2 to +2]]
</div>
<div class="example" title="Picking a date from a range">
 <range ref="/order/shipDate" start="2021-01-01" end="2021-12-31" label="Ship Date"/>
</div>
</div>
<div class="div3">

===<span id="ui-trigger">The trigger Element</span>===

This control allows user-initiated actions and can be used to construct custom controls. It is similar in effect to the HTML <code>button</code> element.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]]

Content: [[#elems-ui-common|UI Common]]*

Most controls must have a single item binding; on trigger it is optional.

Data Binding Restrictions: Binds to any node or an atomic value; the data is not used, only the data's model item properties: 
* the <code>relevant</code> property affects visibility, focus, and navigation order as with other controls, and thus disables the trigger;
* the <code>readonly</code> property has a similar effect as with input controls: the trigger cannot receive focus, cannot be activated, but remains visible with a presentation that indicates it is not activatable; 
* all other properties have no effect.

{{EditorialNote|title=trigger enablement|date=2018-01-17|desc=There is discussion on whether it is preferable to use all MIPS, and only make a trigger activatable when the bound value is valid, relevant, and non-empty if required.}}

Implementation Requirements: The user agent must provide a means to generate a <code>DOMActivate</code> event on the control. 
</div>
This control is activated by user interaction, which causes the DOMActivate event to be dispatched to it; event handlers in the body of the trigger can respond to this event to effect further processing.

Graphical implementations might render this control as a push-button with the label on the button face. Style sheets can be used to style this control in other ways, though a means is provided to suggest an appearance through the <code>appearance</code> attribute. Suggested renditions for the pre-defined values of this attribute are as follows:

:full: visually rendered as a standard button control with border,
:compact: visually rendered as a standard button control without border,
:minimal: as underlined text, such as might be used for an XHTML anchor element.

<div class="example" title="Simple Trigger">
 <trigger label="Click here">
   <message ev:event="DOMActivate">Hello!</message>
 </trigger>
</div>
</div>
<div class="div3">

===<span id="ui-submit">The submit Element</span>===

This control initiates a submission; it is shorthand for a <code>trigger</code> with a <code>send</code> action.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]]

Most controls must have a single item binding; on <code>submit</code>, it is optional.

Special Attributes:

; submission
: Optional reference to the ID of a [[#submit-submission-element|<code>submission</code> element]]. If omitted, then the first <code>submission</code> in document order from the <code>model</code> associated with the [[#in-scope-evaluation-context|in-scope evaluation context]] is used.

Content: [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: Binds to any node or an atomic value. This control does not use the instance data it is bound to, but is affected by the data's model item properties: the <code>relevant</code> property affects if the control can be activated or not; all other properties have no effect.
</div>
This control is activated by user interaction or by the <code>DOMActivate</code> event.

A [[#submit-submission-element|<code>submission</code> element]] is identified from the <code>submission</code> attribute or its default: if no such element is identified then an [[#evt-actionError|xforms-action-error]] with an error-type of <code>send-submission</code> is dispatched; otherwise an [[#submit-evt-submit|xforms-submit]] is dispatched to the element.
This control then becomes unavailable for further activation until the submit process concludes with either an [[#submit-evt-submit-done|xforms-submit-done]] or [[#submit-evt-submit-error|xforms-submit-error]].

Typically, style sheets are used to specify the appearance of controls, however 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]].

<div class="example" title="submit">
 <submit label="OK"/>
 <submit submission="timecard" label="Submit Timecard"/>
</div>
</div>
<div class="div3">

===<span id="ui-selection-commonelems">Selection Controls</span>===

There are two selection controls:
* <code>select</code> which allows the selection of zero or more values from a collection, which are combined into a single value and stored in the bound value;
* <code>select1</code> which allows for the selection of zero or one from the collection, which is then stored in the bound value.
 
The collection of values to be selected from are provided by a combination of <code>item</code> elements, each of which supplies one value, and <code>itemset</code> elements, which provide a sequence of values.

A selection control can be <span id="def-simple-selection">"simple"</span> or <span id="def-complex-selection">"complex"</span>:
* a simple selection only selects [[#def-simpleContent|simpleContent]] values (typically strings), in which case the <code>item</code> or <code>itemset</code> elements use a <code>value</code> child or attribute;
* a complex selection selects more general values (typically with children nodes), and the <code>item</code> and <code>itemset</code> use a <code>copy</code> child or attribute. If one <code>item</code> or <code>itemset</code> element has a <code>copy</code> child or attribute, then all of them must have, and the bound target of the containing selection control must be an element node, otherwise an xforms-binding-error event is dispatched to the containing selection control.

A simple selection can be either "open" or "closed", as indicated by the <code>selection</code> attribute: an open selection allows the selection of values outside the list given. A complex selection is always closed. 

The items from the children of the selection control are evaluated, each being a pair of a label and a value.

The label for each pair must be made available to the user, with an indication of whether the item is selected or not.

Interaction with a label toggles the selected state. On selection, items receive the <code>xforms-select</code> event; on deselection, the <code>xforms-deselect</code> event.

A selection control is [[#def-out-of-range|out-of-range]] if it is bound to data whose value for any reason is not in the collection of possible values.

Typically, a style sheet is used to control the appearance of controls, though a means is provided to suggest an appearance through the <code>appearance</code> attribute. The value of the attribute consists of one of the following values:
* "full": all labels should be rendered at all times;
* "compact": a fixed number of labels should be rendered, with scrolling facilities as needed;
* "minimal": a minimum number of labels should be rendered, with a facility to temporarily render additional choices.

====<span id="ui-select">The select Element</span>====

This control allows the selection of multiple values from a list of choices. 
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-incremental|incremental]]

Special Attributes:

; selection
: Optional value indicating whether the selection is open or closed. Allowable values are "open" and "closed". Default is "closed".

Content: [[#elems-ui-common|UI Common]]*, [[#elems-list-ui-common|List UI Common]]+, [[#elems-ui-common|UI Common]]*

Data Binding Restrictions:  For simple selections, binding must be to any simpleContent capable of holding a sequence or a sequence of atomic values; the datatype may be a non-enumerated value space, e.g., <code>string</code>, or a union of an enumeration and a non-enumerated datatype (called an open enumeration). For complex selections, binding is to an element with no mixed content, or a sequence of atomic values. 
</div>

All items whose values match a value in the bound instance data are initially selected; if a particular value in the bound data matches more than one item, at least one is selected, but it is not further defined which, nor how many. If there is no match, no items are initially selected.
Items with an empty storage data subtree or a storage value that is either empty or contains only white space characters are never selected.

If the bound instance data contains values that do not match any item's value:
* for open selections, all such non-matching values are retained and made available to the user; since there are no associated labels, the value itself is used as the label;
* for closed selections, the control is out-of-range.

Any number of the items may be selected, including none.

For open selections, the control must also allow free data entry, as described in [[#The input Element|The input Element]]. The control must permit multiple values to be entered through free entry. The label of such an entered value is considered identical to the value itself.

Selected values are represented in the bound instance location:
* for simple selections as a space-separated list,
* for complex selections as copies of the subtrees of the selected values.

The content of the bound instance node 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 must be preserved.

For a simple selection, the net effect of newly selected and deselected items is computed into a string, preserving content not associated with selection items.  For complex selections, the individual subtrees associated with the newly selected and deselected items are added or removed individually by using [[#The insert Element|insert]] and [[#The delete Element|delete]]; after which an [[#model-update|update]] is done, followed by a [[#model-refresh|refresh]].

<div class="note">
Note that when the list of values is stored as a space separated list, the values to be selected may not themselves contain spaces. For instance, this is incorrect use:

 <item>
   <label>USA</label>
   <value>United States of America</value>
 </item>
</div>

<div class="example" title="Selecting Ice Cream Flavor">
 <select ref="flavors" label="Flavors">
   <item label="Vanilla">v</item>
   <item label="Strawberry">s</item>
   <item label="Chocolate">c</item>
 </select>

A graphical browser might render this control as any of the following:

{| summary="Selection controls"
! 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 class="example" title="Selecting attributes">
Since a select is essentially a shorthand for inserts and deletes, which can also insert and delete attributes, a selection control can also be used for adding attributes to elements:

 <select ref="a"><nowiki>
    <label>Add attributes</label>
    <item label="class"/>
       <copy ref="attribute('class', 'basic')"/>
    </item>
    <item label="id"/>
       <copy ref="attribute('id', 'aaa')"/>
    </item>
    <item label="href"/>
       <copy ref="attribute('href', 'http://www.example.com')"/>
    </item>
 </select>
 <input ref="a/@class" label="class"/>
 <input ref="a/@id" label="id"/>
 <input ref="a/@href" label="href"/></nowiki>
</div>
</div><div class="div3">

====<span id="ui-select1">The select1 Element</span>====

This control is similar to the <code>select</code> control except that only a single item may be selected from the list of choices: interaction with a label of a non-selected item first deselects any item already selected, and then selects the new item. 

<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]], [[#attrs-incremental|incremental]]

Special Attributes:

; selection
: Optional value indicating whether the selection is open or closed. Allowable values are "open" and "closed". Default is "closed".

Content: [[#elems-ui-common|UI Common]]*, [[#elems-list-ui-common|List UI Common]]+, [[#elems-ui-common|UI Common]]*

Data Binding Restrictions: For simple selections, binds to any simpleContent or an atomic value; for complex selections, binds to an element with no mixed content or an atomic value.
</div>

Any item whose value matches the value of the bound instance data is initially selected; if more than one matches, at least one is selected, but it is not further defined which, nor how many of the matching items is selected. If there is no match, no item is initially selected. For both closed and open selections, any item with an empty storage data subtree or a storage value that is either empty or contains only white space characters is treated identically to any other value.

If the bound instance data is non-empty and does not match any item's value:
* for open selections, the non-matching value is retained and made available to the user; the value is also used as the label;
* for closed selections, the control is out-of-range;

Interaction with the label of an unselected item deselects any already-selected item and then selects the new item; interaction with the label of a selected item deselects that item.

For open selections, the control must also allow free data entry, as described in [[#The input Element|The input Element]]; entering a value selects that value after deselecting any already-selected value. The label of such an entered value is considered identical to the value itself.

The selected value is stored in the bound instance location, for complex selections as a copy of the subtree of the selected value.

<div class="example" title="Pick A Flavor">
 <select1 ref="icecream/flavor" label="Flavour">
   <item label="Vanilla">v</item>
   <item label="Strawberry">s</item>
   <item label="Chocolate">c</item>
 </select1>

A graphical browser might render this 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 box with 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 class="example" title="Combining item and itemset">
With this instance
 <instance id="palette">
    <palette xmlns="">
       <hue name="Salmon">#fa8072</hue>
       <hue name="Olive">#808000</hue>
       <hue name="Navy">#000080</hue>
    </palette>
 </instance>

This select1 combines <code>item</code> and <code>itemset</code> elements to form the collection of items:

 <select1 ref="colour" label="Colour">
    <item label="Black">#000000</item>
    <item label="White">#ffffff</item>
    <itemset ref="instance('palette')/hue" label="{@name}" value="."/>
 </select1>
</div>
<div class="div2">

====<span id="ui-selection-commonelems-choices">The choices Element</span>====

This element is used within selection controls to group available choices. This provides the same functionality as element <code>optgroup</code> in HTML.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]

Content: label?, ([[#elems-list-ui-common|List UI Common]])+
</div>
<div class="example" title="choices">
 <select1 ref="drink" label="Drink">
   <choices label="Hot">
      <item label="Coffee">coffee</item>
      <item label="Tea">tea</item>
   </choices>
   <choices label="Cold">
      <item label="Water">water</item>
      <item label="Milk">milk</item>
   </choices>
 </select1>
</div>

</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 selection list. It is found within elements <code>select1</code> and <code>select</code>, or grouped in element <code>choices</code>.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-value|value]]

Special Attributes:
;copy
: Optional expression giving a value to be copied. Takes precedence over any copy child element.

Content: (value | copy | [[#elems-ui-common|UI Common]])*

Data Binding Restriction: All lexical values must be valid according to the datatype bound to the selection control. If the Single Item 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-error</code> must occur.
</div>
The storage value is obtained by evaluating the <code>value</code> if present, otherwise from the Single Item Binding if present, otherwise by evaluating the <code>value</code> child element, if present, and otherwise from the string content of the <code>item</code> element.

<div class="example" title="item">
These four are equivalent:
 <item label="Credit">cc</item>
 <item label="Credit" value="'cc'"/>
 <item label="Credit"><value>cc</value></item>
 <item><label>Credit</label><value>cc</value></item>
These two are equivalent:
 <item label="{labels/female}">f</item>
 <item><label ref="labels/female"></label><value>f</value></item>

 <item label="Today" value="substring-before(now(), 'T')"/>
</div>
</div><div class="div3">

=====<span id="ui-selection-commonelems-value">The value Element (for item)</span>=====

This element provides a storage value to be used when an <code>item</code> is selected. 
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]] (optional), [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The storage value is obtained by evaluating the <code>value</code> attribute if present, otherwise from the Single Item Binding if present, and otherwise from the inline content of the value element.

<div class="example" title="value">
 <value>3</value>
 <value ref="../a"/>
 <value value="substring-before(now(), 'T')"/>
</div>
</div>
</div>
<div class="div3">

====<span id="ui-selection-commonelems-itemset">The itemset Element</span>====

This element generates <code>item</code> elements from instance values, for <code>select</code> and <code>select1</code> controls.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-ui-common|UI Common]], [[#structure-attrs-nodeset|Sequence Binding]], [[#structure-attrs-value|value]]

Special Attributes:
;'''copy'''
: Optional expression giving a value to be copied. Takes precedence over any <code>copy</code> child element.

Content: ([[#ui-selection-commonelems-value|value]]|[[#ui-selection-commonelems-copy|copy]]), ([[#elems-ui-common|UI Common]])* 
</div>

If there is a <code>copy</code> attribute or child present, this itemset is part of a [[#def-complex-selection|complex selection]]: if the bound target of the containing <code>select</code> or <code>select1</code> element is not an element node, an [[#evt-bindingError|xforms-binding-error]] event is dispatched to the containing selection element.

The sequence binding is evaluated to give a sequence. For each item of this sequence, an associated <code>item</code> element is generated:
* the label is obtained from the <code>label</code> attribute if present, or otherwise the <code>label</code> child element;
* for a simple selection, the <code>value</code> attribute if present, or otherwise the <code>value</code> child, is evaluated to give a simple value;
* for a complex selection, the <code>copy</code> attribute if present, or otherwise the <code>copy</code> child, is evaluated to give a complex value.

Actions appearing in the content of an <code>itemset</code> are created within each <code>item</code> element, and their evaluation context is that of the data item for which the <code>item</code> was generated, as described in [[#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>

<div class="note">

'''Note:'''

Whenever a [[#model-refresh|refresh]] is done, the sequence binding is re-evaluated to update the list of available choices.

</div>

<div class="example" title="Dynamic Choice Of Ice Cream Flavors">
Using the following two models:

 <model id="cone">
   <instance>
     <icecream xmlns="">
       <order/>
     </icecream>
   </instance>
 </model>
 
 <model id="flavors">
   <instance>
     <flavors xmlns="">
       <flavor><description>Vanilla</description></flavor>
       <flavor><description>Strawberry</description></flavor>
       <flavor><description>Chocolate chip</description></flavor>
     </flavors>
   </instance>
 </model>

you can then specify the following control:

 <select model="cone" ref="order" label="Flavors">
   <itemset model="flavors" ref="flavor" label="{description}" copy="description"/>
 </select>

If all three items are then selected, this produces instance data like

 <icecream>
    <order>
       <description>Vanilla</description>
       <description>Strawberry</description>
       <description>Chocolate chip</description>
    </order>
 </icecream>
</div>
<div class="example" title="use of the copy element">
 <model>
    <instance>
       <transaction xmlns="">
          <addressee/>
       </transaction>
    </instance>
    <instance id="contacts">
       <contacts xmlns="">
          <address>
             <name>John Smith</name>
             <street>11 Main Street</street>
             <city>London</city>
             <postcode>W1 1AA</postcode>
             <land>UK</land>
          </address>
          <address>
             ... etc ...
          </address>
          <address>
             ... etc ...
          </address>
       </contacts>
    </instance>
 </model>
  ...
 <select1 ref="addressee">
    <label>Choose address</label>
    <itemset ref="instance('contacts')/address">
       <label ref="name"/>
       <copy ref="."/>
   </itemset>
 </select1>
</div>

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

=====<span id="ui-selection-commonelems-copy">The copy Element (for item and itemset)</span>=====

This element is similar to [[#ui-selection-commonelems-value|the value element]], except that it works with subtrees of instance data rather than simple values.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-single-node|Single Item Binding]]

Content: EMPTY
</div>

The storage value is obtained by evaluating the Single Item Binding.

<div class="example" title="copy element">
 <copy ref="."/>
</div>

</div>
</div>

===<span id="ui-control">The Control Element</span>===

This control embeds a form in the current one, optionally sharing data between the two, and optionally allowing communication via events.
<div class="desc">
Common Attributes: [[#attrs-control-common|Control Common]]

Special attributes:
;resource
: Required URI of a resource containing an XForms Document to be embedded within the invoking form.

Content: [[#elems-ui-common|UI Common]]*
</div>
The <code>resource</code> attribute is evaluated. It should be an XForms document, though implementations may accept a wider class. If no resource is found, or the implementation cannot process it, an [[#evt-linkError| <code>xforms-link-error</code>]] is dispatched to the <code>control</code> element, and the element has no further effect; otherwise the resource is embedded in the current form at the current textual position.

If the <code>control</code> element has a binding it must evaluate to a single element, and the embedded resource must have a [[#structure-shared-element|<code>shared</code>]] element with a binding that also evaluates to a single element, otherwise an [[#evt-bindingError|<code>xforms-binding-error</code>]] is dispatched to the <code>control</code> element.

If the <code>control</code> element has no binding, the embedded resource must either contain no [[#structure-shared-element|<code>shared</code>]] element, or contain one without a binding, otherwise an [[#evt-bindingError|<code>xforms-binding-error</code>]] is dispatched to the <code>control</code> element.

In the absence of the above errors, the embedded resource is further [[#model-processing|initialised and processed]].

If the embedded resource contains a [[#structure-shared-element|<code>shared</code>]] element, the embedded form is initialised with additional effect from that element, and data is shared between the two forms, as described in [[#structure-shared-element|that section]].

The [[#structure-shared-element|<code>shared</code>]] element also permits communication with events using the [[#action-signal|<code>signal</code>]] action.

If the embedded resource contains no [[#structure-shared-element|<code>shared</code>]] element, there is no communication between the two; the embedded resource is freestanding and is processed in the normal way.

<div class="example" title="embedding a game">
 <control resource="game.xhtml"/>
</div>
<div class="example" title="sharing data">
 <control resource="process.xf" ref="data"/>
</div>
<div class="example" title="receiving an event from the embedded XForm">
 <control resource="{choice}" bind="values">
    <toggle ev:event="finished" case="closed"/>
 </control>
</div>
<div class="example" title="two histograms using different data">
 <control resource="histogram.xhtml" ref="before" label="Before"/>
 <control resource="histogram.xhtml" ref="after"  label="After"/>
</div>


<div class="div1">

==<span id="container-controls">Container Controls</span>==

A '''container control''' is a control that combines other controls in its content into user interfaces.

The elements and attributes are:

{| summary="listing of container controls and their attribute and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#ui-group|group]]
| rowspan="1" colspan="1" |
[[#attrs-control-common|Control Common]], collapse ("open"|"closed")
| rowspan="1" colspan="1" |
([[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#ui-switch|switch]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional)
| rowspan="1" colspan="1" | [[#ui-case|case]]+
|-
| rowspan="1" colspan="1" |
[[#ui-case|case]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-ui-common|UI Common]], selected (xs:boolean), name (xs:string)
| rowspan="1" colspan="1" |
([[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*
|-
| rowspan="1" colspan="1" |
[[#action-toggle|toggle]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], case (xs:IDREF)
| rowspan="1" colspan="1" | [[#action-toggle-case|case]]?
|-
| [[#ui-dialog|dialog]]
| [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#attrs-ui-common|UI Common]],  level ("modeless"|"modal"|[[#def-PrefixedName|PrefixedName]]), hide (xs:boolean)
| ([[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*
|-
| [[#action-show|show]]
| [[#attrs-action-common|Action Common]], dialog (xs:IDREF)
| EMPTY
|-
| [[#action-hide|hide]]
| [[#attrs-action-common|Action Common]], dialog (xs:IDREF)
| EMPTY
|-
| rowspan="1" colspan="1" |
[[#ui-repeat|repeat]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-nodeset|Sequence Binding]], indexref (node Expression), startindex (xs:positiveInteger), number (xs:nonNegativeInteger)
| rowspan="1" colspan="1" |
([[#elems-all-controls|Controls]]|[[#action-content-set|Action]])*
|-
| rowspan="1" colspan="1" | Various (global attributes)
| rowspan="1" colspan="1" | [xforms:repeat-ref, xforms:repeat-nodeset (deprecated), xforms:repeat-bind, xforms:repeat-model] (Sequence Binding attributes), xforms:repeat-indexref (node Expression), xforms:repeat-startindex (xs:positiveInteger), xforms:repeat-number (xs:nonNegativeInteger)
| rowspan="1" colspan="1" | N/A
|}

<div class="div2">

===<span id="ui-group">The group Element</span>===

This control aggregates and sets the context for a group of enclosed controls; groups can be nested. The optional <code>label</code> represents a label for the entire group. The optional <code>collapse</code> attribute makes the group interactively collapsible.
<div class="desc">
Common Attributes: [[#structure-attrs-control-common|Control Common]]

Special Attribute:

;collapse
: Optional attribute to make the group collapsible. The value of the attribute gives its current state, one of ("open"|"closed"). If absent, the group is not collapsible.

Content: ([[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*
</div>
A <code>group</code> should have a block layout by default (e.g. a CSS styling of display:block); if the element has an <code>appearance</code> attribute with the value <code>minimal</code>, then the group should have an inline layout.

If the <code>collapse</code> attribute is present, the group is interactively collapsible, and the presentation of the group should make this apparent to the user. If the value of the attribute is <code>open</code> then the group and its label are made available to the user; if the value is <code>closed</code>, only the label is made available. Activating the group toggles between the two states.

If a <code>group</code> element is bound to a node, which is optional, only the <code>relevant</code> model item property has an effect. See [[#ui-processing|Implementation Requirements Common to All Controls]] for details of processing for non-relevance. If a group is disabled, then so is the entire content of the group.

<div class="example" title="group">
 <group ref="address" label="Shipping Address"/>
   <input ref="line_1" label="Address line 1"/>
   <input ref="line_2" label="Address line 2"/>
   <input ref="postcode" label="Postcode"/>
 </group>
</div>
<div class="example" title="collapse">
 <group collapse="open" ref="address" label="Shipping Address"/>
   <input ref="line_1" label="Address line 1"/>
   <input ref="line_2" label="Address line 2"/>
   <input ref="postcode" label="Postcode"/>
 </group>

A graphical browser might display this, toggling between this presentation:

[[Image:group-open.png|A group with collapse="open", showing a title "Shipping address, with an indication that its state is open, and controls for filling in an address]]

and this:

[[Image:group-closed.png|A group with collapse="closed", showing a title "Shipping address, with an indication that its state is closed, and nothing else.]]

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

===<span id="ui-switch">The switch Element</span>===

This is a [[#Container Controls|container control]] that allows parts of the user interface to be switched in and out.
It defines one or more <code>case</code> elements, one of which is rendered at any given time. 
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-single-node|Single Item Binding]] (optional)

Content: [[#ui-case|case]]+
</div>
Initially, and, if there are <code>case</code> elements with a <code>name</code> attribute, any time the value of the Single Node Binding (if present) changes:
* if there is a Single Item Binding, and any of the <code>case</code> elements has a <code>name</code> attribute, the Binding is evaluated as a string, and then compared one-by-one in document order with the <code>name</code> attribute on each case that has one; the first that matches, if any, causes that case to be selected;
* if there is no Binding, or no <code>name</code> matches, the first case with a <code>selected</code> attribute set to <code>true</code>, if any, is selected;
* otherwise the first <code>case</code> in document order is selected.

If a <code>switch</code> element is bound to a node via a Single Item Binding, but no <code>case</code> element has a <code>name</code> attribute, only the <code>relevant</code> model item property of the bound value has an effect, and changes to the bound value do not cause a new case to be selected. See [[#ui-processing|Implementation Requirements Common to All Controls]] for details of processing for non-relevance. If a <code>switch</code> is disabled, then so are all of its cases.

A case can also be selected using <code>toggle</code>, see the [[#action-toggle|toggle]] action for details.

<div class="note">
'''Note:''' A case is selected using the <code>name</code> attribute when selecting via the binding, and the <code>id</code> attribute when using <code>toggle</code>.
</div>

<div class="example" title="Switch with ref">
 <select1 ref="/payment/details/@method" label="Select Payment Method">
   <item label="Credit Card"       value="'creditCard'"/>
   <item label="Bank Account Card" value="'cashCard'"/>
   <item label="Cash on delivery"  value="'COD'"/>
 </select1>
 
 <switch ref="/payment/details/@method">
   <case/>
   <case name="creditCard" label="Credit Card Details">
     ...
   </case> 
   <case name="cashCard" label="Bank Account Card">
     ...
   </case>
   <case name="COD" label="Cash-on-delivery Account Information">
     ...
   </case>
 </switch>
In this example, if the payment method is initially empty, then the first, empty, <code>case</code> will be selected. Once the user chooses a payment method with the <code>select1</code>, then the <code>case</code> is selected whose name matches the selected <code>item</code> value.
</div>
<div class="example" title="Switch with toggle">
 <switch>
   <case id="in">
     <input ref="yourname" label="Please tell me your name">
       <toggle ev:event="DOMActivate" case="out"/>
     </input>
   </case>
   <case id="out">
       Hello <output ref="yourname"/>!
       <trigger label="Edit">
         <toggle ev:event="DOMActivate" case="in"/>
       </trigger>
   </case>
 </switch>
This 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>, switches to the alternate case, with an <code>output</code> rendering. Activating the trigger labeled "Edit" in turn switches back to the original case.
</div>
</div><div class="div3">

====<span id="ui-case">The case Element</span>====

This element contains markup to be conditionally rendered by a <code>switch</code>. 
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-ui-common|UI Common]]

Special Attributes:

; selected
: Optional initial selection status for the case, either <code>true</code> or <code>false</code>. The default value is <code>false</code>.

; name
: Optional name for the case, a string.

Content: ([[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*
</div>
Before a <code>case</code> is selected, any existing selected <code>case</code> is first deselected.

When a <code>case</code> is selected, it receives the event <code>xforms-select</code>, and its content is rendered. The content elements behave as if they were in a <code>group</code> that has become enabled (see [[#The group Element|The group Element]]).

When a <code>case</code> is deselected, it receives the event <code>xforms-deselect</code> and its content is no longer rendered. The content elements behave as if they were in a <code>group</code> element that has become disabled. 

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

===<span id="ui-dialog">The dialog Element</span>===
This [[#Container Controls|container control]] allows the definition of a dialog, which can be shown or hidden at different times.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#attrs-ui-common|UI Common]]

Special Attributes:

;level
: Optional dialog level identifier, one of ("modeless"|"modal"|[[#def-PrefixedName|PrefixedName]]). The default is "modal". This specification does not define behavior for PrefixedName values.
;hide
: Optional boolean, indicating if the processor should provide a way to hide the dialog. The default value is <code><nowiki>true</nowiki></code>. On a graphical browser an "x" could be shown in the dialog title bar when hide is set to <code><nowiki>true</nowiki></code>. If you specify <code><nowiki>hide="false"</nowiki></code>, then you should provide a way to hide the dialog, for instance by having you own "Close" button inside the dialog. This is typically useful when you want to force users to enter some data before proceeding and you don't want them to cancel the current operation by closing the dialog.

Content: ([[#elems-all-controls|Controls]]|[[#elems-ui-common|UI Common]])*
</div>
When a modal dialog is shown the user can't interact with any control on the page outside of that dialog. A graphical browser could visualize this by shielding the document  with a partially transparent mask when a modal dialog is shown.

The dialog generates an implicit group that contains the content elements (i.e. controls and host language elements). When the dialog is shown the implicit group is enabled, when the dialog is hidden the implicit group is disabled.

'''Note:''' It should be possible to show a new dialog from within a modal dialog.

<div class="example" title="dialog">
 <dialog id="my-dialog" label="Please enter your information">
   <input ref="first-name" label="First Name:"/>
   <input ref="last-name"  label="Last Name:"/>
   <input ref="e-mail" label="E-mail:"/>
   <trigger label="Submit">
     <hide ev:event="DOMActivate" dialog="my-dialog"/>
   </trigger>
 </dialog>

A graphical browser might render the above <code>dialog</code> as follows:

[[Image:Dialog$dialog.png|An example dialog]]
</div>
====<span id="action-show">The show Element</span>====
This action shows a specified dialog.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

;dialog
: Required reference to the ID of a <code>dialog</code> element.

Content: EMPTY
</div>
An [[#model-update|update]] is done if necessary.

A <code>dialog</code> element is identified using the <code>dialog</code> attribute. If no such element exists, this action has no effect.

An [[#The_xforms-dialog-show_Event|xforms-dialog-show]] event is dispatched to the identified element.

====<span id="action-hide">The hide Element</span>====
This action hides a specified dialog.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

;dialog
:Required reference to the ID of a <code>dialog</code> element.

Content: EMPTY
</div>
An [[#model-update|update]] is done if necessary.

A <code>dialog</code> element is identified using the <code>dialog</code> attribute. If no such element exists, this action has no effect.

An [[#The_xforms-dialog-hide_Event|xforms-dialog-hide]] event is dispatched to the identified element.

==== The xforms-dialog-show Event ====
Dispatched in response to a [[#The_show_Element|show action]] executed with an existing dialog id.
<div class="desc">
Target:<code>dialog</code>
Bubbles: Yes
Cancelable: Yes
Context Info: none

Default action: Show the dialog if it isn't shown already.
</div>
The default action for this event results in the following steps:
# Adjusts the shown state of the dialog.
# Makes the dialog available to the user.
# Dispatches the [[#The_xforms-dialog-shown_Event|xforms-dialog-shown]] event

==== The xforms-dialog-hide Event ====

Dispatched in response to a [[#The_hide_Element|hide action]] executed with an existing dialog id.
<div class="desc">
Target: <code>dialog</code>
Bubbles: Yes
Cancelable: Yes
Context Info: none

Default action: Hide the dialog if it isn't hidden already.
</div>
The default action for this event results in the following steps:
# Adjusts the shown state of the dialog.
# Makes the dialog unavailable to the user.
# Dispatches the [[#The_xforms-dialog-hidden_Event|xforms-dialog-hidden]] event

==== The xforms-dialog-shown Event ====

Dispatched in response to a dialog being shown.
<div class="desc">
Target:<code>dialog</code>
Bubbles: Yes
Cancelable: No
Context Info: none

Default action: none; notification event only.
</div>

==== The xforms-dialog-hidden Event ====

Dispatched in response to a dialog being hidden.
<div class="desc">
Target: <code>dialog</code>
Bubbles: Yes
Cancelable: No
Context Info: none

Default action: none; notification event only.
</div>

===<span id="ui-repeat">The repeat Element</span>===

This [[#Container Controls|container control]] binds to a sequence of values, allowing a user interface to be generated for each item in the sequence. 
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#attrs-appearance|Appearance]], [[#structure-attrs-nodeset|Sequence Binding]]

Special Attributes:

; indexref
: Optional [[#structure-attrs-single-node|Single Item Binding]] to simpleContent, with which the repeat index is synchronized.
; startindex
: Optional 1-based initial value of the repeat index. The default value is 1. This attribute is ignored if <code>indexref</code> is specified.
; number
: Optional hint of how many elements of the repeat collection to display.

Content: ([[#elems-all-controls|Controls]]|[[#action-content-set|Action]])*
</div>
A repeat control consists of 
* a sequence of items called the <span id="defn-repeat-collection">'''repeat collection'''</span>;
* an index into that collection called the <span id="defn-repeat-index">'''repeat index'''</span>, with a value between 0 and the size of the collection (only ever zero if the sequence is empty), that indicates which repeat item has, or last had, the user focus;
* an optional index reference which reflects the current value of the index; and
* the <span id="defn-repeat-template">'''repeat template'''</span>, which is a copy of the original content of the repeat element.

For each item in the repeat collection, a <span id="def-repeat-item">'''repeat item'''</span> is defined, consisting of the item, and a <span id="def-repeat-object">'''repeat object'''</span> consisting of an implicitly generated <code>group</code> element that binds to the item, and containing a copy of the template. Unlike an explicit <code>group</code>, the binding to the item does not reset the size and position of its context.

These repeat objects together form the run-time content of the repeat.

That is to say, a repeat like
 <repeat ref="/products/product" class="list">
   <output ref="."/><html:br/>
 </repeat>

is conceptually similar to
 <group class="list">
    <group ref="/products/product[1]"><output ref="."/><html:br/></group>
    <group ref="/products/product[2]"><output ref="."/><html:br/></group>
    <group ref="/products/product[3]"><output ref="."/><html:br/></group>
    <group ref="/products/product[4]"><output ref="."/><html:br/></group>
 </group>
<div class="note>
'''Note:''' the repeat collection can be an arbitrary sequence of items: nodes, atomic values or a mix. They don't have to be in document order, and the same node can occur multiple times.
</div>
====<span id="ui-repeat-processing">Repeat Processing</span>====

=====<span id="repeat-initialization">Repeat Initialization</span>=====
During user interface initialization (see [[#The xforms-model-construct-done Event|The xforms-model-construct-done Event]]), the following steps are performed:

# The Sequence Binding is evaluated to give the repeat collection;
# The repeat index is initialized:
## If the collection is empty, 0 is used; otherwise
## If the <code>indexref</code> attribute is specified, it is evaluated as a number in the [[#in-scope-evaluation-context|in-scope evaluation context]] and rounded to the nearest integer. If it is a number it is used, and otherwise 1; otherwise
## If the <code>startindex</code> attribute is specified, its value is used;
## Otherwise 1 is used.
#:If the resulting value is less than 1, and the sequence is not empty, 1 is used, otherwise if it is larger than the size of the collection, the size of the collection is used. 
# A repeat object is generated for each repeat item using the repeat template.

=====Updating=====

Whenever a new item is added to the repeat collection, by whatever means, a new repeat item is created dynamically, and the resulting repeat object is initialized.

Whenever an item is removed from the repeat collection, by whatever means, the corresponding repeat object is eliminated.

These actions must be done before the dispatch of the [[#evt-insert|xforms-insert]] and [[#evt-delete|xforms-delete]] events, so that event handlers for them have access to the new value of the repeat index.

=====<span id="ui-repeat-index-processing">Index Processing</span>=====

If <code>indexref</code> has been specified for a repeat, it is kept up-to-date with the current value of the repeat index: if the repeat index changes, <code>indexref</code> is changed to match, and vice versa. However, this is only possible if <code>indexref</code> references a node that is not readonly. If it is, changes to  <code>indexref</code> will change the repeat index, but not vice versa.

If a new value of the repeat index is ever greater than the size of the repeat collection, the repeat index is set to the size of the repeat collection and the <code>xforms-scroll-last</code> event is dispatched to the repeat.

Similarly, if a new value is ever less than 1 (or 0 for an empty sequence), then <code>xforms-scroll-first</code> is dispatched to the <code>repeat</code> element, and the index is set to 1 (or 0 for an empty sequence).

If items are added to the repeat collection, then the repeat index is set to the position of the last item added.

If items are removed from the repeat collection:
* if, prior to deletion, the repeat index indicated an item still contained in the collection after deletion, then the index is adjusted as necessary to indicate the same item;
* if the repeat index indicated one of the deleted items and the new size of the collection is smaller than the index, the index is changed to the new size;
* otherwise the index is not changed.

Whenever a repeat index is changed, focus is given to the corresponding repeat element, as if by a <code>setfocus</code> action.

<div class="note">
'''Note:''' the value of the repeat index is also available via the <code>index()</code> function, and can be set with the [[#action-setindex|<code>setindex</code>]] action.
</div>

<div class="note">
'''Note:''' attributes that contain an <code>IDREF</code> must be interpreted based on a combination of repeat indexes and where the IDREF attributes appear relative to the element bearing the matching ID. See [[#idref-resolve|Resolving ID References]], for details.
</div>

=====<span id="ui-repeat-ui">Interaction and rendering</span>=====

Repeat items should have a block layout by default (e.g. a CSS styling of display:block). If the <code>repeat</code> element has an <code>appearance</code> attribute with the value <code>minimal</code>, then the repeat items have an inline layout:

 <repeat appearance="minimal" ref="keyword">
    <output value="concat(., if(last(), &apos;&apos;, ', '))"/>
 </repeat>


This can also be achieved with the CSS pseudo-element <code>repeat-item</code>, for instance:

 .list ::repeat-item {display: inline}

 <repeat class="list" ref="1 to 10">
   <output ref="."/>
 </repeat>

The rendering of the repeat item currently referred to by the repeat index can be displayed specially using the pseudo-element <code>::repeat-index</code>:

 ::repeat-index {background-color: yellow}

The number of displayed items might be less than the total number available in the collection; for example, responding to the <code>count</code> attribute hint, 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, and not allowed to scroll out of view.

If the focus is given to a control within a <code>repeat</code> by any means, such as by an XForms action or by user interaction, the repeat index is set to the position of the repeat item that contains the control, and the repeat index of all containing repeats are adjusted appropriately. A repeat index is changed as if by a <code>setindex</code> action.

If focus is given to a <code>repeat</code> element, focus goes to the first enclosed control in navigation order that can accept focus within the repeat item indicated by the repeat index.

If an item of the repeat collection is non-relevant, then the associated repeat object is disabled.

=====Events and Actions=====

Since repeat objects are copies of the repeat template, including action handlers, the action handlers for events targeted at a <code>repeat</code> element should be placed outside of the repeat template, for example:

 <repeat id="X" ... >
   ...
 </repeat>
 
 <action ev:event="xforms-scroll-first" ev:target="X" ev:observer="X">
   ...
 </action>

=====Examples=====
<div class="example" title="Simple repeat">
 <instance>
    <countries>
       <country capital="Paris">France</country>
       <country capital="Rome">Italy</country>
       <country capital="Amsterdam">The Netherlands</country>
    </countries>
 </instance>

 <repeat ref="country">
    <output label="Country" ref="."/>
    <output label="Capital" ref="@capital"/>
 </repeat>
</div>

<div class="example" title="Repeat over atomic values">
 <repeat ref="1 to count(table)">
   <output value="table[.]" label="[{.}]:"/>
 </repeat>
</div>
<div class="example" title="repeat over a heterogeneous instance">
Given the instance:
 <instance>
    <description xmlns="">
        <function>sqrt</function>
        applied to:
        <x>6.25</x>
        &lt;!-- gives two results --&gt;
        <r>2.5</r>
        <r>-2.5</r>
    </description>
 </instance>
Using <code>node()</code> and <code>name()</code>:
 <repeat ref="node()">
    <output ref="." label="{name(.)}"/>
 </repeat>
would give
 function sqrt
 #text    applied to: 
 x        6.25
 #comment gives two results 
 r        2.5
 r        -2.5
while using <code>*</code> and <code>name</code> 
 <repeat ref="*">
    <output ref="." label="name(.)"/>
 </repeat>
would give:
 function sqrt
 x        6.25
 r        2.5
 r        -2.5
</div>
<div class="example" title="Inserting and deleting items">
 <instance>
    <lines xmlns="">
       <line name="a"><price>3.00</price></line>
       <line name="b"><price>32.25</price></line>
       <line name="c"><price>132.99</price></line>
    </lines>
    &lt;i/>
 </instance>

 <repeat ref="line" indexref="i">
   <input ref="@name" label="Name"/>
   <input ref="price" label="Price"/>
 </repeat>
 
 <trigger label="Insert a new item after the current one">
   <action ev:event="DOMActivate">
     <insert ref="line" at="i" position="after"/>
     <setvalue ref="line[i]/@name"/>
     <setvalue ref="line[i]/price">0.00</setvalue>
   </action>
 </trigger>
 
 <trigger label="remove current item">
   <delete ev:event="DOMActivate" ref="line" at="i"/>
 </trigger>
</div>
</div><div class="div3">

====<span id="ui.repeat.via.attrs">Creating Repeating Structures Via Attributes</span>====
When using XForms within host languages like XHTML, it can be necessary to create repeating structures within constructs that don't accept the <code>repeat</code> element as content, such as <code>table</code>. 

To help integrate repeat behavior into host languages, there is an alternative syntax using the following global attributes that is functionally equivalent to the <code>repeat</code> element:

<blockquote>
<code>xforms:repeat-model</code><br />
<code>xforms:repeat-bind</code><br />
<code>xforms:repeat-ref</code><br />
<code>xforms:repeat-nodeset</code> (deprecated)<br />
<code>xforms:repeat-startindex</code><br />
<code>xforms:repeat-number</code><br />
<code>xforms:repeat-indexref</code>
</blockquote>

These attributes are equivalent to the local <code>repeat</code> attributes of the comparable name. A host language can allow these attributes in the appropriate places to enable repeating constructs.

When using the <code>setindex</code> action, its <code>repeat</code> attribute of type <code>idref</code> can point to any element carrying these global repeat attributes. 

Similarly, when using function <code>index</code> for a repeating structure created using the global repeat attributes, the <code>id</code> of that element can be used as the argument to function <code>index</code>.

<div class="example" title="global repeat attributes on an XHTML table">
A version of XHTML might allow the following:
 &lt;table xforms:repeat-ref="...">
   &lt;tr>
     &lt;td><xforms:output ref="..."/></td>
   &lt;/tr>
 &lt;/table>

Note that what gets repeated is the content of the element with the global <code>repeat-</code> attributes, i.e. in this case, the <code>tr</code> is repeated, not the <code>table</code>.  
</div>
<div class="example" title="XHTML table with headers">
 &lt;table>
    &lt;thead>
       <tr>
          <th>Country</th>
          <th>Capital</th>
       </tr>
    </thead>
    &lt;tbody xforms:repeat-ref="countries/country">
       &lt;tr>
          &lt;td><xforms:output ref="."/></td>
          &lt;td><xforms:output ref="@capital"/></td>
       &lt;/tr>
    </tbody>
 &lt;/table>
</div>
</div></div></div>

==<span id="submit">Submission</span>==

Submitting data happens as a response to a [[#submit-submission-element|<code>submission</code> element]] receiving an [[#submit-evt-submit|<code>xforms-submit</code> event]]. This is typically dispatched by a [[#ui-submit|<code>submit</code> control]], or a [[#action-send|<code>send</code> action]].

In brief: the data to be submitted is selected, checked for validity if necessary, serialized, and sent to the receiving service. When the reply is received, it is checked for success, and any associated data is then processed as required.

{| summary="listing of XForms submission element attributes and content model" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" | [[#submit-submission-element|submission]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]]<br />
[[#structure-attrs-evaluation|Evaluation]]<br />
[[#structure-attrs-single-node|Single Item Binding]]<br />
value (expression)<br />
nonrelevant ("keep" | "remove" | "empty")<br />
relevant (xs:boolean) [deprecated]<br />
validate (xs:boolean)<br />

resource (xs:anyURI)<br />
action (xs: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-PrefixedName|PrefixedName]])<br />
serialization (xs:string)<br />
mediatype (xs:string)<br />
encoding (xs:string)<br />

separator (";" | "&amp;")<br />

version (xs:NMTOKEN)<br />
indent (xs:boolean)<br />
omit-xml-declaration (xs:boolean)<br />
standalone (xs:boolean)<br />
cdata-section-elements (QNameList)<br />
includenamespaceprefixes (xs:NMTOKENS)<br />

response-mediatype (xs:string)<br />
replace ("all" | "instance" | "text" | "none" | [[#def-PrefixedName|PrefixedName]])<br />
instance (xs:IDREF)<br />
targetref ([[#structure-attrs-single-node | Single Item Binding]])<br />
target ("_self" | "_blank" | xs:string)
| rowspan="1" colspan="1" |
([[#submit-resource-elem|resource]] [deprecated] | [[#submit-method-elem| method]] [deprecated] | [[#submit-header| header]])*, [[#action-content-set|Action]]<nowiki>*</nowiki>
|}

The following table summarizes the child elements of the <code>submission</code> element. Elements defined in the [[##action-content-set|Actions]] module are also allowed.

{| 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" | Attributes and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" | [[#submit-resource-elem|resource]] (deprecated)
| rowspan="1" colspan="1" | [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], value (string Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" | [[#submit-method-elem|method]] (deprecated)
| rowspan="1" colspan="1" | [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], value (string Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" | [[#submit-header|header]]
| rowspan="1" colspan="1" | [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-nodeset|Sequence Binding]], name (xs:string), value (string Expression)
| rowspan="1" colspan="1" | [[#submit-header-name|name]] [deprecated], [[#submit-header-value|value]]+ [deprecated]
|-
| rowspan="1" colspan="1" | [[#submit-header-name|name]] (for header) (deprecated)
| rowspan="1" colspan="1" | [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-nodeset|Sequence Binding]], name (xs:string), value (string Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" | [[#submit-header-value|value]] (for header) (deprecated)
| rowspan="1" colspan="1" | [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-nodeset|Sequence Binding]], name (xs:string), value (string Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-content-set|Action]]
| rowspan="1" colspan="1" | various
| rowspan="1" colspan="1" | various
|}

<div class="div2">
===<span id="submit-submission-element">The submission Element</span>===

The attributes of <code>submission</code> can be divided into three groups, describing ''what'' is to be submitted, ''how'' it is to be submitted, and what to do with the result.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]

Special Attributes:

''What to submit:''

; [[#structure-attrs-single-node|Single Item Binding]]
: Optional binding that selects the data to be submitted: the node and all its descendants are selected. The default is "/".
; value
: Optional expression, overriding the single item binding, that calculates a value representing the data to be submitted. If this attribute is present, the <code>relevant</code>, <code>nonrelevant</code>, <code>validate</code> and <code>serialization</code> attributes are ignored.
; nonrelevant
: Optional string indicating whether non-relevant values are included in the serialized data; it has no effect if <code>serialization</code> is <code>"none"</code>. Values are <code>"keep"</code>: all values are serialized, <code>"remove"</code>: non-relevant values are not serialised, <code>"empty"</code>: non-relevant nodes are serialized as empty values. The default is <code>"remove"</code>.
; relevant [deprecated in favor of attribute <code>nonrelevant</code>]
: Optional boolean indicating whether only relevant data is serialized. This attribute has no effect if <code>nonrelevant</code> is specified, or <code>serialization</code> is <code>"none"</code>. Values are <code>"true"</code>: equivalent to <code>nonrelevant="remove"</code>, and <code>"false"</code>: equivalent to <code>nonrelevant="keep"</code>. The default is "true".
; validate
: Optional boolean indicating whether data validation is performed. The default is "false" if the value of <code>serialization</code> is "none" and "true" otherwise.

''How to submit it:''

; resource
: URI indicating the destination for the submission. This attribute is required unless the destination URI is provided by the (deprecated) [[#submit-resource-elem | <code>resource</code>]] element, or the (deprecated) <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]
: Optional URI indicating the destination for the submission. Use <code>resource</code> for preference.
; mode
: Optional string defaulting to "asynchronous" and with legal values of "synchronous" and "asynchronous". This controls whether or not user interaction can continue while the submission is in progress, or whether the system blocks until the result has been received.
; method
: Optional string specifying the protocol method to be used to transmit the submission, with a default of "get". See Section [[#submit-protocols|Submission Protocols]] 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>.
; serialization
: Optional string that controls how to serialize the submission data. The format is ''type/subtype'', or the single word "none". Allowable values are "application/xml", "application/x-www-form-urlencoded", "multipart/related", "multipart/form-data", or any of the values allowed in the section [[#initialize-instance-external|Creating instance data from external resources]]. The default value of this attribute is based on the submission <code>method</code> as described in Section [[#submit-protocols|Submission Protocols]]. If the attribute value is "none", then instance data is not serialized, which is useful for requests that either require no data or that have the data already in the URI.
; mediatype
: Optional string specifying the mediatype of the serialization, to be used in the <code>Content-type</code> header of HTTP, or similar, according to the format specified in <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki>. It is the author's responsibility to ensure that the type specified is compatible with the serialization used, such as <code>application/xhtml+xml</code> for posted XML data. The default is serialization-dependent, but is "application/xml" for XML serialization. <div class="note">'''Note:''' This attribute does not affect serialization nor does it override the <code>serialization</code> attribute. It is only used to provide additional information about the submission data.</div>
; encoding
: Optional string specifying the character encoding to be used for serialization. The default is "UTF-8".

If the data is serialized as urlencoded, the following attribute applies:
; separator
: Optional string specifying the separator character between name/value pairs if the serialization used is "application/x-www-form-urlencoded"; otherwise the attribute is ignored. The default is '&'.

If the data is serialized as XML, the following attributes apply:
; version
: Optional string specifying the <code>version</code> of XML to be serialized. The default is "1.0".
; indent
: Optional boolean specifying whether the serializer should add extra white space nodes for readability. The default is "false".
; omit-xml-declaration
: Optional boolean specifying whether to omit the XML declaration on the serialized instance data. The default value is "false".
; standalone
: Optional string specifying whether to include a standalone declaration in the serialized XML. If omitted, then the XML declaration does not include a standalone document declaration; if the <code>omit-xml-declaration</code> attribute has the value <code>true</code>, this attribute is ignored; otherwise the XML declaration includes a standalone document declaration with the same value as this attribute.
; cdata-section-elements
: Optional string specifying element names to be serialized with CDATA sections. The default is empty string.
; includenamespaceprefixes
: Optional string 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 <nowiki>[</nowiki>[[#ref-Exc-C14N |Exc-C14N]]<nowiki>]</nowiki>, the special value <code><nowiki>#default</nowiki></code> specifies the default namespace. When this attribute is present all namespace prefixes not visibly utilized by the submitted instance data are listed.

''What to do with the result:''

;response-mediatype
: Optional mediatype overriding the content-type reported for the returned data.
; replace
: Optional string specifying how the information returned after submit should be applied. The legal values are "all", "instance", "text" and "none", with a default of "all". See [[#Processing_the_Response_from_a_Submission|Processing the Response from a Submission]].
; instance
: Optional IDREF identifying the instance to replace when the <code>replace</code> attribute value is "instance". The default is the instance that contains the submission data. When the <code>replace</code> value is not "instance", this attribute is ignored.
; targetref
: Optional [[#structure-attrs-single-node|Single Item Binding]] that indicates the target node for data replacement. The [[#in-scope-evaluation-context|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.
; target
: Optional presentation context name or keyword when the <code>replace</code> attribute value is "all". Behavior is defined for values "_self" and "_blank"; the default is "_self". In addition, an implementation-dependent presentation context name can be specified. The following are the possible values for the <code>target</code> attribute and the corresponding processing behaviors:
:
:; _self
:: The document is loaded into the current presentation context. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document.
:; _blank
:: The document is loaded into a new presentation context, e.g., a new window or tab. Form processing in the original window or tab continues.
:; Any other value
:: The behavior is implementation-dependent. {{SpecNote|If the host language is HTML, the implementation is encouraged to handle the <code>target</code> attribute as defined in HTML for the <code>form</code> element. In particular, values of "_self", "_blank", "_parent", "_top", as well as browsing context names should be supported.}}

Content: ([[#submit-resource-elem|resource]] [deprecated] | [[#submit-method-elem| method]] [deprecated] | [[#submit-header| header]])*, [[#action-content-set|Action]]<nowiki>*</nowiki>
</div>
<div class="example" title="submission elements">
 <submission<nowiki>
   resource="http://example.com/search"/>

 <submission
   resource="http://example.com/search"
   method="put"/>

 <submission
   resource="http://example.com/search"
   replace="instance"
   instance="results"/>

 <submission
   ref="instance('reference')"
   resource="http://example.com/locate-address"
   replace="instance"
   instance="address"/>

 <submission
   ref="instance('address')"
   resource="http://example.com/new-address"
   method="post"
   replace="none"/>

 <submission id="s1"
   resource="http://example.org/api.php?action=search&amp;format=json&amp;search={search}"
   mediatype="application/json"
   serialization="none"
   mode="synchronous"
   replace="instance"
   instance="iresults"/></nowiki>
</div>
</div>

<div class="div2">

====<span id="submit-header">The header Element (for submission)</span>====

This element is used to change headers, or add extra headers to a submission protocol. 

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-nodeset|Sequence Binding]], [[#structure-attrs-value|value]]

Special Attributes:

;name
: Optional string that overrides the <code>name</code> child element if present.
; combine
: Optional string defaulting to "append" and with legal values of "append", "prepend", and "replace". 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 submission headers with headers provided by the user agent.

Any <code>value</code> attribute present overrides all <code>value</code> child elements.

Content: PCDATA | ([[#submit-header-name|name]], [[#submit-header-value|value]]+) | ([[#submit-header-value|value]]+, [[#submit-header-name|name]])
</div>
The [[#submit-submission-element|<code>submission</code> element]] can contain zero or more <code>header</code> child elements: each produces zero or more header entries containing a name and a value, and how they are to be combined with existing headers. 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 suitably.

* If the <code>header</code> element contains a <code>name</code> attribute, it is used for name of the headers being produced; otherwise there must be a <code>name</code> child element, which is used instead. If the name evaluates to the empty string, no header is produced.

* If the <code>header</code> element has a Sequence Binding, then for each selected item, the values are evaluated; otherwise the values are evaluated once.

* The values are evaluated as follows: if the header element has a <code>value</code> attribute, one header is produced using the name of the header being produced, and the evaluated content of the <code>value</code> attribute; otherwise if there are one or more <code>value</code> child elements, one header is produced per <code>value</code> child element; otherwise one header is produced using the inline content of the element.

The header entry order is determined as follows:

# document order of <code>header</code> elements
# item order of items in <code>ref</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.

<div class="example" title="Setting the Accept header">
 <nowiki><submission
   id="loadConcepts"
   resource="http://example.com/taxonomy/concepts"
   method="get"
   ref="instance('conceptsList')"
   replace="instance">
   <header name="Accept"
     combine="replace">application/sparql-results+xml</header>
 </submission></nowiki>
The submission 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>.
Note that the <code>name</code> attribute is a string, but that <code>value</code>, like all such-named attributes in XForms, is an expression, and so the value must be quoted if it is a string.
</div>
<div class="example" title="Using ref">
 <instance id="headers">
   <my-headers>
     <my-header><head>Content-Type</head><content>application/xml</content></my-header>
     <my-header><head>Accept</head><content>application/xml,application/json</content></my-header>
   </my-headers>
 </instance>
 <submission ...>
    <header
      ref="instance('headers')/my-header"
      name="{head}"
      value="content"/>
 </submission>

This example produces 2 headers:
 Content-Type: application/xml
 Accept: application/xml,application/json
</div></div>

<div class="div3">

=====<span id="submit-header-name">The name Element (for header) (Deprecated)</span>=====

This element, deprecated in favor of using an AVT in the <code>name</code> attribute of the <code>header</code> element, specifies the name of a header entry to be provided to the submission protocol.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
If the <code>model</code> attribute is present and does not identify the containing model, an [[#The xforms-binding-error Event|xforms-binding-error]] is dispatched to the <code>name</code> element.

The header entry name is obtained by evaluating the <code>value</code> attribute if present, and otherwise from the element content. If the result is the empty string, then the entry is considered to be void, and it is not supplied to the submission protocol.

<div class="example" title="name elements">
 <name>Accept</name>
 <name value="'Accept'"/>
 <name value="../header"/
</div>

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

=====<span id="submit-header-value">The value Element (for header) (Deprecated)</span>=====

This element, deprecated in favor of using an AVT in the <code>value</code> attribute of the <code>header</code> element, specifies the value component of a header entry; it may be used more than once in a given element <code>header</code>, in which case each value produces a new header entry.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
If the <code>model</code> attribute is present and does not identify the containing model, an [[#The xforms-binding-error Event|xforms-binding-error]] is dispatched to the <code>value</code> element.

The header entry value is obtained by evaluating the <code>value</code> attribute if present, or otherwise from the string content of the <code>value</code> element.

<div class="example" title="value elements">
 <value>text/css</value>
 <value value="'text/css'"/>
 <value value="../accepted"/
</div>

<div class="note">
'''Note:''' The <code>string</code> conversion function as described in the [[#def-expression-module|expression module]] combines multiple items by concatenating them into a string separated with spaces. As a result, a header value specified by a <code>value</code> element sequence containing multiple items 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 expressions producing sequences for element <code>header</code> with attribute <code>ref</code>, where each item will produce its own separate header entry, and use expressions resulting in only a single item in element <code>value</code>.
</div>
</div>

<div class="div2">

====<span id="submit-resource-elem">The resource Element (Deprecated)</span>====

The <code>resource</code> element (deprecated in favor of using an AVT in the resource attribute) provides the URI used for a submission.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The URI is obtained by evaluating the value attribute, or otherwise from the inline content of the element.

If a <code>submission</code> has more than one <code>resource</code> child element, the first is used.

<div class="example" title="resource elements">
 <nowiki> <submission method="post">
    <resource value="instance('params')/anyURI"/>
 </submission>
 <submission method="get">
    <resource>http://www.example.com/index.html</resource>
 </submission></nowiki>

These are deprecated in favour of the equivalent:

 <nowiki> <submission method="post" resource="{instance('params')/anyURI}"/>
 <submission method="get" resource="http://www.example.com/index.html"/></nowiki>
</div>
</div>
<div class="div2">

====<span id="submit-method-elem">The method Element (Deprecated)</span>====

The <code>method</code> element  (deprecated in favor of using an AVT in the method attribute) provides the method to be used by a submission.

<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The method to be used is obtained by evaluating the <code>value</code> attribute, or otherwise from the string content of the <code>method</code> element.

</div>


<div class="div2">

===<span id="submission-processing">Submission Processing</span>===
In brief, data is selected, checked for validity as necessary, serialized in the required form, and sent to the server. The server sends a response, possibly accompanied by some data which is then dealt with appropriately.

No more than a single submit process can be under way at any time for a particular <code>submission</code> element. From the start of the default action of <code>xforms-submit</code> for a <code>submission</code>, until immediately before [[#submit-evt-submit-done|xforms-submit-done]] or [[#submit-evt-submit-error|xforms-submit-error]] is dispatched to that <code>submission</code>, the default action for subsequent <code>xforms-submit</code> events dispatched to that <code>submission</code> is for those submissions to fail with <code>submission-in-progress</code>.

For brevity in the following, the text "'''submission succeeds'''" means "submission processing concludes after dispatching [[#submit-evt-submit-done|xforms-submit-done]]  to the <code>submission</code> element, with appropriate context information", and the text "'''submission fails with ''error-code'''''" means "the submission processing concludes after dispatching [[#submit-evt-submit-error|xforms-submit-error]] to the <code>submission</code> element, with appropriate context information, including an <code>error-type</code> of ''error-code''". Additionally, "'''and an error-message of ''some value'''''" means that the context information also includes an entry called <code>error-message</code> with that value.

====<span id="submission-processing-select">Selecting and Validating the Submission Data</span>====

If the <code>serialization</code> attribute value is <code>"none"</code>, no data is selected.

Otherwise an [[#model-update|update]] is done if necessary.

* If the <code>value</code> attribute is present, it is evaluated and converted to a string.
* Otherwise, the binding attributes of <code>submission</code> are evaluated; if the result is the empty sequence or an item other than an element or an instance document root node, submission fails with <code>no-data</code>. A copy of the evaluated node and its descendent nodes are selected. Non-relevant nodes are either deselected, or made empty, according to the value of the <code>nonrelevant</code> attribute, or the deprecated <code>relevant</code> attribute. If no nodes remain, submission fails with <code>no-relevant-data</code>. If the attribute <code>validate</code> is <code>true</code>, whether by default or declaration, and any selected instance data node is invalid, submission fails with <code>validation-error</code>.

====<span id="submission-processing-serialize">Serializing the Data</span>====
The submission method is obtained from the <code>method</code> attribute if present, otherwise from the first <code>method</code> child element if any, and otherwise is "get".

The submission resource is obtained from the <code>resource</code> attribute if present, otherwise from the deprecated <code>action</code> attribute if present, and otherwise from the first <code>resource</code> child element, if any; otherwise submission fails with <code>resource-error</code>.

If the value of the submission resource is an absolute URI it is used as  
the submission URI; otherwise (it is a relative URI) the submission URI is constructed by combining the relevant parts of the value of <code>location-uri()</code> and the submission resource.

The protocol to be used is determined from the submission URI.

The serialized data is obtained:
* If the <code>serialization</code> attribute value is <code>"none"</code>, then the empty string is used. 
* Otherwise, the (deprecated) [[#submit-evt-submit-serialize|xforms-submit-serialize]] event is dispatched to the <code>submission</code> element; if the <code>submission-body</code> property of the event is changed from the initial value of empty string, then its content is used.
* Otherwise, if the <code>value</code> attribute was present, then the string obtained from evaluating that is used.
* Otherwise, the default serialization format is determined according to the rules stated in [[#submit-protocols|Submission Protocols]], based on the method and the protocol; if the default is <code>application/xml</code> and the <code>serialization</code> attribute contains a value, that value is used; otherwise the default format is used; the selected data is then serialized in that format according to the rules stated in [[#serialization|Serialization Formats]].

====<span id="submission-processing-submitting">Submitting the Data</span>====
If the data is non-empty and is to be delivered as part of the URI (and has therefore been serialized as <code>application/x-www-form-urlencoded</code>):
* if the submission URI doesn't contain a ? (question mark) character, one is appended;
* otherwise if it doesn't end with the separator character from the <code>separator</code> attribute or its default, one is appended;
* finally the serialized data is appended.

The submission headers 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 using the submission headers, method, resource, and serialized data, as defined in [[#submit-protocols|Submission Protocols]].

If the <code>mode</code> of the <code>submission</code> is <code>asynchronous</code>, processing ends after the above steps. 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 user interaction with all document controls and action processing is suspended until the response from the submission is returned.

{{SpecNote|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 class="example" title="catching and reporting xforms-submit-error">
 <submission resource="..." ...>
    <message ev:event="xforms-submit-error">
       Submission error.
          error-type: <output value="event('error-type')"/>
          error-message: <output value="event('error-message')"/>
          resource-uri: <output value="event('resource-uri')"/>
          response-status-code: <output value="event('response-status-code')"/>
          response-reason-phrase: <output value="event('response-reason-phrase')"/>
    </message>
 </submission>
</div>

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

====<span id="submission-response">Processing the Response from a Submission</span>====

For success responses, if the response does not include a body, submission succeeds; otherwise, processing depends on the value of the <code>replace</code> attribute on element <code>submission</code>:
*<code>none</code>: submission succeeds.
*<code>all</code>: the event [[#submit-evt-submit-done|xforms-submit-done]] [[#intro-reading|may]] be dispatched with appropriate context information, and submit processing concludes with the entire containing document being replaced with the returned body.
*<code>instance</code>: If the type of the body, as overridden by the <code>response-mediatype</code> attribute if present, is not amongst those accepted by the processor, as specified in [[#initialize-instance-external|Creating instance data from external resources]], nothing in the document is replaced and submission fails with <code>result-mediatype</code>, and an error-message of the unacceptable mediatype. Otherwise the body is parsed to give an XPath Data Model according to [[#initialize-instance-external|Creating instance data from external resources]]. If the parse fails, then submission fails with <code>parse-error</code>. If the parse succeeds, then instance data replacement is performed according to [[#Replacing Data with the Submission Response|Replacing Data with the Submission Response]]. If this operation succeeds, submission succeeds.
*<code>text</code>: If the type of the body, as overridden by the <code>response-mediatype</code> attribute if present, is neither amongst those accepted by the processor, as specified in [[#initialize-instance-external|Creating instance data from external resources]], nor a text type (i.e. with a content type not matching <code>text/*</code>), nothing in the document is replaced and submission fails with <code>result-text-mediatype</code>, and an error-message of the unacceptable mediatype. Otherwise the content replacement is performed according to [[#Replacing Data with the Submission Response|Replacing Data with the Submission Response]]. If this operation succeeds, submission succeeds.

For error responses, processing depends on the value of the <code>replace</code> attribute on element <code>submission</code>:
* <code>all</code>: either the document is replaced with an implementation-specific indication of an error, or submission fails with <code>result-error-response</code>.
* any other value: nothing in the document is replaced, and submission fails with <code>result-error-response</code>.
(Further details of the failure are available in the context information).

Behaviors of other possible values for attribute <code>replace</code> are not defined in this specification.

In addition to initiating a submission with its default processing, XForms actions can also provide handlers for the <code>xforms-submit</code> event to perform tasks such as data preparation.

<div class="example" title="Preparing data for submission">
 <nowiki><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></nowiki>

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="div3">

====<span id="submit-data-replacement">Replacing Data with the Submission Response</span>====

First, the '''replacement target node''' is determined from the attributes of the <code>submission</code> element:

* if there is neither an <code>instance</code> attribute nor a <code>targetref</code> attribute, the replacement target node is the document element node of the default instance of the model;

* if there is an <code>instance</code> attribute but no <code>targetref</code> attribute, the replacement target node is the document element node of the instance identified by the <code>instance</code> attribute;

* if there is a <code>targetref</code> attribute, it is evaluated in the [[#in-scope-evaluation-context|in-scope evaluation context]] for the <code>submission</code> element to obtain the replacement target node, except the context item is modified to be the document element of the instance identified by the <code>instance</code> attribute if present.

Then the target is checked for correctness:

* if the <code>instance</code> attribute does not indicate an instance in the same model as the submission, submission fails with <code>target-model-error</code>;
* if the replacement target node is the empty sequence, submission fails with <code>target-empty</code>;
* if <code>replace="text"</code> and the replacement target node is a readonly node, or, if <code>replace="instance"</code> and the replacement target node is a node whose parent is readonly, submission fails with <code>target-readonly</code>;
* if <code>replace="instance"</code> and the replacement target node is a non-element, submission fails with <code>target-non-element</code>.

Then the replacement is done according to the value of the <code>replace</code> attribute:

* <code>text</code>: the response data is encoded as text, regardless of its mediatype, and used to replace the content of the replacement target node using the [[#The setvalue Element|<code>setvalue</code>]] action.

* <code>instance</code>: the XPath Data Model obtained from the submission response is used to replace the target node. This data 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. The replacement is performed as a combination of node [[#The insert Element|insertion]] and [[#The delete Element|deletion]] operations.

<!-- unneeded
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 an [[#model-update|update]] 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 it 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.
-->

{{SpecNote|For backwards compatibility with earlier versions of this specification, the processor may treat an attribute named <code>target</code> as equivalent to <code>targetref</code> as long as there is no <code>targetref</code> attribute present.}}

{{SpecNote|In an asynchronous submission, the replacement action is an outermost action handler, and so 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. With a synchronous submission, the replacement action is not outermost since it occurs during the default processing of <code>xforms-submit</code>; 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>update</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 class="example" title="Replacing an instance">
 <nowiki><submission
   resource="http://example.com/search"
   replace="instance"
   instance="results"/></nowiki>
</div>

<div class="example" title="Replacing an instance, overriding the reported mediatype">
 <nowiki><submission
   resource="http://example.com/search"
   response-mediatype="application/xhtml+xml"
   replace="instance"
   instance="results"/></nowiki>
On occasions servers report a wrong or misleading mediatype, or use a mediatype that obscures that the underlying data is in an XML format. The <code>response-mediatype</code> allows you to override that.
</div>

<div class="example" title="Replacing a subtree of instance data">
 <nowiki><submission
   resource="http://example.com/jsp/prefill"
   method="post"
   ref="name"
   replace="instance"
   targetref="address"/></nowiki>
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="example" title="Replacing text in an instance">
 <nowiki><submission
   resource="http://example.com/postalCodeSearch"
   method="get"
   ref="address"
   replace="text"
   targetref="address/postalCode"/></nowiki>
The address information is passed to a postal code search service that returns a textual result, which is placed into the <code>postalCode</code> element.
</div>
<div class="example" title="Submission and Read-Only Content">
 <model>
   <instance>
     &lt;data xmlns="">
       <name>
         <first-name>John</first-name>
         <last-name>Doe</last-name>
       </name>
       <address>
         <street>123 Main St.</street>
         <city>Smallville</city>
       </address>
     &lt;/data>
   </instance>
 
   <bind ref="name" readonly="true()"/>
   <bind ref="address/street" readonly="true()"/>
 
   <submission id="S1" targetref="name" replace="instance" method="post" resource="..."/>
   <submission id="S2" targetref="name/first-name" replace="instance" method="post" resource="..."/>
 
   <submission id="S3" targetref="name/first-name" replace="text" method="post" resource="..."/>
   <submission id="S4" targetref="address/street" replace="text" method="post" resource="..."/>
 </model>

Submission S1 succeeds because a readonly node (<code>name</code>) can be replaced if its parent is not readonly. Submission S2 fails because a node (<code>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 fails 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="submit-protocols">Submission Protocols</span>===

How instance data is submitted depends on two aspects: 
* the submission protocol, which is determined by the URI scheme in the submission resource, and
* the submission method within the protocol, given by the <code>method</code> attribute, and which also determines the default data serialization format:

{| summary="Serialization and Submission Behaviors" border="1"
! rowspan="1" colspan="1" | URI Scheme
! rowspan="1" colspan="1" |
Method
! rowspan="1" colspan="1" | Default Serialization
! rowspan="1" colspan="1" | Protocol
|-
| 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 <nowiki>[Deprecated]</nowiki>
| 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 <nowiki>[Deprecated]</nowiki>
| 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 <nowiki>[Deprecated]</nowiki>
| 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 [[#submission-processing-serialize|Submission Method]]
|-
| rowspan="1" colspan="1" | (any)
| rowspan="1" colspan="1" |
[[#def-PrefixedName|PrefixedName]]
| rowspan="1" colspan="1" | implementation-defined
| rowspan="1" colspan="1" | implementation-defined
|}

<div class="note">
'''Note:''' Foreign-namespaced attribute values are allowed in the [[#submission-processing-serialize|Submission Method]], but no behavior is defined for them.

</div><div class="div3">
====The HTTP and HTTPS Protocols====
Processors must support HTTP/1.1 <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki>, and HTTPS <nowiki>[</nowiki>[[#ref-rfc-2818 |RFC 2818]]<nowiki>]</nowiki>.

Seven methods are supported in these protocols: get, put, delete, post, and three versions of post but with different default serializations: multipart-post, form-data-post, and urlencoded-post, all three methods deprecated in favor of using <code>post</code> with the corresponding value of <code>serialization</code>.

* get: The serialized form data is delivered as part of the URI that is used during the submit process.
* put: The serialized form data is delivered as the message body.
* post, multipart-post, form-data-post, and urlencoded-post: The serialized form data is delivered as the message body.
* delete: The serialized form data is delivered as part of the URI, in the same manner as with get.

Authors 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>. See also <nowiki>[</nowiki>[[#ref-rfc-2616 |RFC 2616]]<nowiki>]</nowiki> for recommended uses of HTTP GET.

<div class="example" title="Simple search submission">
 <submission<nowiki>
   resource="http://example.com/search"
   method="get"/></nowiki>

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><nowiki>http://example.com/search</nowiki></code>. The result replaces the whole page.
</div>
<div class="example" title="Posting instance data">
 <submission<nowiki>
   resource="https://example.com/jsp/orders"
   method="post"
   ref="/purchaseOrder"/></nowiki>

Submits the XML for a purchase order to a secure server order processing system.
</div>
<div class="example" title="Simple posted login">
 <submission<nowiki>
   resource="https://example.com/login"
   method="urlencoded-post"/></nowiki>

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><nowiki>http://example.com/login</nowiki></code>. The result replaces the whole page.
</div>
<div class="example" title="delete method">
 <submission
   resource="<nowiki>../data/temporary.xml</nowiki>"
   method="delete"
   serialization="none"
   replace="none"/>
</div>
</div>
<div>

====The File Protocol====
Standalone and offline XForms applications can be greatly helped by being able to store and retrieve data locally without recourse to a server. Processors should support the File protocol [RFC 8089]; processors may sandbox the area used for files.

In XForms, the File protocol supports three methods:

* get: All serialized data, if any, is ignored. A file-open dialog is initiated with the user, initialised to the location given in the URI. The user can accept this suggestion, or choose another file as replacement. If the chosen file is readable, its contents are returned as the body of the response, with a suitable mediatype, and the submission succeeds; if the file is not readable, the submission fails with <code>result-error-response</code> and an error-message of <code>file not readable</code>.
* put: A file-save dialog is initiated with the user, initialised to the location given in the URI. The user can accept this suggestion, or choose another file location and name as replacement. If the chosen location is writable, its contents are initialised or replaced with the serialized data of the submission, and the submission succeeds; if the location is not writable, the submission fails with <code>result-error-response</code> and an error-message of <code>file not writable</code>.
* delete: All serialized data, if any, is ignored. A file-delete dialog is initiated with the user, initialised to the location given in the file URI. The user can accept this suggestion, and if the file is deletable, it is deleted, and the submission succeeds; if the file is not deletable, the submission fails with <code>result-error-response</code> and an error-message of <code>file not deletable</code>.

In all three cases, the user can cancel the dialog, in which case the submission fails with <code>result-error-response</code> and an error-message of <code>cancelled</code>.

A submission using any other method with a file: URI fails with <code>result-error-response</code> and an error-message of <code>method not supported</code>.

<div class="example" title="Reading from a local file">
 <submission
   resource="file:data.xml"
   method="get"
   serialization="none"
   replace="instance"
   instance="data"/>

Replaces the instance 'data' with the content of the file data.xml. Serialization, and its associated validity and relevance processing, is not needed.
</div>
<div class="example" title="Saving to a local file">
 <submission
   resource="file:data.xml"
   ref="instance('data')"
   method="put"
   validate="false"
   nonrelevant="keep"
   replace="none"/>

Saves the instance 'data' to the file data.xml without validation checking and relevance pruning.
</div>
</div>
<div>

====The Mailto Protocol====
Processors may support the mailto: protocol [RFC 6068].
 
It supports four methods: post, multipart-post, form-data-post, and urlencoded-post, of which the last three are deprecated in favour of using <code>post</code> with a corresponding value of <code>serialization</code>. For all four methods, the serialized data is delivered as the body of the submission.
 
<div class="example" title="mailto:">
 <nowiki><instance id="mail">
    <mail to="registrations@example.com" xmlns="">
       <subject>Conference registration</subject>
       <cc>secretariat@example.com</cc>
       <body>Please register me for your conference.</body>
    </mail>
 </instance></nowiki>
 <bind ref="to|cc" type="iemail"/>
 
 <nowiki><submission ref="instance('mail')" resource="mailto:{instance('mail')/@to}" method="urlencoded-post" replace="none"/></nowiki>
</div>
<div class="div3">

===<span id="serialization">Serialization Formats</span>===

<div class="div3">

====<span id="serialize-xml">application/xml</span>====
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.

Namespace nodes: 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: The default mediatype 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>.

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>xs:boolean</code> to replace <code>"yes"|"no"</code><nowiki>:</nowiki> <code>version</code>, <code>indent</code>, <code>encoding</code>, <code>omit-xml-declaration</code>, <code>cdata-section-elements</code>. There are no counterparts for <code>doctype-system</code> or <code>doctype-public</code>.

{{SpecNote|We are considering adding extra serialization parameters added by http://www.w3.org/TR/xslt-xquery-serialization/, but are waiting for further implementation experience and user feedback to decide which to add.}}

<div class="example" title="Namespace prefixes">
The following examples show how attribute <code>includenamespaceprefixes</code> on element <code>submission</code> can affect serialization as <code>application/xml</code>. Given the following XForms fragment:

 <model<nowiki>
   xmlns:xforms="http://www.w3.org/2002/xforms"
   xmlns:foo="http://example.org/foo">
   <instance>
     <foo:qname
       xmlns=""
       xmlns:bar="http://example.org/bar"
       xmlns:baz="http://example.org/baz">bar:sample</foo:qname>
   </instance>
   <submission
     method="post"
     resource="..."/></nowiki>
 </model>

The <code>includenamespaceprefixes</code> attribute is not present, which causes all namespace nodes in the instance data (as created following the rules set in [[#The_instance_Element|The instance Element]]) to be serialized, resulting in the following serialized instance data:

 <foo:qname<nowiki>
   xmlns:foo="http://example.org/foo"
   xmlns:bar="http://example.org/bar"
   xmlns:baz="http://example.org/baz">bar:sample</foo:qname></nowiki>

If instead the <code>includenamespaceprefixes</code> is present as follows:

 <submission
   method="post"
   resource="..."
   includenamespaceprefixes=""/>

Then the serialized XML looks like this:

 <foo:qname<nowiki>
   xmlns:foo="http://example.org/foo">bar:sample</foo:qname></nowiki>

Note that <code><nowiki>xmlns:foo="http://example.org/foo"</nowiki></code> is present even if not listed because it is used by an element qualified name. On the other hand the other namespaces are not present because they are not used by element or attribute qualified names and are not listed.

If instead the <code>includenamespaceprefixes</code> is present as follows:

 <submission
   method="post"
   resource="..."
   includenamespaceprefixes="bar"/>

Then the serialized XML looks like this:

 <foo:qname<nowiki>
   xmlns:foo="http://example.org/foo"
   xmlns:bar="http://example.org/bar">bar:sample</foo:qname></nowiki>
</div>

</div><div class="div4">

====<span id="serialize-multipart">multipart/related</span>====

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>xs: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>xs: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="example" title="multipart/related">
 <submission method="multipart-post" resource="<nowiki>http://example.com/photo"</nowiki>/>
Submits the instance data in <code>multipart/related</code>, along with the selected file as an attachment.

 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 class="div4">

====<span id="serialize-form-data">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, ignoring or treating as empty non-relevant elements according to the <code>nonrelevant</code> attribute or the deprecated <code>relevant</code> attribute.
* 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>xs:anyURI</code> and derived types, the serialization content is obtained from the URI. For <code>xs:base64Binary</code>, <code>xs: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>xs:anyURI</code>, <code>xs:base64Binary</code>, <code>xs:hexBinary</code>, and derived types, in which case the header represents the mediatype 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.

<div class="example" title="multipart/form-data">
 <submission
   method="form-data-post"
   resource="<nowiki>http://example.com/photo</nowiki>"/>

Submits the instance data in <code>multipart/form-data</code>, along with the selected file as a part.

 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 class="div4">

====<span id="serialize-urlencode">application/x-www-form-urlencoded</span>====

This format consists of simple name-value pairs, without any structuring retained. It 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 binary content.

The steps for serialization are as follows:

# Each element node is visited in document order, ignoring or treating as empty non-relevant elements according to the <code>nonrelevant</code> attribute or the deprecated <code>relevant</code> attribute. 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). 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). Note that contextual path information is not preserved, nor are namespaces and 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 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. The value of the <code>separator</code> attribute on <code>submission</code> is used between pairs of encoded name/value pairs, e.g. for the separator ";" <code>EltName1=value1;EltName2=value2;EltName3=value3</code>. 

<div class="example" title="application/x-www-form-urlencoded">

Consider the following instance data:

 <PersonName title="Mr">
   <GivenName>René</GivenName>
 </PersonName>

This will give as serialization:

 GivenName=Ren%C3%A9

Note that little of the data is preserved. When greater data integrity is needed a different serialization should be chosen.
</div>
</div></div>
<div class="div3">

====<span id="serialize-json-csv">application/json and text/csv</span>====

As described in the sections on [[#External JSON values|External JSON values]] and [[#External CSV values|External CSV values]], instances adhering to certain formats may also be serialized in JSON and CSV formats.

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

===<span id="submit-events">Submission Events</span>===

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

This event initiates a submission.
<div class="desc">
Target: <code>submission</code>
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: [[#submission-processing|Submission processing]] is started for [[#submit-submission-element|the <code>submission</code> element]].
</div>

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

Dispatched at the beginning of <code>submission</code> serialization (see [[#submission-processing|Submission Processing]]).
<div class="desc">
Target: <code>submission</code>
Bubbles: Yes
Cancelable: No

Context Info:
;submission-body (node-sequence)
: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 Item 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.
</div>
<div class="example" title="Submitting plain text">
  <nowiki><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></nowiki>

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-ready">The xforms-submit-ready Event</span>====

This notification event is dispatched as an indication of readiness just before effective submission
<div class="desc">
Target: <code>submission</code>
Bubbles: Yes
Cancelable: No

Context Info:

;resource-uri (string)
:The submission resource URI that has been prepared for submission (xs:anyURI)
;method (string)
:The protocol method to be used to transmit the submission
;request-mediatype (string)
:The mediatype of the serialization to be used in the <code>Content-type</code> header of HTTP
;request-headers (node-sequence)
:Zero or more elements, each one representing a content header in the prepared request for the submission. The returned node-sequence is empty if there will be 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.
;request-body (object (string or node))
:According to the media-type defined for the submission, a node is returned when possible, if not a string is returned.
</div>
<div class="example" title="Submission Inspector">
 <submission resource=<nowiki>"https://example.com/data"</nowiki> method="put" replace="none">
     <action ev:event="xforms-submit-ready">
          <message value="event('resource-uri')"/>
          <message value="event('mediatype')"/>
          <message value="serialize(event('request-body'))"/>
     </action>
 </submission>

The submission details are inspected before the submission being performed.
</div>
<div class="example" title="Submission Simulation">
 <submission resource=<nowiki>"https://example.com/data"</nowiki> replace="instance" instance="results">
     <action ev:event="xforms-submit-ready">
          <replace ref="instance('results')" with="instance('substitute')"/>
          <cancel/>
     </action>
 </submission>

The submission is simulated replacing the target instance with a substitute.
</div>
</div><div class="div2">

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

This notification event is dispatched as an indication of successful completion of a submission process
<div class="desc">
Target: <code>submission</code>
Bubbles: Yes
Cancelable: No

Context Info:

;resource-uri (string)
:The submission resource URI that succeeded (xs:anyURI)

;response-status-code (number)
:The protocol return code of the success response, or <code>NaN</code> if the submission did not receive a success response.

;response-headers (node-sequence)
:Zero or more elements, each one representing a content header in the success response received by the submission. The returned node-sequence 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.
;response-reason-phrase (string)
: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.
</div>
<div class="example" title="Submission Sequencing, and reading response headers">
 <submission resource=<nowiki>"https://example.com/data"</nowiki> method="put" replace="none">
     <send ev:event="xforms-submit-done" submission="head"/>
 </submission>
 <submission id="head" resource=<nowiki>"https://example.com/data"</nowiki> method="head"
             serialization="none" replace="none">
     <setvalue ev:event="xforms-submit-done"
               ref="mod-time" 
               value="event('response-headers')[name='last-modified']/value" />
 </submission>

The default instance data is submitted; upon successful completion, a second submission is performed to access the time that the server has recorded as the modification time.
</div>
</div><div class="div2">

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

This notification event is dispatched on failure of a submission process.
<div class="desc">
Target: <code>submission</code>
Bubbles: Yes
Cancelable: Yes

Context Info:

;error-type (string)
:One of the following: <code>submission-in-progress</code>, <code>no-data</code>, <code>no-relevant-data</code>, <code>validation-error</code>, <code>parse-error</code>, <code>resource-error</code>, <code>result-mediatype</code>, <code>result-text-mediatype</code>, <code>result-error-response</code>, <code>target-model-error</code>, <code>target-empty</code>, <code>target-readonly</code>, <code>target-non-element</code>.

;error-message (string)
:A message containing further details of the error.

;resource-uri (string)
:The submission resource URI that failed (xs:anyURI)

;response-status-code (number)
:The protocol return code of the error response, or <code>NaN</code> if the failed submission did not receive an error response.

;response-headers (node-sequence)
:Zero or more elements, each one representing a content header in the error response received by a failed submission. The returned node-sequence 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.

;response-reason-phrase (string)
: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.

;response-body (object (string or node-sequence))
: When the error response specifies an XML mediatype 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 mediatype (starting with <code>text/</code>), then the response body is returned as a string. Otherwise, an empty string is returned.

Default action: A warning message must be displayed containing at least all the context info values listed above. For example:
 <message ev:event="xforms-submit-error">
    Submission error.
       error-type: <output value="event('error-type')"/>
       error-message: <output value="event('error-message')"/>
       resource-uri: <output value="event('resource-uri')"/>
       response-status-code: <output value="event('response-status-code')"/>
       response-reason-phrase: <output value="event('response-reason-phrase')"/>
   </message>
</div>
<div class="example" title="Reporting a Submission Error">
 <submission resource=<nowiki>"https://example.com/getRecord"</nowiki> method="post"
             replace="instance" instance="record">
   <message ev:event="xforms-submit-error" ev:default="cancel">A submission error 
                    (<output value="event('error-type')"/>) occurred.</message>
 </submission>
</div>
</div>
<div class="div2">

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

XForms processing is based on responding to events that signal change of state:
in general whenever there is a change of state, events are dispatched to parts of the document affected by the change. Event handlers are then able to respond as needed.

* On start up, each [[#model-initialization|model is initialized]] as a result of receiving the <code>[[#evt-modelConstruct|xforms-model-construct]]</code> event from the system.
* After all models have been initialized, an <code>[[#evt-modelConstructDone|xforms-model-construct-done]]</code> event is dispatched to each model. This results in the [[#model-ui-initialize|user interface being initialized]].
* After all <code>xforms-model-construct-done</code> events have been processed, an <code>[[#evt-ready|xforms-ready]]</code> event is dispatched to each <code>model</code> element, signalling the start of user interface processing.

After this initialization the system goes into stasis, until either the user interacts with the document, thus setting off a new chain of events, or an action handler reacting to <code>xforms-ready</code> initiates a chain of events. 

Events are classified in the following categories:

* Initialization
* Interaction
* Notification
* Error Conditions.

<div class="div2">

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

An event happening usually sets of a chain of other events responding to the changes.
Here, we give the sequences of related events that occur in several common situations; events that may be fired more than once are prefixed with [n].

<div class="div3">

====For Initialization====
* [n] [[#evt-modelConstruct|xforms-model-construct]]
: These may cause a number of <code>xforms-link-error</code> and <code>xforms-compute-error</code>.
* [n] [[#evt-modelConstructDone|xforms-model-construct-done]]
: These may cause a number of <code>xforms-binding-error</code>.
* [n] [[#evt-ready|xforms-ready]]

====<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 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 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 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, and elements that use output</span>====

* The implementation of an <code>[[#ui-output|output]]</code> (and any element that uses it, namely <code>[[#ui-commonelems-label|label]]</code>, <code>[[#ui-commonelems-help|help]]</code>, <code>[[#ui-commonelems-hint|hint]]</code>, and <code>[[#ui-commonelems-alert|alert]]</code>) dispatches <code>[[#evt-output-error|xforms-output-error]]</code> if it is 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 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> 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 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 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 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>====

After an [[#model-update|update]], a [[#model-refresh|refresh]] performs re-evaluation of UI binding expressions and dispatches these events accordingly (the order in which they are dispatched is not defined):
* [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.

</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</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> 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 a 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 the empty sequence for the <code>instance()</code> function. However, an <code>xforms-binding-error</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 binding with a <code>bind</code> attribute, the IDREF of the <code>bind</code> attribute is resolved to a target bind object whose associated sequence is used by the source 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>ref</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 sequence is used in the source binding. Otherwise, the [[#in-scope-evaluation-context|in-scope evaluation context]] item 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 item as the source object, then that bind object is the desired target bind object. Otherwise, the IDREF resolution produces all the bind objects identified. For sources that require only one object, and therefore one item, the first-item rule applies.

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

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

Processors that implement the DOM must provide DOM access to instance data via this interface.

<div class="note">

'''Note:'''

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

</div>

The IDL for the interface is:

 <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 into a readonly node, direct deletion of a child 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 rebuilds any internal data structures used to track computational dependencies within this Model. This method takes no parameters and raises no exceptions.

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

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

This method performs a full recalculation of this Model. This method takes no parameters and raises no exceptions.

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

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

This method performs a full revalidation of this Model. This method takes no parameters and raises no exceptions.

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

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

This method performs a [[#model-refresh|refresh]] of the user interface based on instance nodes within this Model. This method takes no parameters and raises no exceptions.

</div><div class="div2">
====<span id="idl-update">The update() Method</span>====

This method performs an [[#model-update|update]] of this Model, doing as necessary a [[#model-rebuild|rebuild]], [[#model-recalculate|recalculate]], [[#model-revalidate|revalidate]], and [[#model-refresh|refresh]]. This method takes no parameters and raises no exceptions.

</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="div2">

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

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 element, the event bubbling phase, and finally the performance of the event's default action. A handler can stop the event at any stage, and cancel the default action if needed, and perform other actions if needed. An event can carry context information with it, giving further details of the event. A notification event has no default action, and so cannot be cancelled.

Some events have a related action that dispatches the event. These are listed with the events.

{| 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" | Effect
! rowspan="1" colspan="1" | Context
! rowspan="1" colspan="1" | Target element
! rowspan="1" colspan="1" | Related action
|-
| rowspan="1" colspan="4" |
'''[[#Initialization Events|Initialization Events]]'''
|-
| rowspan="1" colspan="1" | [[#evt-modelConstruct|xforms-model-construct]]
| rowspan="1" colspan="1" | Not
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | [[#evt-modelConstructDone|xforms-model-construct-done]]
| rowspan="1" colspan="1" | Not
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | [[#evt-ready|xforms-ready]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | [[#evt-modelDestruct|xforms-model-destruct]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="4" |
'''[[#Interaction Events|Interaction Events]]'''
|-
| rowspan="1" colspan="1" | [[#evt-rebuild|xforms-rebuild]](deprecated)
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
| rowspan="1" colspan="1" | <code>[[#action-rebuild|rebuild]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-recalculate|xforms-recalculate]](deprecated)
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
| rowspan="1" colspan="1" | <code>[[#action-recalculate|recalculate]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-revalidate|xforms-revalidate]](deprecated)
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
| rowspan="1" colspan="1" | <code>[[#action-revalidate|revalidate]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-refresh|xforms-refresh]](deprecated)
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
| rowspan="1" colspan="1" | <code>[[#action-refresh|refresh]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-reset|xforms-reset]](deprecated)
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>model</code>
| rowspan="1" colspan="1" | <code>[[#action-reset|reset]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-focus|xforms-focus]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Doesn't
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-all-controls| Controls]]
| rowspan="1" colspan="1" | <code>[[#action-setfocus|setfocus]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-next|xforms-previous]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Doesn't
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
| rowspan="1" colspan="1" | <code>[[#action-previousfocus|previousfocus]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-next|xforms-next]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Doesn't
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
| rowspan="1" colspan="1" | <code>[[#action-nexfocus|nextfocus]]</code>
|-
| rowspan="1" colspan="1" | [[#evt-help|xforms-help]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-help|xforms-hint]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-activate|DOMActivate]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
|-
| rowspan="1" colspan="1" | [[#The_xforms-submit_Event|xforms-submit]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>submission</code>
| rowspan="1" colspan="1" | <code>[[#action-send|send]]</code>
|-
| rowspan="1" colspan="1" | [[#submit-evt-submit-serialize|xforms-submit-serialize]](deprecated)
| rowspan="1" colspan="1" | Not
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>submission</code>
|-
| rowspan="1" colspan="1" | [[#The_xforms-dialog-show_Event|xforms-dialog-show]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>dialog</code>
| rowspan="1" colspan="1" | <code>[[#action-show|show]]</code>
|-
| rowspan="1" colspan="1" | [[#The_xforms-dialog-hide_Event|xforms-dialog-hide]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Effect
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>dialog</code>
| rowspan="1" colspan="1" | <code>[[#action-hide|hide]]</code>
|-
| rowspan="1" colspan="4" |
'''[[#Notification Events|Notification Events]]'''
|-
| rowspan="1" colspan="1" | [[#evt-insert|xforms-insert]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>instance</code>
|-
| rowspan="1" colspan="1" | [[#evt-delete|xforms-delete]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>instance</code>
|-
| rowspan="1" colspan="1" | [[#evt-valueChanged|xforms-value-changed]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-valid|xforms-valid]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-invalid|xforms-invalid]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-readonly|xforms-readonly]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-readwrite|xforms-readwrite]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-required|xforms-required]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-optional|xforms-optional]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-enabled|xforms-enabled]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-disabled|xforms-disabled]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
|-
| rowspan="1" colspan="1" | [[#evt-DOMFocusIn|DOMFocusIn]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-all-controls| Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-DOMFocusOut|DOMFocusOut]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-all-controls| Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-select|xforms-select]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>item</code> or <code>case</code>
|-
| rowspan="1" colspan="1" | [[#evt-select|xforms-deselect]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>item</code> or <code>case</code>
|-
| rowspan="1" colspan="1" | [[#evt-in-range|xforms-in-range]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-out-of-range|xforms-out-of-range]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | [[#elems-form-controls| Core Controls]]
|-
| rowspan="1" colspan="1" | [[#evt-scroll|xforms-scroll-first]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>repeat</code>
|-
| rowspan="1" colspan="1" | [[#evt-scroll|xforms-scroll-last]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>repeat</code>
|-
| rowspan="1" colspan="1" | [[#The_xforms-submit-done_Event|xforms-submit-done]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>submission</code>
|-
| rowspan="1" colspan="1" | [[#The_xforms-dialog-shown_Event|xforms-dialog-shown]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>dialog</code>
|-
| rowspan="1" colspan="1" | [[#The_xforms-dialog-hidden_Event|xforms-dialog-hidden]]
| rowspan="1" colspan="1" | -
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Notification
| rowspan="1" colspan="1" | None
| rowspan="1" colspan="1" | <code>dialog</code>
|-
| rowspan="1" colspan="4" |
'''[[#Error Handling|Error Handling]]'''
|-
| rowspan="1" colspan="1" | [[#evt-bindingError|xforms-binding-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Fatal
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | any element that can contain a binding expression
|-
| rowspan="1" colspan="1" | [[#evt-expressionError|xforms-expression-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Fatal
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | any element that is not an action element and that can contain an expression which is not a binding expression
|-
| rowspan="1" colspan="1" | [[#evt-actionError|xforms-action-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Fatal
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | any element that is an event observer for an action handler
|-
| rowspan="1" colspan="1" | [[#evt-actionWarning|xforms-action-warning]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Warning
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | any element that is an event observer for an action handler
|-
| rowspan="1" colspan="1" | [[#evt-computeError|xforms-compute-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Fatal
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | [[#evt-versionError|xforms-version-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Fatal
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | The default <code>model</code>
|-
| rowspan="1" colspan="1" | [[#evt-linkError|xforms-link-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Fatal
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>model</code>
|-
| rowspan="1" colspan="1" | [[#evt-output-error|xforms-output-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Warning
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>output</code>|<code>label</code>|<code>help</code>|<code>hint</code>|<code>alert</code>
|-
| rowspan="1" colspan="1" | [[#evt-submit-error|xforms-submit-error]]
| rowspan="1" colspan="1" | Cancelable
| rowspan="1" colspan="1" | Bubbles
| rowspan="1" colspan="1" | Warning
| rowspan="1" colspan="1" | Context
| rowspan="1" colspan="1" | <code>submission</code>
|}

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

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

[[#model-processing|Initialization]] is started by dispatching the event <code>xforms-model-construct</code> to each Model in the containing document. How the Processor itself initializes is implementation dependent.

<div class="div3">

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

Dispatched to each model to initiate processing.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: No
Context Info: None

Default action: a [[#model-initialization|model initialization]] is done for the model.
</div>
</div><div class="div3">

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

Dispatched to each model after the completion of <code>xforms-model-construct</code> processing.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: No
Context Info: None

Default action: If not already done, a [[#model-ui-initialize|User Interface Initialization]] is done, and a copy of each instance in the model is [[#action-retain|retained]] for use by the [[#action-reset|reset action]].
</div>
</div><div class="div3">

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

This notification event is dispatched once for each model, when initialization is completed and user interaction can start.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

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

This notification event is dispatched once for each model, before shutdown of the Processor, which can occur from user action, from the <code>load</code> action, or as a result of form submission.
<div class="desc">
Target: <code>model</code>
Bubbles: No
Cancelable: No
Context Info: None
</div>
</div></div><div class="div2">

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

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

This event is dispatched when the "default action request" for a core control is activated, for instance by pressing a button or hitting enter.
<div class="desc">
Target: [[#elems-form-controls|Core Controls]]
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: varies according to the control it is used on.
</div>
</div><div class="div3">

<div class="div3">

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

Dispatched to set focus to a control.
<div class="desc">
Target: [[#elems-all-controls|Controls]]
Bubbles: No
Cancelable: Yes
Context Info: None

Default action: The target control is given focus, if it is able to accept it.
</div>

See the section on [[#all-controls-interaction|interaction for all controls]] for details.

This event is implicitly invoked when the user changes the focus and to implement accessibility features such as <code>accesskey</code>.
</div>
====<span id="evt-next">The xforms-next and xforms-previous Events</span>====

Dispatched to navigate to the next or previous [[#elems-form-controls|Core Control]] in navigation order.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]
Bubbles: No
Cancelable: Yes
Context Info: None

Default action: focus is given to the next/previous control in navigation order.
</div>

See the section on [[#all-controls-interaction|interaction for all controls]] for details.

<div class="example" title="xforms-next">
 <dispatch ev:event="xforms-value-changed"
           name="xforms-next"
           targetid="here"
           if="string-length(.)=4"/>
</div>

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

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

Dispatched to provide help or hint information.
<div class="desc">
Target: [[#elems-form-controls|Core Control]]
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: If the control has help/hint information attached, it is used to construct a message that is made available to the user. 
</div>
In the absence of such information, default help or hint messages may be made available.

</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 (Deprecated)</span>====

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

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

See chapter [[#The xforms-dialog-show Event|The xforms-dialog-show Event]].

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

See chapter [[#The xforms-dialog-hide Event|The xforms-dialog-hide Event]].

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

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

Dispatched to recompute the computational dependencies within a Model. Deprecated in favor of the related action.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: a [[#model-rebuild|rebuild]] is done for the model.
</div>
</div><div class="div3">

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

Dispatched to recalculate all calculations associated with a Model. Deprecated in favor of the related action.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: a [[#model-recalculate|recalculate]] is done for the model.
</div>
</div><div class="div3">

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

Dispatched to revalidate a Model. Deprecated in favor of the related action.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: a [[#model-revalidate|revalidate]] is done for the model.
</div>
</div><div class="div3">

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

Dispatched to update all controls associated with a Model. Deprecated in favor of the related action.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: a [[#model-refresh|refresh]] is done for the model.
</div>
</div><div class="div3">

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

Dispatched to reset a model back to its original values. Deprecated in favor of the related action.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: Yes
Context Info: None

Default action: a [[#action-reset|reset]] is done for the model.
</div>
</div>

</div>

<div class="div2">

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

Notifications events have no default action, and are therefore not cancelable.

<div class="div3">

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

This notification event is dispatched after successful insertion of one or more nodes by an <code>insert</code> action.
<div class="desc">
Target: <code>instance</code>
Bubbles: Yes
Cancelable: No

Context Info:

;inserted-nodes (node-sequence)
:The instance data node or nodes inserted.

;updated-nodes (node-sequence)
:The instance data text nodes which have been updated by merging text nodes, if any.

;origin-nodes (node-sequence)
:The instance data nodes referenced by the <code>insert</code> action's <code>origin</code> attribute if present, or the empty sequence if not present.

;insert-location-node (node-sequence)
:The <code>insert location node</code> as defined by the <code>insert</code> action.

;position (string)
:The insert position, <code>before</code> or <code>after</code>.

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

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

This notification event is dispatched after successful deletion of one or more nodes by a <code>delete</code> action.
<div class="desc">
Target: <code>instance</code>
Bubbles: Yes
Cancelable: No

Context Info:
;deleted-nodes (node-sequence)
:The instance data node or nodes deleted. Note that these nodes are no longer referenced by their parents.

;updated-nodes (node-sequence)
:The instance data text nodes which have been updated by merging text nodes, if any.

;delete-location (number)
:The <code>delete location</code> as defined by the <code>delete</code> action, or NaN if there is no delete location.

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

====<span id="evt-replace">The xforms-replace Event</span>====
13.3.x The xforms-replace Event
 
This notification event is dispatched after successful execution of a <code>replace</code> action.

<div class="desc">
Target: instance 
Bubbles: Yes 
Cancelable: No
 
Context Info:
 
;inserted-nodes (node-sequence)
:The new instance data node or nodes.

;updated-nodes (node-sequence)
:The instance data text nodes which have been updated by merging text nodes, if any.
 
;deleted-nodes (node-sequence)
:The instance data node or nodes replaced. Note that these nodes are no longer referenced by their parents.
</div>
</div><div class="div3">

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

This notification event is dispatched during a [[#model-refresh|refresh]] after a change to an instance data node bound to a core control.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
<div class="note">
'''Note:'''

For controls with <code>incremental</code>=true, it is not defined how often this event is fired. Implementations should optimize processing (for instance not flashing the entire screen for each character entered, etc.).

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

====<span id="evt-valid">The xforms-valid</span> and <span id="evt-invalid">xforms-invalid Events</span>====

These notification events are dispatched during [[#model-refresh|refresh]] when a bound instance data node changes and is [[#def-valid|valid]]/invalid, or it becomes valid/invalid.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

====<span id="evt-readonly">The xforms-readonly</span> and <span id="evt-readwrite">xforms-readwrite Events</span>====

These notification events are dispatched during [[#model-refresh|refresh]] when a bound instance data node changes and is [[#def-readonly|readonly]]/read-write or it becomes readonly/read-write.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

====<span id="evt-required">The xforms-required</span> and <span id="evt-optional">xforms-optional Events</span>====

These notification events are dispatched during [[#model-refresh|refresh]] when a bound instance data node changes and is [[#def-required|required]]/optional or it becomes required/optional.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

====<span id="evt-enabled">The xforms-enabled</span> and <span id="evt-disabled">xforms-disabled Events</span>====

These notification events are dispatched during [[#model-refresh|refresh]] when a bound instance data node changes and is [[#def-enabled|enabled]]/disabled or it becomes enabled/disabled.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]<nowiki>|</nowiki><code>group</code><nowiki>|</nowiki><code>switch</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">
====<span id="evt-refresh-done">The xforms-refresh-done Event</span>====

This notification event is dispatched when a [[#model-refresh|refresh]] has completed.
<div class="desc">
Target: Default <code>model</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

====<span id="evt-DOMFocusIn">The DOMFocusIn</span> and <span id="evt-DOMFocusOut">DOMFocusOut Events</span>====

These notification events are dispatched when a control receives/loses focus.
<div class="desc">
Target: [[#elems-all-controls| Controls]]
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

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

These notification events are dispatched when an <code>item</code> in a <code>select</code>, <code>select1</code>, or a <code>case</code> in a <code>switch</code> becomes selected or deselected.
<div class="desc">
Target: <code>item</code> or <code>case</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

====<span id="evt-in-range">The xforms-in-range</span> and <span id="evt-out-of-range">xforms-out-of-range Events</span>====

These notification events are dispatched during a [[#model-refresh|refresh]] when a value has changed and can now be represented by the control/not represented by the control.
<div class="desc">
Target: [[#elems-form-controls| Core Controls]]
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</div><div class="div3">

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

These notification events are dispatched when attempting to set a repeat index outside the range of a <code>repeat</code>.
<div class="desc">
Target: <code>repeat</code>
Bubbles: Yes
Cancelable: No
Context Info: None
</div>
</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 class="div3">

==== The xforms-dialog-shown Event ====

See chapter [[#The xforms-dialog-shown Event|The xforms-dialog-shown Event]].

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

==== The xforms-dialog-hidden Event ====

See chapter [[#The xforms-dialog-hidden Event|The xforms-dialog-hidden Event]].

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

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

When errors happen during processing, error events are dispatched, usually to the offending element, allowing the events to be caught and responded to if necessary. XForms 2.0 enhances error handling with the ability to recover from errors, optionally continuing processing after catching an error.

The default action of most error events is to halt processing, but handlers can use <code>defaultAction="cancel"</code> to implement custom error handling and allow processing to continue.

For three events, <code>xforms-action-warning</code>, <code>xforms-output-error</code>, and <code>xforms-submit-error</code>, the default action is to issue a warning, and then allow processing to continue. Cancelling the default in these cases means continuing processing without the warning.

<div class="example" title="Custom error handler">
 <action ev:event="xforms-expression-error" ev:defaultAction="cancel">
   &lt;!-- Custom error handling here --&gt;
 </action>
</div>

<div class="div3">

====<span id="evt-recovery-outside-actions">Error Recovery Outside Actions</span>====

On encountering an error with an expression or binding, a ''recovery value'' is determined for the expression before dispatching an event. Specifically:

# For control bindings, model bindings, values, variables:
#* Upon expression errors, a default value is chosen:
#** the empty sequence for bindings and variable values
#** the empty string for string values
#** <code>xforms-expression-error</code> is dispatched
#* Upon binding errors with the <code>bind</code> attribute
#** the binding resolves to the empty sequence
#** <code>xforms-binding-error</code> is dispatched
#* Upon binding errors with the <code>model</code> attribute
#** the model doesn't change, as if the model attribute was missing
#** the binding resolves to the empty sequence
#** <code>xforms-binding-error</code> is dispatched
# For expression MIP values:
#* Upon expression errors for <code>calculate</code>
#** the destination value is set to blank
#** <code>xforms-expression-error</code> is dispatched
#* Upon expression errors for other MIPs
#** the MIP is not modified, as if the attribute specifying the property was missing
#** <code>xforms-expression-error</code> is dispatched
#* Upon binding errors with complex or readonly content (<code>calculate</code> only)
#** the instance value is not modified
#** <code>xforms-binding-error</code> is dispatched to the model
# For the submission <code>instance</code> attribute:
#* Upon incorrect instance id
#** <code>xforms-submit-error</code> is dispatched, for compatibility with the case of a target error with the <code>targetref</code> attribute

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

====<span id="evt-recovery-inside-actions">Error Recovery Inside Actions</span>====

Any error taking place during action processing stops the outermost action handler. Errors include:

* expression errors
* binding errors with the <code>bind</code> or <code>model</code> attribute
* binding errors with complex or readonly content
* missing mandatory attributes or unsupported attribute values on action elements

The [[#evt-actionError|<code>xforms-action-error</code>]] and [[#evt-actionWarning|<code>xforms-action-warning</code>]] events are dispatched to the [[#def-observer|observer]] of the action. Observers include: controls and the <code>model</code>, <code>instance</code>, and <code>submission</code> elements.

<div class="note">

'''Note:'''

Some actions silently ignore error conditions and are not subject to the processing above, including:

* <code>setvalue</code> pointing to the empty sequence or to an atomic item (such as a string) instead of a node
* <code>delete</code> with the empty sequence or an empty overridden context
* <code>insert</code> with an empty or non-element insert context, an empty overridden context, or an empty origin
* actions with AVTs evaluating to the empty sequence.
</div>

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

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

Dispatched as an indication of any error with a binding not within an action handler.

<div class="desc">
Target: the element that contains the binding expression that is in error
Bubbles: Yes
Cancelable: Yes

Context Info:
;error-message (string)
:Implementation-optional, implementation-dependent error message, or the empty sequence.

Default action: Fatal error (halts processing).
</div>
Examples include:

* a <code>bind</code> attribute <code>IDREF</code> value that refers to an <code>ID</code> not on a <code>bind</code> element
* a <code>model</code> attribute <code>IDREF</code> value that refers to an <code>ID</code> not on a <code>model</code> element
* a <code>model</code> attribute which does not refer to the containing <code>model</code> element, when applicable
* a static or dynamic error with a binding expression expressed with the <code>ref</code> attribute.
<div class="note">

'''Note:'''

Binding errors occurring within action handlers dispatch the [[#evt-actionError|<code>xforms-action-error</code>]] event instead.

</div>

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

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

Dispatched as an indication of any error occurring during evaluation of an expression not within an action handler, excluding binding expressions.

<div class="desc">
Target: any element that is not an action element and that can contain an expression which is not a binding expression
Bubbles: Yes
Cancelable: Yes

Context Info:

;error-message (string)
:Implementation-optional, implementation-dependent error message, or the empty sequence.

Default action: Fatal error (halts processing).
</div>
Examples include:
* a <code>bind</code> computed expression
* a <code>value</code> attribute on <code>output</code> and <code>var</code>

<div class="note">

'''Note:'''

Expression  errors occurring within action handlers dispatch the [[#evt-actionError|<code>xforms-action-error</code>]] event instead.

</div>

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

<div class="div3">

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

Dispatched as an indication of any error occurring during the execution of an action handler, including expression and binding errors.
<div class="desc">
Target: the event [[#def-observer|observer]] that caused the action to be executed
Bubbles: Yes
Cancelable: Yes

Context Info:
;error-type (string)
:One of: <code>expression-error</code>, <code>binding-error</code>, <code>script-error</code>, <code>script-language</code>, <code>setvalue-children</code>, <code>setvalue-root</code>, <code>setindex-repeat</code>, <code>toggle-case</code>, <code>setfocus-control</code>, <code>dispatch-targetid</code>, <code>reset-instance</code>, <code>retain-instance</code>, <code>send-submission</code>.

;error-message (string)
:Implementation-optional, implementation-dependent error message, or the empty sequence.

Default action: Fatal error (halts processing).
</div>
</div><div class="div3">
====<span id="evt-actionWarning">The xforms-action-warning Event</span>====

A non-fatal version of [[#evt-actionError|<code>xforms-action-error</code>]],
dispatched as an indication of any warning occurring during the execution of an action handler.
<div class="desc">
Target: the event [[#def-observer|observer]] that caused the action to be executed
Bubbles: Yes
Cancelable: Yes

Context Info:
;error-type (string)
:Currently only: <code>load-error</code>.

;error-message (string)
:Implementation-optional, implementation-dependent error message, or the empty sequence.

Default action: Warning.
</div>
</div><div class="div3">

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

Dispatched as an indication of an error occurring with computing expressions.
<div class="desc">
Target: <code>model</code>
Bubbles: Yes
Cancelable: Yes

Context Info:

;error-message (string)
:An implementation-specific string that should contain the expression being processed when the error was detected.

Default action: Fatal error (halts processing).
</div>
Examples include:
* an extension function is declared on the <code>functions</code> attribute but is not implemented by the XForms Processor;
* a circular dependency is detected during [[#model-recalculate|recalculate]];
* a computed expression violates a Binding Expression Constraint during [[#model-recalculate|recalculate]].
</div><div class="div3">

====<span id="evt-versionError">The xforms-version-error 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]].
<div class="desc">
Target: the default <code>model</code>
Bubbles: Yes
Cancelable: Yes

Context Info:

;error-message (string)
:An implementation-specific error string

Default action: Fatal error (halts processing).
</div>
<div class="note">

'''Note:'''

This event can be dispatched early during XForms Processor initialization. While the default action of this event can be canceled by an event handler, XForms Processors are not expected to produce XForms user interface elements or execute further XForms action handlers (such as a <code>message</code> action) in response to this event. This event is mainly 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-linkError">The xforms-link-error Event</span>====

Dispatched as an indication of a failure to traverse or process the result of a link, such as schema or instance initialization.
<div class="desc">
Target: <code>model</code> associated with the element performing the link. If the element has a <code>model</code> attribute, that model is used. Otherwise, the <code>model</code> attribute of the closest ancestor element is used. Otherwise, the first model is used.
Bubbles: Yes
Cancelable: Yes

Context Info:

;resource-uri (string)
:The URI associated with the failed link (xs:anyURI)

Default action: Fatal error (halts processing).
</div>
<div class="note">

'''Note:'''

When this event is not canceled, 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.

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

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

Dispatched on failure of an <code>[[#ui-output|output]]</code>, <code>[[#ui-commonelems-label|label]]</code>, <code>[[#ui-commonelems-help|help]]</code>, <code>[[#ui-commonelems-hint|hint]]</code>, or <code>[[#ui-commonelems-alert|alert]]</code> element to render content.
<div class="desc">
Target: The <code>[[#ui-output|output]]</code>, <code>[[#ui-commonelems-label|label]]</code>, <code>[[#ui-commonelems-help|help]]</code>, <code>[[#ui-commonelems-hint|hint]]</code>, or <code>[[#ui-commonelems-alert|alert]]</code> that caused the error.
Bubbles: Yes
Cancelable: Yes
Context Info: None.

Default action: Warning.
</div>
<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="div1">

==<span id="action">Actions</span>==

Actions allow change of state not based directly on user interaction. By listening for events on different elements, actions can be used to react to those events.

Actions are declarative XML event handlers <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> that capture high-level semantics, and as a consequence, are more tractable than methods that rely exclusively on scripting, and thus enhance the accessibility of applications.

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 and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#action-action|action]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], type (xs:string), src (xs:anyURI), charset (xs:string)
| rowspan="1" colspan="1" |
([[#action-content-set|Action]]|[[#structure-var-element|var]])* | [[#action-param|param]]*, [[#action-body|body]]
|-
| rowspan="1" colspan="1" |
[[#action-setvalue|setvalue]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]], value (string Expression)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-insert|insert]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Sequence Binding]], at (number Expression), position ("before"|"after"), origin (node-sequence Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-delete|delete]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Sequence Binding]], at (number Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-setindex|setindex]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], repeat (xs:IDREF), index (number Expression)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-toggle|toggle]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], case (xs:IDREF)
| rowspan="1" colspan="1" | [[#action-toggle-case|case]]? [deprecated]
|-
| rowspan="1" colspan="1" |
[[#action-setfocus|setfocus]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], control (xs:IDREF)
| rowspan="1" colspan="1" | [[#action-setfocus-control|control]]? [deprecated]
|-
| rowspan="1" colspan="1" |
[[#action-dispatch|dispatch]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], name (xs:NMTOKEN), targetid (xs:IDREF), delay (xs:nonNegativeInteger), bubbles (xs:boolean), cancelable (xs:boolean)
| rowspan="1" colspan="1" | [[#action-dispatch-name|name]]? [deprecated], [[#action-dispatch-targetid|targetid]]? [deprecated], [[#action-dispatch-delay|delay]]?  [deprecated], [[#action-dispatch-property|property]]* [in any order]
|-
| rowspan="1" colspan="1" |
[[#action-signal|signal]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], name (xs:NMTOKEN), control (xs:IDREF), delay (xs:nonNegativeInteger), bubbles (xs:boolean), cancelable (xs:boolean)
| rowspan="1" colspan="1" | [[#action-dispatch-property|property]]*
|-
| rowspan="1" colspan="1" |
[[#action-rebuild|rebuild]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-recalculate|recalculate]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-revalidate|revalidate]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-update|update]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-refresh|refresh]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-reset|reset]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-retain|retain]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]]
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-load|load]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]] (optional; deprecated), resource (xs:anyURI), show ("new" | "replace")
| rowspan="1" colspan="1" | [[#action-load-resource|resource]]? [deprecated]
|-
| rowspan="1" colspan="1" |
[[#action-send|send]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], submission (xs:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-return|return]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], nonrelevant ("keep"|"remove"|"empty")
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-renew|renew]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], control (xs:IDREF)
| rowspan="1" colspan="1" | EMPTY
|-
| rowspan="1" colspan="1" |
[[#action-message|message]]
| rowspan="1" colspan="1" |
[[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]] (optional), level ("ephemeral" | "modeless" | "modal"|[[#def-PrefixedName|PrefixedName]])
| rowspan="1" colspan="1" |
(PCDATA|[[#elems-inline|UI Inline]])*
|}

Support elements are:

{| summary="listing of action support elements, attributes, and content models" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
! rowspan="1" colspan="1" | Minimal Content Model
|-
| rowspan="1" colspan="1" |
[[#action-param|param]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]], name (xs:string)
| rowspan="1" colspan="1" |
PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-body|body]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#action-xmlevents|Events]]
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-toggle-case|case]] (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]]
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-setfocus-control|control]] (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]] 
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-dispatch-name|name]] (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]] 
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-dispatch-targetid|targetid]] (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]] 
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-dispatch-delay|delay]] (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]]
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-dispatch-property|property]]
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]], name (xs:string)
| rowspan="1" colspan="1" | PCDATA
|-
| rowspan="1" colspan="1" |
[[#action-load-resource|resource]] (deprecated)
| rowspan="1" colspan="1" |
[[#structure-attrs-common|Common]], [[#structure-attrs-value|value]]
| rowspan="1" colspan="1" | PCDATA
|}

This module also defines the content set <span id="action-content-set">'''"Action"'''</span>, which includes all the above elements:

 (action|setvalue|insert|delete|setindex|toggle|setfocus|dispatch|
  rebuild|recalculate|revalidate|update|refresh|reset|retain|
  load|send|message)*

<div class="example" title="action">
 <trigger label="Reset" label="Reset">
   <reset ev:event="DOMActivate" model="thismodel"/>
 </trigger>

This example defines a trigger that resets all instance values in a model back to their original values. The action is the element <code>reset</code> which is activated when the <code>DOMActivate</code> event occurs on the <code>trigger</code> element.
</div>

===Common Attributes for Actions===
The following attributes are available to all [[#action-content-set|Action]] elements.

'''Action Common''' 
{| id="attrs-action-common" summary="listing of XForms Common Action attributes" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
|-
| rowspan="1" colspan="1" |
[[#action-content-set|Action]]
| rowspan="1" colspan="1" | [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#action-xmlevents|Events]], if (boolean Expression), while (boolean Expression), iterate (node-sequence Expression)
|}

An action is normally performed once when encountered. However, execution may be conditional or iterated with the use of these attributes.

; if
: Optional expression defined below in Section [[#action-conditional|The if Attribute]].
; while
: Optional expression defined below in Section [[#The while attribute|The While Attribute]].
; iterate
: Optional expression defined below in Section [[#The iterate attribute|The Iterate Attribute]].

<span id="action-xmlevents">'''XML Events'''</span>
{| summary="listing of XForms Common Action attributes" border="1"
! rowspan="1" colspan="1" | Element
! rowspan="1" colspan="1" | Attributes and Their Content (after AVT evaluation)
|-
| rowspan="1" colspan="1" |
[[#action-content-set|Action]]
| rowspan="1" colspan="1" | event(NMTOKEN), observer (IDREF), target (IDREF), handler (URI), phase ("capture" | "default"*), propagate ("stop" | "continue"*), defaultAction ("cancel" | "perform"*)
|}
All of the "global" attributes defined in the <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki> specification are usable when prefixed with the XML Events namespace. Processing is defined in section 2.3 of <nowiki>[</nowiki>[[#ref-xml-events |XML Events]]<nowiki>]</nowiki>.

===<span id="action-processing">Processing Common to All Actions</span>===

If an action has a <code>model</code> attribute which does not identify a model element, then an [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>binding-error</code> is dispatched.

If an error occurs during the evaluation of a binding expression on an action, then an [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>binding-error</code> is dispatched.

If an error occurs during the evaluation of a non-binding expression on an action, then an [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>expression-error</code> is dispatched.

If any value of type <code>IDREF</code>, except for <code>model</code>, on an action is required to identify a certain type of element, and doesn't, then an [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>''element''-''attribute''</code> is dispatched, where ''element'' is the name of the action, and ''attribute'' is the name of the attribute at fault.

</div><div class="div3">
===<span id="action-conditions">Conditional and Iterated Execution of Actions</span>===

Any action can be guarded by an expression that determines if, or how often, the action is performed.

====<span id="action-conditional">The <code>if</code> attribute</span>====

An <code>if</code> attribute contains an expression that is evaluated in the [[#element-evaluation-context|element evaluation context]] before the action is executed; the result is converted to <code>boolean</code>. The action is performed only if the result is <code>true</code>.

If this attribute is applied to an <code>action</code> element and it evaluates to <code>false</code>, then none of the contained actions are performed. 

<div class="note">

'''Note:'''

In <code>insert</code> and <code>delete</code> actions, the <code>context</code> attribute is evaluated before the <code>if</code> attribute.

</div>
<div class="example" title="Automatic Focus Advancement">
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.

 <input ref="areaCode" id="AreaCodeControl" incremental="true" label="Area Code">
   <setfocus
     ev:event="xforms-value-changed"
     control="ExchangeControl"
     if="string-length(.)=3 and . > 0"/>
 </input>
 <input ref="exchange" id="ExchangeControl" incremental="true" label="Exchange">
   <setfocus
     ev:event="xforms-value-changed"
     control="LocalControl"
     if="string-length(.)=3 and . > 0"/>
 </input>
 <input ref="local" id="LocalControl" incremental="true" label="Local">
   <setfocus
     ev:event="xforms-value-changed"
     control="ExtensionControl"
     if="string-length(.)=4 and . > 0"/>
 </input>
</div>
<div class="example" title="Handling Focus for Empty Repeats">
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.
 <trigger id="InsertControl" label="Insert Row">
   <action ev:event="DOMActivate">
     <insert
       context="purchaseOrder/lines"
       ref="line"
       at="index('PurchaseOrderRepeat')"
       origin="instance('prototype')"/>
     <setfocus control="PurchaseOrderRepeat"/>
   </action>
 </trigger>
 <repeat ref="purchaseOrder/lines/line" id="PurchaseOrderRepeat">
   ...
   <trigger label="Delete Row">
     <action ev:event="DOMActivate">
       <setfocus control="InsertControl" if="last()=1"/>
       <delete ref="../line" at="index('PurchaseOrderRepeat')"/>
     </action>
   </trigger>
   ...
 </repeat>

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

====<span id="action-iterated">The <code>while</code> attribute</span>====

The <code>while</code> attribute contains an expression that is evaluated in the [[#element-evaluation-context|element evaluation context]] before the action is executed; the result is converted to <code>boolean</code>. If the value 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 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 the expression yields <code>true</code>.

When XForms actions are iteratively executed, they are still subject to the normal action processing rules of updating 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="example" title="Summing Selected Results">
Counter and accumulator variables are created in instance data to sum a selection of values chosen by the user
 <trigger label="Get Sum">
   <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 class="div2">

====<span id="action-iterate-attribute">The <code>iterate</code> attribute</span>====
The <code>iterate</code> attribute contains an expression that is evaluated once in the [[#element-evaluation-context|element evaluation context]] before the action is executed, resulting in a sequence of items. The action is then executed once for each item in the sequence, with the item replacing the default in-scope evaluation context.

<div class="example" title="Set all total children elements to zero">
  <setvalue iterate="*/total" ref="." value="0"/>
</div>

{{SpecNote|Iterate changes the evaluation context for <code>if</code> and <code>while</code> attributes, and is evaluated before either of the two.}}

{{SpecNote|Since the iterate expression is evaluated once using the element evaluation context, before the action is executed, the action will also be executed for nodes that are deleted by the action or its descendent actions. A deleted node no longer belongs to a document, and you can use this characteristic in the if attribute to skip deleted nodes if you need to.}}
</div>

===<span id="action-action">The action Element</span>===

This is a container for other actions.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; type
: Optional MIME type of the language of the script. 

Content: ([[#action-content-set|Action]]|[[#structure-var-element|var]])* | [[#action-param|param]]*, [[#action-body|body]]
</div>
If there is no <code>type</code> attribute, this element is a container for one or more other Actions: when the element is activated, the contained actions are activated one-by-one in order.

If the <code>type</code> attribute is present, and the language it indicates is not supported, 
then when the <code>action</code> element is activated, an [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>script-language</code> is dispatched. The <code>error-message</code> context information may contain a more specific error message. The supported languages depend on the implementation, which may not support any extra languages at all. 

Otherwise, the script in the inline content is executed. If an error occurs during execution, an [[#evt-actionError|xforms-action-error]] with an <code>error-type</code> of <code>script-error</code> is dispatched. The <code>error-message</code> context information may contain a more specific error message. 

<div class="example" title="Grouping Action">
 <action ev:event="DOMActivate">
   <setvalue ref="ready">yes</setvalue>
   <send/>
 </action>
</div>
<div class="example" title="JavaScript Action">
 <action type="text/javascript" ev:event="DOMActivate">
   alert('JavaScript alert: ');
 </action>
</div>
</div>

<div class="div3">

====<span id="action-param">The param Element (for action)</span>====

The <code>param</code> element allows passing one or more parameters to a script when the <code>type</code> attribute of the <code>action</code> element is present. If a <code>param</code> element is present, the <code>body</code> element is required.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Special Attributes:

; name
: Required attribute containing the name of the parameter to pass to the script.

Content: PCDATA
</div>
The value of the parameter is obtained from the <code>value</code> attribute, if present, or otherwise from the inline text. The value can be any sequence of items but is converted to a value compatible with the script type as needed.

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

====<span id="action-body">The body Element (for action)</span>====

This element specifies the body of the script when the <code>type</code> attribute of the <code>action</code> element is present and one or more <code>param</code> elements are present.
<div class="desc">
Common attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]]

Content: ANY
</div>
<div class="example" title="Script with Parameters">
 <action ev:event="DOMActivate" type="text/javascript">
   <param name="star"   value="instance()/star"/>
   <param name="planet" value="instance()/planet"/>
   <body>
     alert('I was just passed a few parameters: star = "' + star + '" and planet = "' + planet + '".');
   </body>
 </action>
</div>
</div>

<div class="div2">

===<span id="action-setvalue">The setvalue Element</span>===

This action sets the value of an instance data node.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
If the Single Item Binding does not select an instance data node, or the instance data node is readonly, this action has no effect.

The value to be used is obtained by evaluating the <code>value</code> attribute, or otherwise from the element content. If neither is present, the empty string ("") is used.

The resulting string is inserted into the instance data as follows:

* Element nodes: If element child nodes are present, then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>setvalue-children</code> is dispatched; otherwise the string becomes the new content of the element.
* Attribute nodes: The string-value of the attribute is replaced with the new value.
* Text nodes: If the new value is the empty string the text node is eliminated; otherwise the text node is replaced with the new value.
* Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
* the root node of an instance: an [[#evt-actionError|xforms-action-error Event]] with an error-type of <code>setvalue-root</code> is dispatched.

<div class="note">

'''Note:'''

The <code>context()</code> function that returns the in-scope evaluation context item, can be used to provide the same initial evaluation context item to both the <code>ref</code> and <code>value</code> attributes. See Appendix [[#data-mutations|Patterns for Data Mutations]] for numerous further usage patterns for <code>setvalue</code>, <code>insert</code> and <code>delete</code>.

</div>

<div class="example" title="setvalue">
 <setvalue ref="a" value="0"/>
 <setvalue ref="a">0</setvalue>
 <setvalue ref="name"/>
 <setvalue ref="count" value=".+1"/>
 <setvalue bind="put-here" value="a/b/c"/>
 <setvalue iterate="player/score" ref="." value="0"/>
</div>
</div><div class="div2">

===<span id="action-insert">The insert Element</span>===

This action inserts items into a sequence. In brief:
*<code>ref</code> or <code>bind</code> gives a target sequence;
*<code>origin</code> gives one or more items to be inserted in the sequence (default: a copy of the last item of the target sequence);
*<code>at</code> gives an index into the target sequence for the insertions (default: the end of the sequence);
*<code>position</code> says whether to insert before or after the given position (default: after).

If the target sequence is empty (and <code>origin</code> is present and non-empty) the origin items are inserted into the context node, ignoring <code>at</code> and <code>position</code>.

<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Sequence Binding]] (optional)

Special Attributes:

; origin
: Optional expression giving a sequence of items to be inserted; default: the last item of the target sequence.
; at
: Optional number expression giving an index into the target sequence where items are to be inserted; default: the end of the sequence.
; position
: Optional selector that indicates where to put the inserted nodes relative to the insert index. Possible values are <code>before</code> and <code>after</code>; default: <code>after</code>.

Content: EMPTY
</div>

The '''target-sequence''' is obtained from the [[#element-evaluation-context|element evaluation context]].

The '''origin-sequence''' is determined: 
* if the <code>origin</code> attribute is given, it is evaluated in the [[#in-scope-evaluation-context|in-scope evaluation context]]; 
* otherwise, if the target-sequence is non-empty, its last node is used; 
* otherwise, the <code>insert</code> action has no effect.

Root nodes (parents of document elements) are removed from the origin-sequence, and the result used. An implementation may choose not to include namespace nodes in the origin-sequence, in particular if the namespace axis is not supported or if inserting the namespace node would make the data model inconsistent. 

If the resulting origin-sequence is empty, the <code>insert</code> action has no effect.

The '''insert index''' is determined:
* if the target-sequence is empty, there is no insert index;
* if the <code>at</code> attribute is present, it is evaluated as a number in the [[#element-evaluation-context|Element Evaluation Context]] and rounded to the nearest integer. If it is not a number, is greater than the target-sequence size, or is less than 1, the <code>insert</code> action has no effect;
* otherwise, the size of the target-sequence is used.

The '''insert location node''' is determined:
* if the target-sequence is empty, the context node from the [[#in-scope-evaluation-context|in-scope evaluation context]] is used; 
* otherwise the target-sequence at the position given by the insert index is used.

If the insert location node is readonly and the target-sequence is empty, or if the parent of the insert location node is readonly,  the <code>insert</code> action has no effect.

In the origin-sequence, each item is treated in order: a node and its entire subtree is copied; a text node is created for each atomic value.

The '''target location''' is determined for each copied node:
* if the target-sequence is non-empty, then the copied node will become the sibling of the insert location node:
** if the insert location node is an attribute or root node, the target location is undefined; 
** otherwise the target location is immediately before or after the insert location node, depending on the <code>position</code> attribute setting or its default;
* if the target-sequence is empty, then the copied node will become a child of the insert location node. The target location is determined by the type of the insert location node:
** the root node of an instance (which is the parent of the root element): 
*** if the copied node is an element, then the target location is the root element of the instance;
*** if the copied node is not an element, then the target location is before the first child of the insert location node;
** an element: 
*** if the copied node is an attribute, then the target location is the attribute list of the element;
*** if the copied node is not an attribute, then the target location is before the first child of the insert location node, or the child list of the insert location node if it is empty;
** otherwise (it cannot be the parent of the copied node, so:) the target location is undefined.

If the target location is undefined, or there is a node type conflict between the copied node and the target location (for example, an attribute cannot be inserted as a sibling of an element), the insertion for that copied node is ignored.

The copied node is inserted:
* 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 copied node is an element, then the instance root element is deleted before the copied node is inserted at the target location;
* if the copied 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;
* otherwise the copied node is inserted into its target location depending on node type. 

Each copied node that is inserted is added to an inserted-nodes list that is provided in the <code>xforms-insert</code> event context information. Each copied node used to update an existing attribute node, the existing attribute node is added to the list of inserted-nodes.

If the list of inserted-nodes is empty, the <code>insert</code> action has no effect.

The <code>insert</code> action is successfully completed by dispatching the <code>xforms-insert</code> event with appropriate context information to the instance. 

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

Processors must at all times keep the data consistent with the constraints imposed by the XPath Data Model. See [[#structure-model-instance|The Instance Element]] for details.
</div>

<div class="example" title="Simple insert">
 <instance>
   &lt;data xmlns="">
     <list><a>1</a><a>2</a><a>3</a></list>
   </data>
 </instance>

 <trigger label="+">
   <insert ref="list/a" ev:event="DOMActivate"/>
 </trigger>
The trigger duplicates the last element of the list (and so if the list is empty, nothing happens).
</div>
<div class="example" title="insert">
 <instance>
   &lt;data xmlns="">
     <list><a>1</a><a>2</a><a>3</a></list>
     <blank><a>0</a></blank>
   </data>
 </instance>

 <trigger label="+">
   <insert context="list" ref="a" origin="../blank/a" ev:event="DOMActivate"/>
 </trigger>
This trigger inserts the 'blank' element at the end of the list, whether empty or not. 

To insert it at the beginning of the list, use:
 <insert context="list" ref="a" at="1" position="before" origin="../blank/a" ev:event="DOMActivate"/>
</div>
<div class="example" title="Adding or replacing an attribute">
 <instance resource="data.xml"/>
 <instance id="template">
    <data xmlns="" total="0"/>
 </instance>
 ...
 <action ev:event="xforms-ready">
    <insert context="/data" origin="instance('template')/@total"/>
 </action>
On initialization, if the document element <code>/data</code> doesn't have a <code>total</code> attribute, one will be created; if it does, it will be replaced.
</div>
<div class="example" title="Inserting into a repeat, whether or not it is empty">
 <instance>
   <purchaseOrder xmlns="">
     <subtotal/>
     <tax/>
     <total/>
   </purchaseOrder>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     ...
     <item>
       <product/>
       <quantity/>
       <unitcost/>
       <price/>
     </item>
     ...
   </prototypes>
 </instance>

 <repeat ref="/purchaseOrder/item" id="R">
    ...
 </repeat>

 <trigger label="Add to purchase order">
   <action ev:event="DOMActivate">
     <insert context="/purchaseOrder" ref="item" at="index('R')" 
             origin="instance('prototypes')/item"/>
     <setfocus control="R"/>
   </action>
 </trigger>
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>

<div class="example" title="Insert and Read-Only Content">
 <model>
   <instance>
     &lt;data xmlns="">
       <name>
         <first>John</first>
         <last>Doe</last>
       </name>
       <address>
         <street>123 Main St.</street>
         <city>Smallville</city>
       </address>
     </data>
   </instance>
 
   <bind ref="name" readonly="true()"/>
   <bind ref="address/street" readonly="true()"/>
 
   <action ev:event="xforms-model-construct-done">
     <insert id="I1" ref="name/*" .../>
     <insert id="I2" ref="address/street" at="1" >
   </action>
 </model>
Insert I1 fails because it attempts to insert into the content of a readonly node (<code>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 [[#data-mutations|Patterns for Data Mutations]] for numerous further usage patterns for <code>setvalue</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.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]], [[#structure-attrs-nodeset|Sequence Binding]]

Special Attributes:
; at
: Optional number expression giving the position in the target sequence where an item is to be deleted.

Content: EMPTY
</div>

The '''target-sequence''' is obtained from the [[#element-evaluation-context|element evaluation context]]. The delete action has no effect if the target-sequence is empty. {{SpecNote|Not expressing the Sequence Binding is deprecated.}}

The '''delete index''', if any, is determined:
* if the <code>at</code> attribute is not given, there is no delete index;
* otherwise, the <code>at</code> attribute is evaluated in an evaluation context where the context node is the first node of the target-sequence, the context size is the size of the target-sequence, and the context position is 1. It is evaluated as a number and rounded to the nearest integer. If it is not a number, greater than the size of the target-sequence, or less than 1, the <code>delete</code> action has no effect.

If there is no delete index, each item in the target-sequence is treated, otherwise only the item at the delete index in the target-sequence is treated.

Items are treated as follows:
* an item is ignored if it is a root node, the root document element of an instance, an atomic value, or its parent is a readonly node;
* otherwise, it is deleted.

If the target-sequence contains nodes from more than one document, the nodes are deleted from their respective document.

If no node is deleted in the preceding steps, the <code>delete</code> action has no effect, otherwise, the <code>delete</code> action is successfully completed by dispatching the <code>xforms-delete</code> event with appropriate context information to the instance.

{{SpecNote|An implementation may choose not to delete namespace nodes, in particular if the namespace axis is not supported or if deleting a namespace node would make the data model inconsistent.}}
{{SpecNote|When a node is deleted from an instance it will no longer have a parent.}}
{{SpecNote|When a deleted node provides the evaluation context for an action, it will keep providing that context as long as the action is running.}}
{{SpecNote|Processors must at all times keep the data consistent with the constraints imposed by the XPath Data Model. See [[#structure-model-instance|The Instance Element]] for details.}}

<div class="example" title="simple deletes">
Delete the first element of a list:
 <delete ref="list/a" at="1"/>
The last:
 <delete ref="list/a" at="last()"/>
Delete all the elements:
 <delete ref="list/a"/>
</div>
<div class="example" title="Using delete and insert to maintain a non-empty repeat">
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. 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>.
 <trigger label="Delete from purchase order">
   <action ev:event="DOMActivate">
     <delete context="/purchaseOrder" ref="item" at="index('R')"/>
     <insert
       context="/purchaseOrder"
       if="not(item)"
       ref="item"
       origin="instance('prototypes')/item"/>
     <setfocus control="R"/>
   </action>
 </trigger>

The <code>delete</code> could read <code><delete ref="/purchaseOrder/item" at="index('R')"/></code>, but the <code>context</code> attribute is here used for symmetry with the <code>insert</code>.
</div>

<div class="example" title="Delete and read-only content">
 <model>
   <instance>
     &lt;data xmlns="">
       <name>
         <first>John</first>
         <last>Doe</last>
       </name>
       <address>
         <street>123 Main St.</street>
         <city>Smallville</city>
       </address>
     &lt;/data>
   </instance>
 
   <bind ref="name" readonly="true()"/>
   <bind ref="address/street" readonly="true()"/>
 
   <action ev:event="xforms-model-construct-done">
     <delete id="D1" ref="name/first"/>
     <delete id="D2" ref="address/street" at="1" >
     <delete id="D3" ref="address" at="1" >
   </action>
 </model>

Delete D1 fails because it attempts to delete from the content of a readonly node (<code>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>

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

===<span id="action-replace">The replace Element</span>===
This action replaces an instance data node with another, a complement of <code>setvalue</code>.
<div class="desc">

Common Attributes: [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]]

Special Attribute:
 
;with
:Required expression giving an item which will replace the Single Item Binding.
 
Content: EMPTY.
</div> 

The Single Item Binding is evaluated to give the target node; if it does
not select an instance data node, or the instance data node's parent is readonly,
the action has no effect.
 
The <code>with</code> attribute is evaluated in the [[#element-evaluation-context|element evaluation context]] to give an item; the
[[#def-first-node-rule|first-item rule]] is applied if necessary. If the item is an atomic value, a text node is created from it.
 
If there is a node type conflict between the source node and the target (for example, trying to replace an attribute with an element), an <code>[[#evt-actionError|xforms-action-error]]</code> event with an <code>error-type</code> of <code>replace-with</code> is dispatched, and the action has no further effect.
 
The target node is replaced with the source node (including its entire subtree), and the <code>[[#evt-replace|xforms-replace]]</code> event is dispatched with appropriate context information to the instance containing the target node.
 
<div class="example" title="replace">
 <replace ref="address" with="contact/address[@type='home']"/>
</div>

See Appendix [[#data-mutations|Patterns for Data Mutations]] for numerous further usage patterns for <code>setvalue</code>, <code>insert</code>, <code>delete</code> and <code>replace</code>.
</div><div class="div2">

===<span id="action-setindex">The setindex Element</span>===

This action sets the repeat index of a [[#The repeat Element|<code>repeat</code>]] control.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; repeat
: Required reference to the ID of a repeat element.
; index
: Required expression that evaluates to a 1-based offset into the sequence.

Content: EMPTY
</div>
An [[#model-update|update]] is done if necessary.

The element referred to by the <code>repeat</code> attribute is identified. If no such <code>repeat</code> element exists, then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>setindex-repeat</code> is dispatched.

The index attribute is evaluated as a number; if it is not a number, this action has no effect. Otherwise the index of the identified <code>repeat</code> is set to the value rounded to the nearest integer. See [[#ui-repeat-index-processing|index processing]] for how this may be responded to by the Processor.

<div class="note">

'''Note:'''

If the <code>repeat</code> element bearing the matching ID resides within another repeating construct such as repeat, the general method described in [[#idref-resolve|Resolving ID References]] is used to determine the desired run-time repeat object.
</div>

<div class="example" title="setindex">
 <setindex repeat="R" index="1"/>
 <setindex repeat="R" index="index('R')+1"/>
</div>

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

===<span id="action-toggle">The toggle Element</span>===
This action selects one possible case from an exclusive list of alternatives in a <code>switch</code> element.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; case
: Optional reference to the ID of a <code>case</code> element child of a <code>switch</code> element. 

Content: [[#action-toggle-case|case]]?
</div>
An [[#model-update|update]] is done if necessary.
 
A [[#ui-case|case]] identifier is obtained from the <code>[[#action-toggle-case|case]]</code> child element of the <code>toggle</code> element or otherwise from the <code>case</code> attribute. If no <code>case</code> element is identified by this value, then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>toggle-case</code> is dispatched.
 
If the identified <code>case</code> has a <code>name</code> attribute, and its containing <code>switch</code> has a Single Item Binding which identifies a node that is not readonly, then
the node is set to the value of the <code>name</code> attribute as if by a <code>setvalue</code> action.
 
The <code>case</code> is selected.

<div class="note">

'''Note:'''

If the <code>case</code> element bearing the matching ID resides in a repeating construct such as <code>repeat</code>, the general method described in [[#idref-resolve|Resolving ID References]] is used to determine the desired run-time case object.
</div>

<div class="example" title="toggle elements">
 <toggle case="home"/>
 <toggle case="{state}"/>
</div>
<div class="div3">

====<span id="action-toggle-case">The case Element (for toggle) (Deprecated)</span>====

The <code>case</code> element (deprecated in favor of using an AVT in the case attribute) provides the identity of a [[#ui-case|case]] element to select within a [[#ui-switch|switch]].
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The [[#ui-case|case]] to be selected is identified by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element.

<div class="example" title="toggle with case">
 <toggle>
   <case value="concat('case_', ../addressBlockType)"/>
 </toggle>
 <toggle>
   <case>home</case>
 </toggle>
</div>
</div></div><div class="div2">

===<span id="action-setfocus">The setfocus Element</span>===

This action gives input focus to a control.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attribute:

; control
: Optional reference to the ID of a [[#def-form-control|control]].

Content: [[#action-setfocus-control|control]]?
</div>
The control to which focus should be given is identified by the <code>control</code> attribute if present, and otherwise by the [[#action-setfocus-control|control]] element. If no such control is identified, then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>setfocus-control</code> is dispatched.

An [[#model-update|update]] is done if necessary.

An <code>[[#The xforms-focus Event|xforms-focus]]</code> event is then dispatched to the identified control.

<div class="note">

'''Note:'''

If the control to be identified is in a repeating construct such as <code>repeat</code>, the method described in [[#idref-resolve|Resolving ID References]] is used.

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

'''Note:'''

Changing the focus to a control within a repeat object may cause one or more repeat index values to be changed as described in the [[#ui-repeat-ui|Repeat Processing]] section.
</div>

<div class="example" title="setfocus">
 <setfocus ev:event="xforms-ready" control="start"/>
</div>
<div class="example" title="setfocus from instance data">
 <setfocus control="{next-incomplete}"/>
</div>
</div>
<div class="div3">

====<span id="action-setfocus-control">The control Element (for setfocus) (Deprecated)</span>====

This element (deprecated in favor of using an AVT in the control attribute) provides the identity of a control to receive focus.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The control to receive focus is identified by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element.

<div class="example" title="setfocus with control element">
 <setfocus><control>start</control></setfocus>
 <setfocus>
   <control value="concat('input_', ../paymentType)"/>
 </setfocus>
</div>
</div>
<div class="div2">

===<span id="action-previousfocus">The previousfocus Element</span>===

This action gives input focus to the previous control in navigation order.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>

An [[#model-update|update]] is done if necessary.

If no control currently has focus, this action has no effect; otherwise the previous control in navigation order is identified, and an <code>[[#The xforms-focus Event|xforms-focus]]</code> event is dispatched to it.

See the section on [[#all-controls-interaction|interaction for all controls]] for details of navigation order.

<div class="note">

'''Note:'''

Changing the focus to a control within a repeat object may cause one or more repeat index values to be changed as described in the [[#ui-repeat-ui|Repeat Processing]] section.
</div>

<div class="example" title="previousfocus">
 <previousfocus/>
</div>
</div>
<div class="div2">

===<span id="action-nextfocus">The nextfocus Element</span>===

This action gives input focus to the next control in navigation order.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>
An [[#model-update|update]] is done if necessary.

If no control currently has focus, this action has no effect; otherwise the next control in navigation order is identified, and an <code>[[#The xforms-focus Event|xforms-focus]]</code> event is dispatched to it.

See the section on [[#all-controls-interaction|interaction for all controls]] for details of navigation order.

<div class="note">

'''Note:'''

Changing the focus to a control within a repeat object may cause one or more repeat index values to be changed as described in the [[#ui-repeat-ui|Repeat Processing]] section.
</div>

<div class="example" title="nextfocus">
 <repeat ref="entry">
    <input ref="." incremental="true" label="4 chars:">
        <nextfocus ev:event="xforms-value-changed" if="string-length(.)=4"/>
    </input>
 </repeat>
 <input ref="name" label="Your name"/>
A number of entries of exactly 4 characters have to be entered. After typing 4 characters, the user is automatically taken to the next entry. After all entries have been filled in, however many there are, the user will be taken to the control to input their name.
</div>
</div>

===<span id="action-dispatch">The dispatch Element</span>===

This action dispatches an event to an element.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; name
: Required string giving the name of the event to dispatch.
; targetid
: Required IDREF identifying a target element.
; delay
: Optional number giving the minimum number of milliseconds to delay dispatching the event. The default is no delay.
; bubbles
: Optional boolean indicating if this event bubbles &mdash; 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
: Optional boolean indicating if this event is cancelable &mdash; 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.

Content: [[#action-dispatch-name|name]]? [deprecated], [[#action-dispatch-targetid|targetid]]? [deprecated], [[#action-dispatch-delay|delay]]?  [deprecated], [[#action-dispatch-property|property]]* [in any order]
</div>
Two kinds of event can be dispatched:

# Predefined events (e.g., xforms-focus), in which case the <code>bubbles</code> and <code>cancelable</code> attributes are ignored and the standard semantics as defined in [[#rpm|Processing Model]] apply;
# User-defined events.

Events can be dispatched either immediately (while the current handler is still active), which is the default, or after the current handler has finished, by using the <code>delay</code> attribute.

The details of the event to be dispatched are collected:
* The name of the event is obtained from the <code>name</code> attribute or otherwise from the [[#action-dispatch-name|name child element]]. If the event name is not specified or an empty string, this action has no effect.
* The event delay, in milliseconds, is obtained from the <code>delay</code> attribute or otherwise from the [[#action-dispatch-delay|delay child element]]. If the value is not a positive or zero integer, this action has no effect; if the value is not specified or an empty string, there is no delay.
* If the event name does not identify a pre-defined event, then the values of <code>cancelable</code> and <code>bubbles</code> are obtained from their respective attributes.
* If the <code>dispatch</code> element has any <code>property</code> child elements, the event context is updated with their values.

The <code>targetid</code> attribute or child element is evaluated to identify an element;
if no such element exists, an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>dispatch-target</code> is dispatched to the default model.

If there is no delay specified then the event is dispatched immediately; otherwise (including when the delay is specified as zero), if there is no event with the same name and target element on the delayed event queue, the event is added to the queue. As soon as possible after the specified delay in milliseconds has elapsed, the event is removed from the delayed event queue and 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.

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, such as removal of controls associated by a <code>repeat</code> with an instance data node that is destroyed.

<div class="example" title="dispatch actions">
 <dispatch name="DOMActivate" targetid="zoomin"/>
 <dispatch name="tick" delay="1000" targetid="clock"/>
 <dispatch name="{../eventname}" targetid="map" bubbles="false">
    <property name="factor" value="10"/>
 </dispatch>
</div>

<div class="note">

'''Note:'''

If the target element is in a repeating construct such as <code>repeat</code>, the method described in [[#idref-resolve|Resolving ID References]] is used to determine it.

</div>

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

<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-property">The property Element (for dispatch)</span>====

Adds context information to an event to be dispatched.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Special Attributes:
;name
:The name of the context information to pass.

Content: PCDATA
</div>
The context information is obtained by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element, and is added to the event's context information for the name. The value can be any sequence of items.

<div class="example" title="Adding extra context information to an an event">
 <dispatch name="update-person" target="my-model">
   <!-- The "person" context information is assigned to the node pointed to by "instance('person')" -->
   <property name="person" value="instance('person')"/>
   <!-- The "min-age" context information is assigned the number 12 -->
   <property name="min-age" value="21"/>
   <!-- The "location" context information is assigned the string 'Michelle' -->
   <property name="new-first-name">Michelle</property>
 </dispatch>
Using the information:
 <action ev:event="update-person">
   <insert context="..." origin="event('person')"/>
   <setvalue ref="..." value="event('min-age')"/>
   <setvalue ref="..." value="event('new-first-name')"/>
 </action>
</div>

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

====<span id="action-dispatch-name">The name Element (for dispatch) (Deprecated)</span>====

The <code>dispatch</code> element (deprecated in favor of using an AVT in the name attribute) provides the name of an event to be dispatched.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The name of the event to be dispatched is obtained by evaluating the value attribute, or otherwise from the inline content of the element.

<div class="example" title="dispatch with name element">
 <dispatch targetid="clock"><name>tick</name></dispatch>
 <dispatch targetid="map"><name value="../eventname"/></dispatch>
</div>
</div><div class="div3">

====<span id="action-dispatch-targetid">The targetid Element (for dispatch) (Deprecated)</span>====

The <code>targetid</code> element (deprecated in favor of using an AVT in the targetid attribute) specifies the target of an event to be dispatched.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The ID of the target element is obtained by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element.

<div class="example" title="dispatch with targetid element">
 <dispatch name="tick"><targetid>clock</targetid></dispatch>
 <dispatch name="ping"><targetid value="../target"/></dispatch>
</div>
</div><div class="div3">

====<span id="action-dispatch-delay">The delay Element (for dispatch) (Deprecated)</span>====

The <code>delay</code> element (deprecated in favor of using an AVT in the delay attribute) specifies the delay in milliseconds before the event should be dispatched.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The delay for the event is obtained by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element.

<div class="example" title="dispatch with delay element">
 <dispatch name="tick" targetid="clock"><delay>1000</delay></dispatch>
 <dispatch name="ping" targetid="pong"><delay value="../timer"/></dispatch>
</div>
</div>
</div>

===<span id="action-signal">The signal Element</span>===

This action causes an event to be dispatched to an embedded or embedding form.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; name
: String giving the name of the event to be dispatched.
; control
: Optional IDREF identifying a [[#ui-control|<code>control</code>]] element.
; delay
: Optional number giving the minimum number of milliseconds to delay dispatching the event. The default is no delay.
; bubbles
: Optional boolean indicating if this event bubbles &mdash; 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
: Optional boolean indicating if this event is cancelable &mdash; 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.

Content: [[#action-dispatch-property|property]]*
</div>

Processing imitates that of the [[#action-dispatch|<code>dispatch</code>]] action.

If the element has a <code>control</code> attribute:

* if the attribute's IDREF does not identify a [[#ui-control|<code>control</code>]] element, an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>signal-control</code> is dispatched to the default model;
* otherwise, if the form embedded by the identified control has no [[#structure-shared-element|<code>shared</code>]] element, this action has no further effect;
* otherwise, the specified event is dispatched to the [[#structure-shared-element|<code>shared</code>]] element of the form embedded by the identified [[#ui-control|<code>control</code>]] element.

If the element has no <code>control</code> attribute:

* if this form is not embedded, this element has no further effect;
* otherwise, the specified event is dispatched to the [[#ui-control|<code>control</code>]] element that caused this form to be embedded.

<div class="example" title="signalling a ready event to the embedding form">
 <signal name="ready"/>
</div>
<div class="example" title="optionally signalling an event">
 <signal if="count = 0" name="finished"/>
</div>
<div class="example" title="signalling to an embedded form">
 <signal control="game" name="restart"/>
</div>
<div class="div2">

===<span id="action-cancel">The cancel Element</span>===

This action cancels the default action of the event currently being handled.

<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY.
</div>

If the current event is cancelable, its default action is cancelled; otherwise the cancel action has no effect.

<div class="example" title="A conditional cancel">
     <action ev:event="xforms-submit">
         <cancel if="state = 'dryrun'"/>
     </action>
</div>
</div><div class="div2">

===<span id="action-rebuild">The rebuild Element</span>===

Causes a [[#model-rebuild|rebuild]] on a model.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>
A rebuild is done on:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model.

<div class="note">Note that since implementations may combine rebuild, recalculate, revalidate, and refresh into fewer steps, this action may result in more than just a rebuild.</div>
</div><div class="div2">

===<span id="action-recalculate">The recalculate Element</span>===

This action causes a [[#model-recalculate|recalculate]] on a model.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>
A recalculate is done on:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model. 

<div class="note">Note that since implementations may combine rebuild, recalculate, revalidate, and refresh into fewer steps, this action may result in more than just a recalculate.</div>
</div><div class="div2">

===<span id="action-revalidate">The revalidate Element</span>===

This action causes a [[#model-revalidate|revalidate]] on a model.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>
A revalidate is done on:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model. 

<div class="note">Note that since implementations may combine rebuild, recalculate, revalidate, and refresh into fewer steps, this action may result in more than just a revalidate.</div>
</div><div class="div2">

===<span id="action-update">The update Element</span>===
This action causes an [[#model-update|update]] on a model.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>
An update is done on:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model. 
</div><div class="div2">

===<span id="action-refresh">The refresh Element</span>===

This action causes a [[#model-refresh|refresh]] on a model. 
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Content: EMPTY
</div>
A refresh is done on:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model.

<div class="note">
Note that since a refresh causes the dispatch of notification events, if it is required for ''everything'' to be up-to-date in the middle of an action, then <code>refresh</code> allows you to do that. Some actions, such as <code>toggle</code> and <code>setindex</code> in effect force a refresh as part of their execution.

Any function which requires asking controls for information, such as <code>index</code> and <code>case</code>, will be up-to-date only after a refresh.
</div>
</div><div class="div2">

===<span id="action-reset">The reset Element</span>===
This action causes one or all of the instances of a model to be reset to their retained values.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special attribute:
;instance
:Optional instance identifier.

Content: EMPTY
</div>
If the <code>instance</code> attribute is present, and it does not identify an instance, then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>reset-instance</code> is dispatched. Otherwise, the instance identified is returned to the state it had the last time it was retained, either during initialization, or as a result of a [[#action-retain|retain action]].

If the attribute is not present, all instances in a model are so treated:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model.  

<div class="example" title="reset">
 <reset/>
 <reset model="m"/>
 <reset instance="admin"/>
</div>
</div><div class="div2">

===<span id="action-retain">The retain Element</span>===
This action causes one or all of the instances of a model to be retained for future use by the [[#action-reset|reset action]]. This is also done automatically for all instances at initialization.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special attribute:
;instance
:Optional instance identifier.

Content: EMPTY
</div>
If the <code>instance</code> attribute is present, and it does not identify an instance, then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>retain-instance</code> is dispatched. Otherwise, the state of the instance identified is retained.

If the attribute is not present, all instances of a model are so treated:
* the model identified by the <code>model</code> attribute, if present;
* otherwise, the model identified by the <code>model</code> attribute of the closest ancestor element, if any;
* otherwise, the first model.

<div class="example" title="retain">
 <retain/>
 <retain model="m"/>
 <retain instance="admin"/>
</div><div class="div2">

===<span id="action-load">The load Element</span>===

This action traverses a link, giving a similar effect to clicking on an <code>a</code> element in HTML.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]] (optional; deprecated)

Special Attributes:

; resource
: Optional URI of a resource to load.
; target
: Optional presentation environment name or keyword. Behavior is defined for values "_self" and "_blank". In addition, an implementation-dependent presentation name can be specified. The default is "_self".
; show [deprecated]
: Optional link behavior specifier. The allowed values are "replace", and "new".

Content: [[#action-load-resource|resource]]?
</div>
A URI is obtained from the <code>resource</code> attribute if present, otherwise from the [[#action-load-resource|resource]] child element if present [deprecated], and otherwise from the Single Item Binding [deprecated]; if none is present the action has no effect.

If the result is an empty sequence, an [[#evt-actionWarning|xforms-action-warning]] is dispatched, with an <code>error-type</code> of <code>load-error</code>, and the <code>load</code> action has no further effect. 

The URI is the address of a resource, defined as an <nowiki>[</nowiki>[[#ref-xlink-1.0 |XLink 1.0]]<nowiki>]</nowiki> link between the <code>load</code> element and the resource indicated. (No XLink <code>actuate</code> value is defined, since control of actuation is defined by XML Events.)

The target presentation environment is obtained from the <code>target</code> attribute, or otherwise the <code>show</code> attribute. If neither is present, "_self" is used.

The link indicated by the URI is traversed. Processing of the resource reached by traversing the link depends on the target presentation environment:

; _self or replace
: The document is loaded into the current presentation environment. XForms processing is ended, exactly as if the user had requested navigating to a new document.
; _blank or new
: The document is loaded into a new presentation environment, e.g., a new window or tab. XForms processing in the original context continues.
; Any other value
: Behavior is implementation-dependent. {{SpecNote|If the host language is HTML, the implementation is encouraged to handle the <code>target</code> attribute as defined in HTML for the <code>a</code> element. In particular, values of "_blank", "_self", "_parent", "_top", as well as browsing context names should be supported.}}

If traversal is not possible or fails, then an 
[[#evt-actionWarning|xforms-action-warning]] should be dispatched, with an <code>error-type</code> of <code>load-error</code>;
however, it is recognized that there are circumstances where this is not possible, such as when the error is discovered after XForms processing has ended.

<div class="example" title="load actions">
 <load resource="{../document}" target="_blank"/>
 <load <nowiki>resource="http://example.com/index.html"</nowiki>/>
</div>
<div class="div3">

====<span id="action-load-resource">The resource Element (for load) (Deprecated)</span>====

The <code>resource</code> child element of <code>load</code> (deprecated in favor of using an AVT in the resource attribute) specifies the URI of a resource.
<div class="desc">
Common Attributes: [[#structure-attrs-common|Common]], [[#structure-attrs-evaluation|Evaluation]], [[#structure-attrs-value|value]]

Content: PCDATA
</div>
The URI is obtained by evaluating the <code>value</code> attribute, or otherwise from the inline content of the element.

<div class="example" title="load actions with resource elements">
  <load target="_blank"><resource value="../document"/></load>
  <load><resource><nowiki>http://example.com/index.html</nowiki></resource></load>
</div>
</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 to a <code>submission</code> element.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; submission
: Optional reference to the ID of a [[#submit-submission-element|<code>submission</code> element]]. If omitted, then the first <code>submission</code> in document order from the <code>model</code> associated with the [[#in-scope-evaluation-context|in-scope evaluation context]] is used.

Content: EMPTY
</div>

A submission element is identified from the submission attribute or its default: if no such element is identified then an [[#evt-actionError|xforms-action-error]] event with an error-type of <code>send-submission</code> is dispatched; otherwise an <code>xforms-submit</code> event is dispatched to the element.

Processing of the <code>xforms-submit</code> event is defined in the processing model &mdash; see [[#The xforms-submit Event|The xforms-submit Event]].

<div class="example" title="send actions">
 <send submission="update"/>
 <send/>
 <send model="M1"/>
</div>

</div>

===<span id="action-return">The return Element</span>===
This action returns values from an embedded XForm.

<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:
; nonrelevant
: Optional string indicating whether non-relevant values are included in the returned data. Values are "keep": all values are returned, "remove": non-relevant values are not returned, "empty": non-relevant nodes are returned as empty values. The default is "remove".
</div>

If the current XForm has not been embedded in another, or the [[#ui-control|<code>control</code> command]] invoking this XForm has not supplied a receiving binding, then an [[#evt-actionError|<code>xforms-action-error</code> event]] with an <code>error-type</code> of <code>return-error</code> is dispatched.

Otherwise, an [[#model-update|update]] is done if necessary, and the binding attributes evaluated to give a nodeset, which is filtered for relevance according to the nonrelevant attribute [[#submission-processing|as for a submission]], and returned to the embedding XForm, where it is used to replace the node specified in the binding attribute of the <code>control</code> element in that XForm, as if by a submission with <code>replace="instance" targetref="..."</code>.

<div class="example" title="return actions">
 <return ref="instance('result')"/>
 <return ref="value[@selected=true()]"/>
 <return ref="address" nonrelevant="keep"/>
</div>
<div class="div2">

===<span id="action-renew">The renew Element</span>===

This action causes the initial values of an embedded XForm to be re-initialised, possibly with new values.

<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]]

Special Attributes:

; control
: Required ID of a [[#ui-control|<code>control</code> element]].

Content: EMPTY
</div>

<div class="example" title="renew action">
 <instance id="start">
   &lt;data xmlns="">
      <attempt>1</attempt>
      <score>0</score>
   </data>
 </instance>
 ...
 <control id="game" resource="game.xml" initial="instance('start')"/>
 <trigger label="restart">
   <action ev:event="DOMActivate">
      <setvalue ref="attempt" value=". + 1"/>
      <setvalue ref="score" value="0"/>
      <renew control="game"/>
   </action>
 </trigger>
</div>

===<span id="action-message">The message Element</span>===

This action presents a message to the user.
<div class="desc">
Common Attributes: [[#attrs-action-common|Action Common]], [[#structure-attrs-single-node|Single Item Binding]], [[#structure-attrs-value|value]] (all optional)

Special Attributes:

; level
: Optional message-level identifier, one of ("ephemeral"|"modeless"|"modal"|[[#def-PrefixedName|PrefixedName]]). The default is "modal". There is no defined behavior for [[#def-PrefixedName|PrefixedName]] values.

Content: (PCDATA|[[#elems-inline|UI Inline]])*
</div>
The message text is obtained by evaluating the value attribute if given, otherwise from the Single Item Binding, if given, and otherwise from the inline content of the element. If the message is obtained from the inline content, then the output of any <code>output</code> controls in the <code>message</code> content is based on the instance data available when the <code>message</code> action occurs.

The user interface for the <code>message</code> action is created, and the message made available to the user in a manner based on the <code>level</code> attribute or its default.

<div class="example" title="message">
 <message value="concat('The time is ', substring-after(now(), 'T'))"/>
</div>

<div class="example" title="display the message 'Hello, world!' at start up">
 <model>
   <instance>
     &lt;data xmlns="">
       <name>John</name>
     &lt;/data>
   </instance>
  
   <action ev:event="xforms-ready">
     <setvalue ref="name">world</setvalue>
     <message>Hello, <output ref="name"/>!</message>
     ...
   </action>
 </model>
</div>
<div class="example" title="reporting an error">
The message includes the latest user input even though other controls not in the <code>message</code> action are not guaranteed to be updated until the end of [[#model-refresh|refresh]] processing:
 <input ref="birthday" label="Enter birthday:">
   <message ev:event="xforms-invalid">
       <output ref="."/> isn't a valid date
   </message>
 </input>
</div>
<div class="example" title="Using an update action ">
Since updates are not done during the processing of an action handler, if a <code>message</code> action is preceded by actions that change instance nodes, and the message references nodes that are computationally dependent on the changed nodes, then an <code>update</code> action should be done before the <code>message</code> action.
For instance, with 
 <model>
   <instance>
     &lt;data xmlns="">
       <x>0</x>
       <y/>
     &lt;/data>
   </instance>
   <bind ref="y" calculate="../x+1"/>
   <action ev:event="xforms-ready">
     <setvalue ref="x" value="1"/> 
     <message><output ref="y"/></message>
   </action>
 </model>
this will result in the value <code>1</code> being output. However, changing the <code>action</code> to
 <action ev:event="xforms-ready">
   <setvalue ref="x" value="1"/>
   <update/> 
   <message><output ref="y"/></message>
 </action>
will result in the output value <code>2</code>.
</div>

====<span id="action-message-modal">Modal messages</span>====
With <code>level="modal"</code>, further user interface operations are blocked until the message is explicitly dismissed by the user.

The Processor should support styling of modal messages in the host language integration.

A graphical browser might render a modal message as follows:
 <model>
   <message level="modal" ev:event="xforms-ready">This is not a drill!</message>
   ...
 </model>
[[Image:ui-modal-message.png|An alert popup, with a warning message.]]

====<span id="action-message-modeless">Modeless messages</span>====
A modeless message is presented until explicitly dismissed, but does not inhibit other user interface operations. A Processor should support styling of ephemeral messages in the host language integration.

A graphical browser might render a modeless message as follows:
 <secret ref="/login/password" label="Password:">
   <message level="modeless" ev:event="xforms-value-changed"
           if="length(.) &gt; 3
               and matches(., '[A-Z]+$')
               and not(matches(., '[a-z]+'))">
      Is your caps-lock key on?
   </message>
 </secret>
[[Image:ui-message-modeless.png|A password text entry form controls, with a tooltip below, reading 'Is your caps-lock key on?']]

====<span id="action-message-ephemeral">Ephemeral messages</span>====

An ephemeral message is presented only briefly, and need not be explicitly dismissed.  A Processor should support styling of ephemeral messages in the host language integration.

In this example, the message appears briefly when a submit control is activated, offering an encouraging message.
 <group label="Change of Address:">
     <input ref="name" label="Name:">
       <hint appearance="minimal">Last, First</hint>
     </input>
     <input ref="website" label="Website:">
       <hint appearance="minimal"><nowiki>http://</nowiki></hint>
     </input>
     <submit submission="apply" label="Apply">
       <message level="ephemeral" ev:event="DOMActivate">Don't forget to write!</message>
     </submit>
 </group>
A graphical browser might render an ephemeral message as follows:
[[Image:ui-message-ephemeral.png|A group of text entry form controls, with a mouse pointer visible on a submit button, and a tooltip below, reading 'Don't forget to write!']]

</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 class="div1">

==<span id="conform">Conformance</span>==

<div class="div2">

===<span id="conform-desc-documents">Conforming XForms Documents</span>===

All XForms Containing Documents [[#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>
* <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>, or a [[#elems-all-controls|control]]. Individual XForms fragments are expected to be schema-valid according to the XML 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 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-2.0 |XPath 2.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>===

There are two levels of conformance: "model", and "full".

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

<span id="conform-model-processor">An '''XForms Model Processor''' [[#intro-reading|must]] support:</span>

* all attributes of the <code>model</code> element;

* all attributes and content of the <code>instance</code> element;

* all attributes, content and other aspects of <code>bind</code> elements;

* all of <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 automatic datatype information defined by XForms;

* parsing inline and external declared XML Schema and consuming their XML Schema datatype information <nowiki>[</nowiki>[[#ref-xschema-2 |XML Schema part 2]]<nowiki>]</nowiki>; the processor [[#intro-reading|should]] consume all XML Schema information available where appropriate in the processing model; 

* all of the [[#submit|Submission module]] except:
** all [http://www.w3.org/TR/REC-xml-names/#NT-NCName NCName] submission methods [[#intro-reading|should]] be supported;  
** 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>file</code>, <code>mailto</code> and <code>ftp</code> schemes [[#intro-reading|may]] be supported;
** submission headers [[#intro-reading|may]] be combined with those from the user agent in the manner specified by the <code>combine</code> attribute;

* all local attributes defined for every supported action, including conditional and iteration attributes;

* the actions <code>action</code>, <code>insert</code>, <code>delete</code>, <code>setvalue</code>, <code>reset</code>, <code>retain</code>, <code>rebuild</code>, <code>recalculate</code>, <code>revalidate</code>, <code>update</code>, and <code>dispatch</code>; 

* the events <code>xforms-model-construct-done</code>, <code>xforms-ready</code>, <code>xforms-link-error</code> and <code>xforms-version-error</code>;

* the <code>ev:event</code> attribute so that XForms action handlers can appear as children of either the target elements of the events they handle or ancestors of those elements. 

An [[#conform-model-processor|XForms Model 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 notification events <code>xforms-insert</code> and <code>xforms-delete</code>, and all other events targetted at <code>model</code> elements except for <code>xforms-refresh</code>;

* the actions <code>send</code>, <code>load</code>, <code>refresh</code>, <code>setindex</code>, <code>setfocus</code>, <code>toggle</code>, and <code>message</code>.

An [[#conform-model-processor|XForms Model Processor]] [[#intro-reading|may]] support:

* user interface creation and refresh behaviors described for <code>model</code> processing; 

* the <code>xforms-refresh</code> event; 

* 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 XForms Processor consisting of a conforming [[#conform-model-processor|XForms Model Processor]] along with the following additional required, recommended and implementation-optional features.

The processor [[#intro-reading|must]] support:
* user interface creation and refresh behaviors described for <code>model</code> processing;
* all [[#elems-form-controls|core controls]], including all of their attributes and child elements;
* all [[#container-controls|container controls]], including all of their attributes and child elements, except that support of the <code>repeat-*</code> attributes is [[#intro-reading|implementation-optional]];
* the actions <code>refresh</code>, <code>setfocus</code>, and <code>message</code>;
* all interaction and notification events targetted at controls and their descendant elements.

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-atomic-value">Atomic value</span>
: A value in the value space of an [[#def-atomic-type|atomic type]].
; <span id="def-atomic-type">Atomic type</span>
: A primitive simple type or a type derived by restriction from another atomic type, as defined in [[#ref-xpath-data-model|XPath Data Model]].
; <span id="def-binding">Binding</span>
: A connection using a [[#def-binding-expression|binding expression]] from a [[#def-control|control]] or a [[#def-model-item-property|model item property]] to an [[#def-item|item]].
; <span id="def-binding-expression">Binding expression</span>
: An expression used in a binding. The language used for the expression is defined by the [[#def-expression-module|expression module]].
; <span id="def-compound-document">Compound Document</span>
: A document that combines multiple document formats either by reference, by inclusion or both, as defined in <nowiki>[</nowiki>[[#ref-cdrf-1.0 |CDRF 1.0]]<nowiki>]</nowiki>.
; <span id="def-computed-expression">Computed expression</span>
: An expression used by model item properties such as <code>relevant</code> and <code>calculate</code> to include dynamic functionality.
; <span id="def-containing-document">Containing document</span>
: A specific document, for example an XHTML document, in which one or more <code>model</code> elements are found.
; <span id="def-form-control">Control</span>
: A point of user interaction (a [[#Core Controls|core control]]) or a container for other controls (a [[#Container Controls|container control]]).
; <span id="def-datatype">Datatype</span>
: From [[#ref-xschema-2 |XML Schema part 2]]: A 3-tuple, consisting of a) a set of distinct values, called its [[#def-value-space|value space]], b) a set of lexical representations, called its [[#def-lexical-space|lexical space]], and c) a set of [[#def-facet|facets]] that characterize properties of the value space, individual values or lexical items.
; <span id="def-non-relevant-form-control">Disabled Control</span>
: A [[#def-control|control]] failing at least one of the [[#form-control-non-relevance-conditions|availability conditions]].
; <span id="def-empty-sequence">Empty sequence</span>
: A [[#def-sequence|sequence]] containing no [[#def-item|items]].
; <span id="def-relevant-form-control">Enabled Control</span>
: A control satisfying all of the [[#form-control-non-relevance-conditions|availability conditions]].
; <span id="def-expression-module">Expression module</span>
: A separate specification defining the expression language used for addressing instance data nodes in binding expressions, to express constraints, and to specify calculations.
; <span id="def-facet">Facet</span>
: From [[#ref-xschema-2 |XML Schema part 2]]: A single defining aspect of a value space. Generally speaking, each facet characterizes a value space along independent axes or dimensions.
; <span id="def-first-node-rule">First-item rule</span>
: When a Single Item Binding selects a sequence of size > 1, the first item in the sequence is used.
; <span id="def-host-language">Host language</span>
: An XML vocabulary, such as XHTML, into which XForms is embedded.
; <span id="def-instance-data">Instance data</span>
: An internal representation of the values and states of data being processed.
; <span id="def-instance-data-node">Instance data node</span>
: A Node from the instance data.
; <span id="def-item">Item</span>
: A node, or an atomic value (such as an integer, date, or string).
; <span id="def-lax-schema-processing">Lax schema processing</span>
: From [[#ref-xschema-1 |XML Schema part 1]]: 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.
; <span id="def-lexical-space">Lexical space</span>
: From [[#ref-xschema-2 |XML Schema part 2]]: 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.
; <span id="def-model-binding-expression">Model Binding expression</span>
: An expression used in the <code>ref</code> attribute of a <code>bind</code> element in a model. Often, a <code>bind</code> also declares [[#def-computed-expression|computed expressions]] for model item properties of the nodes.
; <span>Model item</span>
: An [[#def-instance-data-node|instance data node]] with associated constraints.
; <span id="def-model-item-property">Model item property</span>
: An XForms-specific annotation to an instance data node.
; <span id="def-node">Node</span>
: One of the seven kinds of node defined in the [[#ref-xpath-data-model|XPath Data Model]]: document, element, attribute, text, namespace, processing instruction, and comment.
; <span id="def-observer">Observer</span>
: An element that responds to an event through an event handler attached to it, as defined in [[#ref-xml-events|XML Events]].
; <span id="def-PrefixedName">PrefixedName</span>
: A [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] as defined in [http://www.w3.org/TR/REC-xml-names/#NT-PrefixedName Namespaces in XML].
; <span id="def-schema-constraint">Schema constraint</span>
: A restriction, applied to instance data, based on XML Schema datatypes.
; <span id="def-sequence">Sequence</span>
: A succession of zero or more [[#def-item|items]] as defined in [[#ref-xpath-data-model|XPath Data Model]].
; <span id="def-simpleContent">simpleContent</span>
: Content of a node that has no element children.
; <span id="def-strict-schema-processing">Strict schema processing</span>
: From [[#ref-xschema-1 |XML Schema part 1]]: If the applicable schema does not provide a definition for an element or attribute, then Schema validation marks the item as invalid.
;<span id="def-string-value">String-value</span>
: A property of a Node, the string of characters that go to make up its content, as defined in [[#ref-xpath-data-model|XPath Data Model]].
;<span id="def-typed-value">Typed-value</span>
: A property of a Node, the string-value of the node interpreted according to the type property of the node, as defined in [[#ref-xpath-data-model|XPath Data Model]].
; <span id="def-ui-binding-expression">UI Binding Expression</span>
: An expression used in binding a [[#def-form-control|control]] to the instance.
; <span id="def-valid">Valid node</span>
: An instance data node that is empty and not <code>required</code>, or otherwise whose value satisfies all applicable types and constraint model item properties.
; <span id="def-value-space">Value space</span>
: From [[#ref-xschema-2 |XML Schema part 2]]: 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.
; <span id="def-versionList">versionList</span>
: A list (<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>
: 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): <code>"[1-9]\d*\.\d+"</code>.
; <span id="def-xforms-model">XForms Model</span>
: The individual model items and constraints and other run-time aspects of XForms.
; <span id="def-xforms-processor">Processor</span>
: A software application or program that implements and conforms to the XForms specification.

</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="ref-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
; HTML5
: [http://www.w3.org/TR/html5/forms.html <cite id="ref-html5">HTML5</cite>], 2012. W3C Candidate Recommendation available at: http://www.w3.org/TR/html5/forms.html.
; Language Identification in XML
: Section <cite id="ref-xml-lang>[https://www.w3.org/TR/xml/#sec-lang-tag Language Identification]</cite> in [[#ref-xml-1.0|XML 1.0]].
; 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 2046
: [http://www.ietf.org/rfc/rfc2046.txt <cite id="ref-rfc-2046">RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</cite>], N. Freed, N. Borenstein, 1996. Available at http://www.ietf.org/rfc/rfc2046.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-rfc-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 2818
: [http://www.ietf.org/rfc/rfc2818.txt <cite id="ref-rfc-2818">RFC 2818: HTTP Over TLS</cite>], E. Rescorla, 2000. Available at: http://www.ietf.org/rfc/rfc2818.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.
; RFC 3987
: [http://www.ietf.org/rfc/rfc3987.txt <cite id="ref-rfc-3987">RFC 3987: Internationalized Resource Identifiers (IRIs)</cite>], M. Duerst, M. Suignard, 2005. Available at: http://www.ietf.org/rfc/rfc3987.txt.
; RFC 5321
: [https://tools.ietf.org/html/rfc5321#section-2.3.11 <cite id="ref-rfc-5321">RFC 5321: Simple Mail Transfer Protocol</cite>], J. Klensin, 2008. Available at: http://www.ietf.org/rfc/rfc5321.txt.
; RFC 6531
: [https://tools.ietf.org/html/rfc6531 <cite id="ref-rfc-6531">RFC 6531: SMTP Extension for Internationalized Email</cite>], J. Yao, W. Mao, 2012. Available at: http://www.ietf.org/rfc/rfc6531.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 Character Database
: [http://www.unicode.org/reports/tr44/ <cite id="ref-unicode-character-database">Unicode Standard Annex #44, Unicode Character Database</cite>], Available at: http://www.unicode.org/reports/tr44/.
; Unicode Collation Algorithm
: [http://www.unicode.org/reports/tr10/ <cite id="ref-unicode-collation">Unicode Technical Standard #10, Unicode Collation Algorithm</cite>], Available at: http://www.unicode.org/reports/tr10/.
; XForms 2.0 -- XPath Expressions Module
: [[XPath Expressions Module|XForms 2.0: XPath Expressions Module]], Nick Van den Bleeken (ed.) W3C.
; 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.
; XPath 2.0
: [http://www.w3.org/TR/2010/REC-xpath20-20101214/ <cite id="ref-xpath-2.0">XML Path Language (XPath) 2.0</cite>], Anders Berglund <em>et al.</em>, 2010. W3C Recommendation available at: http://www.w3.org/TR/2010/REC-xpath20-20101214/.
; XPath Data Model
: [http://www.w3.org/TR/2010/REC-xpath-datamodel-20101214/ <cite id="ref-xpath-data-model">XQuery 1.0 and XPath 2.0 Data Model</cite>], Anders Berglund <em>et al.</em>, 2010. W3C Recommendation available at: http://www.w3.org/TR/2010/REC-xpath-datamodel-20101214/ .
; 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.
; XPath and XQuery Functions and Operators 3.0
: [http://www.w3.org/TR/xpath-functions-30/ <cite id="ref-xpath-xquery-functions-operators-30"> XPath and XQuery Functions and Operators 3.0 </cite>], Michael Kay, 2013. W3C Candidate Recommendation available at: http://www.w3.org/TR/xpath-functions-30/.
; XSLT and XQuery Serialization 3.0
: [http://www.w3.org/TR/xslt-xquery-serialization-30/ <cite id="ref-xslt-xquery-serialization-30">XSLT and XQuery Serialization 3.0</cite>], Henry Zongaro, 2013. W3C Candidate Recommendation available at: http://www.w3.org/TR/xslt-xquery-serialization-30/.

</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/.
; CSV
: [https://tools.ietf.org/html/rfc4180 <cite id="ref-csv">Common Format and MIME Type for Comma-Separated Values (CSV) Files</cite>], Y. Shafranovich, 2005, available at https://tools.ietf.org/html/rfc4180.
; 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://exslt.org <cite id="ref-exslt">EXSLT Web site</cite>]. Available at http://exslt.org.
; ICANN
: [https://www.icann.org/news/announcement-2013-08-30-en <cite id="ref-icann">New gTLD Dotless Domain Names Prohibited</cite>], ICANN, 2013. Available at https://www.icann.org/news/announcement-2013-08-30-en.
; ITU E.123
: [http://www.itu.int/rec/T-REC-E.123-200102-I/en <cite id="ref-ITU">Notation for national and international telephone numbers, e-mail addresses and web addresses</cite>], International Telecommunication Union, 2001, available at http://www.itu.int/rec/T-REC-E.123-200102-I/en.
; JSON
: [http://www.ietf.org/rfc/rfc4627.txt <cite id="ref-json">The application/json Media Type for JavaScript Object Notation (JSON)</cite>], D. Crockford, 2006, available at http://www.ietf.org/rfc/rfc4627.txt.
; Media Types
: [http://www.iana.org/assignments/media-types/media-types.xhtml <cite id="mediatypes">Media Types</cite>], IANA, 2017, available at http://www.iana.org/assignments/media-types/media-types.xhtml.
; 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.
; 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/reports/tr24/ <cite id="ref-unicode-scripts"> Script Names</cite>], Mark Davis, 2001. Unicode Technical Report #24 available at http://www.unicode.org/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/.
; 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/.
; 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">

==<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 Item 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 2.0 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 2.0 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">
 <model<nowiki>
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tns="http://www.webservice.net">
   <instance id="data">
     &lt;data xmlns="">
       <city>Victoria</city>
       <country>Canada</country>
       <weather>Mostly sunny and cool. High 12°C. Low 3°C.</weather>
     &lt;/data>
   </instance>

   <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>
   </instance>
   <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 12°C. Low 3°C.</GetWeatherResult>
         </GetWeatherResponse>
       </soap:Body>
     </soap:Envelope>
   </instance>

   <submission
     id="GetWeather" resource="http://www.webservice.net/getweather.asmx"
     method="post"
     ref="instance('GetWeatherSoapIn')"
     mediatype="application/soap+xml;
     resource=http://www.webservice.net/GetWeather"
     replace="instance"
     instance="GetWeatherSoapOut">
       <action ev:event="xforms-submit">
         <setvalue
           ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CityName"
           value="instance('data')/city"/>
         <setvalue
          ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CountryName"
          value="instance('data')/country"/>
       </action>
       <action ev:event="xforms-submit-done">
         <setvalue
           ref="instance('data')/weather"
           value="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeatherResponse/tns:GetWeatherResult"/>
       </action>
   </submission>
 </model>

 <input ref="city" label="City">
    <send ev:event="xforms-value-changed" submission="GetWeather"/>
 </input>
 <input ref="country" label="Country">
    <send ev:event="xforms-value-changed" submission="GetWeather"/>
 </input>
 <output ref="weather" label="The weather forecast is"/></nowiki>
</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<nowiki>
   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></nowiki>

</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="data-mutations">Patterns for Data Mutations (Non-Normative)</span>==

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.

=== Prepend Element Copy ===
Operation<nowiki>: Prepend a new, empty </nowiki><code>person</code> element into a list of <code>people</code>

Pattern: '''<insert context="'''''parent of new element'''''" origin="'''''element to copy'''''"/>'''

The <code>context</code> attribute is used so that it works whether or not the parent element is empty.

 <insert context="people" origin="instance('prototypes')/person"/>

'''Data Before Operation'''

 <instance>
   &lt;data xmlns="">
     <people>
       <person>
         <name>Jane Doe</name>
       </person>
     </people>
   &lt;/data>
  </instance>

  <instance id="prototypes">
    <prototypes xmlns="">
      <person>
        <name/>
      </person>
    </prototypes>
 </instance>

'''Data After Operation'''

 <instance>
   &lt;data xmlns="">
     <people>
       '''<person>'''
         '''<name/'''
       '''</person>'''
       <person>
         <name>Jane Doe</name>
       </person>
     </people>
  &lt;/data>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name/>
     </person>
   </prototypes>
 </instance>

=== Append Element Copy ===

Operation<nowiki>: Append a new, empty </nowiki><code>person</code> element into a list of <code>people</code>

Pattern: '''<insert context="'''''parent of new element'''''" ref="*" origin="'''''element to copy'''''"/>'''

The <code>context</code> attribute is used so that this pattern will work whether or not the parent element is empty.

 <insert context="people" ref="person" origin="instance('prototypes')/person"/>

'''Data Before Operation'''

 <instance>
   &lt;data xmlns="">
     <people>
       <person>
         <name>Jane Doe</name>
       </person>
     </people>
   &lt;/data>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name/>
     </person>
   </prototypes>
 </instance>

'''Data After Operation'''

 <instance>
   &lt;data xmlns="">
     <people>
       <person>
         <name>Jane Doe</name>
       </person>
       '''<person>'''
         '''<name/>'''
       '''</person>'''
     </people>
   &lt;/data>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name/>
     </person>
   </prototypes>
 </instance>

=== Duplicate Element ===
Operation<nowiki>: Duplicate the selected element and place it as a following sibling</nowiki>

Pattern: '''<insert ref="'''''exact element to duplicate'''''"/>'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact element to duplicate, so <code>ref</code> is used. If the element does not exist, the operation will have no effect.

 <insert ref="paragraph[2]"/>

'''Data Before Operation'''

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

'''Data After Operation'''

 <instance>
   <document xmlns="">
     <header>Lorem ipsum</header>
     <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
     <paragraph>Primis abhorreant delicatissimi ...</paragraph>
     '''<paragraph>Primis abhorreant delicatissimi ...</paragraph>'''
     <header>Lorem ipsum</header>
     <header>Lorem ipsum</header>
   </document>
 </instance>

===Set Attribute===

Operation<nowiki>: Create or replace an attribute with a copy of a given attribute</nowiki>

Pattern: '''<insert context="'''''container element receiving attribute'''''" origin="'''''attribute to copy'''''"/>'''

The <code>ref</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.

 <insert context="item[2]" origin="../item[1]/@rating"/>
 <insert context="item[3]" origin="../item[1]/@rating"/>

'''Data Before Operation'''

 <instance>
   <items xmlns="">
     <item key="23" rating="classified"/>
     <item key="42"/>
     <item key="68" rating="unknown"/>
   </items>
 </instance>

'''Data After Operation'''

 <instance>
   <items xmlns="">
     <item key="23" rating="classified"/>
     <item key="42" '''rating="classified"'''/>
     <item key="68" rating="'''classified'''"/>
   </items>
 </instance>

===Remove Element===

Operation<nowiki>: Remove </nowiki><code>item</code> element in case it exists

Pattern: '''<delete ref="'''''exact element to remove'''''"/>'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact element to remove, so <code>ref</code> is used. If the element does not exist, the operation will have no effect.

 <delete ref="item[2]"/>

'''Data Before Operation'''

 <instance>
   <shoppingcart xmlns="">
     <item>
       <product>SKU-0815</product>
       <quantity>1</quantity>
       <unitcost>29.99</unitcost>
       <price>29.99</price>
     </item>
     '''<item>'''
       '''<product>SKU-4711</product>'''
       '''<quantity>3</quantity>'''
       '''<unitcost>7.49</unitcost>'''
       '''<price>22.47</price>'''
     '''</item>'''
   </shoppingcart>
 </instance>

'''Data After Operation'''

 <instance>
   <shoppingcart xmlns="">
     <item>
       <product>SKU-0815</product>
       <quantity>1</quantity>
       <unitcost>29.99</unitcost>
       <price>29.99</price>
     </item>
   </shoppingcart>
 </instance>

===Remove Attribute===

Operation<nowiki>: Remove </nowiki><code>rating</code> attribute in case it exists.

Pattern: '''<delete ref="'''''exact attribute to remove'''''"/>'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact attribute to remove, so <code>ref</code> is used. If the attribute does not exist, the operation will have no effect.

 <delete ref="item/@rating"/>

'''Data Before Operation'''

 <instance>
   <items xmlns="">
    <item key="23" '''rating="classified"'''/>
   </items>
 </instance>

'''Data After Operation'''

 <instance>
   <items xmlns="">
     <item key="23"/>
   </items>
 </instance>

===Remove Sequence===

Operation<nowiki>: Remove </nowiki><code>track</code> sequence in case it exists

Pattern: '''<delete ref="'''''sequence to remove'''''"/>'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate a sequence to remove, so <code>ref</code> is used. If the sequence does not exist, the operation will have no effect.

 <delete ref="track"/>

'''Data Before Operation'''

 <instance>
   <playlist xmlns="">
     <name>Music for Airports</name>
     '''<track id="382"/>'''
     '''<track id="461"/>'''
     '''<track id="629"/>'''
   </playlist>
 </instance>

'''Data After Operation'''

 <instance>
   <playlist xmlns="">
     <name>Music for Airports</name>
   </playlist>
 </instance>

===Copy Sequence===

Operation<nowiki>: Append a </nowiki><code>person</code> sequence into a list of <code>people</code>

Pattern: '''<insert context="'''''parent of new sequence'''''" ref="*" origin="'''''sequence to copy'''''"/>'''

The <code>context</code> attribute is used so that this pattern will work whether or not the parent element is empty.

 <insert context="people" ref="person" origin="instance('prototypes')/person"/>

'''Data Before Operation'''

 <instance>
   &lt;data xmlns="">
     <people/>
   &lt;/data>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name>Jane Doe</name>
     </person>
     <person>
       <name>John Doe</name>
     </person>
     <person>
       <name>Joe Sixpack</name>
     </person>
   </prototypes>
 </instance>

'''Data After Operation'''

 <instance>
   &lt;data xmlns="">
     <people>
       '''<person>'''
         '''<name>Jane Doe</name>'''
       '''</person>'''
       '''<person>'''
         '''<name>John Doe</name>'''
       '''</person>'''
       '''<person>'''
         '''<name>Joe Sixpack</name>'''
       '''</person>'''
     </people>
   &lt;/data>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name>Jane Doe</name>
     </person>
     <person>
       <name>John Doe</name>
     </person>
     <person>
       <name>Joe Sixpack</name>
     </person>
   </prototypes>
 </instance>

===Copy Attribute List===

Operation<nowiki>: Copy attribute list from one </nowiki><code>item</code> to another

Pattern: '''<insert context="'''''exact element receiving attribute list'''''" origin="'''''attribute list to copy'''''"/>'''

 <insert context="item[2]" origin="../item[1]/@*"/>

'''Data Before Operation'''

 <instance>
   <items xmlns="">
     <item key="0" rating="classified"/>
     <item/>
   </items>
 </instance>

'''Data After Operation'''

 <instance>
   <items xmlns="">
     <item key="0" rating="classified"/>
     <item '''key="0" rating="classified"'''/>
   </prototypes>
 </instance>

===Replace Element===

Operation<nowiki>: Replace a </nowiki><code>person</code> element with a new one.

Pattern: '''<replace ref="'''''exact element to replace'''''" with="'''''element to copy'''''"/>'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an exact element to replace, so <code>ref</code> is used. If the element does not exist, the operation will have no effect.

 <replace ref="person[1]" with="instance('prototypes')/person"/>

'''Data Before Operation'''

 <instance>
   <people xmlns="">
     <person>
       <name>John Doe</name>
     </person>
   </people>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name/>
     </person>
   </prototypes>
 </instance>

'''Data After Operation'''

 <instance>
   <people xmlns="">
     <person>
       '''<name/>'''
     </person>
   </people>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <person>
       <name/>
     </person>
   </prototypes>
 </instance>

===Replace Attribute===

Operation<nowiki>: Replace an attribute with the copy of a given attribute</nowiki>

Pattern: '''<setvalue ref="'''''exact attribute to replace'''''" value="'''''attribute to copy'''''"/>'''

If the attribute does not exist, the operation will have no effect.

 <setvalue ref="item[2]/@key" value="../../item[1]/@key"/>

'''Data Before Operation'''

 <instance >
   <items xmlns="">
     <item key="0"/>
     <item key="4711"/>
   </items>
 </instance>

'''Data After Operation'''

 <instance >
   <items xmlns="">
     <item key="0"/>
     <item '''key="0"'''/>
   </items>
 </instance>

===Replace Instance with Insert===

Operation<nowiki>: Replace instance root node with an empty </nowiki><code>shoppingcart</code> element

Pattern: '''<insert ref="'''''root node of instance to replace'''''" origin="'''''element to copy'''''"/>'''

The <code>context</code> attribute is not used because this pattern assumes the ability to indicate an instance root node to replace, so <code>ref</code> is used. Since an instance cannot be empty, <code>ref</code> will always be non-empty. Insert implements special handling for instance root nodes, thus a delete operation is not necessary.

 <insert ref="." origin="instance('prototypes')/shoppingcart"/>

'''Data Before Operation'''

 <instance>
   <shoppingcart xmlns="">
     '''<item>'''
       '''<product>SKU-0815</product>'''
       '''<quantity>1</quantity>'''
       '''<unitcost>29.99</unitcost>'''
       '''<price>29.99</price>'''
     '''</item>'''
     '''<item>'''
       '''<product>SKU-4711</product>'''
       '''<quantity>3</quantity>'''
       '''<unitcost>7.49</unitcost>'''
       '''<price>22.47</price>'''
     '''</item>'''
   </shoppingcart>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <shoppingcart/>
   </prototypes>
 </instance>

'''Data After Operation'''

 <instance>
   <shoppingcart xmlns=""/>
 </instance>

 <instance>
   <prototypes xmlns="">
     <shoppingcart/>
   </prototypes>
 </instance>

===Move Element===

Operation<nowiki>: Copy an existing element to a new parent and remove the original</nowiki>

Pattern: '''<insert context="'''''new parent of element'''''" ref="*" origin="'''''exact element to move'''''"/>''' '''<delete ref="'''''exact element to move'''''"/>'''

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

 <insert context="playlist[2]" ref="track" origin="../playlist[1]/track[2]"/>
 <delete ref="playlist[1]/track[2]"/>

'''Data Before Operation'''

 <instance>
   <library xmlns="">
     <playlist>
       <name>Music for Airports</name>
       <track id="382"/>
       '''<track id="461"/>'''
       <track id="629"/>
     </playlist>
     <playlist>
       <name>Lullabies</name>
       <track id="251"/>
       <track id="331"/>
     </playlist>
   </library>
 </instance>

'''Data After Operation'''

 <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"/>
       '''<track id="461"/>'''
     </playlist>
   </library>
 </instance>

===Move Attribute===

Operation<nowiki>: Copy an existing attribute to a new element and remove the original</nowiki>

Pattern: '''<insert context="'''''exact element receiving attribute'''''" origin="'''''exact attribute to move'''''"/>''' '''<delete ref="'''''exact attribute to move'''''"/>'''

If the attribute to be moved does not exist, both insert and delete operation will have no effect.

 <insert context="item[2]" origin="../item[1]/@rating"/>
 <delete ref="item[1]/@rating"/>

'''Data Before Operation'''

 <instance>
   <items xmlns="">
     <item key="23" '''rating="classified"'''/>
     <item key="42"/>
   </items>
 </instance>

'''Data After Operation'''

 <instance>
   <items xmlns="">
     <item key="23"/>
     <item key="42" '''rating="classified"'''/>
   </items>
 </instance>

===Insert Element into Non-Contiguous, Heterogeneous Sequence===

Operation<nowiki>: Copy an existing element into a non-contiguous, heterogeneous sequence at a specified position</nowiki>

Pattern: '''<insert ref="'''''non-contiguous, heterogeneous sequence'''''" origin="'''''element to copy'''''" at="'''''insert location'''''"/>'''

The <code>context</code> attribute is not used because it adheres to the [[#def-first-node-rule|first-item rule]] and therefore would not allow to select a non-contiguous sequence. The <code>ref</code> attribute is used instead to select a sequence 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>ref</code> and <code>at</code>.

 <insert ref="chapter/*" origin="instance('prototypes')/paragraph" at="7" position="before"/>

'''Data Before Operation'''

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

 <instance id="prototypes">
   <prototypes xmlns="">
     <chapter/>
     <header/>
     <paragraph/>
     <diagram/>
   </prototypes>
 </instance>

'''Data After Operation'''

 <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>
       '''<paragraph/>'''
       <diagram>Exemplum 3</diagram>
     </chapter>
   </document>
 </instance>

 <instance id="prototypes">
   <prototypes xmlns="">
     <chapter/>
     <paragraph/>
     <diagram/>
   </prototypes>
 </instance>

===Move Elements Up and Down in a List===

Operation: Reorder elements in a list by moving them up and down, for instance to sort a list into order of preference.

Pattern: <insert origin="context()" ref="preceding/following-sibling::*[1]" position="before/after"/> <delete ref="."/>

Example data:

 <instance>
    <films xmlns="">
       <film>The Sound of Music</film>
       <film>The Big Lebowski</film>
       <film>Gone with the Wind</film>
       <film>Inception</film>
    </films>
 </instance>

Example controls to effect the movement:

 <repeat ref="film">
    <input ref="." label="Film:"/>
    <trigger ref=".[preceding-sibling::*]" label="↑">
       <action ev:event="DOMActivate">
          <insert origin="context()" ref="preceding-sibling::*[1]" position="before"/>
          <delete ref="."/>
       </action>
    </trigger>
    <trigger ref=".[following-sibling::*]" label="↓">
       <action ev:event="DOMActivate">
          <insert origin="context()" ref="following-sibling::*[1]"/>
          <delete ref="."/>
       </action>
    </trigger>
 </repeat>

What it might look like:

[[Image:Updown.png|A repeat with controls for reordering the list items]]

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

==<span id="Recalculation_Sequence_Algorithm">Recalculation Sequence Algorithm</span> (Non-Normative)==

This appendix gives an example of how a [[#model-recalculate|recalculate]] might be done. The algorithm considers model items and model item properties to be vertices in a directed graph. Edges between the vertices represent computational dependencies.

# A [[#Creating the Master Dependency Directed Graph|master dependency directed graph is created]].
# A [[#Creating the Pertinent Dependency Subgraph|pertinent dependency subgraph is computed]] consisting only of vertices and edges that are reachable from nodes that require recomputation. (Note that on a first recomputation, such as on initialization, 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. An example of a topological sort algorithm can be found in <nowiki>[</nowiki>[[#ref-art |Algorithms]]<nowiki>]</nowiki>.

<div class="div2">

===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''': a reference to the associated instance data node<br />'''type''': indicates the aspect of the instance node represented by the vertex (the text content or a model item property such as <code>readOnly</code> or <code>required</code>)<br />'''depList''': a list of vertices that refer to this vertex<br />'''in-degree''': the number of vertices on which this vertex depends<br />'''visited''': a flag used to ensure vertices are not added to a subgraph multiple times<br />'''index''': an association between vertices in the master dependency directed graph and a subgraph.

</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 <code>calculate</code>, <code>relevant</code>, <code>readonly</code>, or <code>required</code>).

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

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.

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.

Any expression violating any Binding Expression Constraint causes the <code>recalculate</code> flag to be cleared and an [[#evt-computeError|xforms-compute-error]] event to be dispatched. If the event is not canceled, processing halts (this is the default action of the [[#evt-computeError|xforms-compute-error]] event). If the event is canceled, the <code>recalculate</code> process is terminated after the <code>recalculate</code> flag is cleared, but XForms processing otherwise continues.

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

===Creating the Pertinent Dependency Subgraph===

If all calculations must be performed, which is the case initially, 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.

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

It uses depth-first search to explore the master digraph subtrees rooted at each changed vertex. A ''visited'' flag is used to stop exploration at the boundaries of previously explored subtrees (since subtrees can overlap in directed graphs).

<div class="example" title="Sample Algorithm to Create the Pertinent Dependency Subgraph">
 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''
 }
</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">

===Computing Individual Vertices===

The following steps process vertices:

# 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 has a loop. In this case, the <code>recalculate</code> flag is cleared and an [[#evt-computeError|xforms-compute-error]] event is dispatched. If the event is not canceled, processing halts (this is the default action of the [[#evt-computeError|xforms-compute-error]] event). If the event is canceled, the <code>recalculate</code> process is terminated after the <code>recalculate</code> flag is cleared, but processing otherwise continues.

# 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 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>ref</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>

==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 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 latter 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 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 control with text already present. To set the appropriate input mode when entering a 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.

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

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

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 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 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="example" title="user input in Japanese">
 <input ref="name" inputmode="kanji" label="Family name:"/>
 <input ref="nameKana" inputmode="katakana" label="Family name in kana:"/>
 <input ref="given" inputmode="kanji" label="Given name:"/>
 <input ref="givenKana" inputmode="katakana" label="Given name in kana:"/>
 <input ref="email" inputmode="latin lowerCase" label="Email:"/>
 <input ref="phone" inputmode="latin digits" label="Telephone:"/>
 <textarea ref="comments" inputmode="user predictOn" label="Comments:"/>
 <submit submission="sendit" label="Send It"/>
</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" | Relationship to XForms
|-
| rowspan="1" colspan="1" | <code><nowiki>:enabled</nowiki></code> & <code><nowiki>:disabled</nowiki></code>
| rowspan="1" colspan="1" |
Selects any control that is [[#def-relevant-form-control|enabled]] or [[#def-non-relevant-form-control|disabled]] (respectively). Defined in [CSS3].
|-
| rowspan="1" colspan="1" | <code><nowiki>:required</nowiki></code> & <code><nowiki>:optional</nowiki></code>
| rowspan="1" colspan="1" | Selects any core 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" | Selects any core 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" | Selects any core 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" | Selects any core control bound to a node that contains a value the 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" | Selects any core 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" | Relationship to XForms
|-
| rowspan="1" colspan="1" | <code><nowiki>::value</nowiki></code>
| rowspan="1" colspan="1" | Represents the "active" area of a control excluding the label; this corresponds in HTML to <code>input</code> and other control elements. This pseudo-element is a child of the control element, and appears immediately after the required <code>label</code> element.
|-
| rowspan="1" colspan="1" | <code><nowiki>::switch-case</nowiki></code>
| rowspan="1" colspan="1" | Represents the identity of the selected case of a <code>switch</code>.
|-
| rowspan="1" colspan="1" | <code><nowiki>::repeat-item</nowiki></code>
| 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 item, 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" | 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">

===Styling Examples===

The following examples collect together styling recommendations from this document, expressed in CSS. The following namespace declaration is assumed:

 <nowiki>@namespace xf url('http://www.w3.org/2002/xforms');</nowiki>

Most controls have an inline layout by default. 
 <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|switch:enabled { display: inline; }
 xf|repeat:enabled { display: inline; }
 ::repeat-item:enabled, xf|group:enabled { display:block; }</nowiki>

Disabled content is not presented, or it may be styled as disabled.
 <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>

The default display:none styling of :disabled can be overidden. Note that the implementation must also implement the behavior of not accepting user input in the disabled control.

 xf|input.authorization:disabled {
    display: inline; background-color: #bbbbbb
 }

A read-only control should render in a way which indicates that entering or changing the value is not allowed. For example:

 xf|input:enabled:read-only::value
 {
   display: inline; background-color: #888888
 }

Except as noted, enabled controls must distinguish rendering between being bound to a required node versus a non-required node. Exceptions are controls that do not directly render the string value of the bound node (including trigger and the container controls). Below is an example styling 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.

 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
 }

Enabled controls must distinguish rendering between valid and invalid states. Below is an example styling input controls bound to non-empty but invalid nodes with a reddish background.

 xf|input:enabled:invalid:value-non-empty {
    background-color: #ff8080;
 }

Enabled controls must indicate when the bound instance data contains a value or content that the control is not capable of rendering. In this example, select, select1, and range controls bound nodes whose values are not presentable by the controls are styled with in red. 

 xf|select1:enabled:out-of-range, xf|select1:enabled:out-of-range,
 xf|range:enabled:out-of-range {
   color: red;
 }

</div></div>

<div class="div1">

==Complete XForms Examples (Non-Normative)==

This section presents complete XForms examples.

<div class="example" title="XForms in XHTML">
 <html<nowiki> xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ev="http://www.w3.org/2001/xml-events" 
      xml:lang="en">
  <head>
    <title>XForms in XHTML</title>
    <model xmlns="http://www.w3.org/2002/xforms">
       <instance>
          <payment as="credit" xmlns="">
             <cc/>
             <expiry/>
          </payment>
       </instance>
       <submission resource="http://www.example.com/buy.rb" method="post"/>
       <bind ref="cc" type="card-number" constraint="is-card-number(.)"
             relevant="../@as='credit'" required="true()" whitespace="remove"/>
       <bind ref="expiry" constraint="matches(., '^[0-9][0-9]/(0[1-9]|1[012])$')
             relevant="../@as='credit'" required="true()"/>
    </model>
  </head>
  <body>
    ...
    <group xmlns="http://www.w3.org/2002/xforms">
       <select1 ref="@as" label="Select Payment Method">
          <item label="Cash" value="'cash'">
             <message level="modeless" ev:event="xforms-select">
                      Please do not mail cash.</message>
          </item>
          <item label="Credit">credit</item>
       </select1>

       <input ref="cc" label="Credit Card Number"
              alert="Please specify a valid credit card number (spaces permitted)"/>

       <input ref="expiry" label="Expiry Date" hint="YY/MM" alert="Format: YY/MM"/>

       <submit label="Buy"/>
    </group>
    ...
 </body>
 </html></nowiki>
</div>

<div class="example" title="Editing Hierarchical Bookmarks Using XForms">
 <html<nowiki> xml:lang="en"
      xmlns="http://www.w3.org/1999/xhtml"
      xmlns:xforms="http://www.w3.org/2002/xforms"
      xmlns:ev="http://www.w3.org/2001/xml-events">
  <head>
     <title>Editing Hierarchical Bookmarks</title>
     <model version="2.0" xmlns="http://www.w3.org/2002/xforms">
        <instance resource="bookmarks.xml"/>
        <bind ref="section/bookmark/@href" type="anyURI"/>
        <instance id='template'>
            <section name="" xmlns="">
                <bookmark href="" name=""/>
            </section>
        </instance>
        <submission method="post" resource="http://examples.com/"/>
     </model>
  </head>
  <body>
     <group xmlns="http://www.w3.org/2002/xforms">
        <!-- Display bookmarks -->
        <repeat ref="section" id="Sections">
           <input ref="@name" class="editField">
              <label class="sectionLabel">Section</label>
           </input>
           <repeat ref="bookmark" id="Bookmarks">
              <input ref="@name" label="Bookmark name"/>
              <input ref="@href" label="URL"/>
           </repeat>
        </repeat>

        <!-- Insert Bookmark -->
        <trigger label="Insert bookmark">
           <insert ref="section[index('Sections')]/bookmark" origin="instance('template')/bookmark"
                   at="index('Bookmarks')" ev:event="DOMActivate"/>
        </trigger>

        <!-- Delete Bookmark -->
        <trigger label="Delete bookmark">
           <delete ref="section[index('Sections')]/bookmark" 
                   at="index('Bookmarks')" ev:event="DOMActivate"/>
        </trigger>

        <!-- Insert Section -->
        <trigger label="Insert section">
           <insert ref="section" at="index('Sections')" origin="instance('template')"
                   ev:event="DOMActivate"/>
        </trigger>

        <!-- Delete Section -->
        <trigger label="Delete section">
           <delete ref="section" at="index('Sections')" 
                   ev:event="DOMActivate"/>
        </trigger>

        <submit label="Save" hint="Click to submit"/>
    </group>
  </body>
 </html></nowiki>

Initial instance file <code>bookmarks.xml</code><nowiki>:</nowiki>

 <!--This is the bookmarks.xml file -->
 <bookmarks><nowiki>
    <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:/source/xmlevents.xml" name="XML events"/>
       <bookmark href="file:/source/model3.xml" name="model3"/>
       <bookmark href="file:/source/repeat.fo" name="repeat"/>
    </section>
 </bookmarks></nowiki>
</div>

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

<div class="example" title="Histogram Using XForms and SVG">
 <html<nowiki> xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:xf="http://www.w3.org/2002/xforms">
 <head>
    <title>Barchart</title>
    <style type="text/css">
        .xforms-repeat-item {display: inline}
        .histogram  { border: thin black solid; text-anchor:middle; }
        .box    { fill: blue; stroke: black; stroke-width:1; }
        .title  { fill: gray;  }
    </style>
    <model xmlns="http://www.w3.org/2002/xforms">
        <instance id="data" resource="years.xml"/>
        <bind id="histdata" ref="instance('data')/y"/>
 
        <instance id="chart">
            <barchart xmlns="">
                <title>Values</title>
                <n/><miny/><maxy/><depth/><height/><range/><vscale/><hscale/>
            </barchart>
        </instance>
        <bind ref="n"      calculate="count(bind('histdata'))"/>
        <bind ref="maxy"   calculate="max(bind('histdata'))"/>
        <bind ref="miny"   calculate="min(bind('histdata'))"/>
 
        <bind ref="height" calculate="if(../maxy &gt; 0, ../maxy, 0)"/>
        <bind ref="depth"  calculate="if(../miny &amp;lt; 0, 0 - ../miny, 0)"/>
        <bind ref="range"  calculate="../height + ../depth"/>
        <bind ref="vscale" calculate="100 div ../range" type="double"/>
        <bind ref="hscale" calculate="100 div ../n"     type="double"/>
    </model>
 </head>
 <body>
    <svg xmlns="http://www.w3.org/2000/svg" version="1.0" viewBox="0 0 200 200" height="400" width="400" class="histogram">
        <g transform="translate(50,150)">
            <xf:repeat bind="histdata">
                <rect x="{(position() - 1) * instance('chart')/hscale}" 
                      y="{(0 - (choose(. &lt; 0, 0, .) + instance('chart')/depth)) * instance('chart')/vscale}"
                      height="{choose(. &lt; 0, 0 - ., .) * instance('chart')/vscale}" 
                      width="{instance('chart')/hscale}" class="box"/>
            </xf:repeat>
            <text x="50" y="20" class="title"><xf:output ref="title"/></text>
        </g>
    </svg>
 </body>
 </html></nowiki>
</div>

This example might produce a histogram like the following:


[[Image:hist.png|A histogram for a number of values.]]

<div class="div1>

==<span id="version-diffs">Differences between XForms 2.0 and XForms 1.1 (Non-Normative)</span>==
* Expressions
** Uses higher versions of XPath, instead of XPath 1; allows amongst other things atomic values and typed values
** Attribute Value Templates (AVTs) allow calculated values to be used in attributes, enabling the deprecation of many child elements
** Custom functions and variables have been added
** New functions: valid() relevant() readonly() required() case() serialize() seconds-from-epoch() bind() element() attribute() parse() eval() eval-in-context() location-uri() location-param() uri-scheme() uri-scheme-specific-part()  uri-authority() uri-user-info() uri-host() uri-port() uri-path() uri-query() uri-fragment() uri-param-names() uri-param-values() 
* Data
** External instance fallback: if @src on <instance/> fails, the instance is initialised with the inline content.
** Instances are no longer automatically created from the user interface. 
** Multiple MIPs of the same property allowed on one node.
** New whitespace MIP defines how space is treated in values
** json, csv and other external instance data formats are supported
** slight change in how nested binds select items.
* Types
** The definition of validity has been slightly changed to allow empty non-required values to be considered valid. Consequently, the XForms datatypes no longer all include empty as a possible value.
** better email type
** new types:
*** two IRI types
*** iemail type
*** telephone number type
*** HTMLFragment type
* Controls
** The @nodeset attribute is deprecated in favour of @ref everywhere
** The @dir attribute is allowed everywhere for specifying text direction
** Most model-item properties such as @relevant may now appear on controls.
** a new dialog element
** a new <control/> element for embedding an XForm in an XForm, plus actions <return/>, and <renew/>
** repeat has an @indexref attribute
** <repeat appearance='minimal' .../> <group appearance='minimal' ...>
** switch has a @caseref attribute
** an item of a select1 can be deselected
** label, hint, help, alert
*** attributes have been added as alternatives to the child elements
*** properties have been added to the bind element
*** label elements/attributes are consequently now optional on controls
*** Unification of how output, label, help, hint, and alert work.
*** No linking on <help/>
*** @appearance on <alert> (erratum)
* Actions
** @iterate has been added to actions
** <update/>
** <cancel/> action added
** <insert/> no longer makes values of type ID unique
** <insert/> and <delete/> indexes must be in range.
** All actions that have an IDREF attribute now dispatch an xforms-action-error if that attribute does not identify a (suitable) element.
** ability to call script (such as JavaScript) from actions, including passing parameters
** <reset instance="id"/> and <retain/>
** <return/>, and <renew/> to go with <control/> element.
** Small change in the order of evaluation of <load/> attributes 
* Events
** add properties to dispatched events
** xforms-action-warning event added
** xforms-submit-ready event added
** xforms-refresh-done event added
** xforms-rebuild, xforms-recalculate, xforms-revalidate, xforms-refresh, and xforms-reset events deprecated in favour of the respective actions
** xforms-submit-serialize deprecated
** event handlers are no longer disabled when their associated controls are disabled.
** events now conditionally cancellable with <cancel/> action
* Submission
** @response-mediatype overrides incoming mediatype
** get is default submission method
** @nonrelevant replaces @relevant, with new options
** @value available for providing data to be submitted
* Other
** &lt;form&gt; element as root element if one is needed
** p3ptype has been removed
</div>

<div class="div1">

{{:Acknowledgements20}}

{{:ProductionNotes}}

</div></div>
</div>
</div>