This document is also available in these non-normative formats: diff-marked HTML.
Copyright © 2005 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. Patent disclosures relevant to this specification may be found on the XForms Working Group's public patent disclosure page. As of this publication, the XForms Working Group are not aware of any royalty-bearing patents they believe to be essential to XForms 1.1.
1 Introduction
1.1 Reading the Specification
1.2 How the Specification is Organized
1.3 Documentation Conventions
2 XForms Core
2.1 Namespaces for XForms 1.1
2.1.1 No-namespace schema for XForms 1.1
2.1.2 Namespaced schema for XForms 1.1
2.2 Utility Functions used in XPath Expressions
2.2.1 The power() Function
2.2.2 The luhn() Function
2.2.3 The current() Function
2.2.4 The choose() Function
2.2.5 The id() Function
2.2.6 The property() Function
2.2.7 Modification to Exceptions Generated by Errors in Functions
2.3 Accessing Context Information for Events
2.4 New Data Type: Email address
2.5 New Data Type: ID Card Number
2.6 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 close Action Element
3.2.1 The xforms-close Event
3.3 The prompt Action Element
3.4 Conditional Execution of XForms Actions
3.5 Iteration of XForms Actions
3.6 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.3 Integration with SOAP
4.3.1 Representation of SOAP Envelope
4.3.2 Indicating a SOAP submission
4.3.3 SOAP HTTP Binding
4.3.4 Handling the SOAP Response
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
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 Changes (Non-Normative)
D Acknowledgements (Non-Normative)
E Production Notes (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/2004/xforms/)
html: The XHTML 2.0 namespace
ev: The XML Events namespace [XML Events]
my: Any user defined namespace
This is only a convention; any namespace prefix may be used in practice.
The following typographical conventions are used to present technical material in this document.
The XML representations of various elements within XForms are presented using the syntax for Abstract Modules in XHTML Modularization [XHTML Modularization].
Examples are set off typographically:
Example Item
References to external documents appear as follows: [Sample Reference] with links to the references section of this document.
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. |
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/2004/xforms/
<switch xmlns="http://www.w3.org/2004/xforms/"> <case id="in" selected="true"> <input ref="yourname"> <label>Please tell me your name</label> <toggle ev:event="DOMActivate" case="out"/> </input> </case> <case id="out" selected="false"> <html:p>Hello <output ref="yourname" /> <trigger id="editButton"> <label>Edit</label> <toggle ev:event="DOMActivate" case="in"/> </trigger> </html:p> </case> </switch>
The above example is unchanged from the specification in XForms 1.0 with the exception that the new XForms 1.1 namespace is used (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.
Examples (see also 2.5 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('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.
node-set event(string)
Function event
returns context specific information determined by the string
argument. The context information is always returned as an element node with a local name
equal to the parameter name and no namespace URI.
Each events will describe what properties can be accessed by this function. The following is a list of
the properties accessible with the XForms 1.0 events (these are all of type xsd:string
):
xforms-insert
,
xforms-delete
xform-submit-error
,
xforms-link-exception
,
xforms-link-error
,
xforms-compute-exception
Editorial note | |
The xforms-insert and xforms-delete events may need more information to help support decoupling of insert and delete actions from the index updating requirements of the repeat module. See 3.1 Modifications to the insert and delete Actions. |
Examples:
event("description")
Returns a node with either empty content or, if called from an appropriate event handler, the context information defined for the event (e.g. the path expression used for insert/delete).
event("errorinformation")
If called from an appropriate event handler, the returned node contains the context information (e.g. the URI that failed to load for an xforms-link-exception). The returned node content is empty if there is no context information for the event.
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/> <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)
Special Attributes:
Optional XPath expression used to override the in-scope evaluation context for the insert
element.
If the 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 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.
Editorial note | |
The working group is discussing how origin and context might be
able to IDREF a bind nodeset. This may be possible by interpreting non-nodeset
result as an IDREF (with xforms-binding-exception on failure). |
Editorial note | |
The working group is discussing modularization of the XForms model and actions such as insert ,
which would require decoupling repeat index updating. One way this may be achieved is by having
the repeat module set up a listener on the model for the capture phase of xforms-insert
to do the updating. The event context would have to carry a pointer to the inserted node so that the each
repeat's listener could determine whether the insertion is applicable to it. |
... <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)
Special Attributes:
Optional XPath expression used to override the in-scope evaluation context for the delete
element.
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 if="not(/purchaseOrder/item)" context="/purchaseOrder" 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.
Editorial note | |
Further to the point of consistency, it seems prudent to consider adding context to
the Node Set Binding attribute bundle so it can be consumed by not just insert and
delete but also repeat (and itemset ). Aside from consistency,
this might also help with formulating a reasonable relaxation of the definition of
homogeneous collection. |
Editorial note | |
The working group is discussing how context might be
able to IDREF a bind nodeset. This may be possible by interpreting non-nodeset
result as an IDREF (with xforms-binding-exception on failure). |
Editorial note | |
The working group is discussing modularization of the XForms model and actions such as delete ,
which would require decoupling repeat index updating. One way this may be achieved is by having
the repeat module set up a listener on the model for the capture phase of
xforms-delete to do the updating. The event context would have to carry a pointer to
the delete context node, the parent of the deleted node, and the orphaned deleted node so that
each repeat's listener could determine whether the deletion is applicable to it. |
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.
model
Yes
Yes
None.
The default action for this event results in the following: Close down the owner document.
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="lnsertControl" 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>
TBD
In XForms 1.0, the deferred update behavior would choose to run rebuild, recalculate, revalidate and refresh actions directly, bypassing the event system. In XForms 1.1, the events are dispatched as needed.
The detection of the need for deferred update is managed at the level of the XForms model. When XForms action B runs as the result of another XForms action A, then the deferred update behavior of B is further deferred to the completion of A, regardless of whether B is a descendant of A in the XML markup.
Dispatched by the processor immediately before serializing the instance data for submission (immediately before step 3, Section 11.1, XForms 1.0).
Target: submission
Bubbles: Yes
Cancelable: No
Context Info: A node into which data to be submitted can be placed.
The default action for this event is to perform the normal XForms submission serialization if the event context node's content is empty. The content of the event context node is the data sent by the XForms 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 will still be validated according to the rules defined for the xforms-revalidate
event but an xforms-submit-error
will not be dispatched if there is a validation error allowing submission processing to proceed.
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 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, which results in the use of the application/xml
serialization rules.
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.
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.
The default action for this event is nothing; 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. |
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 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 redefining the xforms prefix to be the namespace URI of XForms 1.1, there are some behavioral changes that have been made to elements and features that existed in XForms 1.0. Therefore, some XForms 1.0 forms will require some adjustments beyond simply changing the namespace URI.
This document was produced with the participation of current XForms Working Group participants: