XForms 2.0

5.2.7 xforms:card-number

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

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

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

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

6.1.1 The type Property

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

Computed Expression: No.

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

Default Value: xsd:string.

Inheritance Rules: does not inherit.

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

<model xmlns:my="http://example.org">

   <xs:schema targetNamespace="http://example.org" xmlns:my="http://example.org">
      <xs:simpleType name="Currency">
	<xs:restriction base="xsd:string">
           <xs:enumeration value="USD"/>
           <xs:enumeration value="EUR"/>
	</xs:restriction>
      </xs:simpleType>

      <xs:complexType name="Price">
         <xs:simpleContent>
            <xs:extension base="xsd:double">
               <xs:attribute name="currency" type="my:Currency" use="optional" default="USD"/>
            </xs:extension>
         </xs:simpleContent>
      </xs:complexType>
   </xs:schema>

   <instance>
      <data xmlns="http://example.org">
         <aString>Hello, world!</aString>
         <simpleType>
            <price>100.00</price>
            <price>abc</price>
            <price currency="EUR">100.00</price>
            <price currency="EUR">abc</price>
         </simpleType>
         <complexType>
            <price>100.00</price>
            <price>abc</price>
            <price currency="abc">100.00</price>
            <price currency="EUR">abc</price>
         </complexType>
      </data>
   </instance>

   <bind ref="my:aString" type="xsd:string"/>
   <bind ref="my:simpleType/my:price" type="xsd:double"/>
   <bind ref="my:complexType/my:price" type="my:Price"/>
   <bind ref="my:complexType/my:price[3]/@currency" type="my:Currency"/>
   <bind ref="/my:data" type="xsd:string"/>

</model>

6.1.2 The readonly Property

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

Computed Expression: Yes.

Legal Values: Any expression that is convertible to a boolean as described in the expression module.

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

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

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

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

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

The following example illustrates the ability to override the default readonly setting on calculated nodes.

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

6.1.3 The required Property

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

Computed Expression: Yes.

Legal Values: Any expression that is convertible to a boolean as described in the expression module.

Default Value: false().

Inheritance Rules: does not inherit.

A form may require certain values, and this requirement may be dynamic. When evaluating to true, this model item property indicates that a non-empty instance data node is required before a submission of instance data can occur. Non-empty is defined as: The value of the bound instance data node must be convertible to string using the string conversion function as described in the expression module with a length greater than zero.

Except as noted below, the required model item property does not provide a hint to the XForms user interface regarding visibility, focus, or navigation order. XForms authors are strongly encouraged to make sure that form controls that accept required data are visible. An XForms Processor must provide an indication that a form control is required, and may provide immediate feedback, including limiting navigation. This model item property does not prevent form controls and XForms actions from setting empty strings into data nodes.

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

6.1.4 The relevant Property

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

Computed Expression: Yes.

Legal Values: Any expression that is convertible to a boolean as described in the expression module.

Default Value: true().

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

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

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

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

6.1.5 The calculate Property

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

Computed Expression: Yes.

Legal Values: Any expression.

Default Value: none.

Inheritance Rules: does not inherit.

An XForms Model may include model items whose string values are computed from other values. For example, the sum over line items for quantity times unit price, or the amount of tax to be paid on an order. The formula for such a computed value can be expressed with a calculate property, whose expression is evaluated, converted to a string with the string conversion function as described in the expression module, and stored as the value content of the calculated data node. Chapter Processing Model contains details of when and how the calculation is performed.

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

6.1.6 The constraint Property

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

Computed Expression: Yes.

Legal Values: Any expression that is convertible to a boolean as described in the expression module.

Default Value: true().

Inheritance Rules: does not inherit.

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

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

6.1.7 The p3ptype Property (deprecated)

The p3ptype is deprecated.

Description: Attaches a P3P data element to an instance data node, indicating the specific kind of data collected there. The attribute doesn't support AVT.

Computed Expression: No.

Legal Values: xsd:string.

Default Value: none

Inheritance Rules: does not inherit.

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

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

6.2.1 Atomic Datatype

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

The set of facets associated with a model item must be determined by the following list, as if it were processed in the given order. When multiple datatype restrictions apply to the same model item, the combination of all given restrictions must apply. Note that it is possible to produce a combination of restrictions that is impossible to satisfy; authors are encouraged to avoid this practice.

1. Applicable XML schema definitions (including those associated an external or an inline schema, or by xsi:type)
2. An XForms type constraint associated with the instance data node using XForms binding.
3. If no type constraint is provided, the instance data node defaults to type="xsd:string" (default to string rule).

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

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

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

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

7.6.1 The resource Element

The resource element (deprecated in favor of using an AVT in the resource attribute) allows the URI used for a submission to be dynamically calculated based on instance data.

Common Attributes: Common

Special Attributes:

value

Author-optional attribute containing an expression to evaluate using the in-scope evaluation context. To obtain the URI, the result of the expression is processed as if by call to the string conversion function as described in the expression module. An empty string is used if the evaluation fails.

Content: PCDATA

The URI to be used by the submission can be specified with either the value attribute or the string content of the resource element. If both are specified, then the value attribute takes precedence. If the submission does not have a resource child element, then the submission URI is obtained from the resource attribute or the action attribute.

Example:

<submission method="post">
    <resource value="instance('params')/anyURI"/>
</submission>

7.7.1 The method Element

The method element (deprecated in favor of using an AVT in the method attribute) allows the submission method to be dynamically calculated based on instance data.

Common Attributes: Common

Special Attributes:

value

Author-optional attribute containing an expression to evaluate using the in-scope evaluation context. To obtain the method, the result of the expression is processed as if by call to the string conversion function as described in the expression module. An empty string is used if the evaluation fails.

Content: PCDATA

The method to be used by the submission can be specified with either the value attribute or the string content of the method element. If both are specified, then the value attribute takes precedence. If the submission does not have a method child element, then the submission method is obtained from the method attribute.

7.8.1 The name Element

When the name element appears as a child of element header, it is used to specify the name of a header entry to be provided to the submission protocol.

Common Attributes: Common

If the model attribute is expressed in a name child element of a header element, then an (xforms-binding-exception) occurs if the identified model is not the containing model element.

Special Attributes:

value

Author-optional attribute containing an expression to evaluate using the in-scope evaluation context. To obtain the header name, the result of the expression is processed as if by call to the string conversion function as described in the expression module. An empty string is used if the evaluation fails.

The header entry name may be given by the string content of the name element, or by the result of the value attribute. If both are given, the result from the value attribute takes precedence. If the resulting name is the empty string, then the entry is considered to be void, and it is not supplied to the submission protocol.

7.8.2 The value Element

When the value element appears as a child of element header, it is used to specify the value component of a header entry to be supplied to the submission protocol to be added to the preamble of a submission. The value element may be used more than once in a given element header, in which case each value produces a new header entry.

Common Attributes: Common

If the model attribute is expressed in a value child element of a header element, then an (xforms-binding-exception) occurs if the identified model is not the containing model element.

Special Attributes:

value

Author-optional attribute containing an expression to evaluate using the in-scope evaluation context. To obtain the header entry value, the result of the expression is processed as if by call to the string conversion function as described in the expression module. An empty string is used if the evaluation fails.

The header entry value may be given by the string content of the value element, or by the result of the value attribute. If both are given, the result from the value attribute takes precedence.

7.9.1 The get Submission Method

This submit method represents HTTP GET or the equivalent concept. The serialized form data is delivered as part of the URI that is requested during the submit process.

This method is not suitable for submission of forms that are intended to change state or cause other actions to take place at the server. See [RFC 2616] for recommended uses of HTTP GET.

The URI is constructed as follows:

• The submit URI is examined. If it does not already contain a ? (question mark) character, one is appended. If it does already contain a question mark character and the serialized form data is non-empty, then a separator character from the attribute separator is appended.
• The serialized form data, if any, is appended to the URI.

No message body is sent with the request.

Examples:

<submission resource="http://example.com/search" method="get"/>

<submission resource="file:data.xml" method="get" serialization="none" replace="instance" instance="data" />

7.9.2 The post, multipart-post, form-data-post, and urlencoded-post Submission Methods

These submit methods represent HTTP POST or the equivalent concept (such as a mail message). The serialized form data is delivered as the message body.

