This document is also available in these non-normative formats: diff-marked HTML.
Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
XForms 1.1 refines the XML processing platform introduced by XForms 1.0 by adding several submission capabilties, 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.
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 XForms Working Group as part of the XForms Activity within the W3C Interaction Domain. The authors of this document are the XForms 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 was produced by a group operating under 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.
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 Utility Functions used in XPath
Expressions
2.3.1 The power() Function
2.3.2 The luhn() Function
2.3.3 The current() Function
2.3.4 The choose() Function
2.3.5 The id() Function
2.3.6 The property() Function
2.3.7 Modification to Exceptions
Generated by Errors in Functions
2.4 Accessing Context Information for Events
2.4.1 The xforms-insert Event
2.4.2 The xforms-delete Event
2.4.3 The xforms-submit-error Event
2.4.4 The xforms-submit-done
Event
2.4.5 The xforms-link-exception
Event
2.4.6 The xforms-link-error Event
2.4.7 The xforms-compute-exception
Event
2.5 New Data Type: Email address
2.6 New Data Type: ID Card Number
2.7 XForms Datatypes to Allow Empty
Content
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 close Action Element
3.3.1 The xforms-close Event
3.4 The prompt Action Element
3.5 Conditional Execution of XForms
Actions
3.6 Iteration of XForms Actions
3.7 Modifications to Deferred Update Behavior
of Actions
4 Submission
4.1 New Submission Events
4.1.1 The xforms-submit-serialize
Event
4.2 New Submission Attributes
4.2.1 The validate attribute on
element submission
4.2.2 The relevant attribute on
element submission
4.2.3 The mode attribute on element
submission
4.3 Changed Submission Events
4.3.1 The xforms-submit Event
4.4 The resource Element
4.5 The header Element
4.6 Submission Options
4.7 The get Submit Method
4.8 Integration with SOAP
4.8.1 Representation of SOAP Envelope
4.8.2 Indicating a SOAP submission
4.8.3 SOAP HTTP Binding
4.8.4 Handling the SOAP Response
4.9 New Submission Methods
4.9.1 The delete submission
method
5 User Interface Improvements and Changes
5.1 Inline Rendition of Non-Text Media
Types
5.1.1 The xforms-output-error
Event
5.2 Add UI Common to output
5.3 Remove Linking Attributes from Actions and
Metadata Elements
5.4 Appearance Hint for
Triggers
5.5 Support switch in repeat
5.6 Support help and hint in item and
choices
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
A Schema for XForms 1.1
B References
B.1 Normative References
B.2 Informative References
C Acknowledgements (Non-Normative)
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].
The specification is organized as a set of changes relative to [XForms 1.0]. Chapters are arranged by topic.
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 Item
References to external documents appear as follows: [Sample Reference] with links to the references section of this document.
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. |
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
.
Target: the default model
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
errorinformation | string | An implementation-specific error string |
<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.
The XML Schema definition of XForms 1.1 is available in two forms.
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.
<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.
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
<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).
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
).
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.6 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
.
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
.
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.
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.
string property(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
.
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.
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 :
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.
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. |
node | node-set | The parent of the instance data node deleted. |
Default Action: None; notification event only.
Dispatched as an indication of: failure of a submission process
Target: submission
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
errorname | string | Either
submission-in-progress , no-data ,
validation-error , parse-error or
resource-error . |
errorinformation | string | The submission method URI that failed (xsd:anyURI) |
code | number when available, node-set when not | 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.
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.
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.
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.
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.
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.
This type defines the basic structure of an ID number that conforms to [ISO 7812-1:2000]. Various ID cards use this
standard as the format for their numbers including those issued by Financial
Institutions for Debit and Credit cards. The ID number is a pattern
restriction on xsd:string
: it must be between 12 and 19 digits
(0 - 9).
:<xsd:simpleType name="ID-card-number"> <xsd:annotation> <xsd:documentation> This type defines an ID number that conforms to ISO/IEC 7812-1:2000 Identification cards -- Identification of issuers -- Part 1: Numbering system. This type does not apply the Luhn checksum algorithm. </xsd:documentation> </xsd:annotation> <xsd:restriction base="xsd:string"> <xsd:minLength value="12"/> <xsd:maxLength value="19"/> <xsd:pattern value="[0-9]+"/> </xsd:restriction> </xsd:simpleType>
The standard defines the structure of the number as well as how to apply
the Luhn formula to ensure a correct check digit. This type only specifies
the format of the number. The complementary XPath function
luhn()
should be used to validate that the ID number conforms to
the specification.
<xforms:model> <xforms:instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number>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.
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.
insert
and delete
ActionsXForms 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.
insert
ActionThe 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:
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.
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.
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
.
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
.
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
The insert
action is successfully completed by
dispatching the xforms-insert
event.
... <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.
... <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> ...
<insert nodeset="some/node"/>
<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.
repeat
, whether or not it is
emptyWhen 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>
delete
ActionThis 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:
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.
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 XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
The delete
action is successfully completed by
dispatching the event xforms-delete
.
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"
, but the context
attribute was added for consistency with the insert
action.
load
ActionThis 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.
close
Action ElementThis action is used to dispatch an xforms-close
event to a
model.
Common attributes: Common, Events
Special attributes: None
Dispatches an xforms-close
event to the default model.
<trigger> <label>Close</label> <close ev:event="DOMActivate"/> </trigger>
xforms-close
EventThis 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.
prompt
Action ElementThis 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+
<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).
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.
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> ...
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>
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.
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 <= 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>
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.
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
.
Dispatched at the beginning of submission
serialization (see
4.3.1 The xforms-submit Event).
Target: submission
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
data | string (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 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.
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
.
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()
.
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.
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-error
with 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-error
with 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-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 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-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 errorname
of
resource-error
.
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:
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.
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:
Required attribute containing a string for the name of the header.
If the string is empty, then the header
element is
ignored.
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.
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 action
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 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.
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.
This section describes the integration of XForms submission with [SOAP 1.1] and [SOAP 1.2]
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).
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.
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 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.
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.
delete
submission methodElement 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
.
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. |
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 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
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.
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="/data" mediatype="image/*"> <xforms:message ev:event="xforms-output-error" level="ephemeral">Error in image data.</xforms:message> </xforms: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>
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.
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.
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. |
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.
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>
See also the full example
The hint
for the first choices
element could be
rendered like this:
The hint
for the first item
element could be
rendered like this:
Editorial note | |
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. |
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.
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.
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.
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.
This document was produced with the participation of current XForms Working Group participants: