1 About the XForms 1.0 Specification
1.1 Background
Forms are an important part of the Web, and they continue to be the
primary means of interactivity used by many Web sites. Web applications and
eCommerce solutions have sparked the demand for better web forms with richer
interactions. XForms are the response to this demand—extended analysis,
followed by the creation of a new platform-independent markup language for
online interaction between an XForms
Processor and a remote entity. XForms are the successor to HTML
forms, and benefit from the lessons learned in the years of HTML forms
implementation experience.
Further background information on XForms can be found at
http://www.w3.org/MarkUp/Forms.
1.2 Reading the Specification
This specification has been written with various types of readers in
mind—in particular XForms authors and XForms implementors. We hope the
specification will provide authors with the tools they need to write efficient,
attractive, and accessible documents, without overexposing them to the XForms
implementation details. Implementors, however, should find all they need to
build conforming XForms Processors. The specification begins with a general
presentation of XForms and becomes more and more technical and specific towards
the end. For quick access to information, a general table of contents, specific
tables of contents at the beginning of each section provide easy
navigation.
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 may, must, and
should in accord with RFC 2119.
1.3 How the Specification is Organized
The specification is organized into the following chapters:
- Chapters 1 and 2
-
An introduction to XForms. The introduction includes a brief
tutorial on XForms, and a discussion of design principles.
- Chapters 3 and up
-
XForms reference manual. The bulk of the reference manual consists
of the specification of XForms. This reference defines XForms and how XForms
Processors must interpret the various components in order to claim
conformance.
- Appendices
-
Appendixes contain a normative description of XForms described in
XML Schema, information on references, and other useful information.
1.4 Documentation Conventions
The following highlighting and typography is used to present technical
material in this document:
Throughout this document, the following namespace prefixes
and corresponding namespace identifiers are used:
xforms: The XForms namespace
4.1 The XForms Namespace
html: The XHTML namespace
[XHTML 1.0]
xsd: The XML Schema namespace
[XML Schema part 1]
xsi: The XML Schema for instances namespace
[XML Schema part 1]
xlink: The XLink namespace [XLink]
ev: The XML Events namespace
[XML Events]
my: Any user defined namespace
This is by convention only; any namespace prefix may be used in
practice.
Official terms are defined in the following manner:
[Definition: You can find most terms in the
chapter 3 Terminology]. Links to terms may be specially highlighted in the text, though
typically only on introductory usage or when special attention needs to be
directed toward the term.
The XML representations of various elements within XForms are presented
as follows: Listed are the element name, names of all attributes, allowed
values of attributes appearing after a "=" character, default values
of attributes appearing after a ":" character, and allowed content.
One or more headings below the table provide additional explanatory
information.
Example: XML Syntax Representation <example>
<example
count = xsd:integer
size = (small | medium | large) : medium
>
<!-- Content: (allowed-content) -->
</example>
count - description of this
attribute
size - description
of this attribute
Certain common attributes 4.2 Horizontally Applicable
Markup are
not shown in the syntax representations except when special attention needs to
be called to their presence.
Non-normative short examples are set off typographically:
Example Item
or
References to external documents appear as follows:
[Sample Reference] with links to the references section of this
document.
- Sample Reference
- Reference - linked to from
above.
The following highlighting is used for non-normative commentary:
Note:
A general admonition to readers.
| Editorial note: Editorial Note Name | |
| Editorial commentary, not intended for final
publication. |
Issue (issue-id):
Issue-Name
A specific issue to which input from readers is requested, not
intended for final publication.
For diff-marked formatted text, note that newly added text appears like
this, changed text appears like this, and deleted text appears like
2 Introduction to XForms
This informative chapter provides an easily approachable description of
the design of XForms, describing the major components and how they relate. Not
every feature of XForms is covered here. For a complete, normative description
of XForms, refer to the remainder of this document.
2.1 Purpose and Presentation
For explanatory purposes, a form can be considered to consist of
'purpose', 'presentation', and 'data'. Some examples:
| Purpose |
Presentation |
Data |
| Data collection |
Arrangement of form controls |
Registration information |
| Time card |
How dates are entered |
Days and hours worked |
| Order form |
How to render the form controls on small devices |
Order, shipping, and payment info |
| Information Please |
How the form integrates with a Web site |
User contact information |
The design of HTML forms didn't separate the purpose of a form from its
presentation; additionally, they only offered a restricted representation for
data captured through the form.
Here is a summary of the primary benefits of using
XForms:
- Strong typing
-
Submitted data is strongly typed and can be checked using
off-the-shelf tools. Type validation rules help client-side validation.
- Re-use existing schema.
-
This obviates duplication, and ensures that updating the
validation rules as a result of a change in the underlying business logic does
not require re-authoring validation constraints within the XForms application.
- Annotate external schema
-
This enables the XForms author go beyond the basic set of
constraints available from the back-end. Providing such additional constraints
as part of the XForms Model enhances the overall usability of the resulting web
application.
- Submit XML.
-
This obviates the need for custom server-side logic to marshall
the submitted data to the application back-end. The received XML instance
document can be directly validated and processed by the application back-end.
- Internationalization
-
Using XML 1.0 ensures that the submitted data is
internationalized.
- Enhanced accessibility.
-
XForms separates content and presentation. User interface
controls encapsulate all relevant metadata such as labels, thereby enhancing
accessibility of the application when using different modalities.
- Multiple device support.
-
The high-level nature of the user interface controls, and the
consequent intent-based authoring of the user interface makes it possible to
re-purpose the user interaction to different devices.
- Declarative event handlers.
-
By defining XML-based declarative event handlers such as
setFocus, message, and setValue that cover common
use cases, the majority of XForms documents remain statically analyzable as
opposed to imperative program code.
2.2 Current Approach: HTML
Consider a simple eCommerce form authored in HTML:
<html>
<head>
<title>eCommerce Form</title>
</head>
<body>
<form action="http://example.com/submit" method="post">
<table summary="Payment method selector">
<tr>
<td><p>Select Payment Method:</p></td>
<td><label><input type="radio" name="as" value="cash"/>Cash</label>
<label><input type="radio" name="as" value="credit"/>Credit</label></td>
</tr>
<tr>
<td><label for="cc">Credit Card Number:</label></td>
<td><input type="text" name="cc" id="cc"/></td>
</tr>
<tr>
<td><label for="exp">Expiration Date:</label></td>
<td><input type="text" name="exp" id="exp"/></td>
</tr>
<tr>
<td colspan="2"><input type="submit"/></td>
</tr>
</table>
</form>
</body>
</html>A browser might render this form as follows:
This form makes no effort to separate purpose (data collection
semantics) from presentation (the input form controls), and offers no
control over the basic name/value pair serialization of the resulting data. The
XForms standard greatly improve the expressive capabilities of electronic
forms.
2.3 Transition to XForms
| Editorial note: T. V. Raman | |
Note that xforms:xform from the previous
draft is now renamed to xforms:model; the earlier
xforms:model is now named xforms:schema |
With the XForms approach, forms are comprised of a section
that describes what the form does, called the XForms Model, and another section that
describes how the form is to be presented. The only presentation option defined
in the XForms 1.0 specification is the XForms User Interface, which is a
device-independent, platform-neutral set of form controls suitable for general-purpose
use. This flexible architecture, however, allows others to attach user
interfaces to an XForms Model, as illustrated here:
The simplest case involves authoring the new XForms form controls,
leaving out the other sections of the form. To convert the previous form into
XForms this way, a model element is needed in the head
section of the document:
<xforms:model>
<xforms:submitInfo action="http://examples.com/submit" id="submit"/>
</xforms:model>
With these changes to the containing document, the previous example
could be rewritten like this (note that we have intentionally defaulted the
XForms namespace prefix in this example):
<selectOne ref="as">
<caption>Select Payment Method</caption>
<choices>
<item>
<caption>Cash</caption>
<value>cash</value>
</item>
<item>
<caption>Credit</caption>
<value>credit</value>
</item>
</choices>
</selectOne>
<input ref="cc">
<caption>Credit Card Number</caption>
</input>
<input ref="exp">
<caption>Expiration Date</caption>
</input>
<submit>
<caption>Submit</caption>
</submit>Notice the following features of this design:
-
The user interface is not hard-coded to use radio buttons. Different
devices (such as a voice browser) can render the concept of
"selectOne" as appropriate.
-
Form controls always have captions directly associated with them, as
child elements—this is a key feature designed to enhance the
accessibility of forms.
-
There is no need for an enclosing form element, as in HTML.
See (See 2.6 Multiple Forms per Document for details on how to author
multiple forms per page)
-
Markup for specifying form controls has been simplified
-
Data gets submitted as XML.
With these changes, the XForms
Processor will be able to directly submit XML instance data. The XML
is constructed by creating a root element with child elements reflecting the
names specified in each form control via attribute ref. In this
example, the submitted data would look like this:
<instanceData>
<as>Credit</as>
<cc>1235467789012345</cc>
<exp>2001-08</exp>
</instanceData>
2.4 Providing XML Instance Data
Authors will often desire greater control over exact construction of the
submitted instance data. XForms allows data to be checked
for validity interactively as the form is being filled.
XForms processing keeps track of the state of the partially filled form
through instance data, which
provides an outline of the desired XML data in the form of a skeleton XML
instance, including namespace information. The instance data starts off with
any initial values for the form, is updated as the user fills the form, and
eventually is serialized and submitted. The initial instance data is defined in
the instance element inside the model element, as
follows:
<xforms:model>
<xforms:instance>
<payment as="credit" xmlns="http://commerce.example.com/payment">
<cc/>
<exp/>
</payment>
</xforms:instance>
<xforms:submitInfo action="http://example.com/submit" method="post"/>
</xforms:model>This design has features worth calling out:
-
There is complete flexibility in the structure of the XML. Notice
that XML namespaces are now used, and that a wrapper element of the author's
choosing wraps the instance data.
-
Empty elements cc and exp serve as placeholders in
the XML structure, and will be filled in with form data provided by the
user.
-
An initial value ("credit") for the form control is provided through the instance data, in this
case an attribute as. In the submitted XML, this initial value will
be replaced by the user input, if any.
To connect this instance data with form controls, the ref
attributes on the form controls need to point to the proper part of the
instance data, using binding
expressions:
.. xmlns:my="http://commerce.example.com/payment"...
<xforms:selectOne ref="my:payment/@as">
...
<xforms:input ref="my:payment/my:cc">
...
<xforms:input ref="my:payment/my:exp">Binding expressions are based on XPath [XPath 1.0],
including the use of the @ character to refer to attributes, as seen here.
2.5 Constraining Values
Referring to the earlier HTML form in 2.2 Current Approach: HTML,
there are several aspects that would be desirable to express, but would only be
possible through the addition of unstructured script code:
-
The credit card information form controls cc and exp are only relevant if the "credit" option is chosen in the as form control.
-
The credit card information form controls cc and exp should be required when the "credit" option is chosen in the as form control.
-
The form control cc should accept digits only, and should have between 14 and 18
digits.
-
The form control exp should accept only valid month/date combinations.
By specifying an additional component,
model item
constraints, authors can include rich declarative datatype and
validation information in forms, taken from XML Schema
datatypes and also XForms-specific constraints, such as relevant.
XForms
constraints appear on bind elements, while
Schema constraints are expressed
in an XML Schema fragment, either inline or external. For example:
... xmlns:my="http://commerce.example.com/payment"...
<xforms:bind ref="my:payment/my:cc"
relevant="my:payment/[@as == 'credit']"
required="true"
type="my:cc"/>
<xforms:bind ref="my:payment/my:exp"
relevant="my:payment/[@as == 'credit']"
required="true"
type="xsd:gYearMonth"/>
<xforms:schema>
<xsd:schema ...>
...
<xsd:simpleType name="cc">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{14,18}"/>
</xsd:restriction>
</xsd:simpleType>
...
</xsd:schema>
</xforms:schema>
2.6 Multiple Forms per Document
XForms processing places no limits on the number of individual forms
that can be placed in a single containing document. When multiple
forms share the same containing document, multiple model elements are
needed. The first model element may omit a unique id
attribute (as have all the examples above), but subsequent model
elements require an id so that they can be referenced from elsewhere
in the containing document.
The other side of the equation is that form controls throughout the
document need to specify which model element contains the instance
data to which they bind. This is accomplished through a model
attribute alongside the ref attribute. this. The default for the
model attribute is to refer to the first model element in
document order.
To add a second form, an opinion poll, to our commerce example, the
following would be authored in the head section of the document:
<xforms:model>
<xforms:instance>
...payment instance data...
</xforms:instance>
<xforms:submitInfo action="http://example.com/submit" method="post"/>
</xforms:model>
<xforms:model id="poll">
<xforms:submitInfo .../>
</xforms:model>Additionally, the following markup would appear in the body section of
the document:
<xforms:selectOne ref="pollOption" model="poll">
<xforms:caption>How useful is this page to you?</xforms:caption>
<xforms:choices>
<xforms:item>
<xforms:caption>Not at all helpful</xforms:caption>
<xforms:value>0</xforms:value>
</xforms:item>
<xforms:item>
<xforms:caption>Barely helpful</xforms:caption>
<xforms:value>1</xforms:value>
</xforms:item>
<xforms:item>
<xforms:caption>Somewhat helpful</xforms:caption>
<xforms:value>2</xforms:value>
</xforms:item>
<xforms:item>
<xforms:caption>Very helpful</xforms:caption>
<xforms:value>3</xforms:value>
</xforms:item>
</xforms:choices>
</xforms:selectOne>
<xforms:submit submitInfo="poll">
<xforms:caption>Submit</xforms:caption>
</xforms:submit>The main difference to note here is the use of model="poll", which identifies which form the form control binds to.
2.7 Complete Document
This chapter has presented various bits and pieces of XForms as a tool
to help readers understand the design. For convenience, the
entire document is given here in one piece..
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:xforms="http://www.w3.org/2001/12/xforms"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:my="http://commerce.example.com/payment"
xml:lang="en">
<head>
<title>XForms in XHTML</title>
<xforms:model>
<xforms:instance>
<payment as="credit" xmlns="http://commerce.example.com/payment">
<cc/>
<exp/>
</payment>
</xforms:instance>
<xforms:schema xlink:href="payschema.xsd"/>
<xforms:submitInfo action="http://example.com/submit" method="post"/>
<xforms:bind ref="my:payment/my:cc"
relevant="my:payment/@as == 'credit'"
required="true" type="my:cc"/>
<xforms:bind ref="my:payment/my:exp"
relevant="my:payment/@as == 'credit'"
required="true" type="xsd:gYearMonth"/>
</xforms:model>
</head>
<body>
...
<group xmlns="http://www.w3.org/2001/12/xforms" ref="my:payment">
<selectOne ref="@as">
<caption>Select Payment Method</caption>
<choices>
<item>
<caption>Cash</caption>
<value>cash</value>
</item>
<item>
<caption>Credit</caption>
<value>credit</value>
</item>
</choices>
</selectOne>
<input ref="my:cc">
<caption>Credit Card Number</caption>
</input>
<input ref="my:exp">
<caption>Expiration Date</caption>
</input>
<submit>
<caption>Submit Form</caption>
</submit>
</group>
...
</body>
</html>
7 XPath Expressions in XForms
XForms uses XPath to address instance data nodes in binding
expressions, to express constraints, and to specify calculations.
7.1 Datatypes
XPath data types are used only in Binding expressions and
computed expressions. XForms
uses XPath datatypes boolean, string, number and node-set. A future version of XForms is expected to use XPath 2.0, which
includes support for XML Schema datatypes.
7.2 Instance Data
For each model element, the XForms processor maintains the
state in an internal structure called instance
data that conforms to the XPath Data Model
[XPath 1.0]. Elements and attributes in the instance data may
have namespace information associated with them, as defined in the XPath Data
Model. Unless otherwise specified, all instance data elements and attributes
are unqualified. In addition, XForms processors must provide
DOM access to this instance data via the interface defined below.
interface XFormsModelElement : org.w3c.dom.Element
The method getInstanceDocument returns a DOM Document that
corresponds to the instance data associated with this XForms Model.
Return value: org.w3c.dom.Document
raises (DOMException); if there is no model with the
specified model-id.
7.3 Evaluation Context
Within XForms, XPath expressions reference abstract instance data
(using the "path" portion of XPath), instead of a concrete XML
document. This reference is called a binding expression in this
specification. Every XPath expression requires an evaluation context. The
following rules are used in determining evaluation context when evaluating
binding expressions in XForms:
-
The context node for outermost form
control elements is the XPath root (/). A " form control element" is any
element other than bind that is explicitly
allowed to have a binding expression attribute. A form control element is
"outermost" when the node-set returned by the XPath
expression ancestor::* includes no form control element nodes.
-
The context node for non-outermost form
control elements is the first node of the
binding expression of the immediately enclosing element. An element is
"immediately enclosing" when it is the first form
control element node in the node-set returned by the XPath expression ancestor::*. This is also referred to as "scoped resolution".
-
The context node for the ref attribute on
bind is the XPath root. The context node for other attributes of
bind is the first node of the node-set returned from the binding
expression in the sibling ref attribute.
-
The context size and position are both exactly 1.
-
No variable bindings are in place.
-
The available function library is defined below.
-
Any namespace declarations in scope for the attribute that defines
the expression are applied to the expression.
Example: Binding Expression Context
Nodes
<group ref="level1/level2/level3">
<selectOne ref="elem" ... />
<selectOne ref="@attr" ... />
</group>
In this example, the group has a binding expression of level1/level2/level3. According to the rules above, this outermost element would have a
context node of /, which is the root of the instance data, or the parent to the
elem element. Both of the selectOnes then inherit a context node from their parent, the context node being /level1/level2/level3. Based on this, the selectOne binding expressions evaluate respectively to /level1/level2/level3/elem and /level1/level2/level3/@attr. Matching instance data follows:
Example: Sample Instance
<level1>
<level2>
<level3 attr="xyz">
<elem>xyz</elem>
</level3>
</level2>
</level1>
7.4 Forms Core Function Library
The XForms Core Function Library includes the entire
[XPath 1.0] Core Function Library, including operations on
node-sets, strings, numbers, and booleans.
This section defines a set of required functions for use within
XForms.
7.4.1 Boolean Methods
7.4.1.1 boolean-from-string()
boolean boolean-from-string(string)
Function boolean-from-string returns true if the required parameter string is "true", or false if parameter string is "false". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression. If the parameter
string matches neither "true" nor "false", according to a case-insensitive
comparison, processing stops with a fatal error.
7.4.1.2 if()
string if(boolean, string, string)
Function if evaluates the first
parameter as boolean, returning the second parameter when true, otherwise the third parameter.
7.4.2 Number Methods
Note:
The XPath number datatype and associated methods and
operators use IEEE specified representations. XForms Basic Processors are not
required to use IEEE, and thus might yield slightly different results.
7.4.2.1 avg()
number avg(node-set)
Function avg returns the arithmetic average of
the result of converting the string-values of each node in the argument
node-set to a number. The sum is computed with sum(), and divided with div by the value computed with count().
7.4.2.2 min()
number min(node-set)
Function min returns the minimum value of the
result of converting the string-values of of each node in argument node-set to a number. "Minimum" is determined with the < operator. If the parameter is an empty node set, the
return value is NaN.
7.4.2.3 max()
number max(node-set)
Function max returns the maximum value of the
result of converting the string-values of each node in argument node-set to a number. "Maximum" is determined with the < operator. If the parameter is an empty node set, the
return value is NaN.
7.4.2.4 count-non-empty()
number count-non-empty(node-set)
Function count-non-empty returns the number of
non-empty nodes in argument node-set. A node is considered non-empty if it is convertible into a string with
a greater-than zero length.
7.4.2.5 cursor()
number cursor(
string )
Function cursor takes a string
argument that is the idref of a repeat and returns the current position of the repeat
cursor for the identified repeat—see 10.3 Repeating Structures
for details on repeat and its associated repeat cursor. If the
specified argument does not identify a repeat, this function throws an
error.
Example: cursor
<xforms:button>
<xforms:caption>Add to Shopping Cart</xforms:caption>
<xforms:insert ev:event="ev:activate" position="after"
nodeset="items/item" at="cursor('cartUI')"/>
</xforms:button>
7.4.3 String Methods
7.4.3.1 property()
string property(string)
Function property returns the XForms Property
named by the string parameter.
The following properties are available for reading (but not
modification).
- version
-
version is defined as the string "1.0" for XForms 1.0
- conformance-level
-
conformance-level strings are defined in 12 Conformance.
Example: property
<xforms:instance>
...
<xforms:bind ref="info/xforms-version" calculate="property('version')"/>
...
</xforms:instance>
7.4.3.2 now()
string now()
The now function returns the current system
date and time as a string value in the canonical Schema xsd:dateTime format. If time zone information is available, it is included
(normalized to UTC).
8 Form Controls
XForms User Interface controls, also called
form controls, are declared using
markup elements, and their behavior refined via markup attributes. This markup
may be further decorated with class attributes that can be used in
CSS stylesheets to deliver a customized look and feel. XForms user interface
controls are bound to the underlying instance data using
binding attributes as defined in the
chapter 6 Constraints.
Form controls enable accessibility by taking a uniform approach to such
features as captions, help text, tabbing and keyboard shortcuts.
Internationalization issues are addressed by
following the same design principles as in XHTML. All form controls are
suitable for styling using Aural CSS (ACSS) style properties.
Form controls are as general and high-level as possible without
sacrificing the ability to deliver real implementations. For instance, to
select one or more items from a set, form controls
selectOne and selectMany, are provided. Form controls
distinguish the functional aspects of the underlying control, from the
presentational aspects (through class attributes) and behavior
(through XForms Action elements). This separation enables the expression of the
intent underlying a particular form control—see
[AUI97] for a definition of such high-level
user interaction primitives.
For each form control, the following sections describe:
Description
Examples
Data Binding Restrictions
Implementation Requirements
XML Representation
XForms user interface controls use common attributes and elements that are
defined later in this chapter (8.12 Common Markup ).
8.1 input
Description: This form control enables free-form data entry.
<input ref="order/shipTo/street" class="streetAddress">
<caption>Street</caption>
<hint>Please enter the number and street name</hint>
</input>
In the above, the class attribute can
be used by a stylesheet to specify the display size of the form control. Note
that the constraints on how much text can be input are obtained from the
underlying XForms Model definition and not from these display properties.
A graphical browser might render the above example as follows:
Data Binding Restrictions: Binds to any simpleContent (except
xsd:base64Binary, xsd:hexBinary or any datatype derived from those).
Implementation Requirements: Must allow entry of a lexical
value for the bound datatype. Implementations should provide the most
convenient means possible for entry of datatypes and take into account
localization and internationalization issues such as representation of numbers.
For example, an input bound to an instance data node of type Date might provide a calendar control to enter dates; similarly, an input
control bound to data instance of type boolean might be rendered as a simple checkbox.
Example: XML Representation: <input>
<input
(single node binding attributes)
(common attributes)
inputMode = xsd:string
>
<!-- caption, (help|hint|alert|action|extension)* -->
</input>
(single node binding attributes)
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
common attributes defined in
8.12.1 Common Attributes
inputMode -
this form control accepts an input mode hint. B Input Modes
8.2 textarea
Description: This form control enables free-form data entry and is
intended for use in entering multiline content, e.g., the body of an email
message.
Example: Email Message Body
<textarea ref="message/body" class="messageBody">
<caption>Message Body</caption>
<hint>Enter the text of your message here</hint>
</textarea>
In the above, the class attribute can be used by a
stylesheet to specify the display size of the form control. Note that the
constraints on how much text can be input are obtained from the underlying
XForms Model definition and not from these display properties.
A graphical browser might render the above example as follows:
Data Binding Restrictions: Binds to xsd:string or any derived simpleContent.
Implementation Requirements: Must allow entry of a lexical
value for the bound datatype, including multiple lines of text.
Example: XML Representation: <textarea>
<textarea
(single node binding attributes)
(common attributes)
inputMode = xsd:string
>
<!-- caption, (help|hint|alert|action|extension)* -->
</textarea>
(single node binding attributes) - Selection of instance
data node, defined at 8.12.2 Single Node Binding Attributes
common attributes defined in
8.12.1 Common Attributes
inputMode - this form control accepts an input mode hint. B Input Modes
8.3 secret
Description: This form control is used for entering information that is
considered sensitive, and thus not echoed to a visual or aural display as it is
being entered, e.g., password entry.
Example: Password Entry
<secret ref="/login/password">
<caption>Password</caption>
<hint>Please enter your password --it will not
be visible as you type.</hint>
</secret>
A graphical browser might render this form control as follows:
Data Binding Restrictions: Identical to input.
Implementation Requirements: In general, implementations,
including accessibility aids, must render a "*" or similar character
instead of the actual characters entered, and thus must not render the entered
value of this form control. Note that this provides only a casual level of
security; truly sensitive information will require additional security measures
outside the scope of XForms.
Example: XML Representation
<secret>
<secret
(single node binding attributes)
(common attributes)
inputMode = xsd:string
>
<!-- caption, (help|hint|alert|action|extension)* -->
</secret>
(single node binding attributes)
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
common attributes defined
in 8.12.1 Common Attributes
inputMode - this form control accepts
an input mode hint. B Input Modes
8.4 output
Description: This form control renders a value from the instance data,
but provides no means for entering or changing data. It is typically used to
display values from the instance, and is treated as display:inline for purposes of layout.
Example: Explanatory Message
I charged you
<output ref="order/totalPrice"/>
and here is why:
A graphical browser might render an output form control as follows:
Data Binding Restrictions: Binds to any simpleContent.
Implementation Requirements: Must allow display of a lexical
value for the bound datatype. Implementations should provide the most
convenient means possible for display of datatypes and take into account
localization and internationalization issues such as representation of
numbers.
Example: XML Representation: <output>
<output
(single node binding attributes)
>
<!-- empty content -->
</output>
(single node binding attributes) - Selection of instance
data node, defined at 8.12.2 Single Node Binding Attributes
8.5 upload
Description: This form control enables the common feature found on Web
sites to upload a file from the local file system, as well as accepting input
from various devices including microphones, pens, and digital cameras.
Example: Uploading An Image
<upload ref="mail/attach1" mediaType="image/*">
<caption>Select image:</caption>
</upload>
A graphical browser might render this form control as follows:
Data Binding Restrictions: This form control can only be bound to
datatypes xsd:base64Binary or xsd:hexBinary, or types derived by restriction from these.
Implementation Requirements: For suitable
mediaTypes:
-
Implementations with a file system should support file
upload—selecting a specific file. The types of files presented by default must reflect the
mediaType specified in the XForms Model, for example defaulting to only audio
file types in the file dialog when the mediaType is "audio/*". In
XForms 1.0, there is a 1:1 binding between a upload form control and one of the
binary datatypes, although that single file may be compound (e.g.
application/zip).
-
Implementations with specific pen/digitizer hardware should (and
implementations with other pointing devices may) support
"scribble"—allowing in-place creation of pen-based data.
.
-
Implementations with specific audio recording capabilities should
support record audio—in-place recording of an audio clip.
-
Implementations with a digital camera/scanner interface
or screen capture should support acquire
image—in-place upload of images from an attached device.
-
Implementations with video recording capability should provide a
record video option.
-
Implementations with 3d capabilities should provide a 3d interface
option .
-
Implementations may provide proprietary implementations (for
example, a mediaType of text/rtf could invoke an edit window with a proprietary
word processing application)
-
Implementations are encouraged to support other input devices not
mentioned here.
-
Implementations which cannot support upload for the given
mediaType must make this apparent to the user.
Example: XML Representation: <upload>
<upload
(single node binding attributes)
(common attributes)
mediaType = list of content types
>
<!-- caption, (help|hint|alert|action|extension)* -->
</upload>
(single node binding attributes) - Selection of instance data node,
defined at 8.12.2 Single Node Binding Attributes
common attributes defined in 8.12.1 Common Attributes
mediaType - list of suggested media types, used by the XForms Processor
to determine which input methods apply.
8.6 range
Description: This form control allows selection from a continuous range
of values.
Example: Picking From A Range
<range ref="/stats/balance" start="-2.0" end="2.0" stepSize="0.5">
<caption>Balance</caption>
</range>
A graphical browser might render this as follows:
Data Binding Restrictions: Binds only the following list of
datatypes, or datatypes derived by restriction from those in the list: xsd:duration, xsd:date, xsd:time, xsd:dateTime, xsd:gYearMonth, xsd:gYear, xsd:gMonthDay, "xsd:gDay", xsd:gMonth, xsd:float, xsd:decimal, xsd:double.
Implementation Requirements: Must allow input of a value corresponding
to the bound datatype. Implementations should inform the user of the upper and
lower bounds, as well as the step size, if any. In graphical environments, this
form control may be rendered as a "slider" or "rotary
control".
Notice that the attributes of this element encapsulate sufficient
metadata that in conjunction with the type information available from the
XForms Model proves sufficient to produce meaningful prompts when using
modalities such as speech, when using an accessibility aid. Thus, an aural user
agent might speak a prompt of the form Please pick a date in the range
January 1, 2001 through December 31, 2001.
Example: XML Representation: <range>
<range
(single node binding attributes)
(common attributes)
start = datavalue
end = datavalue
stepSize = datavalue-difference
>
<!-- caption, (help|hint|alert|action|extension)* -->
</range>
(single node binding attributes)
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
common attributes defined in
8.12.1 Common Attributes
start -
optional hint for the lexical
starting bound for the range, of the
same datatype bound to the form control
end -
optional hint for the ending bound for the range,
of the same datatype bound to the form control
stepSize -
optional hint to use for incrementing or
decrementing the value within the form
control, of a datatype that can express the difference between two values of
the datatype bound to the form control
8.7 button
Description: This form control is similar to the HTML element of the
same name and allows for user-triggered actions. This form control may also be
used to advantage in realizing other custom form controls.
Example:
Example: Simple Button
<button>
<caption>Click here</caption>
</button>
Data Binding Restrictions: Binding not possible for this form
control.
Implementation Requirements: The user agent must provide a
means to generate an xforms:activate event on the form control. Graphical implementations would typically
render this form control as a push-button with the caption on the button face.
Stylesheets can be used to style the button as an image.
Example: XML Representation: <button>
<button
(common attributes)
>
<!-- caption, (help|hint|alert|action|extension)* -->
</button>
common attributes defined in
8.12.1 Common Attributes
8.8 submit
Description: This form control initiates
submission of all or part of the instance data to which it is
bound.
Example:
Example: Submit
<submit submitInfo="timecard">
<caption>Submit Timecard</caption>
</submit>
Data Binding Restrictions: Binding not possible for this form
control.
Implementation Requirements: Upon receiving event xforms:activate, this form control dispatches an xforms:submit event to the indicated element submitInfo. If no attribute
submitInfo is specified, the first element submitInfo, in
document order, is used.
Example: XML Representation: <submit>
<submit
(common attributes)
submitInfo = xsd:IDREF
>
<!-- caption, (help|hint|alert|action|extension)* -->
</submit>
submitInfo - Required reference to element
submitInfo
common attributes defined in 8.12.1 Common Attributes
8.9 selectOne
Description: This form control allows the user to make a single
selection from multiple choices.
Example: Pick A Flavor
<selectOne ref="my:icecream/my:flavor">
<caption>Flavour</caption>
<item>
<caption>Vanilla</caption>
<value>v</value>
</item>
<item>
<caption>Strawberry</caption>
<value>s</value>
</item>
<item>
<caption>Chocolate</caption>
<value>c</value>
</item>
</selectOne>
In the above example, selecting one of the choices will result in the
associated value given by element value on the selected item being set
in the underlying data instance at the location icecream/flavor.
A graphical browser might render this form control as any of the
following:
| listbox |
checkbox |
radio |
menu |
|
 |
|
 |
Data Binding Restrictions: Binds to any simpleContent.
Implementation Requirements: The caption for each choice must
be presented, allowing at all times exactly one selection. This form control
stores the value corresponding to the selected choice in the location addressed
by attribute ref. The value to be stored is either directly
specified as the contents of element value, or specified indirectly
through attribute ref on element value.
Note that the datatype bound to this form control may include a
non-enumerated value space, e.g., xsd:string. In this case, control selectOne may have attribute
selection="open". The form control should then allow free
data entry, as described in 8.1 input.
If the initial instance value matches none of the possible
storage values of given items, and selection is set to closed, the first item is selected. Otherwise, the first matching item is
selected.
For open selections: If the initial instance value matches
none of the possible storage values of given items, the selected value is the
initial lexical value. Otherwise, the first matching item is selected. Free
entry text is handled the same as form control input
8.1 input.
User interfaces may choose to render this form control as a pulldown
list or group of radio buttons, among other options. The selectUI attribute
offers a hint as to which rendering might be most appropriate, although any
styling information (such as CSS) should take precedence.
Typically, a stylesheet would be used to determine the exact appearance
of form controls, though a means is provided to suggest an appearance through
an attribute. The value of the attribute consists of one of the following
values, each of which may have a platform-specific look and feel.
radio
checkbox
menu
listbox
Example: XML Representation: <selectOne>
<selectOne
(single node binding attributes)
(common attributes)
selectUI = ("radio" | "checkbox" | "menu" | "listbox" )
selection = "open" | "closed" : "closed"
>
<!-- caption, (choices|item|itemset)+, (help|hint|alert|action|extension)* -->
</selectOne>
(single node binding attributes)
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
common attributes defined
in 8.12.1 Common Attributes
selectUI - appearance
override
selection - optional attribute determining
whether free entry is allowed in the list.
8.10 selectMany
Description: This form control allows the user to make multiple
selections from a set of choices.
Example: Selecting Ice Cream Flavor
<selectMany ref="my:icecream/my:flavors">
<caption>Flavours</caption>
<choices>
<item>
<caption>Vanilla</caption>
<value>v</value>
</item>
<item>
<caption>Strawberry</caption>
<value>s</value>
</item>
<item>
<caption>Chocolate</caption>
<value>c</value>
</item>
</choices>
</selectMany>
In the above example, more than one flavor can be selected.
A graphical browser might render form control selectMany as
any of the following:
| listbox |
checkbox |
radio |
menu |
|
|
This configuration is not recommended. |
 |
