W3C

XForms 1.1

W3C Working Draft 03 November 2006

This version:
http://www.w3.org/TR/2006/WD-xforms11-20061103/
Latest version:
http://www.w3.org/TR/xforms11/
Previous version:
http://www.w3.org/TR/2006/WD-xforms11-20060714/
Editor:
John M. Boyer, IBM

This document is also available in these non-normative formats: diff-marked HTML.


Abstract

XForms 1.1 refines the XML processing platform introduced by XForms 1.0 by adding several submission capabilities, a more powerful action processing facility, the ability to manipulate data arbitrarily and to access event context information, and by adding numerous helpful data types, utility functions, user interface improvements, and action event handlers.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a Working Draft of the W3C. This document has been produced by the W3C Forms Working Group as part of the Forms Activity within the W3C Interaction Domain. The authors of this document are the Forms Working Group participants.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Comments on this document are welcome. Please send them to the public mailing list www-forms-editor@w3.org. (archive). It is inappropriate to send discussion email to this address.

This document is governed by the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1 Introduction
    1.1 Reading the Specification
    1.2 How the Specification is Organized
    1.3 Documentation Conventions
2 XForms Core
    2.1 Version Control in XForms Processors
        2.1.1 The xforms-version-exception Event
    2.2 Namespaces for XForms 1.1
        2.2.1 No-namespace schema for XForms 1.1
        2.2.2 Namespaced schema for XForms 1.1
    2.3 Remove Linking Attributes from XForms
    2.4 Utility Functions used in XPath Expressions
        2.4.1 The power() Function
        2.4.2 The luhn() Function
        2.4.3 The current() Function
        2.4.4 The choose() Function
        2.4.5 The id() Function
        2.4.6 The property() Function
        2.4.7 The days-to-date() Function
        2.4.8 The seconds-to-dateTime() Function
        2.4.9 The local-date() Function
        2.4.10 The local-dateTime() Function
        2.4.11 The encode() Function
        2.4.12 The decode() Function
        2.4.13 The digest() Function
        2.4.14 The hmac() Function
        2.4.15 The random() Function
        2.4.16 Modification to Exceptions Generated by Errors in Functions
    2.5 Accessing Context Information for Events
        2.5.1 The xforms-insert Event
        2.5.2 The xforms-delete Event
        2.5.3 The xforms-submit-error Event
        2.5.4 The xforms-submit-done Event
        2.5.5 The xforms-link-exception Event
        2.5.6 The xforms-link-error Event
        2.5.7 The xforms-compute-exception Event
    2.6 New Data Type: Email address
    2.7 New Data Type: ID Card Number
    2.8 XForms Datatypes to Allow Empty Content
    2.9 The value Element
    2.10 Resolving ID References in XForms
        2.10.1 References to Elements within a repeat Element
        2.10.2 References to Elements within a bind Element
3 Actions
    3.1 Modifications to the insert and delete Actions
        3.1.1 The insert Action
        3.1.2 The delete Action
    3.2 The load Action
    3.3 The control Element Child of the setfocus Element
    3.4 The case Element Child of the toggle Element
    3.5 Improvements to the dispatch Action
        3.5.1 The name and target Child Elements
        3.5.2 Delayed Event Dispatching
    3.6 The messsage Action
    3.7 The close Action Element
        3.7.1 The xforms-close Event
    3.8 The prompt Action Element
    3.9 Conditional Execution of XForms Actions
    3.10 Iteration of XForms Actions
    3.11 Modifications to Deferred Update Behavior of Actions
4 Submission
    4.1 New and Revised Submission Attributes
        4.1.1 The validate Attribute on Element submission
        4.1.2 The relevant Attribute on Element submission
        4.1.3 The serialize Attribute on Element submission
        4.1.4 The mode Attribute on Element submission
        4.1.5 Replacing Text with a Submission Response
        4.1.6 The target Attribute on Element submission
        4.1.7 The delete submission method
    4.2 The resource Element and Attribute
    4.3 Submission verb Attribute and Element
        4.3.1 The verb Attribute
        4.3.2 The verb Element
    4.4 The header Element
        4.4.1 The name Element
        4.4.2 The value Element
    4.5 New Submission Events
        4.5.1 The xforms-submit-serialize Event
    4.6 Changed Submission Events
        4.6.1 The xforms-submit Event
    4.7 Submission Options
    4.8 The get Submit Method
    4.9 Integration with SOAP
        4.9.1 Representation of SOAP Envelope
        4.9.2 Indicating a SOAP submission
        4.9.3 SOAP HTTP Binding
        4.9.4 Handling the SOAP Response
5 User Interface Improvements and Changes
    5.1 Inline Rendition of Media Types Other than Plain Text
        5.1.1 The xforms-output-error Event
    5.2 Add UI Common to output
    5.3 Appearance Hint for Triggers
    5.4 Support switch in repeat
6 Conformance
    6.1 XForms Model
    6.2 XForms User Interface
    6.3 XForms Namespace
    6.4 Incompatibilities between XForms 1.0 and XForms 1.1

Appendices

A Schema for XForms 1.1
B References
    B.1 Normative References
    B.2 Informative References
C Acknowledgements (Non-Normative)


1 Introduction

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/2002/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: Example item
Example Item

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

Sample Reference
Reference - linked to from above.

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

Note:

A gentle explanation to readers.

Editorial note: Editorial Note Name 
Editorial commentary, not intended for final publication.

Issue (sample-implementation-issue):

Issue-Name

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

Resolution:

None recorded.

2 XForms Core

2.1 Version Control in XForms Processors

In XForms 1.1, the model element supports an optional attribute called version.

Default value: 1.0

Legal values: "1.0", "1.1"

A non-legal value for the version attribute is handled as if the default value were specified.

The version setting used by an XForms processor must be obtained from the default model, which is the first model in document order.

If the XForms processor does not support behaviors of the language version indicated by the version setting, then the XForms processor must terminate processing after dispatching xforms-version-exception.

2.1.1 The xforms-version-exception Event

Target: the default model

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
errorinformationstringAn implementation-specific error string
Example: Handler for xforms-version-exception
<model>
  <message level="modal" ev:event="xforms-version-exception" ref="event('errorinformation')"/>
  ...
</model>

Since the version attribute is not specified on the model, the default of 1.0 is used, so the message action is performed if the XForms processor does not support 1.0-specific behaviors in its processing of the XForms vocabulary.

Default Action: Fatal error.

2.2 Namespaces for XForms 1.1

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

2.2.1 No-namespace schema for XForms 1.1

XForms 1.1 includes a schema with no target namespace which allows XForms to be incorporated into another namespace using the XML Schema include facility. This kind of schema is sometimes referred to as a Chameleon schema.

Example: XForms 1.1 "included" in XHTML 2
<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>

This example is a redefinition of one provided in the XForms 1.0 Recommendation. In XForms 1.0 the <p> element would have required a namespace prefix to indicate that is comes from the XHTML namespace.

2.2.2 Namespaced schema for XForms 1.1

XForms 1.1 also includes a schema which has a target namespace specified and as such is compatible with the XForms 1.0 definition. This schema includes all of the no-namespace schema and assigns is a target namespace of http://www.w3.org/2002/xforms

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

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

2.3 Remove Linking Attributes from XForms

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 elements, including instance, message, label, help, hint, and alert.

Note:

A host language may make available an attribute with behavior similar to the HTML src attribute, but if so, then content associated with the URI given by the attribute is obtained according to a schedule defined by the host language.

For element instance, XForms 1.1 provides a new optional attribute resource that provides an xsd:anyURI link to externally defined initial instance data. The link is traversed during xforms-model-construct if the instance contains no inline XML data. If the link traversal fails, it is treated as an xforms-link-exception. The resource attribute is ignored if the instance contains XML data when the instance is initialized during xforms-model-construct.

2.4 Utility Functions used in XPath Expressions

2.4.1 The power() Function

number power(number, number)

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

Examples:

power(-1, 0.5)

returns NaN.

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

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

2.4.2 The luhn() Function

boolean luhn(string?)

If the string parameter conforms to the pattern restriction of the xforms:ID-card-number type, then this function applies the luhn formula described in [ISO 7812-1:2000] and returns true if the number satisfies the formula. Otherwise, false is returned. If the parameter is omitted, it defaults to the string-value of the current context node.

Examples (see also 2.7 New Data Type: ID Card Number):

luhn(.)

returns true if and only if the context node contains a string that contains 12 to 19 digits and satisfies the formula.

luhn('4111-1111-1111-1111')

returns true. Other examples of string constants that will return true are : 5431-1111-1111-1111, 341-1111-1111-1111 and 6011-6011-6011-6611.

luhn('123')

returns false.

2.4.3 The current() Function

node-set current()

Returns the context node used to initialize the evaluation of the containing XPath expression.

Examples:

For the following instance data:

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

and the following value calculation bind:

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

the content value of /converter/convertedAmount is the product of /converter/amount and the conversion table rate given by the rate element whose currency attribute value matches the content of /converter/currency.

For the following instance data:

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

and the following repeat structure:

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

the output should contain Jan Feb Mar.

2.4.4 The choose() Function

object choose(boolean, object, object)

If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. If the types of the two object parameters are not the same (e.g. one node-set and the other a string), then the type of the object returned is determined by rationalizing the types of the two object parameters in the same manner as XPath comparison.