Examples:

<submission resource="https://example.com/jsp/orders" method="post" ref="/purchaseOrder" />

<submission resource="http://example.com/login" method="urlencoded-post"/>

7.9.3 The put Submission Method

This submit method represents HTTP PUT or the equivalent concept (such as writing to a local file). The serialized form data is delivered as the message body.

Example:

<submission resource="file:data.xml" ref="instance('data')" method="put" validate="false" relevant="false" replace="none" />

7.9.4 The delete Submission Method

This submit method represents HTTP DELETE or the equivalent concept (such as deleting a local file). The serialized form data is delivered in the same manner as the get submission method (see The get Submission Method).

7.9.5 Serialization

<submission method="multipart-post" resource="http://example.com/photo" />

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

<submission method="form-data-post" resource="http://example.com/photo" />

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

GivenName=Ren%C3%A9

<PersonName title="Mr">
  <GivenName>René</GivenName>
</PersonName>

7.10.1 Representation of SOAP Envelope

The Single Item Binding of the submission 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.

7.10.2 Indicating a SOAP submission

For a SOAP submission, the mediatype attribute of the submission must be set to the MIME type of application/soap+xml. The form author may append charset and action MIME parameters.

7.10.3 SOAP HTTP Binding

The method attribute of the submission must be set to get or post in order to access the SOAP HTTP binding.

If method="get", then the SOAP response message exchange pattern is used. The HTTP headers must contain the Accept parameter with a value conforming to the following properties:

• must begin with application/soap+xml
• If the submission mediatype contains a charset MIME parameter, then it is appended to the application/soap+xml MIME type. Otherwise, a charset MIME parameter with same value as the encoding attribute (or its default) is appended to the application/soap+xml MIME type.
• No other MIME parameters from the mediatype are copied to the application/soap+xml MIME type
• The q MIME parameter must not be specified in the application/soap+xml MIME type so that the default quality of 1 is used.

