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

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

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.

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

2.3.2 The luhn() Function

booleanluhn(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.

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.

2.3.4 The choose() Function

objectchoose(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.3.5 The id() Function

node-setid(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.3.6 The property()
Function

stringproperty(string)

This function acts as it did in XForms 1.0 except it returns "1.1" for the
version.

Examples:

property("version")

returns 1.1.

property("conformance-level")

may return full.

2.3.7
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.4 Accessing Context
Information for Events

objectevent(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.4.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:

Property

Type

Value

description

string

The XPath expression associated with
the Node-Set Binding of the insert action.

node

node-set

The instance data node
inserted.

Default Action: None; notification event only.

2.4.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:

Property

Type

Value

description

string

The XPath expression associated with
the Node-Set Binding of the delete action.

The protocol return code of the error
response, or empty node-set if the failed submission did not receive
an error response.

headers

node-set

Zero or more elements, each one
representing a content header in the error response received by a
failed submission. The returned node-set is empty if the failed
submission did not receive an error response or if there were no
headers. Each element has a local name of header with
no namespace URI, a string content equal to the value of the header,
and an attribute called name containing the name of the
header.

Default Action: None; notification event only.

2.4.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:

Property

Type

Value

code

number

The protocol return code of the
success response.

headers

node-set

Zero or more elements, each one
representing a content header in the success response received by the
submission. The returned node-set is empty if there were no headers
in the success response. Each element has a local name of
header with no namespace URI, a string content equal to
the value of the header, and an attribute called name
containing the name of the header.

Default Action: None; notification event only.

2.4.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:

Property

Type

Value

errorinformation

string

The URI that failed to load
(xsd:anyURI)

Default Action: Fatal error.

2.4.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:

Property

Type

Value

errorinformation

string

The URI that failed to load
(xsd:anyURI)

Default Action: None; notification event only.

2.4.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:

Property

Type

Value

errorinformation

string

The expression being processed when
the exception was detected, which is
implementation-specific

Default Action: Fatal error.

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

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

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.

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

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.

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

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:

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.

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.

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:

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

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.

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.

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.

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

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.

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.

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.

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 insert
context. If the model attribute is given and indicates a
model different than th eone 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:

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.

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.

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:

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.

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

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

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.

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.

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.

The form author could have written
nodeset="/purchaseOrder/item", 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 and header child elements that are
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.4 The resource
Element for details about the resource element. See 4.5 The header Element for details about the
header element.

3.3.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.4 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.5
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.

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.

3.6 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

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

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:

rebuildrecalculaterevalidaterefresh

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

insertdelete

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
rebuildfor 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.1.1 The
xforms-submit-serialize Event

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 data 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 data property string is
empty, then no operation is performed so that the submission
will use the normal serialization data (see 4.3.1 The xforms-submit Event).
Otherwise, if the event context data property string is
non-empty, then the serialization data for the submission is set
to be the content of the data string.

4.2 New Submission
Attributes

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

4.2.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 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 validate 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.2.3 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.3
Changed Submission Events

4.3.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
errorname of submission-in-progress.

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

A node from the instance data is selected, based on attributes on
the submission element. If the attributes of
submission select an empty nodeset, then submission
processing is stopped after dispatching event
xforms-submit-errorwith context information
containing an errorname 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.

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-errorwith context information
containing an errorname of
validation-error.

The event xforms-submit-serialize is dispatched.
If the data property of the event is changed from the
initial value of empty string, then the content of the data
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.6 Submission
Options .

The submission serialization is submitted
using the protocol indicated by the rules stated at 4.6 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. An xforms-link-exception (2.4.5 The xforms-link-exception
Event) occurs if the parse fails , and submission
processing concludes after dispatching xforms-submit-error
with appropriate context information, including an errorname
of parse-error. However, if the XML parse succeeds,
then all of the internal instance data of the instance indicated by the
instance attribute setting is replaced with the result. Once
the XML instance data has been replaced, the rebuild, recalculate,
revalidate and refresh operations are performed on the model, without
dispatching events to invoke those four operations. This operation
is associated with special deferred update behavior.
Submission processing then concludes after dispatching
xforms-submit-donewith 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-errorwith appropriate context
information, including an errorname 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-donewith appropriate context
information.

For a success response not including a body, submission processing
concludes after dispatching xforms-submit-donewith
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-errorwith appropriate context
information, including an errorname of
resource-error.

4.4 The resource
Element

When it appears as the first child element of submission, the
resource element overrides the action attribute and
allows the URI used for submission to be dynamically calculated based on
instance data. Due to the ability to specify the URI with the
resource element, the action attribute is not
mandatory on a submission, but one of the action
attribute and the resource child element is mandatory.

Common Attributes: Common, Events

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

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

Common Attributes: Common, Events

Special Attributes:

name

Required attribute containing a string for the name of the header.
If the string is empty, then the header element is
ignored.

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 can be specified with either the value
attribute or the string content of the header element. If both
are specified, then the value attribute takes precedence.

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

action (xsd:anyURI) or resource
element

method (xsd:string, enumerated below)

header elements

For the URI scheme obtained from the actionattribute 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 scheme

method

Serialization

Submission

http https mailto

"post"

application/xml

HTTP POST or equivalent

http https file

"get"

application/x-www-form-urlencoded

HTTP GET or equivalent

http https file

"put"

application/xml

HTTP PUT or equivalent

http https mailto

"multipart-post"

multipart/related

HTTP POST or equivalent

http https mailto

"form-data-post"

multipart/form-data

HTTP POST or equivalent

http https mailto

"urlencoded-post"

application/x-www-form-urlencoded

HTTP POST or equivalent

(any)

any other QNAME with no prefix

N/A

N/A

(any)

any QNAME with a prefix

implementation-defined

implementation-defined

Note:

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

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

4.8 Integration with SOAP

4.8.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.8.2 Indicating a SOAP
submission

For a SOAP submission, the mediatype attribute of the
submissionmust 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.8.3 SOAP HTTP
Binding

The method attribute of the submissionmust 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:

If the submission mediatype contains a
charset MIME parameter, then it is appended to the 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
ContentType 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 ContentType 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.8.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.

4.9 New Submission
Methods

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

5 User Interface
Improvements and Changes

5.1 Inline Rendition of
Non-Text Media Types

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

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

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

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

If the mediatype attribute or element is given, then the 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 is of type xsd:base64Binary, then
the data is base-64 decoded.

If the instance node is of type xsd:hexBinary, then the
data is hex-binary decoded.

If the instance node is of 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.

Editorial note

What of types derived from
base64Binary, hexBinary and anyURI? The question for anyURI seems a
bit more near-term than the one for base64Binary and hexBinary.

The rendition of the output is updated if the referenced node
or its content or if the media type changes. The media type can change due
to DOM mutation of the content of the mediatype attribute or
element or by a change to the mediatype element's referenced
node or its content.

Failure to render the content indicated by the output element
should result in an
xforms-output-error, a non-fatal error that does not halt XForms
processing. Failures can occur for many reasons, including

Data to be decoded does not conform to the format of
xsd:base64Binary or xsd:hexBinary

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

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

An unrecognized media type identifier string

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

<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 Remove Linking
Attributes from Actions and Metadata Elements

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

5.4 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.5 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 form controls in 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 nodes from the containing
repeat element(s). Similarly, a toggle element may
have one or more repeat element ancestors, so a single
toggle element corresponds to one or more run-time toggle
objects. In this case, the indexes of the repeat
element(s) that contain the switch and the toggle
as well as the document location of the switch relative to the
toggle are used to determine which switch object is to
be manipulated by a toggle object.

The toggle action is performed by a run-time toggle object. The
toggle action begins IDREF resolution by searching the document for the
case element identified by the case attribute of
the toggle object. If the document does not contain a
case element with the matching ID, then the toggle action has no
effect. Otherwise, the switch element containing the
case is obtained. Then, the ancestor repeat
elements of the switch element are partitioned into two subsets,
those in common with the toggle element and those that are not
in common. For the repeat elements that are in common, the
desired switch object exists in the set of run-time objects
containing the toggle object. Finally, for each ancestor
repeat of the switch element that is not in common
with the toggle element, the current index of the
repeat determines the set of run-time objects that contains the
desired switch object that is toggled.

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. Thus, XForms 1.1 would have this functionality by virtue of its
availability as of XForms 1.0 Third Edition.

5.6 Support help
and hint in item and choices

In XForms 1.0, help and hint are possible
children of item because the content model of item
is (UI Common)*. In XForms 1.1, help and hint are
also allowed as children of choices in order to provide
additional information about groups of items in lists.

Example: Using help/hint in lists

Given the following form:

<xf:select1 ref="/my:root/my:color">
<xf:label>Choose a color </xf:label>
<xf:hint>Colors are non-verbal communication. They create a physical and emotional reaction.</xf:hint>
<xf:help>Select the color that you like the most</xf:help>
<xf:choices>
<xf:label>Cool Colors</xf:label>
<xf:hint>Cool colors tend to have a calming effect</xf:hint>
<xf:help>Select one of these, if you wish to choose a cool color</xf:help>
<xf:item>
<xf:label>Blue</xf:label>
<xf:value>#0000ff</xf:value>
<xf:hint>strong, important, peaceful, intelligent</xf:hint>
<xf:help>Select this if you like blue</xf:help>
</xf:item>
<!-- other cool colors... -->
</xf:choices>
<!-- further choices/items for warm and neutral colors... -->
</xf:select1>

The content model of
itemset has deliberately not been modified because there
is no defined method for events to propagate from generated
content

Editorial note

Adding (UI.Common)* to the
content model of choices might be a clearer approach
rather than explicitly adding help and
hint. This would allow alert and
action elements on choices; which seems
like a good idea at this time.

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.