Example:

choose(count(x) > 0, x, y)

Returns the node-set of matching x if it is non-empty and the node-set matching y otherwise.

2.4.5 The id() Function

node-set id(object, node-set?)

The object parameter provides one or more IDREFs. This may be in the form of a string containing a space-separated list of IDREFs or a node-set, each node of which contains an IDREF. The node-set parameter provides nodes in one or more documents to be searched. If the node-set parameter is not given or is empty, then the document to be searched is the one containing the context node of the function call. For each node in the node-set parameter (or its default), the set of element nodes are collected with IDs that match the IDREFs from the object parameter. The result of this function is a node-set containing the union of the collected element nodes from each string. An element node can be assigned an ID by means of an xml:id attribute or an attribute that is assigned the type ID by a DTD or xsd:ID by an XML schema.

Editorial note 
The means of associating an ID with a node seems incomplete. Does the XForms type MIP also apply such that an element would be returned if it contains an attribute with a matching ID and the XForms type has assigned the xsd:ID type to that attribute? Perhaps more of an edge case, but what would it mean if an xsd:ID type were assigned directly to the element's content by an xsi:type attribute or a schema? Should the element be returned if it contains the matching ID? Finally, do XML schema types derived from xsd:ID count?

Example:

id('X Y', instance('Z'))

Returns nodes identified by X or Y from the XML document in the instance identified by Z.

2.4.6 The property() Function

string property(string)

This function accepts a string identifying a property name. If the property name is not recognized, empty string is returned. The property definitions for this function are as follows:

PropertyReturn Value
version1.1
conformance-levelfull, basic or a string beginning with full or basic
Any other NCNAMEReserved. Their use results in an xforms-compute-exception
QNameButNotNCNAMEAn implementation-specific property value, such as a locale or timezone for the user agent. If the implementation does not support the property, then empty string is returned.

Examples:

property('version')

returns 1.1

property('conformance-level')

may return full

2.4.7 The days-to-date() Function

string days-to-date(number)

This function returns a string containing a lexical xsd:date that corresponds to the number of days passed as the parameter according to the following rules:

The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and 1970-01-01. An input parameter value of NaN results in output of the empty string.

Examples:

days-to-date(11688)

returns 2002-01-01

days-to-date(-1)

returns 1969-12-31

2.4.8 The seconds-to-dateTime() Function

string seconds-to-dateTime(number)

This function returns string containing a lexical xsd:dateTime that corresponds to the number of seconds passed as the parameter according to the following rules:

The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired dateTime and 1970-01-01T00:00:00Z. An input parameter value of NaN results in output of the empty string.

Example:

seconds-to-dateTime(0)

returns 1970-01-01T00:00:00Z

2.4.9 The local-date() Function

string local-date()

This function returns a lexical xsd:date obtained as if by the following rules: the result of now() is converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion of the result of now() is returned. In either case, the time zone is omitted from the return result.

Example:

local-date()

could return 2006-10-13

2.4.10 The local-dateTime() Function

string local-dateTime()

This function returns a lexical xsd:dateTime obtained as if by the following rules: the result of now() is converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result of now() is returned.

Example:

local-dateTime()

could return 2006-10-13T16:04:17-07:00

2.4.11 The encode() Function

string encode(string, string?)

This function accepts a string of data and an optional string indicating an encoding method. The data string is serialized as UTF-8, and the result is encoded by the indicated method and returned by the function. This recommendation defines the values hex and base64 for the second string parameter that indicates the encoding method. If the parameter is missing, then the default is base64. The hex and base64 encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary and base64Binary, respectively. Any other string value given for the encoding method results in an xforms-compute-exception.

Example:

encode('abc', 'hex')

returns 616263

2.4.12 The decode() Function

string decode(string, string?)

This function accepts a string of data and an optional string indicating the encoding of the data. This recommendation defines the values hex and base64 for the second string parameter that indicates the data encoding. If the parameter is missing, then the default is base64. The hex and base64 encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary and base64Binary, respectively. Any other string value given for the encoding method results in an xforms-compute-exception.

The data is base64 or hex decoded. An xforms-compute-exception occurs if the data violates any base64 or hex encoding rules, such as containing invalid characters for the encoding. If the decoding succeeds, the result is interpreted as a UTF-8 serialization, and it is converted to an XPath string.If the decoded data is found to violate the UTF-8 encoding rules, then an empty string is returned. Otherwise, the XPath string result is returned.

Examples:

decode('616263', 'hex')

returns abc

decode('abcdefg', 'hex')

results in xforms-compute-exception due to odd length of data and invalid character in data

2.4.13 The digest() Function

string digest(string, string, string?)

This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:

KeywordsHash AlgorithmStatus
md5, MD5The MD5 hash algorithm defined in [MD5]Required
sha1, sha-1, SHA1, SHA-1The SHA-1 hash algorithm defined in [SHA2] Required
sha256, sha-256, SHA256, SHA-256The SHA-256 hash algorithm defined in [SHA2]Required
sha384, sha-384, SHA384, SHA-384The SHA-384 hash algorithm defined in [SHA2]Optional
sha512, sha-512, SHA512, SHA-512The SHA-512 hash algorithm defined in [SHA2]Optional
Any other NCNAMEReserved. Their use results in an xforms-compute-exceptionRequired
QNameButNotNCNAMEAn implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an xforms-compute-exception occurs.Required

This recommendation defines the values hex and base64 for the third string parameter that indicates the encoding method. If the parameter is missing, then the default is base64. The hex and base64 encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary and base64Binary, respectively. Any other string value given for the encoding method results in an xforms-compute-exception.

hash-encode('abc', 'sha1', 'hex')

returns a9993e364706816aba3e25717850c26c9cd0d89d.

hash-encode('abc', 'md5', 'hex')

returns 900150983cd24fb0d6963f7d28e17f72.

hash-encode('abc', 'sha256', 'hex')

returns ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

2.4.14 The hmac() Function

string hmac(string, string, string, string?)

This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in [HMAC] and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.

The following table presents the keywords for the third string parameter and the corresponding hash algorithms:

KeywordsHash AlgorithmStatus
md5The MD5 hash algorithm defined in [MD5]Required
sha1, sha-1, SHA1, SHA-1The SHA-1 hash algorithm defined in [SHA2] Required
sha256, sha-256, SHA256, SHA-256The SHA-256 hash algorithm defined in [SHA2]Required
sha384, sha-384, SHA384, SHA-384The SHA-384 hash algorithm defined in [SHA2]Optional
sha512, sha-512, SHA512, SHA-512The SHA-512 hash algorithm defined in [SHA2]Optional
Any other NCNAMEReserved. Their use results in an xforms-compute-exceptionRequired
QNameButNotNCNAMEAn implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an xforms-compute-exception occurs.Required

This recommendation defines the values hex and base64 for the fourth string parameter that indicates the encoding method. If the parameter is missing, then the default is base64. The hex and base64 encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary and base64Binary, respectively. Any other string value given for the encoding method results in an xforms-compute-exception.

2.4.15 The random() Function

number random(boolean?)

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

Example:

random()

could return 0.14159265358979

2.4.16 Modification to Exceptions Generated by Errors in Functions

The boolean-from-string() function returns false when its string parameter does not match a case-insensitive comparison to the valid lexical values for an xsd:boolean, rather than halting processing with an xforms-compute-exception event.

When an error occurs in an XPath function, an xforms-compute-exception occurs only if the function appears in the expression of a model item property. When an error occurs in a function that appears in any other XForms attribute that contains an XPath expression, such as nodeset, ref or at, then an xforms-binding exception occurs.

2.5 Accessing Context Information for Events

object event(string)

Function event returns context specific information determined by the string argument. The returned context information is an XPath object whose type and content depends upon the requested property. Each event describes what properties can be accessed by this function and the type and value that will be returned as the result.

Some properties defined for an event may be unavailable if certain prerequisite conditions were not met prior to the event being dispatched. Implementations may also add custom properties. If the event context information does not contain the property indicated by the string argument, then an empty node-set is returned.

Examples:

event('description')

If called from an xforms-insert event handler, a string is returned containing the XPath expression used by the insert action.

event("errorinformation")

If called from an xforms-link-exception event handler, a string is returned containing the URI that failed to load.

The properties of new XForms 1.1 events are described in the appropriate sections of this specification. The following is a list of the properties accessible with the XForms 1.0 events:

2.5.1 The xforms-insert Event

Dispatched in response to: Successful insertion of a node by an XForms insert action.

Target: instance

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
bindingstringThe attribute value of the insert action's nodeset or bind attribute.
inserted-nodenode-setThe instance data node inserted.
origin-nodenode-setThe instance data node referenced by the insert action's origin attribute if present, or the empty nodeset if not present.
insert-locationnumberThe insert location as defined by the insert action.
positionstringThe insert position, before or after.

Default Action: None; notification event only.

2.5.2 The xforms-delete Event

Dispatched in response to: Successful deletion of a node by an XForms delete action.

Target: instance

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
bindingstringThe attribute value of the delete action's nodeset or bind attribute.
parent-nodenode-setThe parent of the instance data node deleted.
delete-locationnumberThe delete location as defined by the delete action.

Default Action: None; notification event only.

