XForms 1.1

1.1 Reading the Specification

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

This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].

1.2 How the Specification is Organized

The specification is organized as a set of changes relative to [XForms 1.0]. Chapters are arranged by topic.

1.3 Documentation Conventions

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

xforms: The XForms 1.1 namespace (http://www.w3.org/2004/xforms/)
html: The XHTML 2.0 namespace
ev: The XML Events namespace [XML Events]
my: Any user defined namespace

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

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

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

Examples are set off typographically:

Example Item

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

Sample Reference

Reference - linked to from above.

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

2.1 Namespaces for XForms 1.1

The XML Schema definition of XForms 1.1 is available in two forms.

<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">
    <p>Hello <output ref="yourname" />
      <trigger id="editButton">
        <label>Edit</label>
        <toggle ev:event="DOMActivate" case="in"/>
      </trigger>
    </p>
  </case>
</switch>

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

2.2 Utility Functions used in XPath Expressions

power(-1, 0.5)

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

luhn(.)

luhn('123')

<xforms:instance xmlns="">
	<converter>
	       <amount>100</amount>
	       <currency>jpy</currency>
	       <convertedAmount></convertedAmount>
	</converter>
</xforms:instance>

<xforms:instance xmlns="" id="convTable">
	<convTable date="20040212" currency="cdn">
	       <rate currency="eur">0.59376</rate>
	       <rate currency="mxn">8.37597</rate>
	       <rate currency="jpy">80.23451</rate>
	       <rate currency="usd">0.76138</rate>
	</convTable>
</xforms:instance>

<bind nodeset="convertedAmount" 
      calculate="../amount * 
                 instance('convTable')/rate[@currency=current()/../currency]"/>

<xforms:instance xmlns="" id="i1">
	<months>
	       <mon>01</mon>
	       <mon>02</mon>
	       <mon>03</mon>
	</months>
</xforms:instance>
<xforms:instance xmlns="" id="i2">
	<months>
	       <month code="01">Jan</month>
	       <month code="02">Feb</month>
	       <month code="03">Mar</month>
	</months>
</xforms:instance>

<repeat nodeset="mon">
	<output value="instance('i2')/month[@code = current()]/>
</repeat>

property("version")

property("conformance-level")

2.3 Accessing Context Information for Events

node-set event(string)

Function event returns context specific information determined by the string argument. The context information is always returned as an element node with a local name equal to the parameter name and no namespace URI.

Each events will describe what properties can be accessed by this function. The following is a list of the properties accessible with the XForms 1.0 events (these are all of type xsd:string):

description

xforms-insert, xforms-delete

errorinformation

xform-submit-error, xforms-link-exception, xforms-link-error, xforms-compute-exception

Examples:

event("description")

event("errorinformation")

2.4 New Data Type: Email address

XForms provides support for several built-in datatypes, includes datatypes derived by restriction, derived by list, and derived by union from these base types. XForms also defines new derived datatypes that are commonly used in forms. The following text describes a new derived datatype, xforms:email, introduced for XForms 1.1. This datatype represents an email address, as defined by [RFC 2822]. Internationalized email addresses are not restricted by XForms beyond the definition in the RFC. For simplicity, some extremely uncommon features of the RFC syntax are not allowed, such as "Obsolete Addressing" from section 4.4, square-bracketed "domain-literal"s, and insignificant whitespace and comments.

Examples of valid xforms:email addresses

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

Examples of invalid xforms:email addresses

editors@(this is a comment)example.info
editors{at}example{dot}info

<xsd:simpleType name="email">

  <xsd:restriction base="xsd:string">

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

  </xsd:restriction>

</xsd:simpleType>

2.5 New Data Type: ID Card Number

This type defines the basic structure of an ID number that conforms to [ISO 7812-1:2000]. Various ID cards use this standard as the format for their numbers including those issued by Financial Institutions for Debit and Credit cards. The ID number is a pattern restriction on xsd:string: it must be between 12 and 19 digits (0 - 9).

:<xsd:simpleType name="ID-card-number">
    <xsd:annotation>
      <xsd:documentation>
        This type defines an ID number that conforms to ISO/IEC 7812-1:2000  
	       Identification cards -- Identification of issuers -- Part 1: Numbering system. 
	       This type does not apply the Luhn checksum algorithm.
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:string">
      <xsd:minLength value="12"/>
      <xsd:maxLength value="19"/>
      <xsd:pattern value="[0-9]+"/>
    </xsd:restriction>
  </xsd: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 XPath function luhn() should be used to validate that the ID number conforms to the specification.

<xforms:model>
  <xforms:instance>
    <payment method="cc" xmlns="http://commerce.example.com/payment">
      <number/>
      <expiry/>
    </payment>
  </xforms:instance>
  <xforms:bind nodeset="number" type="xforms:ID-card-number" constraint="luhn(.)"/>
</xforms:model>

3.1 The duplicate Action Element

This action is used to clone and insert a subtree from one place in an instance to another place in an instance.

Common attributes: Common, Events, Single Node Binding

Special attributes:

origin

Required XPath expression to determine where to get the structure to clone from.

before

Optional XPath expresison to determine where to insert the node

The rules for duplicate processing are as follows:

1. The structure to be cloned is determined by evaluating the node-set from the origin attribute with the same context used for the single node binding.

2. The first node in document order is selected from the origin node-set. If the node-set is empty or the first node is either the root node or a namespace node, then the action has no effect.

3. The selected node for cloning is now cloned as is defined by the metode cloneNode in DOM Level 2 API. This will be the cloned subtree.

4. The node which will get the cloned subtree as a child or attribute is determined by the Single Node Binding attributes, this will be the parent node. If the parent node is not a root node or an element node then the action has no effect.

5. If the before attribute is present it is evaluated to determine where to place the cloned subtree. The first node in document order is selected from the before node-set and will be the before node. If that node is not a child of the parent node, then this action has no effect.

6. The cloned subtree is now inserted into the instance by the following rules:

   • If the parent node is an element and the cloned subtree an attribute then it will be inserted as an attribute of the parent node. If the parent node has an attribute with the same local name and namespace URI then that attribute is replaced.

     Otherwise

     If there was no before attribute or if it evaluated to an empty node-set, then the cloned node is appended to the parent node's children.

     Otherwise

     The cloned subtree is added as a child of the parent node in such a way that the previous sibling of the before node is the top element of the cloned subtree.

   If the insertion will make an instance that is not well-formed then this action must not have any effect.

7. If a node was successful inserted into the instance an xforms-duplicate event is dispatched.

	<xforms:instance id="dest">
	  <persons xmlns=""/>
	</xforms:instance>
	<xforms:instance id="proto">
	  <person xmlns="">
	       <name>David Landwehr</name>
	  </person>
	</xforms:instance>
	
	<xforms:trigger>
	  <xforms:label>Create new person</xforms:label>
	  <xforms:duplicate ref="instance('dest')" 
	                       origin="instance('proto')"
	                       ev:event="DOMActivate"/>
	</xforms:trigger>
	

        <xforms:instance id="dest">
          <persons xmlns="">
                <person>
                  <name>Roland Merrick</name>
                </person>
          </persons>
        </xforms:instance>
        <xforms:instance id="proto">
          <person xmlns="">
                <name>David Landwehr</name>
          </person>
        </xforms:instance>
        
        <xforms:trigger>
          <xforms:label>Create new person as a first child</xforms:label>
          <xforms:duplicate ref="instance('dest')" 
                                origin="instance('proto')" 
                                before="*[1]" 
                                ev:event="DOMActivate"/>
        </xforms:trigger>
        

        <xforms:instance id="dest">
          <persons xmlns="">
                <person>
                  <name>David Landwehr</name>
                </person>
          </persons>
        </xforms:instance>
        <xforms:instance id="proto">
          <attibutes xmlns="" gender="male"/>
        </xforms:instance>
        
        <xforms:trigger>
          <xforms:label>Insert a gender attribute</xforms:label>
          <xforms:duplicate ref="instance('dest')/person" 
                                origin="instance('proto')/@gender" 
                                ev:event="DOMActivate"/>
        </xforms:trigger>
        

3.2 The destroy Action Element

The destroy action is used to delete a node from the instance.

Common attributes: Common, Events, Single Node Binding

This action is used to remove nodes from the instance.

The rules for destroy processing are as follows:

1. The node to delete is selected from the Single Node Binding attributes.

2. If the node is a root node or a namespace node then the action has no effect otherwise the node is removed from the instance.

3. If a node was successful removed from the instance an xforms-destroy event is dispatched.

<xforms:instance>
  <data xmlns=""><element>Value</element></data>
</xforms:instance>
<xforms:bind nodeset="element" id="element"/>
<xforms:trigger>
  <xforms:label>Delete element</xforms:label>
  <xforms:destroy ev:event="DOMActivate" bind="element"/>
</xforms:trigger>

<xforms:instance>
  <data xmlns="" attr="Value"/>
</xforms:instance>
<xforms:trigger>
  <xforms:label>Delete attribute</xforms:label>
  <xforms:destroy ev:event="DOMActivate" ref="@attr"/>
</xforms:trigger>

3.3 The close Action Element

This action is used to dispatch an xforms-close event to a model.

Common attributes: Common, Events

Special attributes: None

Dispatches an xforms-close event to the default model.

        <trigger>
          <close ev:event="DOMActivate"/>
        </trigger>
        

3.4 Modifications to the insert and delete Actions

In XForms 1.1, the insert action behaves as in XForms 1.0 except that the prototype for the instance data to be inserted is obtained from the live instance DOM rather than from initialization instance data. Specifically, the source of the prototype is obtained by evaluating the nodeset against the current instance DOM, then choosing the node indicated by the attribute at.

In XForms 1.0, the delete action has no effect if the homogeneous collection indicated by the nodeset attribute is empty. In XForms 1.1, the delete action also has no effect if the homogeneous collection contains only one node. This restriction is necessary because an homogeneous collection that becomes empty no longer has prototypical data needed to perform future insert actions.

It is recommended that form authors precede a delete action with setvalue actions that clear the data to empty values so that deleting the only member of an homogeneous collection appears to the end-user as if the member has been cleared. Alternately, it is recommended that form authors use the duplicate and destroy actions to manipulate homogeneous collections.

3.5 Modifications to Deferred Update Behavior of Actions

TBD

In XForms 1.0, the deferred update behavior would choose to run rebuild, recalculate, revalidate and refresh actions directly, bypassing the event system. In XForms 1.1, the events are dispatched as needed.

The detection of the need for deferred update is managed at the level of the XForms model. When XForms action B runs as the result of another XForms action A, then the deferred update behavior of B is further deferred to the completion of A, regardless of whether B is a descendant of A in the XML markup.

4.1 Improved Targetting of Returned Data

In XForms 1.0, the target of XML data returned by a submission with replace="instance" was the same from which the instance was drawn. We now want the returned XML data to be able to be placed in an alternate instance. The submission element must allow a new optional attribute called instance of type IDREF. If given, this attribute indicates the instance to be replaced with the XML data returned from the submission.

An anticipated use of this attribute is to target a returned SOAP envelope at a scratch instance. The form author can then catch the xforms-submit-done event and use XForms actions to copy the underlying payload to one or more data instance nodes.

4.2 New Submission Events

4.3 New Submission Attributes

4.4 Integration with SOAP

5.1 Inline Rendition of Non-Text Media Types

In XForms 1.0, the output element can take a single node binding indicating an instance node whose textual content is to be rendered inline. In XForms 1.1, the content model of the output element is enhanced to allow the specification of a mediatype attribute or a mediatype child element.

The mediatype attribute and mediatype child element are ignored unless the output has a single node binding that resolves to an instance node with non-empty content.

When both the mediatype attribute and the mediatype element are given, the attribute takes precedence. When the mediatype element has both content and a single node binding, the single node binding takes precedence. When neither the mediatype attribute nor the mediatype element are given, the output behaves as in XForms 1.0, rendering inline the text content of an identified instance node.

The mediatype attribute or element indicates the desired type of media rendition that should be performed if it is possible to do so (e.g. a voice-only device cannot render a digital image). The desired rendition type is indicated by a string value, such as image/* or image/png, in the mediatype attribute value, the content of the node referenced by the mediatype element, or the mediatype element content.

If the mediatype attribute or element is given, then the instance node indicated by the single node binding must be decoded or dereferenced prior to rendition based on schema or XForms data type. An instance node of type xsd:base64Binary or xsd:hexBinary is decoded, and an instance node of type xsd:anyURI is dereferenced.

The rendition of the output is updated if the referenced node or its content or if the media type changes. The media type can change due to DOM mutation of the content of the mediatype attribute or element or by a change to the mediatype element's referenced node or its 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 for many reasons, including

• Data incorrectly identified as xsd:base64Binary or xsd:hexBinary

• An xforms-link-error dereferencing a node of type xsd:anyURI

• A data format error (e.g. invalid or unsupported image format)

• An unrecognized media type identifier string

5.2 Add UI Common to output

In XForms 1.0, an output can have an optional label. In XForms 1.1, the content model for output is change to include (UI Common)* so that help, hint, alert and XForms action elements can also appear as children of an output.

5.3 Remove Linking Attributes from Actions and Metadata Elements

In order to better encapsulate and separate the behavior of an XForms processor from that of a host language processor, the src attribute is not available to XForms 1.1 message, label, help, hint, alert elements.

6.1 XForms Model

TBD

6.2 XForms Namespace

XForms elements may be used in the namespace declared in this specification. However, the XForms namespace is designed to be a chameleon namespace that allows XForms elements to be imported into a host language. Therefore, an XForms processor should allow parameterization of the namespace URI. Any element with a local name of an elements defined by XForms would then be recognized for XForms processing if the element's namespace URI also matched the URI parameter provided to the XForms processor.

6.3 Incompatibilities between XForms 1.0 and XForms 1.1

While many XForms 1.0 forms will operate as originally intended when migrated to an XForms 1.1 processor by simply redefining the xforms prefix to be the namespace URI of XForms 1.1, there are some behavioral changes that have been made to elements and features that existed in XForms 1.0. Therefore, some XForms 1.0 forms will require some adjustments beyond simply changing the namespace URI.