Data Binding Restrictions: any simpleContent capable of
holding a sequence.
Note:
A limitation of the Schema list datatypes is that whitespace
characters in the storage values (the value="..." attribute of the item element) are always interpreted as
separators between individual data values. Therefore, authors should avoid
using whitespace characters within storage values with list simpleContent.
Example: Incorrect Type Declaration
<item>
<value>United States of America</value>
...
</item>
when selected, this item would introduce not one but four additional
selection values: "America", "of", "States", and
"United".
Implementation Hints: An accessibility aid might allow the user to
browse through the available choices and leverage the grouping of choices in
the markup to provide enhanced navigation through long lists of choices.
Example: XML Representation: <selectMany>
<selectMany
(single node binding attributes)
(common attributes)
selectUI = ("radio" | "checkbox" | "menu" | "listbox")
>
<!-- caption, (choices|item|itemset)+, (help|hint|alert|action|extension)* -->
</selectMany>
(single node binding attributes)
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
common attributes defined
in 8.12.1 Common Attributes
selectUI - appearance override
8.11 Common Markup for selection controls
8.11.1 choices
This element is used within selection form controls to group available
choices. This provides the same functionality as element optgroup in
HTML.
Example: XML Representation: <choices>
<choices>
<!-- caption?, (choices|item)+ -->
</choices>
8.11.2 item
This element specifies the storage value and caption to
represent an item in a list. It is found within elements selectOne and
selectMany, or grouped in element choices.
Example: XML Representation:
<item>
<item>
<!-- caption, value, (help|hint|alert|action|extension)* -->
</item>
id = xsd:ID - optional unique
identifier.
8.11.3 itemset
Element itemset allows the creation of dynamic selections
within controls selectOne and selectMany, where the available
choices are determined at run-time. The node-set that holds the available
choices is specified via attribute nodeset. Child elements
caption and value indirectly specify the caption and storage
values. Notice that the run-time effect of itemset is the same as
using element choices to statically author the available choices.
Example: XML Representation:
<itemset>
<itemset
(node-set binding attributes)
>
<!-- caption, value, (help|hint|alert|action|extension)* -->
</itemset>
node-set binding attributes - required node-set selector that specifies the node-set
holding the available choices.
The following example shows element itemset within control
selectMany to specify a dynamic list of ice cream flavors:
Example: Dynamic Choice Of Ice Cream Flavors
<model id="cone">
<instance>
<my:icecream>
<my:flavours/>
</my:icecream>
</instance>
</model>
<model id="flavours">
<instance>
<my:flavours>
<my:flavour type="v">
<my:description>Vanilla</my:description>
</my:flavour>
<my:flavour type="s">
<my:description>Strawberry</my:description>
</my:flavour>
<my:flavour type="c">
<my:description>Chocolate</my:description>
</my:flavour>
</my:flavours>
</instance>
</model>
<!-- user interaction markup -->
<selectMany model="cone" ref="my:icecream/my:flavours">
<caption>Flavors</caption>
<itemset model="flavours" nodeset="my:flavours/my:flavour">
<caption ref="my:description"/>
<value ref="@type"/>
</itemset>
</selectMany>
8.11.4 value
This element provides a storage value to be used when an item
is selected.
Data Binding Restriction: All lexical values must be valid according
to the datatype bound to the selection control.
Example: XML Representation: <value>
<value
(single node binding attributes)
>
<!-- ##any -->
</value>
single node binding attributes - optional
binding selector that specifies a location from where the
storage value is to be fetched.
If inline content and a ref attribute are both specified,
the ref attribute is used.
8.12 Common Markup
The preceding form control definitions make reference to child elements
and attributes that are common to several of the form controls. This section
defines these common markup components.
8.12.1 Common Attributes
The following attributes are common to many user-interface related
XForms elements.
Example: XML Representation: Common Attributes
xml:lang = xsd:language
class = space separated list of classes
navIndex = xsd:nonNegativeInteger : 0
accessKey = xsd:token
xml:lang - Optional standard XML attribute to specify a
human language for this element.
class - Optional selector for a style rule.
navIndex - Optional attribute is a non-negative integer
in the range of 0-32767 used
to define the navigation sequence. This gives the author control over the
sequence in which form controls
are traversed. The default navigation order is specified in the chapter 11 Processing Model.
accessKey - Optional attribute defines a shortcut for
moving the input focus directly
to a particular form control.
The value of this is typically a single character which when pressed together
with a platform specific modifier key (e.g. the alt key) results
in the focus being set to this form
control.
8.12.2 Single Node Binding Attributes
The following attributes define a binding between a form control and
an instance data node.
Example: XML Representation: Single Node Binding
Attributes
ref = binding-expression
model = xsd:IDREF
bind = xsd:IDREF
ref - Binding expression.
Details in the chapter 6 Constraints. The first-node rule applies to the nodeset selected here.
model -
Optional instance data selector. Details in the
section 6.4.3 Binding References.
bind - Optional reference to a bind element
It is an error if the model
idref value refers to an id not on a model element, or if the
bind idref value refers to an id not on a bind element.
8.12.3 Nodeset Binding Attributes
The following attributes define a binding between a form control and a
node-set returned by the XPath expression.
Example: XML Representation: Nodeset Binding Attributes
nodeset = binding-expression
model = xsd:IDREF
bind = xsd:IDREF
nodeset - Binding expression.
Details in the chapter 6 Constraints.
model - Optional instance data selector.
Details in the chapter 6 Constraints.
bind - Optional reference to a bind element
It is an error if the model
idref value refers to an id not on a model element, or if the
bind idref value refers to an id not on a bind element.
8.12.4 Common Child Elements
The child elements detailed below provide the ability to attach
metadata to form controls.
Instead of supplying such metadata e.g., the label for a form control,
as inline content of the contained element caption, the metadata can
be pointed to by using a simple XLink attribute xlink:href on these
elements. Notice that systematic use of this feature can be exploited in
internationalizing XForms user interfaces by:
-
Factoring all human readable messages to a separate resource XML
file.
-
Using URIs into this XML resource bundle within individual caption
elements
-
Finally, an XForms processor can use content negotiation to obtain
the appropriate XML resource bundle, e.g., based on the accept-language headers from the client, to serve up the user interface with messages
localized to the client's locale.
8.12.4.1 caption
The required element caption labels the containing form
control with a descriptive label. Additionally, the caption makes it possible
for someone who can't see the form control to obtain a short description while
navigating between form controls.
Example: XML Representation: <caption>
<caption
(common attributes)
(single node binding attributes)
xlink:href = xsd:anyURI
>
<!-- ##any -->
</caption>
common attributes - defined in
8.12.1 Common Attributes
single node binding attributes
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
xlink:href = xsd:anyURI -
link to external caption
The caption specified can exist in instance data, in a
remote document, or as inline text. If multiple captions are specified in this
element, the order of preference is: ref, xlink:href,
inline.
An accessibility aid would typically speak the metadata encapsulated
here when the containing form control gets focus.
8.12.4.2 help
The optional element help provides a convenient
way to attach help information to a form control. This is equivalent to a xforms:help event handler that responds with a <message
type="modeless">.
Example: XML Representation: <help>
<help
(common attributes)
(single node binding attributes)
xlink:href = xsd:anyURI
>
<!-- ##any -->
</help>
(common attributes) - defined
in 8.12.1 Common Attributes
single node binding attributes
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
xlink:href = xsd:anyURI -
link to external help
The message specified can exist in instance data, in a
remote document, or as inline text. If multiple captions are specified in this
element, the order of precedence is: ref, xlink:href,
inline.
8.12.4.3 hint
The optional element hint provides a convenient
way to attach hint information to a form control. This is equivalent to a xforms:hint event handler that responds with a <message
type="ephemeral">.
Example: XML Representation:
<hint>
<hint
(common attributes)
(single node binding attributes)
xlink:href = xsd:anyURI
>
<!-- ##any -->
</hint>
(common attributes) - defined in 8.12.1 Common Attributes
single node binding attributes
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
xlink:href = xsd:anyURI -
link to external hint
The message specified can exist in instance data, in a
remote document, or as inline text. If multiple captions are specified in this
element, the order of precedence is: ref, xlink:href,
inline.
8.12.4.4 alert
The optional element alert provides a
convenient way to attach alert or error information to a form control. This is
equivalent to a xforms:alert event handler that responds with a <message
type="modal">.
Example: XML Representation: <alert>
<alert
(common attributes)
(single node binding attributes)
xlink:href = xsd:anyURI
>
<!-- ##any -->
</alert>
(common attributes) - defined
in 8.12.1 Common Attributes
single node binding attributes
- Selection of instance data node, defined at
8.12.2 Single Node Binding Attributes
xlink:href = xsd:anyURI -
link to external alert
The message specified can exist at in instance data, in a
remote document, or as inline text. If multiple captions are specified in this
element, the order of precedence is: ref, xlink:href,
inline.
8.12.4.5 extension
Example: XML Representation: <extension>
The optional element extension is a container
for application-specific extension elements from any namespace
other than the XForms namespace. This specification does not
define the processing of this element.
<extension>
<!-- ##other -->
</extension>
For example, metadata could be attached to an individual
form control as follows:
<input ref="dataset/user/email" id="email-input">
<caption>Enter your email address</caption>
<extension>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description about="#email-input">
<my:addressBook>personal</my:addressBook>
</rdf:Description>
</rdf:RDF>
</extension>
</input>
9 XForms Actions
All form controls defined in this specification have a set of common
behaviors that encourage consistent authoring and look and feel
for XForms-based applications. This consistency comes from attaching a common
set of behaviors to the various form controls. In conjunction with the event
binding mechanism provided by [XML Events], these handlers
provide a flexible means for forms authors to specify event processing at
appropriate points within the XForms user interface.
NOTE: This example is based on the XML Events specification
[XML Events], which is proceeding independently from XForms,
and thus might be slightly incorrect.
Example: Action Syntax
<xforms:button>
<xforms:caption>Reset</xforms:caption>
<xforms:resetInstance ev:event="xforms:activate"/>
</xforms:button>
This example recreates the behavior of the HTML reset button,
which this specification does not define as an independent form control.
For each built-in XForms action, this chapter lists the following:
Name
Description of behavior
XML Representation
Sample usage
All elements defined in this chapter explicitly allow global
attributes from the XML Events namespace, and apply the processing defined in
that specification in section 2.3 [XML Events].
9.1 dispatch
This action explicitly dispatches an XForms Event to a specific element
identified by the target attribute.
Example: XML Representation: <dispatch>
<dispatch
name = xsd:NMTOKEN
target = xsd:IDREF
bubbles = xsd:boolean : true
cancelable = xsd:boolean : true
/>
name = xsd:NMTOKEN - required name of the event\
to dispatch.
target = xsd:IDREF - required
reference to the event target.
bubbles = xsd:boolean : true - boolean indicating
if this event bubbles—as defined in DOM2
events.
cancelable = xsd:boolean : true - boolean indicating
if this event is cancelable—as defined in DOM2 events.
For events defined in the XForms specification, attributes
bubbles and cancelable have no effect, since these event
properties are defined in chapter 11 Processing Model.
9.2 refresh
This action dispatches an xforms:refresh event.
Example: XML Representation: <refresh>
9.3 recalculate
This action dispatches an xforms:recalculate event.
Example: XML Representation: <recalculate>
9.4 revalidate
This action dispatches an xforms:revalidate event.
Example: XML Representation: <revalidate>
9.5 setFocus
This action explicitly sets focus to the form control
referenced by the idref attribute by dispatching an xforms:focus event. Note that this event is implicitly invoked to implement XForms
accessibility features such as accessKey.
Example: XML Representation: <setFocus>
<setFocus
idref = xsd:IDREF
/>
idref = xsd:IDREF - required reference to a form control
Setting focus to a repeating structure sets the focus to the
member represented by the repeat cursor.
9.6 loadURI
This action performs an XLink traversal.
Example: XML Representation:
<loadURI>
<loadURI
(single node binding attributes)
xlink:href = xsd:anyURI
xlink:show = ("new" | "replace" | "embed" | "other" | "none")
/>
(single node binding attributes) -
Selects the instance data node containing the URI.
xlink:href
- optional URI to load.
xlink:show
- optional link behavior specifier.
Either the single node binding attributes, pointing to a URI in the
instance data, or the attribute xlink:href are required. If both are
present, the action has no effect.
Possible values for attribute xlink:show have the following
processing for the document (or portion of a document) reached by traversing
the link:
- new
-
The document is loaded into a new window (or other presentation
context). Form processing in the original window continues.
- replace
-
The document is loaded into the current window. Form processing is
interrupted, exactly as if the user had manually requested navigating to a new
document.
- embed
-
The document is incorporated into the current window in an
application-specific manner. Form processing continues.
- other
-
The document is loaded in an application-specific manner. The
application should look for other markup present in the link to determine the
appropriate behavior.
- none
-
The document is loaded in an application-specific manner. The
application should not look for other markup present in the link
to determine the appropriate behavior.
9.7 setValue
This action explicitly sets the value of the specified instance data
node.
Example: XML Representation: <setValue>
<setValue
(single node binding attributes)
value = XPath expression
>
<!-- literal value -->
</setValue>
(single node binding attributes) -
Selects the instance data node where the value is to be
stored.
value = XPath expression - XPath
expression to evaluate, with the result
stored in the selected instance data node.
The element content of setValue specifies the
literal value to set; this is an alternative to specifying a computed value via
attribute value. The following two examples contrast these
approaches:
Example: setValue with Expression
<setValue bind="put-here" value="a/b/c"/>
This causes the string value at a/b/c in the instance data
to be placed on the single node selected by the bind element with
id="put-here".
Example: setValue with Literal
<setValue bind="put-here">literal string</setValue>
This causes the value "literal string" to be placed on the single node selected
by the bind element with id="put-here".
If neither a value attribute nor text content are present, the effect is to set the value of the selected node to the empty string ("").
9.8 submitInstance
This action explicitly initiates submit processing by
dispatching an xforms:submit event.
Example: XML Representation: <submitInstance>
<submitInstance
submitInfo = xsd:IDREF
/>
id = xsd:ID - optional unique identifier.
submitInfo = xsd:IDREF - optional reference to a
submitInfo element.
Note:
This XForms Action is a convenient way of expressing the
following:
<dispatch target="mysubmitinfo" name="submitInstance"/>
9.9 resetInstance
This action explicitly initiates reset processing by
dispatching an xforms:reset event.
Example: XML Representation: <resetInstance>
<resetInstance
model = xsd:IDREF
/>
model = xsd:IDREF - Selection of instance data for
reset,defined at 8.12.3 Nodeset Binding Attributes
9.10 setRepeatCursor
This action marks a specific item as current in a repeating sequence
(within 10.3 Repeating Structures).
Example: XML Representation:Action <setRepeatCursor>
<setRepeatCursor
repeat = xsd:IDREF
cursor = XPath expression that evaluates to number
/>
repeat = xsd:IDREF - required reference to a repeat
cursor = XPath expression that evaluates to number
- required 1-based offset into the sequence.
9.11 insert
This action copies nodes from the containing document into
the instance data. Any nodes of type xsd:ID are not
copied.
The rules for insert processing are as follows:
-
A new node-set is created by evaluating the node-set binding
attributes against the containing document child nodes of
instance.
-
The last node of this node-set is deep copied into the instance
data, such that the inserted node appears immediately before or after
(depending on the value of attribute position) the n-th node in the node-set returned by evaluating the node-set binding
attributes against the instance data, where n represents the number returned from node-set index evaluation,
below.
Note:
The XForms Action setValue can be used in
conjunction with insert to provide specific initial values for the
newly inserted nodes.
The rules for selecting a node-set index are as follows:
-
The return value of the XPath expression in attribute at
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 NaN, the insert operation has no effect.
-
If the result is not a valid index for the node-set, it is clipped
to the either 1 or the size of the node-set, whichever is closer.
This action results in the insertion of model items to the
XForms Model. These model items should be constructed by re-evaluating any
necessary bindings and applying the XForms Constraints in scope for each node.
When used with repeating structures 10.3 Repeating Structures, this causes the
instantiation of the necessary user interface for populating a new entry in the
underlying collection.
Example: XML Representation:Action <insert>
<insert
(node-set binding attributes)
at = XPath expression
position = "before" | "after"
/>
(nodeset binding attributes) - Selection of
instance data nodes, defined at 8.12.3 Nodeset Binding Attributes
at - required XPath expression evaluated to determine
insert location.
position - required selector if
insert before/after behavior.
An example of using insert with a repeating
structure is located at 10.3 Repeating Structures.
9.12 delete
This action deletes nodes from the instance data.
The rules for delete processing are as follows:
-
A node-set is produced by evaluating the node-set binding attributes
against the instance data.
-
The n-th node is deleted from the instance data, where n represents the number returned from node-set index evaluation, defined
in 9.11 insert.
This action results in the deletion of model items to the
XForms Model. These model items should be deleted by re-evaluating any bindings
that refer to the nodes being deleted. When used with repeating structures,
this causes the destruction of the necessary user interface for populating the
entry at the current cursor position in the underlying collection.
Example: XML Representation:Action <delete>
<delete
(node-set binding attributes)
at = XPath expression
/>
(nodeset binding attributes) - Selection of
instance data nodes, defined at 8.12.3 Nodeset Binding Attributes
at - XPath expression evaluated to determine
insert location.
An example of using delete with a repeating
structure is located at 10.3 Repeating Structures.
9.13 toggle
This action selects one possible choice from an exclusive
list e.g., within 10.2 Conditional Constructs For Dynamic User Interfaces, by dispatching an xforms:toggle event.
Example: XML Representation: Action <toggle>
<toggle
case = xsd:IDREF
/>
case = xsd:IDREF - required reference to a case section
inside the conditional construct
The toggle action adjusts all selected
attributes on the affected cases to reflect the new state.
9.14 script
This action executes script.
Example: XML Representation: Action <script>
<script
type = xsd:string
>
<!-- #CDATA -->
</script>
type = xsd:string - required
mime-type identifier of scripting language used
9.15 message
This action encapsulates a message to be displayed to the user.
Example: XML Representation: <message>
<message
(single node binding attributes)
xlink:href = xsd:anyURI
level = "ephemeral" | "modeless" | "modal"
>
<!-- mixed content -->
</message>
(single node binding attributes) - optional attributes that point
to the instance data for a string message.
xlink:href = xsd:anyURI - optional specifier of an external resource for the message.
level - required message level identifier.
The message specified can exist in instance data, in a remote
document, or as inline text. If multiple captions are specified in this
element, the order of preference is: ref, xlink:href,
inline.
A graphical browser might render an ephemeral message as follows:
A graphical browser might render a modeless message as follows:
A graphical browser might render a modal message as follows:
9.16 action
This element can be used to bind XForms Actions to form controls and
group them around a common event handler.
Example: XML Representation: <action>
<action
>
<!-- Action handlers -->
</action>
10 XForms User Interface
This chapter covers XForms features for combining
form controls into user
interfaces.
All form controls defined in 8 Form Controls are treated as
individual units for purposes of visual
layout e.g., in XHTML processing. Aggregation of form controls with markup
defined in this chapter provides semantics about the relationship among user
interface controls; such knowledge can be useful in delivering a coherent UI to
small devices. For example, if the user interface needs to be split up over
several screens, controls appearing inside the same aggregation would typically
be rendered on the same screen or page.
10.1 Grouping Form Controls
The group element is used as a container for defining a
hierarchy of form controls. Groups can be nested to create complex
hierarchies.
Example: XML Representation: <group>
<group
(single node binding attributes)
(common attributes)
>
<!-- caption?, ##all -->
</group>
(single node binding attributes) - Selection of instance
data node, defined at 8.12.2 Single Node Binding Attributes
(common attributes) - defined in
8.12.1 Common Attributes
Example: Grouping Related Controls
<group ref="address">
<caption>Shipping Address</caption>
<input ref="line_1" >
<caption>Address line 1</caption>
</input>
<input ref="line_2" >
<caption>Address line 2</caption>
</input>
<input ref="postcode">
<caption>Postcode</caption>
</input>
</group>
The hierarchy defined by nested group elements is used to determine the
traversal order specified by attribute navIndex on form controls.
Setting the input focus on a group results in the focus being set to the first
form control in the tabbing order within that group.
10.2 Conditional Constructs For Dynamic User Interfaces
The XForms User Interface allows the authoring of dynamic user
interfaces, i.e., user interfaces that vary based on the current state of the
instance data being populated. As an example, portions of a questionnaire
pertaining to the user's automobile may become relevant only if
the user has answered in the affirmative to the question 'Do you own a car?'.
Another use case for such dynamic user interfaces is when the underlying
XForms Model contains conditional
structures.
This element contains one or more case elements. Each
case has an id attribute that is used within event handlers to activate or deactivate that portion
of the user interface created by the markup contained within that case
element.The attribute selected provides an
initial selected case, as well as provides access to the currently selected
case, through live updates to the attribute values in the containing
document. This example shows how to provide a conditional user
interface.
Example: switch
<switch id="sw">
<case id="in" selected="true">
<input ref="yourname">
<caption>Please tell me your name</caption>
</input>
</case>
<case id="out" selected="false">
<html:p>Hello <output ref="yourname" />.</html:p>
</case>
</switch>
The above results in the portion of the user interface contained in the
first the case being initially displayed. The XForms Action
toggle activates and deactivates different portions of this
conditional construct.
Example: XML Representation: <switch>
<switch
(single node binding attributes)
(common attributes)
>
<!-- case+ -->
</switch>
(single node binding attributes) - Selection of instance data node,
defined at 8.12.2 Single Node Binding Attributes
(common attributes) - defined in
8.12.1 Common Attributes
- optional selector for initial case.
Example: XML Representation: <case>
<case
selected = xsd:boolean
>
<!-- ##any -->
</case>
selected = xsd:boolean - optional
selection status for the case.
If multiple cases within a switch are
marked as selected="true", the first selected case remains and all others are
deselected. If none are selected, the first becomes selected.
10.3 Repeating Structures
The XForms Model allows the definition of repeating structures such as
multiple items being purchased within a purchase order. When defining the
XForms Model, such higher-level aggregations are constructed out of basic
building blocks; similarly, this section defines higher-level user interface
constructs that build on the form controls defined previously that can bind to
data structures such as lists and collections. Element repeat
encapsulates a UI mapping over a homogeneous collection, in other words, a
collection consisting of data items having the same type and structure.
<repeat nodeset="/cart/items/item">
<input ref="." .../><html:br/>
</repeat>
Note that controls for adding or removing repeating entries may appear
within the repeat, (causing the add/remove controls themselves to repeat), or may appear
outside the repeat.
Another way to view repeat processing (disregarding special user
interface interactions) is to consider "unrolling" the repeat. The
above example is similar to the following (assuming four item elements in the
returned node-set):
<!-- unrolled repeat -->
<input ref="/cart/items/item[1]" .../><html:br/>
<input ref="/cart/items/item[2]" .../><html:br/>
<input ref="/cart/items/item[3]" .../><html:br/>
<input ref="/cart/items/item[4]" .../><html:br/>
Notice that the model item for the collection being populated would
typically have defined attributes minOccurs and
maxOccurs; these values may in turn determine if the user agent
displays appropriate UI controls for the user to add or delete entries in the
collection. Event listeners separately control UI aspects such as scrolling and
insertion. This specification does not specify normative means for displaying
such add and delete controls; as with the rest of the XForms User Interface
design, these are left to be flexible while showing a default presentation.
<model>
<instance>
<my:lines>
<my:line name="a">
<my:price>3.00</my:price>
</my:line>
<my:line name="b">
<my:price>32.25</my:price>
</my:line>
<my:line name="c">
<my:price>132.99</my:price>
</my:line>
</my:lines>
</instance>
</model>
...
<repeat id="lineset" nodeset="my:lines/my:line">
<input ref="my:price">
<caption>Line Item</caption>
</input>
<input ref="@name">
<caption>Name</caption>
</input>
</repeat>
<button>
<caption>Insert a new item after the current one</caption>
<action ev:event="ev:activate">
<insert nodeset="my:lines/my:line"
at="cursor('lineset')"
position="after"/>
<setValue ref="my:lines/my:line[cursor('lineset')]/@name"/>
<setValue ref="my:lines/my:line[cursor('lineset')]/price">0.00</setValue>
</action>
</button>
<button>
<caption>remove current item</caption>
<delete ev:event="ev:activate" nodeset="my:lines/my:line"
at="cursor('lineset')"/>
</button>
Example: XML Representation: <repeat>
<repeat
(node-set binding attributes)
(common attributes)
startIndex = xsd:positiveInteger : 1
number = xsd:nonNegativeInteger
>
<!-- ##any -->
</repeat>
(nodeset binding attributes) - Selection of context node-set,
defined at 8.12.3 Nodeset Binding Attributes
(common attributes) - defined in
8.12.1 Common Attributes
startIndex - 1-based hint to the XForms Processor
as to which starting element from the collection to
display.
number - hint to the XForms Processor
as to how many elements from the collection to
display.
10.3.1 Repeat Processing
The user interface markup for repeating structures adds encapsulation
metadata about the collection being populated. Processing for repeating
structures takes into account a cursor that points to a
current item in the data instance. This cursor is used as a
reference point for insert and delete XForms Actions.
Notice that the contained XForms form controls inside element
repeat do not explicitly specify the index of the collection entry
being populated. This is intentional; it keeps both authoring as well as the
processing model simple.
The binding expression attached to the repeating sequence returns a
node-set of the collection being populated, not an individual node. Within the
body of element repeat binding expressions are evaluated with a
context node of the node determined by the repeatCursor.
Repeat processing uses XPath expressions to address the
collection over which element repeat operates. The XPath expression
used as the value of attribute nodeset must select a node-set of
contiguous child element nodes, with the same local name and namespace name, of
a common parent node. The behavior of element repeat with respect to
other XPath node-sets is undefined.
A simple but powerful consequence of the above is that if the XForms
Model specifies nested collections, then a corresponding user interface can
nest repeat elements. The form controls appearing inside
repeat need to be suitable for populating individual items of the
collection.
The XForms Actions enumerated at 9 XForms Actions may be used
within event listeners attached to button elements placed inside the
body of construct repeat.
10.3.2 User Interface Interaction
As specified, element repeat allows us to bind a user
interface to a dynamic homogeneous collection.
The number of displayed items might be less than the total number
available. In such a case, the presentation would only render a portion of the
repeating items at a given time. For example, a graphical user interface might
present a scrolling table. The current item indicated by the repeat cursor should be presented
at all times, for example, not allowed to scroll out of view.
11 Processing Model
Note:
This chapter has undergone significant revision since last
publication. The diff-marked version of this chapter does not include
indications of changes, due to the large amount of new material.
This chapter defines the XForms processing model declaratively, i.e.,
describing the various states attained by an XForms processor, and the possible
state transitions that exist with respect to each of these states. In defining
these states and state transitions, this chapter enumerates the pre-conditions
and post-conditions that must be satisfied in each of these states. XForms
Processors may be implemented in any manner, so long as the end results are
identical to that described in this chapter.
The XForms processing model consists of the following three phases:
-
initialization
-
User interaction
-
Submission
Each of these phases is further subdivided as explained in detail in
subsequent sections of this chapter. State transitions in the processing model
occur when specific events are received, and the event handler that processes
the event determines the new state.
11.1 Events Overview
Thus, XForms processing is defined in terms of events, event handlers,
and event responses. XForms uses the events system defined in
[DOM2 Events], with a event Capture phase, arrival of the
event at its Target, and finally the event Bubbling Phase.
| Event name |
Cancelable? |
Bubbles? |
Target element |
| 11.2 Initialization Events |
| modelConstruct |
No |
No |
model |
| modelInitialize |
No |
No |
model |
| initializeDone |
No |
No |
model |
| UIInitialize |
No |
No |
model |
| formControlInitialize |
No |
No |
model |
| 11.3 Interaction Events |
| previous |
Yes |
Yes |
form control |
| next |
Yes |
Yes |
form control |
| focus |
Yes |
Yes |
form control |
| blur |
Yes |
Yes |
form control |
| activate |
Yes |
Yes |
form control |
| valueChanging |
Yes |
Yes |
form control |
| valueChanged |
Yes |
Yes |
form control |
| scrollFirst |
Yes |
Yes |
repeat |
| scrollLast |
Yes |
Yes |
repeat |
| insert |
No |
Yes |
instance |
| delete |
Yes |
Yes |
instance |
| select |
Yes |
Yes |
form control or switch |
| deselect |
Yes |
Yes |
form control or switch |
| help |
Yes |
Yes |
form control |
| hint |
Yes |
Yes |
form control |
| alert |
Yes |
Yes |
form control |
| valid |
No |
Yes |
form control |
| invalid |
No |
Yes |
form control |
| refresh |
Yes |
Yes |
model |
| revalidate |
Yes |
Yes |
form control or model |
| recalculate |
Yes |
Yes |
model |
| reset |
Yes |
Yes |
model |
| 11.4 XForms Submit |
| submit |
Yes |
Yes |
submitInfo |
| 11.5 Error Indications |
| schemaConstraintsError |
No |
Yes |
model |
| traversalError |
No |
Yes |
model |
| invalidDatatypeError |
No |
Yes |
model |
Note:
Events editorial whiteboard:
If the submit event targets submitInfo (which seems
reasonable), we should allow XForms Actions as children of
<submitInfo>.
Did we get rid of destruct? I couldn't find a reference
either way.
11.2 Initialization Events
This section defines the various stages of the
initialization phase.The processing application begins
initialization by dispatching an event xforms:modelConstruct to each XForms Model in the containing document.
11.2.1 xforms:modelConstruct
Dispatched in response to: XForms Processor initialization.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
-
Schema is loaded, if any.
-
An XPath data model is constructed from the instance data,
according to the following rules:
-
From an external source
-
If there is no reference to an external instance, from an
inline instance
Note:
If neither of these are supplied, the instance is constructed
from the user interface, during user interface construction.
-
Following this, an xforms:modelInitialize event is dispatched to element model.
11.2.2 xforms:modelInitialize
Dispatched in response to: completion of xforms:modelConstruct processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
-
The instance data has been structurally validated against the
Schema, if any. If structural validation fails, all XForms processing for this
containing document halts.
-
If applicable, P3P has been initialized.
[P3P 1.0]
-
The instance data has been constructed.
-
The xforms:initializeDone event is dispatched to the model element after initialization
of that model element is completed but before rendering of the UI has
started.
-
After all XForms Models are initialized, the host must dispatch an
xforms:UIInitialize event to each model element.
11.2.3 xforms:initializeDone
Dispatched in response to: xforms:modelInitialize processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
11.2.4 xforms:UIInitialize
Dispatched in response to: XForms Processor user interface
initialization.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
The host processor traverses the containing document, and for each
form control, dispatches a xforms:formControlInitialize event to the form
control.
11.2.5 xforms:formControlInitialize
Dispatched in response to: xforms:UIInitialize processing.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
Default processing for this event results in the following:
If the referenced model contains doesn't have instance data, it is
created by following the rules for default instance data.
@@@text here on default XForms Model construction.
11.3 Interaction Events
11.3.1 DOM Mutation Events
Dispatched in response to: any change in the instance data.
Target: instance data node
Bubbles: Yes
Cancelable: No
Context Info: varies
In implementations that support the DOM, standard DOM mutation events
should be dispatched to the changing target nodes whenever the instance data
changes. Note that script, using the method getInstanceDocument() and a
tree-walk, is required to associate event handlers with the instance data.
11.3.2 xforms:next and xforms:previous
Dispatched in response to: user request to navigate to the next or
previous form control.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for these events results in the following:
Navigation according to the default navigation order. For example, on a
keyboard interface, "tab" would typically generate an xforms:next event, while "shift+tab" would generate an xforms:previous event.
Navigation is determined on a containing document-wide basis. The
basic unit of navigation is the form control. The <group>,
<repeat>, and <switch> structures also serve as
navigation units, but instead of providing a single navigation point, they
create a local navigation context for child form controls (and possibly other
substructures). The navigation sequence is determined as follows:
-
Those navigation units that support navIndex and assign a positive value to it are navigated first.
-
Outermost navigation units are navigated in increasing order
of the navIndex value. Values need not be sequential nor must they begin with any
particular value. Navigation units that have identical navIndex values are be navigated in document order.
-
Ancestor navigation units establish a local navigation
sequence. All navigation units within a local sequence are navigated, in
increasing order of the navIndex value, before any outside the local sequence are navigated. Navigation
units that have identical navIndex values are navigated in document order.
-
Those form controls that do not supply navIndex or supply a value of "0" are navigated next. These form
controls are navigated in document order.
-
Those form controls that are disabled, hidden, or not relevant are assigned a relative order in the overall sequence but do not
participate as navigable controls.
-
The navigation sequence past the last form control (or before the
first) is undefined. XForms Processors may cycle back to the first/last
control, remove focus from the form, or other possibilities.
11.3.3 xforms:focus and xforms:blur
Dispatched in response to: a form control gaining or losing focus
through any means.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for these events results in the following: None;
notification events only.
| Editorial note | |
Do these events apply also to group,
switch, and repeat? |
11.3.4 xforms:activate
Dispatched in response to: the "default action request" for
a form control, for instance pressing a button or hitting enter.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None;
notification event only.
11.3.5 xforms:valueChanging
Dispatched in response to: an interactive change to an instance data
node bound to a form control.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Certain form controls allow interactive response without finalizing on
a value. Examples of this include edit boxes (users can type various characters
before navigating away) and slider controls (users can be continuously
adjusting the value before releasing at a certain value). Interactive temporary
values such as this are expressly allowed to be "invalid", that is
outside the permissible value space. This is because incomplete data may be
present while the user is entering transitional values.
Example: A partially entered credit card value of "3" is not
valid because it doesn't (yet) have enough characters. This is permitted
temporarily, as long as the user remains on the form control. XForms Full
Processors would update/refresh on every character. XForms Basic Processors
would typically only update/refresh on the final value.
Default processing for this event results in the following:
-
If the partial value meets all validity constraints, it is
reflected in the instance data. If not, the instance data remains as it was
before processing this event.
-
Event recalculate has been dispatched to element model.
-
Event refresh has been dispatched to element model.
Implementations that choose to implement valueChanging are expected optimize processing (for instance not flashing the entire
screen for each character entered, etc.).
Note:
XForms Basic processors are not required to generate or respond to
these events.
11.3.6 xforms:valueChanged
Dispatched in response to: a change to an instance data node bound to
a form control, when the user navigates away from the form control.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
-
The value from the form control is reflected in the instance
data.
-
Event revalidate has been dispatched to element model.
-
Event recalculate has been dispatched to element model.
-
Event refresh has been dispatched to element model.
11.3.7 xforms:scrollFirst
Dispatched in response to: a repeat view is scrolled past the
beginning of the repeat items.
Target: repeat
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None;
notification event only.
11.3.8 xforms:scrollLast
Dispatched in response to: a repeat view is scrolled past the end of
the repeat items.
Target: repeat
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None;
notification event only.
11.3.9 xforms:insert and xforms:delete
Dispatched in response to: A event handler invoking an XForms Action
insert or delete.
Target: instance
Bubbles: Yes
Cancelable: No
Context Info: Path expression used for insert/delete.
Default processing for these events results in the following: None;
notification event only.
11.3.10 xforms:select and xforms:deselect
Dispatched in response to: an item in a selectOne,
selectMany, or switch becoming selected or deselected.
Target: form control or switch
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: None;
notification event only.
11.3.11 xforms:help and xforms:hint
Dispatched in response to: a user request for help or hint
information.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for these events results in the following: None;
notification event only. User agents may provide default help or hint
messages.
11.3.12 xforms:alert
Dispatched in response to: a form control failing validation.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: An error
message displayed, informing the user of the action needed to make the form
control valid.
11.3.13 xforms:valid
Dispatched in response to: a form control becoming valid with respect
to the bound instance data.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None;
notification event only.
11.3.14 xforms:invalid
Dispatched in response to: a form control becoming invalid with
respect to the bound instance data.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following:
11.3.15 xforms:refresh
Dispatched in response to: a request to update all form controls
associated with a particular XForms Model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following: The user
interface will reflect the state of the model. This means:
-
All form controls show the current value corresponding to the
bound instance data.
-
All form controls show the validity state of the corresponding
bound instance data.
-
Any form control associated with a model item property
relevant evaluating to false is disabled/hidden/etc.
11.3.16 xforms:revalidate
Dispatched in response to: a request to revalidate one or all form
controls associated with a particular XForms Model.
Target: model or a form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
Revalidation may occur targeted to a context form control. The
default handling for this event must satisfy the following conditions:
-
The bound instance data node is checked against any bound Schema
Constraints. If any fail, the context form control is considered invalid.
-
The bound instance data node is checked against any bound XForms
Constraints. If any fail, the context form control is considered invalid.
-
If the context form control is invalid, the XForms Processor must
dispatch event invalid to the context form control. Otherwise, event valid must be dispatched to the form control.
When element model is targeted by this event, the above is
applied to every form control in document order.
11.3.17 xforms:recalculate
Dispatched in response to: a request to recalculate all calculations
associated with a particular XForms Model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
An XPath expression is bound either to the value or to a model item
property (e.g. required, relevant) of one or more instance nodes. The combination of an XPath expression
with a single instance node's value or model item property is considered as a
single computational unit, a compute, for the purposes of
recalculation.
When it is time to recalculate a compute, the XPath expression is
evaluated in the context of the instance node whose value or model item
property is associated with the compute. The XPath expression may
reference or refer to another instance node, in which
case the value of the instance node is referenced. Each referenced
instance node has as dependents those computes which directly
refer to the instance node. Self-references are explicitly ignored, i.e. if an
expression associated with a compute refers to the instance node associated
with the compute, then the instance node does not take itself as a dependent. A
compute is computationally dependent on an instance node (whose
value may or may not be computed) if there is a path of dependents leading from
the instance node through zero or more other instance nodes to the compute. A
compute is part of a circular dependency if it is computationally
dependent on itself.
When a recalculation event begins, there will be a list L
of one or more instance nodes whose values have been changed, e.g. by user
input being propagated to the instance.
-
An XForms processor must not recalculate computes that are not
computationally dependent on one or more of the elements in L.
-
An XForms processor must perform a single recalculation of each
compute that is computationally dependent on one or more of the elements in
L.
-
An XForms processor must recalculate a compute C
after recalculating all computes of instance nodes on which C is
computationally dependent. (Equivalently, an XForms processor must recalculate
a compute C before recalculating any compute that is
computationally dependent on the instance node associated with
C.)
-
Finally, if a compute is part of a circular dependency and also
computationally dependent on an element in L, then an XForms
processor MUST report an exception.
D Recalculation Sequence Algorithm describes one possible method for achieving
the desired recalculation behavior.
11.3.18 xforms:reset
Dispatched in response to: a user request to reset the instance
data.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
-
All of the instance data is selected for resetting.
-
New instance data for the selected instance data is prepared,
based on the instance element associated with the current
model element, according to the rules for initialization above.
-
The selected instance data is replaced with the new instance
data.
11.4 XForms Submit
Form filling experience ends with submitting the form, or perhaps
starting over. The XForms processing for these events are covered here. The
following sections describe how the instance data is prepared for
submission.
11.4.1 xforms:submit
Dispatched in response to: a user request to submit the instance
data.
Target: submitInfo
Bubbles: Yes
Cancelable: Yes
Context Info: None
Default processing for this event results in the following:
-
A node from the instance data is selected, based on the attribute
ref on element submitInfo. This node and all child nodes,
are considered for the remainder of the submit process.
-
All selected instance data is revalidated.
Any invalid instance data stops submit processing.
-
Selected instance data is serialized according to one of the
processes defined below, as indicated by element submitInfo attributes
mediaType and mediaTypeExtension. Nodes that have an
associated relevant constraints that evaluates to false are not serialized.
-
Instance data is delivered over the network using the network
protocol indicated by element submitInfo attribute
method.
Note:
The HTTP "get" protocol is deprecated for use in form
submission. Form authors should use "post" for greater
compatibility.
-
The response returned from the submission is applied as follows:
if element submitInfo attribute replace has the value of
"all", the entire containing document is replaced. If the attribute
value is "instance", the response is parsed as XML and the internal instance data is
replaced with the result, using the same processing as remote instance data
retrieved through xlink:href, and the xforms:initialize event is dispatched to element model. Behaviors of other possible values for attribute replace
are not defined in this specification.
Under no circumstances may more than a single
concurrent submit process be under way for a particular XForms Model.
11.4.2 application/x-www-form-urlencoded
This format is selected by the string application/x-www-form-urlencoded in element submitInfo attribute mediaType.
Note:
This serialization format is deprecated, and will be
removed in a future version of the XForms specification. For greater
compatibility with XML and non-western characters, form authors should choose a
different serialization format.
This format is intended to facilitate the integration of XForms into
HTML forms processing environments, and represents an extension of the
[XHTML 1.0] form content type of the same name with
extensions to expresses the hierarchical nature of instance data.
This format is not suitable for the persistence of binary content.
Therefore, it is recommended that XForms capable of containing binary content
use either the multipart/form-data (11.4.3 multipart/form-data) or
text/xml (11.4.4 text/xml) formats.
Issue (issue-urlencoding-mods):
Modifications to urlencoding process
The urlencoding technique given here does not exactly match how
legacy implementations produce urlencoded data. (In particular, we are adding
contextual information with slashes and multiple location-steps) Will this
approach interfere with legacy implementations?
Issue (issue-utf8-encoding):
Under discussion is the intent to have the data be UTF8 encoded;
however, this is dependent upon IETF developments. Would UTF8 meet the needs of
the forms community?
Instance data is urlencoded with the following rules:
-
Each element node is visited in document order. If the
element contains only a single node, it is selected for inclusion. Note that
attribute information is not preserved.
-
Elements selected for inclusion are encoded as
"EltName=value;", where "=" and ";" are literal
characters, "EltName" represents the element local name, and
"value" represents the contents of the text node. Note that
contextual path information is not preserved, nor are namespace prefixes, and
multiple elements might have the same name.
-
All such encodings are concatenated, maintaining
document order. The resulting string is urlencoded, as in HTML processing.
Example:
Example: application/x-www-form-urlencoded
This format consists of simple name-value pairs.
<PersonName title="Mr">
<FirstName>Roland</FirstName>
</PersonName>
Here is the instance data for the above example. Note that very little of
the data is preserved. Authors desiring greater data integrity should select a different
serialization format.
11.4.3 multipart/form-data
This format is selected by the string multipart/form-data in element submitInfo attribute mediaType.
This format is intended to facilitate the integration of XForms into
HTML forms processing environments, and represents an extension of the
[XHTML 1.0] form content type of the same name that expresses
the hierarchical nature of instance data. Unlike the
application/x-www-form-urlencoded (11.4.2 application/x-www-form-urlencoded)
format, this format is suitable for the persistence of binary content.
This format follows the rules of all multipart MIME data streams for
form data as outlined in [RFC 2388], with the
"name" of each part being the canonical binding expression that
references the selected instance data node.
Example:
Example: multipart/form-data
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="/PersonName/@title"
Mr
--AaB03x
Content-Disposition: form-data; name="/PersonName/FirstName"
Roland
--AaB03x
...Possibly more data...
--AaB03x-
This format consists of sets of a canonical binding expression paired
with a value.
<PersonName title="Mr">
<FirstName>Roland</FirstName>
</PersonName>
Here is the instance data for the above example.
11.4.4 text/xml
This format is selected by the string text/xml in element submitInfo attribute mediaType.
This format permits the expression of the instance data as XML that is
straightforward to process with off-the-shelf XML processing tools. In
addition, this format is suitable for the persistence of binary content.
The steps for building this persistence format is as follows:
-
An XML document is produced following
the rules of the XML output method defined in XPath [XSLT]
section 16 and 16.1, using the values supplied as attributes of the
submitInfo element.
11.4.4.1 Binary Content
Instance data nodes with values of the types xsd:base64Binary and
xsd:hexBinary are specifically allowed, and are included in the serialized data
according to the rules defined in [XML Schema part 2]
Issue (issue-instance-metadata):
Where a value within the instance data represents binary content,
can we store meta-information with an xform:mediaType attribute reflecting the appropriate content type (e.g.,
"image/jpg")?
11.5 Error Indications
11.5.1 xforms:schemaConstraintsError
Dispatched in response to: instance data becoming schema-invalid.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None;
notification event only. Default error handling may be used.
11.5.2 xforms:traversalError
Dispatched in response to: a failure in link traversal of an
xlink:href attribute value.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: The URI that failed to load.
Default processing for this event results in the following: None;
notification event only. Default error handling may be used.
11.5.3 xforms:invalidDatatypeError
Dispatched in response to: an invalid parameter passed to an XForms
function.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
Default processing for this event results in the following: None;
notification event only. Default error handling may be used.