2.5.3 The xforms-submit-error Event

Dispatched as an indication of: failure of a submission process

Target: submission

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
error-typestringOne of the following: submission-in-progress, no-data, validation-error, parse-error, resource-error , target-error.
resource-uristringThe submission resource URI that failed (xsd:anyURI)
response-status-codenumberThe protocol return code of the error response, or NaN if the failed submission did not receive an error response.
response-headersnode-setZero or more elements, each one representing a content header in the error response received by a failed submission. The returned node-set is empty if the failed submission did not receive an error response or if there were no headers. Each element has a local name of header with no namespace URI and two child elements, name and value, whose string contents are the name and value of the header, respectively.
response-reason-phrasestringThe protocol response reason phrase of the error response. The string is empty if the failed submission did not receive an error response or if the error response did not contain a reason phrase.
response-bodyobject (string or node-set) When the error response specifies an XML media type as defined by [RFC 3023], the response body is parsed into an XML document and the root element of the document is returned. If the parse fails, or if the error response specifies a text media type (starting with text/), then the response body is returned as a string. Otherwise, an empty string is returned.

Default Action: None; notification event only.

2.5.4 The xforms-submit-done Event

Dispatched as an indication of: successful completion of a submission process

Target: submission

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
resource-uristringThe submission resource URI that succeeded (xsd:anyURI)
response-status-codenumberThe protocol return code of the success response, or NaN if the submission did not receive an error response.
response-headersnode-setZero or more elements, each one representing a content header in the success response received by the submission. The returned node-set is empty if the submission did not receive a response or if there were no headers. Each element has a local name of header with no namespace URI and two child elements, name and value, whose string contents are the name and value of the header, respectively.
response-reason-phrasestringThe protocol response reason phrase of the success response. The string is empty if the submission did not receive a response or if the response did not contain a reason phrase.

Default Action: None; notification event only.

2.5.5 The xforms-link-exception Event

Dispatched as an indication of: a failure in link traversal of a linking attribute.

Target: model

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
resource-uristringThe URI that failed to load (xsd:anyURI)

Default Action: Fatal error.

2.5.6 The xforms-link-error Event

Dispatched as an indication of: a failure in link traversal in a situation not critical to form processing.

Target: model

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
resource-uristringThe URI that failed to load (xsd:anyURI)

Default Action: None; notification event only.

2.5.7 The xforms-compute-exception Event

Dispatched as an indication of: an error occurring during XPath evaluation.

Target: model

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
error-messagestringAn implementation-specific string that shoudl contain the expression being processed when the exception was detected.

Default Action: Fatal error.

2.6 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

Note:

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

Note:

To be added to the Schema for XForms 1.1--the following datatype:

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

The following text is only for discussion in the Working Group, and will be removed before first publication of this document. Since regular expressions aren't a programming language, there's no way to define a common recurring segment, and the regular expression tends to get a little repetitive. Taken one step at a time, however, it makes perfect sense.

The main achievement in this lengthy statement is the definition of what the email address specification calls "atext", which is defined alpha characters, digits, or one of the following characters: "!" "#" "$" "%" "&" "'" "*" "+" "-" "/" "=" "?" "^" "_" "`" "{" "|" "}" "~" In regular expression syntax, the definition for a single character of atext looks like this: [A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~] . If regular expressions had a way to define a commonly-recurring string, the regular expression might look like this (with spaces added for readability): atext+ (\. atext+)* @ atext+ (\. atext+)* But alas, the actual regular expression needs to repeat the full definition of atext four times, yielding the full definition of the email datatype.

2.7 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).

Example: xforms:ID-card-number type definition
:<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.

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

This example specifies that the element number is of the type ID-card-number and that to be valid the luhn function must evaluate to true indicating that check digit is valid.

2.8 XForms Datatypes to Allow Empty Content

Many default XML schema types report empty content as invalid. The following XForms datatypes are defined to allow either empty content or the content allowed by the corresponding XML schema datatype. XForms Processors must treat the datatypes listed in the section as in-scope without requiring the inclusion of an XML Schema.

Built-in primitive types:

xforms:dateTime
xforms:time
xforms:date
xforms:gYearMonth
xforms:gYear
xforms:gMonthDay
xforms:gDay
xforms:gMonth
xforms:string
xforms:boolean
xforms:base64Binary
xforms:hexBinary
xforms:float
xforms:decimal
xforms:double
xforms:anyURI
xforms:QName

Built-in derived types:

normalizedString
token
language
Name
NCName
ID
IDREF
IDREFS
NMTOKEN
NMTOKENS
xforms:integer
xforms:nonPositiveInteger
xforms:negativeInteger
xforms:long
xforms:int
xforms:short
xforms:byte
xforms:nonNegativeInteger
xforms:unsignedLong
xforms:unsignedInt
xforms:unsignedShort
xforms:unsignedByte
xforms:positiveInteger

Note:

Some of the corresponding XML schema datatypes do allow empty content, but the matching XForms datatypes are defined anyway for convenience so that form authors can uniformly use the XForms-defined datatypes.

2.9 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 node binding expression, if specified

  2. the result of evaluating an XPath expression appearing in attribute value, if specified

  3. the inline content of the value element (when neither the single node binding nor the value attribute are expressed).

Common Attributes: Common, Single Node Binding (optional)

Special Attributes:

value

An XPath 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 node binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the single node binding.

Data Binding Restriction: All lexical values must be valid according to the datatype bound to the selection control.

2.10 Resolving ID References in XForms

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

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

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

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

2.10.1 References to Elements within a repeat Element

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

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

2.10.2 References to Elements within a bind Element

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

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

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

3 Actions

3.1 Modifications to the insert and delete Actions

XForms 1.1 enhances the insert and delete actions so that they are more generally applicable to instance node duplication and destruction, and so that they can be used more effectively with an homogeneous collection that become empty.

3.1.1 The insert Action

The insert action is used to create a new node of instance data by cloning an existing instance node. Attributes of action insert specify the node to be cloned and the location within instance data where the clone will appear. The clone is a deep copy of the original node except the contents of nodes of type xsd:ID are modified to remain as unique values in the instance data after the clone is inserted.

Common Attributes: Common (optional), Events (optional), Node Set Binding (required)

If the bind attribute appears, it provides the insert context. If the model attribute is given and indicates a model different than the one containing the in-scope evaluation context node, then the in-scope evaluation context is changed prior to evaluation of the Special Attributes of the insert element. The size and position are changed to 1, and the node is changed to the document element node of the default instance of the indicated model.

Special Attributes:

context

Optional XPath expression used to change the in-scope evaluation context for the insert element. This attribute is ignored if the bind attribute is provided. If the context attribute is not given, then the default insert context is the in-scope evaluation context. Otherwise, the XPath expression is evaluated using the in-scope evaluation context, and the first node rule is applied to obtain the insert context. The insert action is terminated with no effect if the insert context is the empty node-set or if the context attribute is not given and the Node Set Binding node-set is empty.

origin

Optional XPath expression indicating the node to be cloned. If the attribute is not given and the Node Set Binding node-set is empty, then the insert action is terminated with no effect. Otherwise, if this attribute is not given, then the last node of the Node Set Binding node-set is cloned. If the attribute is given, it is evaluated in the insert context using the first node rule. If the result is a node, then it is cloned, and otherwise the insert action is terminated with no effect.

at

Optional XPath expression evaluated to determine the insert location within the Node Set Binding node-set. If the Node Set Binding node-set is empty, then this attribute is ignored. If the attribute is not given, then the default is the size of the Node Set Binding node-set. Otherwise, the insert location is determined from this attribute as follows:

  1. The evaluation context node is the first node in document order from the Node Set Binding node-set, the context size is the size of the Node Set Binding node-set, and the context position is 1.

  2. The return value is processed according to the rules of the XPath function round(). For example, the literal 1.5 becomes 2, and the literal 'string' becomes NaN.

  3. If the result is in the range 1 to the Node Set Binding node-set size, then the insert location is equal to the result. If the result is non-positive, then the insert location is 1. Otherwise, the result is NaN or exceeds the Node Set Binding node-set size, so the insert location is the Node Set Binding node-set size.

The insert location node is the node in the Node Set Binding node-set at the position given by the insert location.

position

Optional selector that indicates where to put the cloned node relative to the insert location. Valid values are before and after, and the latter is the default. This attribute is ignored if the Node Set Binding node-set is empty. If the node at the insert location within the Node Set Binding node-set is the document element of an instance, then this attribute is ignored.

Provided the insert action has not been terminated due to the conditions stated above, the processing rules for the insert action are as follows:

  1. The target location of the insertion for the cloned node is determined as follows:

    1. If the Node Set Binding node-set is empty, then the target location is before the first child or attribute of the insert context node, based on the node type of the cloned node.

    2. If the node type of the cloned node does not match the node type of the insert location node, then the target location is before the first child or attribute of the insert location node node, based on the node type of the cloned node.

    3. If the Node Set Binding node-set and insert location indicate the root element of an instance, then that instance root element location is the target location.

    4. Otherwise, the target location is immediately before or after the insert location node, based on the position attribute setting or its default.

  2. The cloned node is inserted at the target location. If the target location was the root element of an instance, then the cloned node replaces the instance root element. If the cloned node is a duplicate of another attribute in its parent element, then the duplicate attribute is removed. If the cloned node cannot be placed at the target location due to a node type conflict, then the insert action is terminated with no effect.

  3. The index for any repeat that is bound to a homogeneous collection where the cloned node was added is updated to point to the newly inserted node, and the index of any repeat nested within an updated repeat is re-initialized to the startindex of the nested repeat.

  4. The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.

  5. The insert action is successfully completed by dispatching the xforms-insert event.

Example: Inserting the clone of a prototypical element (append child, prepend child)
...
<xforms:instance id="people">
  <people xmlns=""/>
</xforms:instance>
<xforms:instance id="personProto">
  <person xmlns="">
      <name>Jane Q. Public</name>
  </person>
</xforms:instance>
...
<xforms:trigger>
  <xforms:label>Append new person</xforms:label>
  <xforms:insert context="instance('people')" nodeset="person" origin="instance('personProto')" ev:event="DOMActivate"/>
</xforms:trigger>

<xforms:trigger>
  <xforms:label>Prepend new person</xforms:label>
  <xforms:insert context="instance('people')" nodeset="person" origin="instance('personProto')" 
                 at="1" position="before" ev:event="DOMActivate"/>
</xforms:trigger>
...
		

Note:

Generalized append/prepend child can be done with nodeset="*" for elements and nodeset="@*" for attributes.

Example: Replacing an instance
...
<xforms:instance id="people">
  <people xmlns="">
    <person>
      <name>Jane Q. Public</name>
    </person>
    <person>
      <name>John Hancock</name>
    </person>
  </people>
</xforms:instance>
...
<xforms:instance id="peopleProto">
  <people xmlns=""/>
</xforms:instance>
...
<trigger>
  <label>Clear Person List</label>
  <insert context="instance('people')" nodeset="." origin="instance('peopleProto')" ev:event="DOMActivate"/>
</trigger>
...
		
Example: Duplicating a node
<insert nodeset="some/node"/>
		
Example: Copying an attribute
<xforms:instance xmlns="">
   <data>
      <item show="true">...</item>
      <item>...</item>
      <item willbesecondattr="true" show="false">...</item>
      <item willbesecondattr="false" show="false">...</item>
   </data>
</xforms:instance>
...
<insert nodeset="item[2]" origin="item[1]/@show"/>
<insert nodeset="item[3]" origin="item[1]/@show"/>
<insert nodeset="item[4]/@show" origin="item[1]/@show"/>
...
		

After the insert actions, all item elements have attribute show="true", and it will be the first attribute except for the last item. The existing show attribute is removed from the third and fourth item, but in the third item the location of the new attribute is at the beginning due to node type mismatch, and in the fourth item the location of the new attribute after (due to position default) the existing show attribute.

Example: Inserting into a repeat, whether or not it is empty

When the repeat is empty, the at index is zero so a new item is prepended. When the repeat is non-empty, the new item is added after the node currently indexed by repeat R.

...
<xforms:instance xmlns="">
   <purchaseOrder>
        <subtotal/>
        <tax/>
        <total/>
   </purchaseOrder>
</xforms:instance>
<xforms:instance xmlns="" id="prototypes">
    <prototypes>
       ...
       <item>
           <product/>
           <quantity/>
           <unitcost/>
           <price/>
       </item>
    </prototypes>
</xforms:instance>
...
<repeat nodeset="/purchaseOrder/item">
   ...
</repeat>
...
<xforms:trigger>
  <xforms:label>Add to purchase order</xforms:label>
  <xforms:action ev:event="DOMActivate>
    <xforms:insert context="/purchaseOrder" nodeset="item" at="index('R')" origin="instance('prototypes')/item"/>
    <xforms:setfocus control="R"/>
  </xforms:action>
</xforms:trigger>
			

3.1.2 The delete Action

This action deletes a node from instance data.

Common Attributes: Common (optional), Events (optional), Node Set Binding (required)

If the bind attribute appears, it provides the delete context. If the model attribute is given and indicates a model different than the one containing the in-scope evaluation context node, then the in-scope evaluation context is changed prior to evaluation of the Special Attributes of the delete element. The size and position are changed to 1, and the node is changed to the document element node of the default instance of the indicated mode.

Special Attributes:

context

Optional XPath expression used to change the in-scope evaluation context for the delete element. This attribute is ignored if the bind attribute is provided. If the attribute is not given, then the default delete context is the in-scope evaluation context. Otherwise, the XPath expression is evaluated using the in-scope evaluation context, and the first node rule is applied to obtain the delete context. The delete action is terminated with no effect if the delete context is the empty node-set or if the context attribute is not given and the Node Set Binding node-set is empty.

at

Optional XPath expression evaluated to determine the delete location within the Node Set Binding node-set. If the Node Set Binding node-set empty, then this attribute is ignored. If the attribute is not given, then the default is the size of the Node Set Binding node-set. Otherwise, the delete location is determined from this attribute as follows:

  1. The evaluation context node is the first node in document order from the Node Set Binding node-set, the context size is the size of the Node Set Binding node-set, and the context position is 1.

  2. The return value is processed according to the rules of the XPath function round(). For example, the literal 1.5 becomes 2, and the literal 'string' becomes NaN.

  3. If the result is in the range 1 to the Node Set Binding node-set size, then the delete location is equal to the result. If the result is non-positive, then the delete location is 1. Otherwise, the result is NaN or exceeds the Node Set Binding node-set size, so the delete location is the Node Set Binding node-set size.

Provided the insert action has not been terminated due to the conditions stated above, the rules for delete processing are as follows:

  1. The node at the delete location in the Node Set Binding node-set is deleted, except if the node is the root document element of an instance then the delete action is terminated with no effect.

  2. The index for any repeat that is bound to a homogeneous collection that contained the deleted node is not changed except:

    1. When the last remaining item in the collection is removed, the index position becomes 0.

    2. When the index was pointing to the deleted node, which was the last item in the collection, the index is changed to point to the new last node of the collection and the indexes of inner repeats are reinitialized.

    3. When the index was pointing to the deleted node, which was not the last item in the collection, the index position is not changed but the indexes of inner repeats are re-initialized.

    To re-initialize a repeat index means to set it to the startindex value.

  3. The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.

  4. The delete action is successfully completed by dispatching the event xforms-delete.

Example: Deleting from a repeat

In this example, the trigger is not in the repeat. When it is activated, the indexed item in the repeat is first deleted. Next, if that was the last item, then a new prototypical item is inserted so that the repeat does not become empty. The focus is then sent back to the repeat from the trigger.

...
<xforms:trigger>
  <xforms:label>Delete from purchase order</xforms:label>
  <xforms:action ev:event="DOMActivate>
    <xforms:delete context="/purchaseOrder" nodeset="item" at="index('R')"/>
    <xforms:insert context="/purchaseOrder" if="not(item)"
                   nodeset="item" origin="instance('prototypes')/item"/>
    <xforms:setfocus control="R"/>
  </xforms:action>
</xforms:trigger>
			

Note:

The form author could have written nodeset="/purchaseOrder/item" in the delete action, but the context attribute was added for consistency with the insert action.

3.2 The load Action

This action element from XForms 1.0 is augmented in XForms 1.1 to support the resource child element that is also defined for submission.

When used as a child element of load, the resource element overrides the resource attribute. Other than this exception, see 4.2 The resource Element and Attribute for details about the resource element.

3.3 The control Element Child of the setfocus Element

In XForms 1.0, the setfocus action dispatches the event xforms-focus to a run-time element that is determined with the aid of a control specifier, an IDREF given by attribute control. This section defines a child element of setfocus named control that is an alternative means of providing the control specifier.

Element: control

Common attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the control specifier, the result of the expression is processed as if by call to the XPath string function.

The control specifier of the setfocus action is given by the control attribute or the control element. If both are given, the element takes precedence. Due to the addition of the element, the control attribute is no longer required, but either the control attribute or the control element must appear. The control element can provide the control specifier IDREF with either its string content or the value attribute. If both are given, then the value attribute takes precedence.

<setfocus>
	<control value="concat('input_', ../paymentType)"/>
</setfocus>

Note:

Whether the IDREF is obtained from the control attribute or element, the IDREF may not uniquely identify the desired form control if the element bearing the matching ID resides in a repeating construct such as element repeat. The general method described in 2.10 Resolving ID References in XForms is used to determine the desired form control.

3.4 The case Element Child of the toggle Element

In XForms 1.0, the toggle action determines the case element that must become selected by its containing switch. This is done with the aid of a case specifier, an IDREF given by attribute case. This section defines a child element of toggle named case that is an alternative means of providing the case specifier.

Element: case

Common attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the case specifier, the result of the expression is processed as if by call to the XPath string function.

The case specifier of the toggle action is given by the case attribute or the case element. If both are given, the element takes precedence. Due to the addition of the element, the case attribute is no longer required, but either the case attribute or the case element must appear. The case element can provide the case specifier IDREF with either its string content or the value attribute. If both are given, then the value attribute takes precedence.

<toggle>
	<case value="concat('case_', ../addressBlockType)"/>
</toggle>

Note:

Whether the IDREF is obtained from the case attribute or element, the IDREF may not uniquely identify the desired case if the case element bearing the matching ID resides in a repeating construct such as element repeat. The general method described in 2.10 Resolving ID References in XForms is used to determine the desired run-time case object.