If method="post", then the SOAP request-response message exchange pattern is used. For SOAP 1.2, the current submission behavior of using the mediatype attribute value as the value of the Content-type 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 (http://schemas.xmlsoap.org/soap/envelope/), then:

• the Content-type HTTP header is changed to text/xml
• the charset MIME parameter is appended . The charset parameter value from the mediatype attribute is used if it is specified. Otherwise, the value of the encoding attribute (or its default) is used.
• if the action MIME parameter appears in the mediatype then a SOAPAction HTTP header is added and given a value equal to the content of the action MIME parameter

Example:

<model xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:tns="http://www.webservice.net">
   <instance id="data">
       <data xmlns="">
           <city>Victoria</city>
           <country>Canada</country>
           <weather>Mostly sunny and cool. High 12C. Low 3C.</weather>
       </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 12C. Low 3C.</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; action=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 </label>
   <send ev:event="xforms-value-changed" submission="GetWeather"/>
</input>
<input ref="country">
   <label>Country </label>
   <send ev:event="xforms-value-changed" submission="GetWeather"/>
</input>
<output ref="weather">
   <label>The weather forecast is </label>
</output>

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns:tns="http://www.webservice.net" targetNamespace="http://www.webservice.net">
  <wsdl:types>
    <xs:schema elementFormDefault="qualified" targetNamespace="http://www.webservice.net">
      <xs:element name="GetWeather">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="1" name="CityName" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="1" name="CountryName" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="GetWeatherResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="1" name="GetWeatherResult" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      ...
  </wsdl:types>

  <wsdl:message name="GetWeatherSoapIn">
    <wsdl:part name="parameters" element="tns:GetWeather" />
  </wsdl:message>
  <wsdl:message name="GetWeatherSoapOut">
    <wsdl:part name="parameters" element="tns:GetWeatherResponse" />
  </wsdl:message>
  ...
  <wsdl:portType name="GetWeatherSoap">
    <wsdl:operation name="GetWeather">
      <wsdl:input message="tns:GetWeatherSoapIn" />
      <wsdl:output message="tns:GetWeatherSoapOut" />
    </wsdl:operation>
    ...
  </wsdl:portType>
  ...
  <wsdl:binding name="GetWeatherSoap" type="tns:GetWeatherSoap">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
    <wsdl:operation name="GetWeather">
      <soap:operation soapAction="http://www.webservice.net/GetWeather" style="document" />
      <wsdl:input>
        <soap:body use="literal" />
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal" />
      </wsdl:output>
    </wsdl:operation>
    ...
  </wsdl:binding>

  <wsdl:service name="GetWeatherService">
    <wsdl:port name="GetWeatherSoap" binding="tns:GetWeatherSoap">
      <soap:address location="http://www.webservice.net/getweather.asmx" />
    </wsdl:port>
    ...
  </wsdl:service>
</wsdl:definitions>

7.10.4 Handling the SOAP Response

The XForms processor 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 xforms-submit-error event is dispatched.

On successful completion, the results are consumed according to the XForms submission process, culminating in an xforms-submit-done 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.

8.1.1 Implementation Requirements Common to All Form Controls

XForms user interface controls are bound to the underlying instance data using binding attributes as defined in the chapter Model Item Properties.

Form controls enable accessibility by taking a uniform approach to such features as labels, help text, navigation, and keyboard shortcuts. Internationalization issues are addressed by following the same design principles as in XHTML. All form controls are suitable for styling as aural or visual media.

Form controls encapsulate high-level semantics without sacrificing the ability to deliver real implementations. For instance, the form control select enables the user to select items from a set. These form controls distinguish the functional aspects of the underlying control from the presentational and behavioral aspects. This separation enables the expression of the intent underlying a particular form control — see [AUI97] for a definition of such high-level user interaction primitives.

Form controls when rendered display the underlying data values to which they are bound. While the data presented to the user through a form control must directly correspond to the bound instance data, the display representation is not required to match the lexical space value of the bound instance data. For example, user agents should apply appropriate conventions to the display of dates, times, durations and numeric values including separator characters.

All form controls must meet the following implementation requirements:

• All form controls, including container form controls, should have an inline layout by default (e.g. for a host language that supports CSS, the default styling should be display:inline). By default, repeat items should have a block layout (e.g. a default styling of display:block for host languages that support CSS).
• If a form control violates its data binding restriction, an xforms-binding-exception must occur.
  Note: Form controls that read or write simpleContent produce this exception whenever and as soon as they are bound to an element node that has an element child node.
• Form controls that write simpleContent to instance data must do so exactly as defined by the XForms Action setvalue (The setvalue Element).
  Note: If a form control binds to an element node, then regardless of how many child nodes the element has, the result of the form control writing to the bound element node is that it has either a single non-empty text node child, or no children if the simpleContent written is the empty string (which is in accord with the data model of [XPath 1.0]).
• All form controls that read simpleContent instance data must do so as follows:
  • Element nodes: If element child nodes are present, then an xforms-binding-exception occurs. Otherwise, return the string value of the node.
  • Attribute nodes: returns the string-value of the node.
  • Text nodes: returns the string-value of the node.
  • Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
  • the XPath root node: an xforms-binding-exception occurs.
    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 form control becoming non-relevant 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.
• Form controls are considered to be relevant if none of the following apply and non-relevant if any of the following apply:
  • the Single Item Binding is expressed and resolves to empty sequence,
  • the Single Item Binding is expressed and resolves to a non-relevant instance node,
  • the form control is contained by a non-relevant switch or group (which includes a non-relevant repeat item), or
  • the form control is contained by a non-selected case element of a switch.

    When a form control becomes non-relevant, it must receive event xforms-disabled and then the XForms action handlers that are listening for events on the non-relevant form control must be disabled.

    When a non-relevant form control changes to being relevant, the XForms action handlers that listen for events on the form control must become enabled and then the form control must be updated to represent the current value(s) and model item properties of the instance node(s) to which it is bound or to which it refers. The following events must be dispatched to the form control: xforms-enabled, xforms-value-changed, one of xforms-valid or xforms-invalid, one of xforms-readonly or xforms-readwrite, one of xforms-required or xforms-optional, and one of xforms-in-range or xforms-out-of-range.

• Except as noted, relevant form controls must distinguish rendering between being bound to a required node versus a non-required node. Exceptions are form controls that do not directly render the string value of the bound node (including trigger and the container form controls). Control of this behavior should be made available to stylesheets.
• Relevant form controls must distinguish rendering between valid and invalid states. Control of this behavior should be made available to stylesheets.
• Relevant form controls must indicate when the bound instance data contains a value or content that the form control is not capable of rendering. Control of this behavior should be made available to stylesheets.
• If a form control binds to a readonly node or an atomic value, then the form control must not allow the user to modify the node value. The relevant form control that is bound to a readonly node or an atomic value should render in a way which indicates that entering or changing the value is not allowed. Control of the render behavior should be made available to stylesheets.

Sections in this chapter define the various form controls by specifying the following:

Description
Common Attributes
Special Attributes
Examples
Data Binding Restrictions
Implementation Requirements

8.1.2 The input Element

Description: This form control enables free-form data entry or a user interface component appropriate to the datatype of the bound node..

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

inputmode

Author-optional. This form control accepts an input mode hint. Input Modes.

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default value for this attribute is false.

Data Binding Restrictions: Binds to any simpleContent (except xsd:base64Binary, xsd:hexBinary or any datatype derived from these) or an atomic value.

Implementation Requirements: Must allow entry of a lexical value for the bound datatype. Implementations should provide a convenient means for entry of datatypes and take into account localization and internationalization issues such as representation of numbers. For example, an input bound to an instance data node of type xsd:date might provide a calendar control to enter dates; similarly, an input control bound to of type boolean might be rendered as a checkbox.

Examples:

<input ref="order/shipTo/street" class="streetAddress">
  <label>Street</label>
  <hint>Please enter the number and street name</hint>
</input>

<input ref="order/shipDate">
  <label>Ship By</label>
  <hint>Please specify the ship date for this order.</hint>
</input>

<input ref="/search/expr">
  <label>Search term(s):</label>
  <send ev:event="DOMActivate" submission="doSearch" />
</input>

<submit submission="doSearch">
  <label>Search</label>
</submit>

8.1.3 The secret Element

Description: This form control is used to provide the user with the ability to supply information to the system in a manner that makes it difficult for someone, other than the user, who may be observing the process to discern the value that is being supplied. A common use is for password entry.

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

inputmode

Author-optional. This form control accepts an input mode hint. Input Modes.

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default value for this attribute is false.

Data Binding Restrictions: Binds to any simpleContent (except xsd:base64Binary, xsd:hexBinary or any datatype derived from these) or an atomic value.

Implementation Requirements: Implementations, including accessibility aids, must obscure the value being entered into this form control. One possible approach would be to render a "*" or similar character instead of the actual characters entered. Note that this provides only a casual level of security; truly sensitive information will require additional security measures outside the scope of XForms.

Example:

<secret ref="/login/password">
  <label>Password</label>
  <hint>The password you enter will not be displayed.</hint>
</secret>

8.1.4 The textarea Element

Description: This form control enables free-form data entry and is intended for use in entering multiline content, e.g., the body of an email message.

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

inputmode

Author-optional. This form control accepts an input mode hint. Input Modes.

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default value for this attribute is false.

Data Binding Restrictions: Binds to any simpleContent (except xsd:base64Binary, xsd:hexBinary 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.

Example:

<textarea ref="message/body" class="messageBody">
  <label>Message Body</label>
  <hint>Enter the text of your message here</hint>
</textarea>

8.1.5 The output Element

Description: This form control renders content based in part on instance data, but it provides no means for entering or changing data.

Common Attributes: Common, Single Item Binding (author-optional)

Special Attributes:

appearance

This form control does not use the UI Common attribute group, but nevertheless still contains an author-optional appearance attribute, as defined above.

value

Author-optional. An expression to be evaluated. The string result of the evaluation is rendered by the form control. If binding attributes are present to select a node, this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the Single Item Binding. This expression is re-evaluated whenever there is a change in any node to which the expression refers. An empty string is used if the evaluation fails.

mediatype

Author-optional attribute used to indicate that data obtained from the Single Item Binding should be rendered (after decoding, if needed) according to a desired media type indicated by the attribute value string, such as image/* for image rendition. If the mediatype element appears as a child of the output, then it overrides this attribute. If the media type is not specified by this attribute or by the mediatype element, then the the default is to present the indicated data as plain text (with no decoding according to datatype).

Data Binding Restrictions: Binds to any simpleContent or an atomic value.

Implementation Requirements: Must allow display of a value for the bound datatype. Implementations should provide a convenient means for display of datatypes and take into account localization and internationalization issues such as representation of numbers and dates.

Element output can be used to display the value of a particular instance node by using a Single Item Binding; it can also be used to display the result of evaluating an expression by specifying the expression to be evaluated via attribute value. Note that the Single Item Binding attributes and value on element output are mutually exclusive.

By default, the output element simply renders the plain text of the value attribute or the item indicated by the Single Item Binding. However, if the Single Item Binding indicates a non-empty value, and the media type is specified based on the mediatype attribute or mediatype child element, then the string value of the item must be decoded or dereferenced according to its datatype, and the result should be rendered according to the indicated media type if it is possible to do so (e.g. a voice-only device cannot render a digital image).

If the Single Item Binding is absent or if it does not indicate a non-empty value, then the media type specification is ignored if given. Otherwise, if the Single Item Binding produces a non-empty value, and the media type is specified, then decoding or dereferencing of the item prior to rendition is performed by datatype as follows:

• If the item either is of type or is derived from type xsd:base64Binary, then the data is base-64 decoded.
• If the item either is of type or is derived from type xsd:hexBinary, then the data is hex-binary decoded.
• If the item either is of type or is derived from type xsd:anyURI, then the data is treated as a URI and dereferenced.
• If the item is of any other type, then the data is used without modification.

If the output rendition is based on the value attribute, then the rendition is updated if the nodes referenced by the value expression change or if the content of any of the referenced nodes changes. Otherwise, the rendition of an output is updated if the item referenced by the Single Item Binding changes, if the content of the referenced item changes, or if the media type changes. The media type can change by a change to the mediatype element's referenced item or its content (a host language may also allow DOM mutation of the content of the mediatype attribute or element). A change to the label associated with the output causes an update to the rendition of the label (which may affect the layout position of the main output content).

Failure to render the content indicated by the output element should result in an xforms-output-error, a non-fatal error that does not halt XForms processing. Failures can occur on initial creation of the output or during user interface refresh (see Section The xforms-refresh Event). Failures can occur for many reasons, including

• Data to be decoded does not conform to the format of xsd:base64Binary or xsd:hexBinary
• An error dereferencing the URI in a item of or derived from type xsd:anyURI
• A data format error (e.g. invalid or unsupported image format)
• An unrecognized media type identifier string

The content model for the output element includes UI Common in order to allow action handlers for the xforms-output-error as well as to allow more comprehensive behavior and information to be provided for the output, e.g. via the hint element.

Examples:

I charged you -
<output ref="order/totalPrice"/>
- and here is why:

<model>
	<instance>
		<data xmlns=""/>
	</instance>
	<bind ref="/data" type="xsd:base64Binary"/>
</model>

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

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

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

A graphical browser may take into account the appearance and the localization information from the host language and present the above output form controls as follows:

Lexical: 1998-01-19 Full: 19 janvier 1998 Minimal: 19/01/1998

8.1.6 The upload Element

Description: This form control enables the common feature found on Web sites to upload a file from the local file system, as well as accepting input from various devices including microphones, pens, and digital cameras.

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

mediatype

Author-optional. Space-separated list of suggested media types, used by the XForms Processor to determine the possible sources of data to upload.

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default for this form control is false.

Data Binding Restrictions: This form control can only be bound to datatypes xsd:anyURI, xsd:base64Binary or xsd:hexBinary, or types derived by restriction from these.

Implementation Requirements: For base64Binary or hexBinary data binding:

• When bound to an instance data node of type xsd:base64binary, xsd:hexBinary, or a type derived by restriction thereof, on activation upload places the binary content in the content of the node with the indicated encoding.

Implementation Requirements: For anyURI data binding:

• When bound to an instance data node of type xsd:anyURI (or a type derived by restriction thereof), on activation upload places a URI in the content of the node.
  
  For security reasons, the XForms Processor must not dereference the URI bound to this form control without explicit user permission.
  Note: Implementors note that upload must associate the binary content, mediatype, and filename with that URI for Serialization as multipart/related and Serialization as multipart/form-data serialization.

• Implementations with a file system should support file upload — selecting a specific file. The types of files presented by default should reflect the mediatype specified by attribute mediatype, for example defaulting to only audio file types in the file dialog when the mediatype is "audio/*".

Implementation Requirements: For all data bindings:

• Implementations with specific pen/digitizer hardware should (and implementations with other pointing devices may) support scribble — allowing in-place creation of pen-based data.
• Implementations with specific audio recording capabilities should support record audio — in-place recording of an audio clip.
• Implementations with a digital camera, scanner interface or screen capture should support acquire image — in-place upload of images from an attached device.
• Implementations with video recording capability should provide a record video option.
• Implementations with 3d capabilities should provide a 3d interface option.
• Implementations may provide proprietary implementations (for example, a mediatype of text/rtf could invoke an edit window with a proprietary word processing application)
• Implementations are encouraged to support other input devices not mentioned here.
• Implementations which cannot support upload for the given mediatype must make this apparent to the user.

See the child elements filename (The filename Element) and mediatype (The mediatype Element (for upload)).

Example:

<upload ref="mail/attachment" mediatype="image/*">
  <label>Select image:</label>
  <filename ref="@filename" />
  <mediatype ref="@mediatype" />
</upload>

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

8.1.7 The range Element

Description: This form control allows selection from a sequential range of values.

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

start

Author-optional attribute containing a hint for the lexical starting bound for the range — a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model.

end

Author-optional attribute containing a hint for the ending bound for the range — a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model.

step

Author-optional attribute containing a delta-value to use for incrementing or decrementing the value. Must be of a type capable of expressing the difference between two legal values of the underlying data.

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default for this form control is false.

Data Binding Restrictions: Binds only the following list of datatypes, or datatypes derived by restriction from those in the list: xsd:duration, xsd:date, xsd:time, xsd:dateTime, xsd:gYearMonth, xsd:gYear, xsd:gMonthDay, xsd:gDay, xsd:gMonth, xsd:float, xsd:double, and xsd:decimal.

Implementation Requirements: Must allow input of a value corresponding to the bound datatype. Implementations should inform the user of the upper and lower bounds, as well as the step size, if any. If the instance data value is outside the upper or lower bounds, this form control must indicate an out-of-range condition. In graphical environments, this form control may be rendered as a "slider" or "rotary control".

In the event of overlapping restrictions between the underlying datatype and the start and end hints, the most restrictive range should be used.

Notice that the attributes of this element encapsulate sufficient metadata that in conjunction with the type information available from the XForms Model proves sufficient to produce meaningful prompts when using modalities such as speech, e.g., when using an accessibility aid. Thus, in the example below, an aural user agent might speak a prompt of the form Please pick a date in the range January 1, 2001 through December 31, 2001.

Examples:

<range ref="/stats/balance" start="-2.0" end="2.0" step="0.5">
  <label>Balance</label>
</range>

<range ref="/order/shipDate" start="2001-01-01" end="2001-12-31">
  <label>Ship Date</label>
</range>

8.1.8 The trigger Element

Description: This form control is similar to the HTML element button and allows for user-triggered actions. This form control may also be used to construct other custom form controls.

Common Attributes: Common, UI Common, Single Item Binding (author-optional)

Data Binding Restrictions: Binds to any node or an atomic value. This form control does not directly interact with form data, but is affected by model item properties of the bound node, thus binding attributes are not required.

Implementation Requirements: The user agent must provide a means to generate an DOMActivate event on the form control. Graphical implementations might render this form control as a push-button with the label on the button face. Style sheets can be used to style this form control as an image, hyperlink, or other presentation.

Although a trigger element receives events associated with model item properties of a bound node, such as xforms-readonly and xforms-invalid, the XForms processor must not impart special behaviors on this control for model item properties other than the model item property relevant of a bound data node. For example, the readonly model item property of a bound data node does not affect whether or not the trigger can be activated.

Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute appearance. 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": rendered with no border, a transparent background and underline font effect. This rendition hint is meant to be analogous to the typical visual rendition of an XHTML anchor element.

Example:

<trigger>
  <label>Click here</label>
</trigger>

8.1.9 The submit Element

Description: This form control initiates a submission .

Common Attributes: Common, UI Common, Single Item Binding (author-optional)

Special Attributes:

submission

Author-optional attribute containing a reference to element submission. If this attribute is given but does not identify a submission element, then activating the submit does not result in the dispatch of an xforms-submit event. If this attribute is omitted, then the first submission in document order from the model associated with the in-scope evaluation context is used.

Data Binding Restrictions: Binds to any node or an atomic value. This form control does not directly interact with form data, but is affected by model item properties of the bound node, thus binding attributes are not required.

Implementation Requirements: The default action for event DOMActivate is to dispatch event xforms-submit to the submission element specified by attribute submission (or its default). Upon activation, this control must become unavailable for further activations until the submit process concludes with either an xforms-submit-done or xforms-submit-error event.

Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute appearance. Suggested renditions for the pre-defined values of this attribute are the same as for trigger.

Example:

<submit submission="timecard">
  <label>Submit Timecard</label>
</submit>

8.1.10 The select Element

Description: This form control allows the user to make multiple selections from a set of choices.

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

selection

Author-optional attribute determining whether free entry is allowed in the list. Default is "closed".

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default for this form control is true.

Data Binding Restrictions: any simpleContent capable of holding a sequence or a sequence of atomic values. The restriction to binding simpleContent exists when the choices are authored as part of the user interface control as shown in this section. Element itemset (described in The itemset Element) creates dynamic selection items and allows the available choices to be obtained from an XForms Model. When itemset uses the value element, the restriction to binding simpleContent remains in effect. However, the itemset also allows for the selection and deselection of subtrees of instance data using the copy element, and when using that construct, the data binding restriction to simpleContent is relaxed, but the form control must bind to an element with no mixed content or a sequence of atomic values.

<item>
  <value>United States of America</value>
  ...
</item>

Implementation Requirements: The label for each choice must be presented, and the control must allow any number of selections, possibly none. When this form control uses the value element for selection, it stores the values corresponding to the selected choices in a space separated list in the location addressed by the binding attributes. The values to be stored for selected items are either directly specified as the contents of element value, or specified indirectly through binding attributes on element value. When this form control uses the copy element for selection, it stores copies of the subtrees corresponding to the selected choices in the location addressed by the binding attributes.

The datatype bound to this form control may include a non-enumerated value space, e.g., xsd:string, or a union of a enumeration and a non-enumerated datatype (called an open enumeration). In this case, control select may have attribute selection="open". The form control must then allow free data entry, as described in The input Element. The form control may permit multiple values to be entered through free entry.

For closed selections: If the instance data matches the storage data of one or more of the selection items, those items are selected. If there is no match, no items are initially selected. If any of the stored values or subtree copies do not correspond to an item with a matching storage value or subtree, the form control must indicate an out-of-range condition. If the form control switches to or from being out-of-range, then xforms-out-of-range or xforms-in-range must be dispatched to the form control.

For open selections: When using dynamic selections with the itemset and copy elements, open selection has no effect. If the instance data matches the storage values specified by one or more of the selection items, then all such matching items are selected. If any instance data list values do not match the storage value specified by one or more of the items, all such non-matching values are retained, as if entered through free entry. Free entry text is handled the same as form control input (The input Element), possibly in multiplicity.

For both closed and open selections, any selection item with an empty storage data subtree or a storage value that is either empty or contains only white space characters must remain deselected.

For both closed and open selections, the above rules describe which items are considered to be selected and deselected by the control. The select form control changes the states of selected and deselected items on creation, refresh, and user selection or deselection of an item. Newly selected items receive the event xforms-select immediately after all newly deselected items receive the event xforms-deselect. The content of the instance node bound to the selection control must only be changed by the addition or deletion of storage data associated with items that have been selected or deselected. Content not associated with selection items is preserved. For selection controls that use the value element, the net effect of newly selected and deselected items is computed into a string, preserving content not associated with selection items, and the result is then committed to the bound instance node by using the XForms Action The setvalue Element. For selection controls that use the copy element, the individual subtrees associated with the newly selected and deselected items are added or removed individually by using The insert Element and The delete Element.

Implementation Hints:

For closed selections, when the form control is created or refreshed to reflect bound instance data, behavior equivalent to the following steps occurs:

1. The content parts (space-separated values or subtree copies) in the bound instance data node are compared with the form control items' storage data (values or subtree copies).
2. Each item with storage data (value or subtree copy) equal to an instance data content part becomes selected if it was not already selected.
3. Each item with storage data missing from the instance data content becomes deselected if it was not already deselected.
4. If there are instance data content parts for which there is no corresponding selection item, the form control indicates an out-of-range condition.

When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:

1. If the item's storage data (value or subtree copy) was not present in the bound instance data, the item's storage data is inserted into the instance data content list. The exact location of the insertion is implementation-dependent. Any other item having the same storage data becomes selected as well.
2. If the item's storage data was already present in the bound instance data, the bound instance data is left unchanged.

When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:

1. If the item's storage data was present in the bound instance data, the item's storage data is removed from the instance data content list. Any other item having the same storage data becomes deselected as well.
2. If the item's storage data was already absent from the bound instance data, the bound instance data is left unchanged.

For open selections: when the form control is created or refreshed to reflect bound instance data, the behavior is the same as with closed selection, except the form control never indicates an out-of-range condition.

An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.

Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute appearance. The value of the attribute consists of one of the following values:

"full": all choices should be rendered at all times.
"compact": a fixed number of choices should be rendered, with scrolling facilities as needed
"minimal": a minimum number of choices should be rendered, with a facility to temporarily render additional choices

Example:

<select ref="my:flavors">
  <label>Flavors</label>
  <choices>
    <item>
      <label>Vanilla</label>
      <value>v</value>
    </item>
    <item>
      <label>Strawberry</label>
      <value>s</value>
    </item>
    <item>
      <label>Chocolate</label>
      <value>c</value>
    </item>
  </choices>
</select>

8.1.11 The select1 Element

Description: This form control allows the user to make a single selection from multiple choices.

Common Attributes: Common, UI Common, Single Item Binding

Special Attributes:

selection

Author-optional attribute determining whether free entry is allowed in the list. Default is "closed".

incremental

Author-optional. When true, this form control will generate additional xforms-value-changed events. The default for this form control is true.

Data Binding Restrictions: Binds to any simpleContent or an atomic value. The restriction to binding simpleContent exists when the choices are authored as part of the user interface control as shown in this section. Element itemset (described in The itemset Element) creates dynamic selection items and allows the available choices to be obtained from an XForms Model. When itemset uses the value element, the restriction to binding simpleContent remains in effect. However, the itemset also allows for the selection and deselection of subtrees of instance data using the copy element, and when using that construct, the data binding restriction to simpleContent is relaxed, but the form control must bind to an element with no mixed content or an atomic value.

Implementation Requirements: The label for each choice must be presented, and the control must allow at all times exactly one selection. When this form control uses the value element for selection, it stores the value corresponding to the selected choice in the location addressed by the binding attributes. The value to be stored is either directly specified as the contents of element value, or specified indirectly through binding attributes on element value. When this form control uses the copy element for selection, it stores a copy of the subtree corresponding to the selected choice in the location addressed by the binding attributes.

The datatype bound to this form control may include a non-enumerated value space, e.g., xsd:string, or a union of a enumeration and a non-enumerated datatype (called an open enumeration). In this case, control select1 may have attribute selection="open". The form control must then allow free-form data entry, as described in The input Element.

For closed selections: If the instance data matches the storage data of one of the selection items, that item is selected. If there is no match, no items are initially selected. If there is no match and the storage data is non-empty, the form control must indicate an out-of-range condition. If the form control switches to or from being out-of-range, then xforms-out-of-range or xforms-in-range must be dispatched to the form control.

For open selections: When using dynamic selections with the itemset and copy elements, open selection has no effect. If the instance data matches the storage value specified by one of the selection items, then the first such matching item is selected. Otherwise, no items are selected and the instance data value is retained, as if entered through free text entry. Free entry text is handled the same as form control input (The input Element).

For both closed and open selections, any selection item with a storage value which is empty or which contains only white space characters is deemed to be selected if the bound data node value exactly matches the storage value of the selection item. Furthermore, selecting a selection item with a storage value which is empty or which contains only white space characters places the storage value into the bound data node value.

For both closed and open selections, the above rules describe which items are considered to be selected by the control. Items that are not selected are considered to be deselected. The select1 form control changes the states of selected and deselected items on creation, refresh, and user selection or deselection of an item. A newly selected item receives the event xforms-select immediately after all other items receive the event xforms-deselect. The content of the instance node bound to the selection control must only be changed by the addition or deletion of storage data associated with items that have been selected or deselected. Content not associated with selection items is preserved. For selection controls that use the value element, the net effect of newly selected and deselected items is computed into a string, preserving content not associated with selection items, and the result is then committed to the bound instance node by using the XForms Action The setvalue Element. For selection controls that use the copy element, the individual subtrees associated with the newly selected and deselected items are added or removed individually by using The insert Element and The delete Element.

Implementation Hints:

For closed selections, when the form control is created or refreshed to reflect bound instance data, behavior equivalent to the following steps occurs:

1. The bound instance data is compared with the items' storage data (values or subtree copies).
2. If no item with storage data (value or subtree copy) in the bound instance data node is selected, then the first item with storage data in the instance data content, if any, becomes selected. Otherwise, if an item with storage data in the bound instance data node is selected, then the first selected item remains selected, and any other items with storage data matching the selected item are deselected.
3. If there is a selected item, then all items with storage data not equal to the selected item are deselected, and their representative storage data is removed from the bound instance node content.
4. If no item has storage data in the bound instance data node content and the instance data node content is not empty, then the form control indicates an out-of-range condition.

When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:

1. All selected items other than the newly selected item are deselected, if any, and the storage data of any deselected items whose storage data does not match the newly selected item are removed from the bound instance node data.
2. The newly selected item becomes selected. If its storage data (value or subtree copy) is not present in the bound instance data, then the item's storage data is inserted into the instance data. The exact location of the insertion is implementation-dependent, but the newly inserted data is not accompanied by any other data unless the data does not match any items for the selection control.

When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:

1. The item is deselected and its storage data is removed from the bound instance node data.
2. If the bound instance data node is not empty, then the form control indicates an out-of-range condition.

For open selections: when the form control is created or refreshed to reflect bound instance data, the behavior is the same as with closed selection, except the form control never indicates an out-of-range condition.

An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.

User interfaces may choose to render this form control as a pulldown list or group of radio buttons, among other options. The appearance attribute offers a hint as to which rendering might be most appropriate, although any styling information (such as CSS) should take precedence.

Example:

<select1 ref="my:flavor">
  <label>Flavor</label>
  <item>
    <label>Vanilla</label>
    <value>v</value>
  </item>
  <item>
    <label>Strawberry</label>
    <value>s</value>
  </item>
  <item>
    <label>Chocolate</label>
    <value>c</value>
  </item>
</select1>

8.2.1 The label Element

This element provides a descriptive label for the containing form control. The descriptive label can be presented visually and made available to accessibility software so the visually-impaired user can obtain a short description of form controls while navigating among them.

Common Attributes: Common, UI Common, Single Item Binding (author-optional)

Special Attributes: None

The label specified can exist in instance data or as inline text. If more than one source of label is specified in this element, the order of precedence is: Single Item Binding attributes, inline text.

An accessibility aid might speak the metadata encapsulated here when the containing form control gets focus.

8.2.2 The help Element

The author-optional element help provides a convenient way to attach help information to a form control.

Common Attributes: Common, UI Common, Linking, Single Item Binding (author-optional)

Special Attributes: None

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: Single Item Binding attributes, inline text.

XForms processors should choose an appropriate presentation for the help content, and should allow styling if the host language integration supports it, for example with CSS.

If the host language integration supports Linking, the help link should be made available through an appropriate presentation mechanism. With appearance="minimal", the help link should be associated with the label.

With no host-language styling and no appearance specified, a graphical browser should present help as an ephemeral message. The following example shows how such help might be presented in a graphical browser:

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

8.2.3 The hint Element

The author-optional element hint provides a convenient way to attach hint information to a form control.

Common Attributes: Common, UI Common, Single Item Binding (author-optional)

Special Attributes: None

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: Single Item Binding attributes, inline text.

XForms processors should choose an appropriate presentation for the hint, and should allow styling if the host-language integration supports it, for example with CSS. With no attribute appearance and no host-language styling, a presentation should be the same as an ephemeral message associated with the label, which a graphical browser might render as follows:

<input ref="po/address/street1">
  <label>Street</label>
  <hint>Please enter the number and street name</hint>
</input>

With appearance="minimal", a hint should be associated with the value yet distinguished from actual values.

<group ref="registration">
  <input ref="name">
    <label>Name: </label>
    <hint appearance="minimal">Last, First</hint>
  </input>
  <input ref="website">
    <label>Website: </label>
    <hint appearance="minimal">http://</hint>
  </input>
</group>

A graphical browser might render such a a hint as follows:

8.2.4 The alert Element

The author-optional element alert provides a convenient way to attach alert or error information to a form control. Rendering of this element is implementation-defined, and there is no default level such as modal or ephemeral for the displayed message.

Common Attributes: Common, Single Item Binding (author-optional)

Special Attributes: None

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: Single Item Binding attributes, inline text. See XForms and Styling for examples to see how this might be presented to the user.

8.3.1 The choices Element

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

Common Attributes: Common

8.3.2 The item Element

This element specifies the storage value and label to represent an item in a list. It is found within elements select1 and select, or grouped in element choices.

Common Attributes: Common

8.3.3 The value Element

This element provides a storage value to be used when an item is selected. The storage value is determined by one of three methods, in order of precedence:

1. the value of a node indicated by a Single Item Binding expression, if specified
2. the result of evaluating an expression appearing in attribute value, if specified
3. the inline content of the value element (when neither the Single Item Binding nor the value attribute are expressed).

Common Attributes: Common, Single Item Binding (author-optional)

Special Attributes:

value

Author-optional. An expression to be evaluated. The string result of the evaluation is used as the storage value of the item when it is selected. If a Single Item Binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the Single Item Binding. An empty string is used if the evaluation fails.

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 xforms-binding-exception must occur.

9.1.1 The group Element

The group element is used as a container for defining a hierarchy of form controls. Groups can be nested to create complex hierarchies. The author-optional label element has special significance when it appears as the first element child of group, representing a label for the entire group.

Common Attributes: Common, UI Common, Single Item Binding (author-optional)

Although a group element receives events associated with model item properties of a bound node, such as xforms-readonly and xforms-invalid, no special behavior is imparted by the group onto the content elements in the group as a direct result of any model item property. The model item property relevant of a bound data node can indirectly affect the content of the group via its contribution to deciding whether the group is relevant or non-relevant. A group is considered to be non-relevant if and only if:

• the Single Item Binding is expressed and resolves to empty sequence,
• the Single Item Binding is expressed and resolves to a non-relevant instance node,
• the group is contained by a non-relevant switch or group (which includes a non-relevant repeat object), or
• the group is contained by a non-selected case element of a switch.

All content elements (e.g. core form controls, groups, switches, repeats and host language content) within a non-relevant group are handled as non-relevant. When a group becomes non-relevant, it must receive event xforms-disabled and then the XForms action handlers that are listening for events on the non-relevant group must be disabled. When a non-relevant group changes to being relevant, the XForms action handlers that listen for events on the group must become enabled and then the group must receive the event xforms-enabled.

Example:

<group ref="address">
  <label>Shipping Address</label>
  <input ref="line_1">
    <label>Address line 1</label>
  </input>
  <input ref="line_2">
    <label>Address line 2</label>
  </input>
  <input ref="postcode">
    <label>Postcode</label>
  </input>
</group>

Setting the input focus on a group results in the focus being set to the first form control in the navigation order within that group.

9.2.1 The switch Element

This element contains one or more case elements, any one of which is rendered at a given time. When the switch is created, the initially selected case is governed by the caseref attribute if specified, and otherwise by the selected attributes of the cases. The selected case can then be changed by the toggle action or by any change of the data node indicated by the caseref attribute, if specified. When a new case becomes selected, any previously selected case becomes deselected. The selected and deselected case elements receive events xforms-select and xforms-deselect regardless of how they are selected and deselected.

Common Attributes: Common, UI Common, Single Item Binding (author-optional)

Special Attributes:

caseref

Author-optional XPath expression indicating an instance node with which the identity of the selected case is synchronized.

If the caseref attribute is specified, then it takes precedence over the selected attributes of the case elements, whether or not it indicates an existing instance node and whether or not the instance node contains a value that matches the ID of a case. The caseref attribute is evaluated relative to the Single Item Binding, if specified, or the in-scope evaluation context otherwise. The result is interpreted as a node-sequence, and the first node is obtained, if any. It is an xforms-binding-exception if the first node obtained has a child element. The caseref value is considered to be the string value of the first node if the expression result is a non-empty nodeset, and empty string if the result is not a node-sequence or an empty sequence.

The result of the caseref expression is kept up to date in a manner consistent with user interface bindings. It is an xforms-binding-exception if the expression changes to indicating a node-sequence whose first node has a child element. The caseref value can change due to a change of the value of the node indicated by the caseref expression, or by the expression binding changing, either from one node to another, from not indicating a node to indicating a node, or from indicating a node to not indicating a node. If the caseref value changes, then the selected case of the switch is changed to reflect the new caseref value.

Whether initially selecting a case or selecting a case due to a caseref value change, the case that is selected is based on ID matching. If the caseref value is a non-empty string that matches the ID of a case in the switch, then the matched case is selected. If the caseref value is empty string or is not equal to the ID of a case in the switch, then the selected case is the first case child element of the switch. In this latter circumstance, if caseref refers to a node, the value of the node is not changed.

If the caseref attribute is not specified, then the initially selected case is governed by the selected attributes of the case elements, and changes to the selected case can only be made by the toggle action.

If the caseref attribute is specified, then changes to the selected case can be made by changes to the caseref value as described above, such as by the setvalue action. Changes to the selected case can also be performed by the toggle action, but these are performed by performing a setvalue action if the caseref attribute is specified and indicates a node. If the node is readonly or if the toggle action does not indicate a case in the switch, then no value change occurs and therefore no change of the selected case occurs.

If the switch element contains a Single Item Binding, then it receives events associated with model item properties of a bound node, such as xforms-readonly and xforms-invalid. No special behavior is imparted by the switch onto the content elements in the selected case as a direct result of any model item property. The model item property relevant of a bound data node can indirectly affect the content of the selected case via its contribution to deciding whether the containing switch is relevant or non-relevant. The non-relevance of a switch is determined in the same way as it is for group and similarly applies to the entire content. Also, as with group, when a switch becomes non-relevant, it must receive event xforms-disabled and then the XForms action handlers that are listening for events on the non-relevant switch must be disabled. As well, when a non-relevant switch changes to being relevant, the XForms action handlers that listen for events on the switch must become enabled and then the switch must receive the event xforms-enabled.

Example:

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

The above results in the portion of the user interface contained in the first case being displayed initially. This prompts for the user's name; filling in a value and activating the control e.g., by pressing enter results switches to the alternate case, with a read-only output rendering. Activating the trigger labeled "Edit" in turn switches back to the original case.

Example:

  <label>Select Payment Method</label>
  <item><label>Credit Card</label><value>creditCard</value></item>
  <item><label>Bank Account Card</label><value>cashCard</value></item>
  <item><label>Cash on delivery</label><value>COD</value></item>

   <case id="creditCard">
       <label>Credit Card Details</label>
       ...
   </case>

   <case id="cashCard">
       <label>Bank Account Card</label>
        ...
   </case>

   <case id="COD">
       <label>Cash-on-delivery Account Information</label>
       ... 
   </case>

In this example, if the payment method is initially empty, then initially the credit card details case will be selected. Once the user chooses a payment method with the select1, then the case is selected whose ID matches the selected item value.

9.2.2 The case Element

This element encloses markup to be conditionally rendered. When a case is selected, it receives the event xforms-select, and its content is rendered. When a case is deselected, it receives the event xforms-deselect. The content elements (e.g. form controls, groups, switches, repeats and host language elements) within a non-selected case behave as if they were in a non-relevant group (see The group Element). Similarly, content elements in a case that becomes selected behave as if they were in a group that has become relevant. If the containing switch does not specify the caseref attribute, then the attribute selected determines the initial selected state of the case, and the toggle action is used to change the selected case. The toggle action uses a case attribute or a case child element to make an ID reference to the case of the switch to select.

Common Attributes: Common

Special Attributes:

selected

Author-optional initial selection status for the case. The default value is "false". This attribute is ignored if the switch specifies the caseref attribute.

If the containing switch does not specify the caseref attribute, then the initially selected case within a switch is the one marked as selected="true". If multiple cases within a switch are marked as selected="true", the first selected case in document order is initially selected and all others are deselected. If none of the cases within a switch are marked as selected="true", the first case in document order becomes initially selected.

9.3.1 The repeat Element

This element defines a UI mapping over a sequence selected by Sequence Binding Attributes. This sequence is called a repeat collection. The markup contained within the body of element repeat specifies the template of the user interface to be generated for each item of the repeat collection. For each item of the repeat collection, a repeat item is defined to be the aggregation of the item, its position, the size of the repeat collection, and a repeat object. A repeat object is an implicitly generated group element that contains the set of run-time objects generated to represent the repeat template content for a single repeat item of the repeat collection. These run-time objects are form controls, XForms actions and other host language elements that correspond to markup content in the repeat template. If an item of the repeat collection is non-relevant, then the rendering approach used to signify non-relevance is applied to the user interface controls of the associated repeat object.

The XForms processor associates with each repeat collection an integer value, called a repeat index, that is between 0 and the size of the repeat collection to indicate a repeat object that may be the focus of certain XForms processor operations.

Common Attributes: Common, UI Common, Sequence Binding

Special Attributes:

indexref

Author-optional XPath expression indicating an instance node with which the repeat index is synchronized.

startindex

Author-optional 1-based initial value of the repeat index. The default value is 1. This attribute is ignored if the indexref is specified.

number

Author-optional hint to the XForms Processor as to how many elements from the collection to display.

Example:

<repeat ref="/cart/products/product">
  <input ref="." ...>
     <label>...</label>
  </input>
  <html:br/>
</repeat>

The repeat element operates over a repeat collection by creating repeat objects and binding them to the items of the collection. Another way to conceptually grasp repeat processing (disregarding special user interface interactions) is to consider "unrolling" the repeat. The above example is similar to the following (given four product elements in the returned sequence):

  <input ref="/cart/products/product[1]"><label>...</label></input><html:br/>
  <input ref="/cart/products/product[2]"><label>...</label></input><html:br/>
  <input ref="/cart/products/product[3]"><label>...</label></input><html:br/>
  <input ref="/cart/products/product[4]"><label>...</label></input><html:br/>

The repeat collection can be an arbitrary sequence of items. The items in the repeat collection can be either nodes, atomic values or a mix of them. The nodes in the repeat collection don't have to be in document order, and the same node can occur multiple times in the repeat collection.

<repeat ref="1 to 10">
  <output value="." ...>
     <label>...</label>
  </input>
  <html:br/>
</repeat>

The capture and bubble phases of events dispatched to the run-time objects behave as if the repeat object were a child of element repeat. The repeat template content, including action handlers, is made unavailable to the host language processor. Copies of the repeat template content, including Action handlers, are made available via the repeat objects. Thus, to handle an event targeted at a repeat element, it is necessary to place the action handler outside of the repeat template, as in this example:

<repeat id="X" ... >
        ...
</repeat>

<action ev:event="xforms-scroll-first" ev:target="X" ev:observer="X">
   ...
</action>

XForms Actions insert and delete (see XForms Actions) can be used to directly operate on a repeat collection sequence, and the XPath function index can be used to help focus the behavior of the actions at a point of interest to the user. For example:

<model>
  <instance>
    <my:lines>
      <my:line name="a">
        <my:price>3.00</my:price>
      </my:line>
      <my:line name="b">
        <my:price>32.25</my:price>
      </my:line>
      <my:line name="c">
        <my:price>132.99</my:price>
      </my:line>
    </my:lines>
  </instance>
</model>
  ...
<repeat id="lineset" ref="my:line">
  <input ref="my:price">
    <label>Line Item</label>
  </input>
  <input ref="@name">
    <label>Name</label>
  </input>
</repeat>

<trigger>
  <label>Insert a new Line Item after the current one</label>
  <action ev:event="DOMActivate">
    <insert ref="my:line" at="index('lineset')" position="after"/>
    <setvalue ref="my:line[index('lineset')]/@name"/>
    <setvalue ref="my:line[index('lineset')]/price">0.00</setvalue>
  </action>
</trigger>

<trigger>
  <label>remove current item</label>
  <delete ev:event="DOMActivate" ref="my:line" at="index('lineset')"/>
</trigger>

If the indexref attribute is specified, then it takes precedence over the startindex attribute, whether or not the indexref expression indicates an existing instance node and whether or not the instance node contains an integer value between 0 and the size of the repeat collection. The indexref attribute is evaluated relative to the in-scope evaluation context of the repeat element. The result is interpreted as a node-sequence, and the first node is obtained, if any. It is an xforms-binding-exception if the first node obtained has a child element. A numeric result is calculated. If the indexref evaluation does not produce a first node, then the numeric result is NaN. Otherwise, the content of the first node is converted to a number (possibly NaN). If the numeric result is NaN, then the indexref value is 0 if the repeat collection is empty and 1 otherwise. If the numeric result is not NaN, then the numeric result is rounded to the nearest integer, and the indexref value is the closest integer to the numeric result that is in the range 0 to the size of the repeat collection.

The result of the indexref expression is kept up to date in a manner consistent with user interface bindings. It is an xforms-binding-exception if the expression changes to indicating a node-sequence whose first node has a child element. The indexref value can change due to a change of the value of the node indicated by the indexref expression, or by the expression binding changing, either from one node to another, from not indicating a node to indicating a node, or from indicating a node to not indicating a node. If the indexref value changes, then the repeat index associated with the repeat collection is changed.

Whether during initialization or in response to a change of the indexref value, the new setting for the repeat index may not be equal to the data value in the node indicated by indexref. This can occur if the data value was rounded or if it was coerced to be in the range 0 to the size of the repeat collection. In this circumstance, if the indexref expression indicates a node, the value of the node is not changed.

If the indexref attribute is not specified, then the repeat index is initialized to the closest integer to the value in the startindex attribute, or its default, that is in the range 0 to the size of the repeat collection, and changes to the repeat index can only be made by the setindex action.

If the indexref attribute is specified, then changes to the repeat index can be made by changes to the indexref value as described above, such as by the setvalue action. Changes to the repeat index can also be performed directly by the setindex action, but these are performed by performing a setvalue action if the indexref attribute is specified and indicates a node. If the node is readonly, then no value change occurs and therefore no change of repeat index occurs.

Regardless of how the repeat index value is changed, if the new value was greater than the size of the non-empty repeat collection, then the event xforms-scroll-last is dispatched to the repeating element to indicate that the repeat index value was coerced to the size of the repeat collection. Similarly, if the new value was increased to 1, then xforms-scroll-first is dispatched to the repeat element.

9.3.2 Nested Repeats

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

It is possible to nest repeat elements to create more powerful user interface for editing structured data. Editing Hierarchical Bookmarks Using XForms is an example of a form using nested repeats to edit hierarchical data consisting of bookmarks within multiple sections. Consider the following insert statement that appears as part of that example.

<insert ref="section[index('repeatSections')]/bookmark"
        at="index('repeatBookmarks')"
        position="after"/>

The above insert statement is used in that example to add new bookmark entries into the currently selected section. The inner (nested) repeat operates on bookmarks in this selected section; The index — as returned by XForms function index — for this inner repeat starts at 1. Hence, after a new empty section of bookmarks is created and becomes current, the first insert bookmark operation adds the newly created bookmark at the front of the list.

9.3.3 Repeat Processing

During user interface initialization (see The xforms-model-construct-done Event), the following steps are performed for repeat:

1. The Sequence Binding is evaluated to locate the repeat collection to be operated on by this repeat.
2. The repeat index is initialized.
3. Repeat items are generated with repeat objects each having a user interface as specified by the repeat template for the requisite number of members of the repeat collection as specified by attributes on element repeat.

A new repeat item is created dynamically at any time in the lifecycle of the form (i.e. any time after xforms-model-construct-done) whenever a new item is added to the repeat collection. There are many ways to add new items to a repeat collection, including but not limited to the following:

• An insert action can add one or more nodes that match the repeat sequence;
• The new instance data subtree created by a submission instance replacement may contain nodes that match the repeat sequence;
• A setvalue action or a calculate may change a value that causes one or more items to match the repeat sequence.

Any time a new repeat item is created, XML Event handlers declared within the corresponding repeat object are initialized, and the user interface form controls generated for the repeat object are initialized in the same manner as the user interface initialization that is performed during default processing of xforms-model-construct-done. For example, if the repeat object contains an inner repeat run-time object, then it is initialized according to the list of steps at the beginning of this section (Repeat Processing).

If one or more items have been added to the repeat collection by for example an insert action, then the repeat items corresponding to the new items must be created and initialized, and the repeat index must be updated to indicate the repeat item corresponding to the last item added by the insert.

The repeat item generation and repeat index update on insertion must behave as if it occurs in response to the xforms-insert event dispatched by the insert action. The index update must behave as if it occurs when the xforms-insert event reaches the parent of the target instance element in the capture phase.

A repeat item can also be destroyed dynamically at any time in the lifecycle of the form whenever an item is removed from the repeat collection. When a repeat item is destroyed, the repeat object and all of its inner form controls are eliminated, including inner repeats, switches and groups, and all XML Event handlers created by the repeat object are eliminated. There are many ways to remove repeat items from a repeat collection, including but not limited to the following:

• A delete action can remove items that matched the repeat sequence;
• The new instance data subtree created by a submission instance replacement may replace items that matched the repeat sequence;
• A setvalue action or a calculate may change a value that causes one or more items to stop matching the repeat sequence.

If one or more items have been removed from the repeat collection by a delete action, then the repeat items corresponding to the deleted items must be destroyed and the repeat index must be updated based on the rules below.

1. If, prior to item deletion, the repeat index indicated a repeat item that is still contained in the repeat collection after item deletion, then the index is adjusted, if necessary, to indicate that same repeat item.
2. Otherwise, if all repeat items in the collection have been destroyed, the repeat index is set to 0.
3. Otherwise, if the repeat index was pointing to one of the deleted repeat items, and if the new size of the collection is smaller than the index, the index is changed to the new size of the collection.
4. Otherwise, if the repeat index was pointing to one of the deleted repeat items, and if the new size of the collection is equal to or greater than the index, the index is not changed.

The repeat index update on deletion behaves as if it occurs in response to the xforms-delete event dispatched by the delete action. Specifically, the index update behaves as if it occurs when the xforms-delete event reaches the parent of the target instance element in the capture phase.

9.3.4 User Interface Interaction

Element repeat enables the binding of user interaction to a sequence, referred to as repeat collection. The number of displayed items might be less than the total number available in the collection. In this case, the presentation would render only a portion of the repeat objects at a given time. For example, a graphical user interface might present a scrolling table. The current item indicated by the repeat index should be made available to the user at all times, for example, not allowed to scroll out of view. The XForms Actions enumerated at XForms Actions may be used within event listeners to manipulate the repeat collection being populated by scrolling, inserting, and deleting entries.

Notice that the markup encapsulated by element repeat acts as the template for the user interface that is presented to the user. As a consequence, statically authored IDREF attributes must be interpreted based on a combination of repeat indexes and where the IDREF attributes appear relative to the element bearing the matching ID. Based on the IDREF resolution rules given in Resolving ID References in XForms, it is possible to toggle the case of a switch even when it is within one or more repeat elements. Similarly, it is possible to set the focus to controls and dispatch events to elements that are within one or more repeat elements.

If the focus is transferred to a form control within a repeat by any means, such as by an XForms action or by user interaction, the index of the repeat is updated to indicate the item of the repeat collection that contains the control. If the repeat item containing the focused control contains any inner repeat objects, their indexes are not changed. However, the repeat index update is recursive for all outer repeats that contain the focused control; the index of each outer containing repeat is adjusted appropriately. These changes of repeat index occurs as if by invoking the setindex action.

9.3.5 Creating Repeating Structures Via Attributes

Element repeat enables the creation of user interfaces for populating repeating structures. When using XForms within host languages like XHTML, it is often necessary to create repeating structures within constructs such as table. Thus, one might wish to use element repeat within a table to create the rows of a table, where each row of the table binds to a distinct member of a repeat collection. Since html:table doesn't (and perhaps never will) allow xforms:repeat elements as children, another syntax is needed.

 <table>
   <repeat ref="...">
     <tr>
       <td>...</td>
       ...
     </tr>
   </repeat>
 </table>

More generally, there is a need to integrate repeat behavior into host languages at points where the content model of the host language does not or cannot provide the appropriate extension hooks via modularization. To accommodate this, XForms defines an alternative syntax that is functionally equivalent to the repeat element, using the following global attributes:

xforms:repeat-model
xforms:repeat-bind
xforms:repeat-ref
xforms:repeat-nodeset (deprecated)
xforms:repeat-startindex
xforms:repeat-number
xforms:repeat-indexref

The above attributes are equivalent to the local repeat attributes of the same name, except for the namespace qualifications and the prefix repeat-. A host language can include these attributes in the appropriate places to enable repeating constructs. For example, a version of XHTML might use:

 <table xforms:repeat-ref="...">
   <tr>
     <td><xforms:output ref="..."/></td>
   </tr>
 </table>

Additionally, when using XForms Action setindex, attribute repeat of type idref can point to any element carrying these global repeat attributes. Similarly, when using function index against a repeating structure created via the repeat- attributes, the id of that element can be used as the argument to function index.

9.3.6 The itemset Element

This element allows the creation of dynamic selections within controls select and select1, where the available choices are determined at run-time. The sequence that holds the available choices is specified via the Sequence Binding. Child elements label and value indirectly specify the label and storage values. Notice that the run-time effect of itemset is the same as using element choices with child item elements to statically author the available choices.

For each item of the Sequence Binding, an associated item element is created. XForms Actions appearing in the content of an itemset are created within each item element, and the in-scope evaluation context for these XForms Actions is based on the data item for which the item was generated as described in Section Evaluation Context.

Common Attributes: Common, Sequence Binding

The following example shows element itemset within control select to specify a dynamic list of ice cream flavors:

<model id="cone">
  <instance>
    <my:icecream>
      <my:order/>
    </my:icecream>
  </instance>
</model>
<model id="flavors">
  <instance>
    <my:flavors>
      <my:flavor type="v">
        <my:description>Vanilla</my:description>
      </my:flavor>
      <my:flavor type="s">
        <my:description>Strawberry</my:description>
      </my:flavor>
      <my:flavor type="c">
        <my:description>Chocolate</my:description>
      </my:flavor>
    </my:flavors>
  </instance>
</model>
<select model="cone" ref="my:order">
  <label>Flavors</label>
  <itemset model="flavors" ref="my:flavor">
    <label ref="my:description"/>
    <copy ref="my:description"/>
  </itemset>
</select>

9.3.7 The copy Element

Structurally, this element is similar to The value Element. It differs in that it can only be used within itemset, and that it works with subtrees of instance data rather than simple values.

Common Attributes: Common, Single Item Binding (author-optional)

If the Single Item Binding attributes indicate a node in a model other than the bound item of the containing selection control, then an xforms-binding-exception must occur. When a copy node is selected, the following rules apply:

• The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an exception results (The xforms-binding-exception Event).
• The element node associated with the item, selected by the binding attributes on copy, is deep copied as a child of the target node by using an insert action (The insert Element).
• A full computational dependency rebuild is done, followed by recalculate, revalidate, and refresh.

When a copy item is deselected, the following rules apply:

• The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an exception results (The xforms-binding-exception Event).
• The child element node associated with the item, selected by the binding attributes on copy, is deleted by using a delete action (The delete Element).
• A full computational dependency rebuild, followed by recalculate, revalidate, and refresh.