3.5 Improvements to the dispatch Action

3.5.1 The name and target Child Elements

In XForms 1.0, the dispatch action dispatches and event given by attribute name to an element identified by the target attribute. This section defines new child elements of dispatch that provide a means of specifying the name and target of the event with instance data.

Element: name

Common attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the event name, the result of the expression is processed as if by call to the XPath string function.

The event name of the dispatch action is given by the name attribute or the name element. If both are given, the element takes precedence. Due to the addition of the element, the name attribute is no longer required, but either the name attribute or the name element must appear. The name element can provide the event name with either its string content or the value attribute. If both are given, then the value attribute takes precedence.

Element: target

Common attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the event target, the result of the expression is processed as if by call to the XPath string function.

The event target of the dispatch action is given by the target attribute or the target element. If both are given, the element takes precedence. Due to the addition of the element, the target attribute is no longer required, but either the target attribute or the target element must appear. The target element can provide an IDREF for the event target with either its string content or the value attribute. If both are given, then the value attribute takes precedence.

Note:

Whether the IDREF is obtained from the target attribute or element, the IDREF may not uniquely identify the desired target object if the element bearing the matching ID resides in a repeating construct such as element repeat. The general method described in 2.10 Resolving ID References in XForms is used to determine the desired target object.

3.5.2 Delayed Event Dispatching

A new attribute named delay of type xsd:nonNegativeInteger is defined for the dispatch action. The attribute is optional with a default of 0. The attribute indicates the minimum number of milliseconds to delay dispatching of the event to the target. A new child element of dispatch named delay is also defined as follows:

Element: delay

Common attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the event delay, the result of the expression is processed as if by call to the XPath string function. If the result does not conform lexically to xsd:nonNegativeInteger, then the result of 0 is used.

The event delay of the dispatch action is given by the delay attribute or the delay element. If both are given, the element takes precedence. The delay element can provide the delay with either its string content or the value attribute. If both are given, then the value attribute takes precedence.

If the event delay is 0, then the specified event is dispatched as the result of the dispatch action. Otherwise, the event delay is greater than 0, and the specified event is added to the delayed event queue unless an event with the same name and target element already exists on the delayed event queue. The dispatch action has no effect if the event delay is greater than zero and the specified event is already in the delayed event queue.

Note:

Since an element bearing a particular ID may be repeated, the delayed event queue may contain more than one event with the same name and target IDREF. It is the name and the target run-time element that must be unique.

If a run-time element is destroyed, then any delayed events targeted at that element are removed from the delayed event queue. A run-time element may be destroyed for a number of reasons, including shutdown of the form or removal of form controls associated by a repeat with an instance data node that is destroyed.

As soon as possible after the specified delay has elapsed, the event is removed from the delayed event queue and then dispatched. In the same manner used to handle user-generated events or the completion of an asynchronous submission, the dispatch and processing of delayed events is done without interrupting the processing of another event and its event handlers.

Note:

Because the delayed event is first removed from the delayed event queue and then dispatched, a handler for a given event may dispatch the event again with a delay. This can be used to perform simple polling operations. Moreover, the if attribute can be applied to the dispatch action to decide when to discontinue the polling based on a setting in instance data.

3.6 The messsage Action

The attribute level is optional and defaults to modal.

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

Example: Closing a document
<trigger>
  <label>Close</label>
  <close ev:event="DOMActivate"/>
</trigger>
        

3.7.1 The xforms-close Event

This event, dispatched to the default model element, results in closing down the owner document. In a rendering environment, this may close down the user agent that renders the document.

Target: the default model

Bubbles: Yes

Cancelable: Yes

Context Info: None.

Default Action: The owner document is closed down.

3.8 The prompt Action Element

This action provides a prompt and a modal method for the user to respond by activating a trigger. If XForms actions are associated with the DOMActivate of the trigger activated by the user, then those actions are performed. When a DOMActivate event bubbles up to the prompt element from any of its child trigger controls, this action releases the modal prompt and stops the propagation of the event. More generally, this action stops the propagation in the bubble phase of any events that reaches the prompt element.

Common attributes: Common, Events

Special attributes: None

Content: label, trigger+

Example: Getting confirmation to proceed with a submission
        <trigger>
          <label>Submit Personal Business Commitments</label>
          <prompt ev:event="DOMActivate">
              <label>You will not be able to modify your PBC's again unless your manager 
                          returns them to you.  Are you sure you want to submit?</label>
              <trigger>
                  <label>Yes</label>
                  <send ev:event="DOMActivate" submission="X"/>
              </trigger>
              <trigger>
                  <label>No</label>
              </trigger>
          </prompt>
        </trigger>
        

Note:

Actions performed in response to activation of a trigger in a prompt are subject to normal deferred update behavior (i.e. rebuild, recalculate, revalidate, refresh do not occur until after the prompt, or later if the prompt is part of an even larger action sequence).

3.9 Conditional Execution of XForms Actions

The if attribute can be added to any XForms action. It contains an [XPath 1.0] expression that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is converted to a boolean as if converted with the boolean() function defined by the [XPath 1.0] specification. If the converted result of the expression evaluates to false, then the action is not performed. If the converted result is true, then the action is performed.

If this attribute is applied to an XForms action element and the converted result of evaluation is false, then all of the actions within the action element are omitted from the execution of the XForms action sequence that invoked the action element. If the result is true, then the contained actions are performed according to the normal processing rules such as deferred update behavior and applicability of conditional and iterative attributes.

Example: Automatic Focus Advancement

The setfocus action in each input control is executed only if the node bound to the control is a number of a particular length. The exacting form author could perform further validity tests.

...
<input ref="areaCode" id="AreaCodeControl" incremental="true">
	<label>Area Code</label>
	<setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/>
</input>
<input ref="exchange" id="ExchangeControl" incremental="true">
	<label>Exchange</label>
	<setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/>
</input>
<input ref="local" id="LocalControl" incremental="true">
	<label>Local</label>
	<setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/>
</input>
...
Example: Handling Focus for Empty Repeats

The trigger that performs a delete conditionally sets the focus to a control outside of the repeat if the repeat becomes empty due to the deletion. The setfocus is called first because the delete removes the context node.

...
<trigger id="InsertControl">
	<label>Insert Row</label>
	<action ev:event="DOMActivate">
		<insert context="purchaseOrder/lines" nodeset="line" 
				at="index('PurchaseOrderRepeat')" origin="instance('prototype')"/>
		<setfocus control="PurchaseOrderRepeat"/>
	</action>
</trigger>
<repeat nodeset="purchaseOrder/lines/line" id="PurchaseOrderRepeat">
	...
	<trigger>
	  <label>Delete Row</label>
		  <action ev:event="DOMActivate">
			  <setfocus control="InsertControl" if="last()=1"/>
			  <delete  nodeset="../line" at="index('PurchaseOrderRepeat')"/>
		  </action>
	</input>
	...
</repeat>

3.10 Iteration of XForms Actions

The while attribute can be added to any XForms action. It contains an [XPath 1.0] expression that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is converted to a boolean as if converted with the boolean() function defined by the [XPath 1.0] specification. If the converted result of the expression is true, then the XForms action is performed and then the expression is re-evaluated. The XForms action is iterated repeatedly until the converted result of the expression evaluates to false.

If this attribute is applied to an XForms action element, then the sequence of XForms actions in its content are executed repeatedly once for each time the immediately preceding evaluation of the expression yields a result of true.

When XForms actions are iteratively executed, they are still subject to the normal action processing rules such as deferred update and applicability of conditional and iterative attributes.

If an action bears this attribute and the if attribute, then the expressions of both attributes must evaluate to true before each iterative execution of the action.

Example: Summing Selected Results

Counter and Accumlator Variables are Created in Instance Data to Sum a Selection of Values Chosen by the User

<trigger>
	<label>Get Sum</label>
	<action ev:event="DOMActivate">
		<setvalue ref="instance('temps')/counter" value="1"/>
		<setvalue ref="instance('temps')/accumulator" value="0"/>
		<action while="instance('temps')/counter &lt;= count(/some/nodes)">
			<setvalue ref="instance('temps')/accumulator" 
				value=". + /some/nodes[instance('temps')/counter]"
				if="boolean-from-string(/some/nodes[instance('temps')/counter]/@selected)"/>
			<setvalue ref="instance('temps')/counter" value=". + 1"/>
		</action>
	</action>
</trigger>

3.11 Modifications to Deferred Update Behavior of Actions

An outermost action handler is an action that is activated when the XForms processor is not executing any other action handlers.

An inner action handler is an action that is activated when the XForms processor is executing the declared actions of an outermost action handler. An inner action handler may be within the content of the outermost action handler, or it may be executed as the response to an event dispatched while performing all of the actions initiated by the outermost action handler.

Deferred Updates: Sequences of one or more XForms Actions have a deferred effect on XForms model and user interface processing. Implementations are free to use any strategy to accomplish deferred updates, but the end result must be as follows: Instance data changes performed by a set of actions do not result in immediate computation dependency rebuilding, recalculation, revalidate and form control refreshing until the termination of the outermost action handler, as described here. Each XForms model can be thought of as having a set of deferred update Boolean flags, initially false at the start of an outermost action handler, to indicate whether each of the actions rebuild, recalculate, revalidate, and refresh are required for that model upon termination of the outermost action handler.

By default, the behavior of an action handler is performed one time when the action is encountered in the execution sequence. However, execution of an action handler may be conditional or iterated, as described in 3.9 Conditional Execution of XForms Actions and 3.10 Iteration of XForms Actions.

Execution of an outermost action handler begins by setting the XForms processor into the state of executing an outermost action handler. The outermost action handler is then performed, which may include the execution of inner action handlers. Finally, the XForms processor is set into the state of not executing an outermost action handler and then the deferred update is performed for each model. The deferred update behavior for a model consists of examining each deferred update Boolean flag in the order of rebuild, recalculate, revalidate, and refresh, and for each true flag, set the flag to false and then dispatch the proper event to the model for that deferred update flag (i.e. dispatch xforms-rebuild for a true rebuild flag, xforms-recalculate for a true recalculate flag, xforms-revalidate for a true revalidate flag, and xforms-refresh for a true refresh flag).

Note:

The XForms processor is not considered to be executing an outermost action handler at the time that it performs deferred update behavior for XForms models. Therefore, event handlers for events dispatched to the user interface during the deferred refresh behavior are considered to be new outermost action handler.

Actions that directly invoke rebuild, recalculate, revalidate, or refresh always have an immediate effect, and clear the corresponding deferred update flag. The XForms Actions in this category are:

rebuild
recalculate
revalidate
refresh

XForms Actions that change the tree structure of instance data result in setting all four deferred update flags to true for the model over which they operate. The XForms Actions in this category are:

insert
delete

XForms Actions that change only the value of an instance node results in setting the deferred update flags for recalculate, revalidate, and refresh to true and making no change to the deferred update flag for rebuild for the model over which they operate. The XForms Actions in this category are:

setvalue

Finally, the reset action clears all of the deferred update flags for a model. Similarly, if the default processing of xforms-submit replaces instance data in a model, then the deferred update flags for that model are cleared immediately before the behaviors are peformed for xforms-rebuild, xforms-recalculate, xforms-revalidate, and xforms-refresh.

4 Submission

4.1 New and Revised Submission Attributes

There are several new attributes and attribute values that provide new capabilities to the submission element in XForms 1.1. This section describes many of the new attributes as well as new attribute values for some existing attributes, and the following new attributes are described in separate sections because they are related to new child elements of submission: resource (4.2 The resource Element and Attribute) and verb (4.3.1 The verb Attribute).

4.1.1 The validate Attribute on Element submission

The submission element must allow a new optional attribute named validate of type boolean. The default value is true.

If the value of attribute validate is true by declaration or default, then the processing of a submission is unchanged from XForms 1.0, i.e. the instance being submitted must be valid for processing to proceed.

If the value of attribute validate is false, then the processing of a submission is changed from XForms 1.0 in the following way: The instance data will not be validated, and the submission processing will be allowed to proceed even if there is a selected instance data node that is either required but empty or not valid according to the definition provided in the text of the xforms-revalidate event.

4.1.2 The relevant Attribute on Element submission

The submission element must allow a new optional attribute named relevant of type boolean. The default value is true.

If the value of attribute relevant is true by declaration or default, then the processing of a submission is unchanged from XForms 1.0, i.e. the instance being submitted will not contain instance data nodes whose model item property relevant evaluates to false().

If the value of attribute relevant is false, then the processing of a submission is changed from XForms 1.0 in the following way: When the instance is serialized it will contain all selected instance data nodes, including instance data nodes whose model item property relevant evaluates to false().

4.1.3 The serialize Attribute on Element submission

The submission element must allow a new optional attribute named serialize of type boolean. The default value is true.

If the value of attribute serialize is true by declaration or default, then the processing of a submission is unchanged from XForms 1.0, i.e. the submission serialization logic occurs.

If the value of attribute serialize is false, then the processing of a submission is changed from XForms 1.0 in the following way: instance data is not serialized or submitted.

4.1.4 The mode Attribute on Element submission

The submission element must allow a new optional attribute named mode of type string. The valid values for this attribute are synchronous and asynchronous. The default value is asynchronous.

If the value of attribute mode is synchronous, then the default processing of xforms-submit must include the steps that apply the response returned from the submission. The default processing must block further action processing and the XForms processor must suspend user interaction with form controls until the submission response is returned. The user agent may signify that it has entered a waiting state (e.g. with an hourglass cursor), and the user agent may provide a means of terminating the submission, which would correspond to an error response from the submission.

If the value of attribute mode is asynchronous, whether by declaration or default, then the default processing of xforms-submit concludes once the submission has been initiated. With respect to the content of the submission serialization, the XForms processor must behave as if the submission serialization is completely formed prior to initiating the submission.

4.1.5 Replacing Text with a Submission Response

In XForms 1.1, the replace attribute of submission supports the additional value of text. If this setting is made, and the submission response conforms to an XML mediatype (as defined by the content type specifiers in [RFC 3023]) or a text media type (as defined by a content type specifier of text/*), then the response data is encoded as text and replaces the content of the replacement target node. See 4.1.6 The target Attribute on Element submission for further information about the replacement target node. If the content type of the submission response is not an XML mediatype or text mediatype as defined above, then the submission ends after dispatching the event xforms-submit-error with an error-type of resource-error.

4.1.6 The target Attribute on Element submission

The submission element must allow a new optional attribute named target of type string. The attribute value is interpreted as an XPath expression returning a node-set, the first node of which is used as the replacement target node for the submission response.

The default replacement target node is the document element node of the instance identified by the instance attribute, which is equal to the default instance of the model if not specified. The evaluation context for this attribute is the in-scope evaluation context for the submission element, except the context node is modified to be the document element of the instance identified by the instance attribute if it is specified.

This attribute is evaluated only once a successful submission response has been received and if the replace attribute value is instance or text. If the evaluation of the target attribute produces an empty nodeset or a nodeset in which the first node is not an element node, then submission processing ends after dispatching the event xforms-submit-error with an error-type of target-error.

When the replace attribute contains the value text, then the replacement target node is used as described in 4.1.5 Replacing Text with a Submission Response. When the replace attribute contains the value instance, then the XML obtained from the submission response is used to replace the target node. The XML in the response may have comment and processing instruction nodes before and after the document element. These nodes are discarded if the replacement target node is not the document element of an instance. Otherwise, those processing instructions and comments replace any processing instructions and comments that previously appeared outside of the document element of the instance being replaced.

4.1.7 The delete submission method

Element submission must allow the value delete for attribute method and provide delete submission behavior as defined in [RFC 2616].

Note:

[RFC 2616] allows the server to respond with content, or with code 204 without content. If submission attribute replace is instance and there is no content in the response, then the submission will fail with xforms-link-exception. Even if content is returned, the content may not be an XML media type. Therefore, form authors who do not have control over the server are recommended not to use submission attribute replace = instance.

4.2 The resource Element and Attribute

In XForms 1.0, the URI for submission is provided by the action attribute. For consistency, form authors may now alternately use the attribute resource of type xsd:anyURI. If both action and resource are present, then the resource attribute takes precedence.

When it appears as the first child element of submission, the resource element provides the submission URI, overriding the resource attribute and the action attribute. This element allows the URI used for submission to be dynamically calculated based on instance data. Individually, the resource element, the resource attribute and the action attribute are not required. However, one of the three is mandatory.

Common Attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the URI, the result of the expression is processed as if by call to the XPath string function.

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 element as its first child, then the submission URI is obtained from the resource attribute or the action attribute.

4.3 Submission verb Attribute and Element

4.3.1 The verb Attribute

The submission element must allow a new optional attribute named verb of type string. The default value is determined based on the URI scheme and the method attribute using the rules in 4.7 Submission Options. For example, under the http and https schemes, the methods post and urlencoded-post correspond to the verb POST. If given, the verb attribute overrides the default verb used in submission.

4.3.2 The verb Element

The submission element can optionally a child element named verb, which must appear immediately after the optional resource element. This element provides the submission verb, overriding the setting obtained from the verb attribute (or its default).

Common Attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the verb, the result of the expression is processed as if by call to the XPath string function.

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

4.4 The header Element

The header element can be used to contribute information to the preamble of a submission in a manner appropriate to the protocol. The submission element can contain zero or more header child elements, which must appear immediately after the optional resource and verb elements.

Common Attributes: None

Special Attributes:

nodeset

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. One header is generated for each node selected by this attribute.

Content: name, value

If the header element does not contain a nodeset attribute, then one header is created. If the header element contains a nodeset attribute, then one header is created per selected node. The name and value of the header are obtained from the required child elements name (4.4.1 The name Element) and value (4.4.2 The value Element). If the name obtained from the name element is the empty string, then the header is omitted from the submission preamble.

If a header element defines the Content-type header, then this setting overrides a Content-type set by the mediatype attribute.

The headers defined by header elements are appended to the set of other headers which may exist for a submission. In the case of a multipart submission, the headers are appended to those for the first part of the submission.

4.4.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 to be added to the preamble of a submission. The name element may be used more than once if the containing header element specifies a nodeset attribute.

Common Attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the header name, the result of the expression is processed as if by call to the XPath string function.

The header 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 header name is the empty string, then the header is considered to be void, and it is not added to the submission preamble.

4.4.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 to be added to the preamble of a submission. The value element may be used more than once if the containing header element specifies a nodeset attribute.

Common Attributes: None

Special Attributes:

value

Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the header value, the result of the expression is processed as if by call to the XPath string function.

The header 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.

4.5 New Submission Events

4.5.1 The xforms-submit-serialize Event

Dispatched at the beginning of submission serialization (see 4.6.1 The xforms-submit Event).

Target: submission

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
submission-bodystring (text node)An initially empty string into which event handlers can write data to use in the submission in lieu of the default instance data serialization.

Note:

The submission-body property is a string, but the event() function encapsulates the string in a text node so that the string can be modified by the setvalue action, which sets a value into a node determined by its Single Node Binding.

Default Action: If the event context submission-body property string is empty, then no operation is performed so that the submission will use the normal serialization data (see 4.6.1 The xforms-submit Event). Otherwise, if the event context submission-body property string is non-empty, then the serialization data for the submission is set to be the content of the submission-body string.

4.6 Changed Submission Events

4.6.1 The xforms-submit Event

Under no circumstances may more than a single concurrent submit process be under way for a particular XForms submission. From the start of the default action of xforms-submit, until its termination (immediately before dispatching xforms-submit-done or xforms-submit-error), the default action for subsequent xforms-submit events is to dispatch xforms-submit-error with context information containing an error-type of submission-in-progress.

Otherwise, default action for this event results in the following steps:

  1. The data model is updated. Specifically, if the deferred update rebuild flag is set for the model containing this submission, then the rebuild operation is performed without dispatching an event to invoke the operation. Then, if the deferred update recalculate flag is set for the model containing this submission, then the recalculate operation is performed without dispatching an event to invoke the operation.

  2. A node from the instance data is selected, based on attributes on the submission element. if the attributes of submission select an empty nodeset, a non-relevant node or a non-element node, then submission processing is stopped after dispatching event xforms-submit-error with context information containing an error-type of no-data. Otherwise, the indicated node and all nodes for which it is an ancestor are considered for the remainder of the submit process. if the attribute relevant is true, whether by default or declaration, then any node which is considered not relevant as defined in 6.1.4 The relevant Property is removed.

  3. If the attribute validate is true,whether by default or declaration, then all selected instance data nodes are checked for validity according to the definition in Section 4.3.5 (no notification events are marked for dispatching due to this operation). Any selected instance data node that is required but empty or found to be invalid stops submission processing after dispatching event xforms-submit-error with context information containing an error-type of validation-error.

  4. The headers are determined using the header element(s) in the submission and the mediatype attribute or its default.

  5. The verb is determined using the verb element, verb attribute, or the method attribute.

  6. The submission URL is determined using the resource element, resource attribute, or the action attribute.

  7. If the serialize attribute is false, then the submission serialization is the empty string. Otherwise, the submission serialization is determined as follows. The event xforms-submit-serialize is dispatched. If the submission-body property of the event is changed from the initial value of empty string, then the content of the submission-body property string is used as the submission serialization. Otherwise, the submission serialization consists of a serialization of the selected instance data according to the rules stated at 4.7 Submission Options.

  8. The submission is performed based on the headers, verb, URL, and submission serialization . The exact rules of submission are based on the protocol scheme and the method as defined in 4.7 Submission Options.

If the mode of the submission is asynchronous, then default processing for this event ends after the above steps, and submission processing is resumed once the response from the submission is returned. If the mode of the submission is synchronous, then the XForms processor suspends user interaction with all form controls of the document and action processing is blocked within in the default processing for this event until the response from the submission is returned.

The response returned from the submission is applied as follows:

  • For a success response including a body, when the value of the replace attribute on element submission is "all", the event xforms-submit-done is dispatched with appropriate context information, and submit processing concludes with entire containing document being replaced with the returned body.

  • For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]), when the value of the replace attribute on element submission is "instance", the response is parsed as XML. If the parse fails, then submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of parse-error. However, if the XML parse succeeds, then instance data replacement is performed according to the rules in 4.1.6 The target Attribute on Element submission. This operation may fail if the target attribute is specified and does not produce an element node result. In this case, submission ends after dispatching event xforms-submit-error with appropriate context information, including an error-type of target-error. Otherwise, the instance data replacement succeeds. Once the XML instance data has been successfully replaced, the rebuild, recalculate, revalidate and refresh operations are performed on the model, without dispatching events to invoke those four operations. This sequence of operations is associated with special deferred update behavior. Submission processing then concludes after dispatching xforms-submit-done with appropriate context information.

  • For a success response including a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]), when the value of the replace attribute on element submission is "instance", nothing in the document is replaced and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

  • For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]) or a text media type (as defined by a content type of text/*), when the value of the replace attribute on element submission is "text", the response is encoded as text. Then, the content replacement is performed according to the rules specified in 4.1.5 Replacing Text with a Submission Response and 4.1.6 The target Attribute on Element submission. If the evaluation of an expressed target attribute failed, then the submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of target-error. Otherwise, if the replaced content contained one or more element nodes, then the rebuild operation is invoked without dispatching an event for the operation. Then, the recalculate, revalidate and refresh operations are performed on the model, without dispatching events to invoke those operations. This sequence of operations is associated with special deferred update behavior. Finally, submission processing then concludes after dispatching xforms-submit-done with appropriate context information.

  • For a success response including a body that is both a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]) and a non-text type (i.e. with a content type not matching text/*), when the value of the replace attribute on element submission is "text", nothing in the document is replaced and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

  • For a success response including a body, when the value of the replace attribute on element submission is "none", submission processing concludes after dispatching xforms-submit-done with appropriate context information.

  • For a success response not including a body, submission processing concludes after dispatching xforms-submit-done with appropriate context information.

  • Behaviors of other possible values for attribute replace are not defined in this specification.

  • For an error response nothing in the document is replaced, and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

4.7 Submission Options

The XForms Model specifies a submission element containing the following attributes and child elements that affect serialization and submission. This section summarizes the behaviors for the allowable values of these attributes and child elements, and introduces the following sections that define the behavior for serialization and submission. (See Section 3.3.3 for additional submission attributes and subelements that affect serialization.)

  • attribute action (xsd:anyURI), attribute resource or resource element

  • attribute method (xsd:string, enumerated below)

  • header elements

  • the verb element or attribute

For the URI scheme obtained from the action attribute, resource attribute or resource element, XForms normatively defines a binding to HTTP/1.1 [RFC 2616].

Note:

Other bindings, in particular to the URI scheme "mailto:" may, and the schemes "https:" and "file:" should, be supported. Bindings to these schemes are not normatively defined in XForms. Implementations that choose to provide a binding to these schemes should pay particular attention to privacy and security concerns. Within the "http:" and "https:" schemes, form creators are encouraged to follow the finding of the W3C Technical Architecture Group on when to use the GET method: [TAG Finding 7]

The method attribute determines the serialization format, and the URI scheme used in the action attribute attribute or resource element determines the submission protocol, according to the following table:

URI schememethodSerializationSubmission
http https mailto"post"application/xmlHTTP POST or equivalent
http https file"get"application/x-www-form-urlencodedHTTP GET or equivalent
http https file"delete"application/x-www-form-urlencodedHTTP DELETE or equivalent
http https file"put"application/xmlHTTP PUT or equivalent
http https mailto"multipart-post"multipart/relatedHTTP POST or equivalent
http https mailto"form-data-post"multipart/form-dataHTTP POST or equivalent
http https mailto"urlencoded-post"application/x-www-form-urlencodedHTTP POST or equivalent
(any)any other QNAME with no prefixN/AN/A
(any)any QNAME with a prefiximplementation-definedimplementation-defined

Note:

Foreign-namespaced attributes are allowed on element submission, but no behavior is defined by XForms.

Note:

The verb element or attribute overrides the default submission verb from the submission column in the submission options table above.

4.8 The get Submit 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, then a separator character from the attribute separator is appended.

  • The serialized form data is appended to the URI.

No message body is sent with the request.

4.9 Integration with SOAP

This section describes the integration of XForms submission with [SOAP 1.1] and [SOAP 1.2]

4.9.1 Representation of SOAP Envelope

The single-node 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.

Note:

The form author may choose to store the data payload in one instance and copy the data to the submission instance containing the SOAP envelope as part of an xforms-submit event handler. The form author is responsible for declaring the appropriate model item properties on both instances (e.g. the relevant declarations).

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

Note:

The action MIME parameter has no effect unless the submission method is "post" because the GET method implies no SOAP processing by the receiving SOAP node.

Note:

SOAP 1.1 does not support the HTTP GET operation.

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

  • 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 change to text/xml

  • the charset MIME parameter is appended if it was specified in the mediatype

  • 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

Note:

XForms 1.1 does not support the SOAP email binding, so method="post" with a mailto: scheme results in an xforms-submit-error event before any submit processing message is dispatched.

Note:

XForms 1.1 does not support the SOAP 1.1 binding to the HTTP Extension Framework.

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

5 User Interface Improvements and Changes

5.1 Inline Rendition of Media Types Other than Plain Text

In XForms 1.0, the output element can take a single node binding indicating an instance node whose plain text 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 element 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 plain 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.

Note:

Implementations may handle the output content as presentation-only or as interactive conten, and interactive content may be isolated from or capable of accessing the enclosing document that contains the output. Further implementation experience and user feedback is required. For example, if the output content includes XForms user interface elements, it may be desirable for them to access a default XForms model in the output content or from the enclosing document..

If the mediatype attribute or element is given, then the data obtained from the instance node indicated by the single node binding must be decoded or dereferenced prior to rendition as follows:

  • If the instance node either is of type or is derived from type xsd:base64Binary, then the data is base-64 decoded.

  • If the instance node either is of type or is derived from type xsd:hexBinary, then the data is hex-binary decoded.

  • If the instance node either is of type or is derived from type xsd:anyURI, then the data is treated as a URI and dereferenced.

  • If the instance node is of any other type, then the data is used without modification.

Example: Displaying an image uploaded to instance data

Given the following model:

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

The following controls can upload an image to instance data and display it:

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

The rendition of the output is updated if the referenced node or its content changes, or if the media type changes. The media type can change by a change to the mediatype element's referenced node or its content (a host language may also allow DOM mutation of the content of the mediatype attribute or element).

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 to be decoded does not conform to the format of xsd:base64Binary or xsd:hexBinary

  • An xforms-link-error dereferencing the URI in a node of or derived from type xsd:anyURI

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

  • An unrecognized media type identifier string

5.1.1 The xforms-output-error Event

Dispatched by the processor immediately after the first failure of an output to render or update the rendition of content.

Target: output

Bubbles: Yes

Cancelable: No

Context Info: None.

Default Action: None; notification event only.

Since the output element can be the target of the xforms-output-error, the content model for the output is opened further to include XForms actions.

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 changed to include (UI Common)* so that help, hint, alert and XForms action elements can also appear as children of an output.

Example: Indicating an error displaying an image
<xforms:output ref="/data" mediatype="image/*">
	<xforms:message ev:event="xforms-output-error" level="ephemeral">Error in image data.</xforms:message>
</xforms:output>
Example: Providing better information on output to the user
<xforms:output ref="/purchaseOrder/Total">
	<xforms:alert>The purchase order total is too high.</xforms:alert>
	<xforms:hint>Make two or more separate orders.</xforms:hint>
</xforms:output>

5.3 Appearance Hint for Triggers

XForms 1.0 defines the attribute appearance for all form controls. It is an optional attribute that provides a rendering hint to the user agent. The XForms 1.0 Recommendation provides some examples of how a user agent may interpret the appearance hint for form controls such as select1 and select. This specification provides the further example for the trigger and submit form controls that user agent processors may interpret the value "minimal" in the attribute appearance as a hint to visually render the trigger with no border, a transparent background and an underline. This rendition hint is meant to be analogous to the typical visual rendition of an XHTML anchor element.

5.4 Support switch in repeat

The content model for element repeat includes switch. For each instance data node in the Node Set Binding, the repeat element instantiates a set of run-time objects that correspond to the content of the repeat contextualized by the instance data node. When a switch element has one or more repeat element ancestors, then one or more rum-time switch objects are instantiated based on contextualizing the switch element with the nodes from the containing repeat element(s). Each switch object contains the set of case objects that correspond to the case elements of the originating switch element, and they are similarly contextualized by the containining repeat element(s). The method for switching cases of a repeated switch with the toggle action is described in 2.10 Resolving ID References in XForms.

Editorial note 
The XForms 1.0 recommendation mentions that future versions of XForms may specify the behavior of switch in repeat based on implementation experience and user feedback. This has occurred in XForms 1.0 processors as they have matured, along with the observation that the IDREF problem for toggle is also applicable to other actions such as setfocus and setindex. Since XForms 1.0 does not specify the behavior of these actions when the identified element appears within a repeat, the current intent of the working group is to issue an erratum to XForms 1.0 Second Edition to allow switch in repeat as a straightforward result of specifying the general solution to the problem of referencing repeated controls by ID, which now appears in 2.10 Resolving ID References in XForms. Thus, XForms 1.1 would have this functionality by virtue of its availability as of XForms 1.0 Third Edition.

6 Conformance

6.1 XForms Model

The XForms model can contain or reference XML schemas, XForms instance elements, XForms bind elements, XForms submission elements, and XForms actions. XForms submission elements can also contain XForms actions.

An XForms processor should permit XForms actions to handle the following events: xforms-rebuild, xforms-recalculate, xforms-revalidate, xforms-refresh. An XForms processor must permit XForms actions to handle all other events targetted at model and submission elements. An XForms processor must support direct appearance of the namespace-qualified event attribute (from [XML Events]) on an XForms action that is a child of the event target. An XForms processor should support the definition of XForms actions for events that bubble to the parent of the event target. An XForms processor may support all other attributes, elements and features of XML events.

The following conformance statements pertain to message actions used in events targetted at model and submission elements. An XForms processor must support presentation of the XPath string of the message content. An XForms processor should support the use of the XForms output as part of message action textual content for all model and submission events after the last xforms-model-construct default action has been performed. An XForms processor may support the inclusion of other child elements to mark up the text content of message actions.

An XForms processor may support submissions prior to the xforms-ready event and after the xforms-model-destruct event. An XForms processor must support submissions requested as of the xforms-ready event and prior to the xforms-model-destruct event. An XForms processor should support all submission methods and must support the post, get and put methods.

Except as noted above, an XForms processor must support all features of the XForms model element and its contents, including their interactions (e.g. the effects on submission of the relevant model item properties expressed by bind elements). This also includes features expressed not just by elements and attributes, but also by their content, such as the additional XPath functions and schema data types defined by XForms.

6.2 XForms User Interface

The XForms user interface elements include basic form controls such as input, trigger and select1 as well as elements for organizing and iterating other elements, such as group, switch and repeat. Other XForms user interface elements, such as label, help, hint and alert, provide additional information about the elements that contain them. There are also additional support elements such as itemset for select1 and case for switch. Finally, XForms defines several events that are targetted at certain user interface elements. These events occur at specified times in the XForms processing model as well as due to user interaction, and XForms actions can be defined to respond to these events.

An XForms processor should support all features of all XForms user interface elements, except as follows. An XForms processor may support the inclusion of child elements other than output to mark up the text content of message actions. An XForms processor may support the attributes, elements and features of XML events for events targetted at user interface elements. If any user interface events are not supported, then XForms model events that are defined in terms of the issuance of user interface events should have the same net effect on user interface elements as if the events' default actions had occurred. For example, the xforms-refresh should result in an update of the values and state of the user interface.

6.3 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.4 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 changing the version on the default model to 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 may require adjustments beyond simply changing the version number.

A Schema for XForms 1.1

Editorial note 
The link to the XForms 1.1 schema must be provided here.

B References

B.1 Normative References

HMAC
RFC 2104 - HMAC: Keyed-Hashing for Message Authentication, H. Krawczyk, M. Bellare, R. Canetti, 1997. Available at http://www.ietf.org/rfc/rfc2104.txt
ISO 7812-1:2000
ISO/IEC 7812-1:2000 Identification cards -- Identification of issuers -- Part 1: Numbering system.
MD5
RFC 1321: The MD5 Message-Digest Algorithm, R. Rivest, 1992. Available at http://www.ietf.org/rfc/rfc1321.txt
RFC 2119
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
RFC 2616
RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, 1999. Available at: http://www.ietf.org/rfc/rfc2616.txt.
RFC 3023
RFC 3023: XML Media Types, M Murata, S. St. Laurent, D. Kohn, 2001. Available at: http://www.ietf.org/rfc/rfc3023.txt.
SHA2
SECURE HASH STANDARD. FIPS PUB 180-2, August 2002. Available at http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
SOAP 1.1
Simple Object Access Protocol (SOAP) 1.1 , D. Box, D. Ehnebuske, G. Kakivaya, A. Layman, N. Mendelsohn, H. F. Nielsen, S. Thatte, D. Winer, 2000. Available at: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
SOAP 1.2
SOAP Version 1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley, N. Mendelsohn, J.-J. Moreau, H. F. Nielsen, 2003. Available at: http://www.w3.org/TR/2003/REC-soap12-part1-20030624/.
TAG Finding 7
TAG Finding: URIs, Addressability, and the use of HTTP GET, Ian Jacobs, 2004. Available at: http://www.w3.org/2001/tag/doc/whenToUseGet-20040321
XForms 1.0
XForms 1.0 Second Edition, John Boyer, David Landwehr, Micah Dubinko, Roland Merrick, T. V. Raman, Leigh Klotz, 2006. W3C Recommendation available at: http://www.w3.org/TR/xforms/.
XPath 1.0
XML Path Language (XPath) Version 1.0, James Clark, Steve DeRose, 1999. W3C Recommendation available at: http://www.w3.org/TR/xpath.
XML Schema part 2
XML Schema Part 2: Datatypes, Paul V. Biron, Ashok Malhotra, 2001. W3C Recommendation available at: http://www.w3.org/TR/xmlschema-2/.

B.2 Informative References

XHTML Modularization
Modularization of XHTML, M. Altheim, et. al., 2001. W3C Recommendation available at http://www.w3.org/TR/xhtml-modularization/.
XML Events
XML Events - An events syntax for XML, Steven Pemberton, T. V. Raman, Shane P. McCarron, 2003. W3C Recommendation available at: http://www.w3.org/TR/xml-events/.

C Acknowledgements (Non-Normative)

This document was produced with the participation of current XForms Working Group participants: