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 this.
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. One common
case might be submitting XML data that is validated against a
predefined DTD or XML Schema.
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.
... 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..
Note:
The DOCTYPE declaration below is technically not valid, since
XHTML 1.1 does not include XForms elements in any content models.
The Working Group is developing a DOCTYPE declaration for the
combination of XHTML and XForms.
<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>
4 Document Structure
The XForms specification is an application of XML [XML 1.0], and has been designed for use within
other XML vocabularies, in particular XHTML [XHTML 1.0]. This chapter discusses the
structure and high-level features of XForms that allow this
specification to be used with other document types.
4.1 The XForms Namespace
The XForms namespace has the URI:
http://www.w3.org/2001/12/xforms. Any future Working Drafts are expected to use a different
identifier, though a final identifier will
be allocated before XForms becomes a W3C Recommendation.
XForms Processors must use the XML namespaces mechanism [XML Names] to recognize elements and
attributes from this namespace.
4.2 Horizontally Applicable
Markup
For cases when a particular element needs to be referred to from
another context, every element in the XForms namespace has declared
an attribute id of type xsd:ID in the
Schema for XForms.
Foreign-namespaced attributes are allowed on any XForms element.
The XForms Processor must ignore any foreign-namespaced elements or
attributes that are unrecognized.
Except where specifically allowed by the Schema for XForms,
foreign-namespaced elements are not allowed as content of elements
in the XForms namespace.
4.3 XForms
Head Elements
4.3.1 model
Element model is used
as a container for other XForms elements,
and can serve as the root element of a standalone document or
be embedded in the head section
of other document types such as XHTML. A single containing
document may contain any number of model
elements.
| Editorial
note |
|
|
under discussion are XLink attributes on the
model element. These are:
xlink:type="extended" and
xlink:role="http://www.w3.org/2001/12/xforms" - and they
should be defaulted or even fixed in the Schema/DTD.
|
Example: XML Representation:
<model>
<model
id = xsd:ID
>
<!-- Content: instance?, schema?, (privacy|submitInfo|bind|action|extension)* -->
</model>
id = xsd:ID - Optional unique identifier used to refer to
this particular model element.
For example:
<model xmlns="http://www.w3.org/2001/12/xforms" id="Person">
<instance xlink:href="http://example.com/cgi-bin/get-instance" />
<schema xlink:href="Schema-Questionnaire.xsd" />
...
</model>
4.3.2 instance
Element instance is used to define initial instance
data. The instance data may be defined inline or obtained from a
external URI.
Example: XML Representation:
<instance>
<instance
xlink:href = xsd:anyURI
>
<!-- Content: (##other) -->
</instance>
xlink:href = xsd:anyURI - Optional link to externally
defined instance data
The content of the instance element is arbitrary
XML in any namespace other than the XForms namespace. Authors must
ensure that proper namespace declarations are used for content
within the instance element.
| Editorial
note |
|
|
As above, we need to find a place to discuss
the defaulted attributes. Here they are
xlink:role="http://www.w3.org/2001/12/xforms-instance"
xlink:type="locator"
|
Issue
(issue-schemalocation):
Should a schemaLocation attribute, linking the
instance data with a schema definition, be present here?
4.3.3 schema
Element schema is
used to define the schema portion of the
XForms Model. The schema
information may be defined inline or obtained from an
external URI.
Example: XML Representation:
<schema>
<schema
xlink:href = xsd:anyURI
>
<!-- Content: ##other (though typically <xsd:schema>) -->
</schema>
xlink:href = xsd:anyURI - Optional link to an externally
defined XForms Model.
| Editorial
note |
|
|
As above, we need to find a place to discuss
the defaulted attributes. Here they are
xlink:role="http://www.w3.org/2001/12/xforms-model"
xlink:type="locator"
|
4.3.4 submitInfo
Element submitInfo provides information on how,
where and what to submit .
Example: XML Representation:
<submitInfo>
<submitInfo
(single node binding attributes)
action = xsd:anyURI
mediaTypeExtension = "none" | qname-but-not-ncname : "none"
method = "post" | "get" | qname-but-not-ncname : "post"
version = xsd:NMTOKEN
indent = xsd:boolean
encoding = xsd:string
mediaType = xsd:string
omitXMLDeclaration = xsd:boolean
standalone = xsd:boolean
CDATASectionElements = list of xsd:QName
replace = "all" | "instance" | "none" | qname-but-not-ncname : "all"
>
<!-- Content: (##empty) -->
</submitInfo>
single node binding attributes - optional selector
enabling submission of a portion of the instance data
action - Required destination for submitted instance
data.
mediaTypeExtension
- Optional information, additional to the mediaType, describing the
serialization format.
method - Optional indicator as to the protocol to be used to
deliver the serialized instance data.
version - corresponds to the version attribute
of xsl:output
indent - corresponds to the indent attribute of
xsl:output
encoding - corresponds to the encoding
attribute of xsl:output
mediaType - corresponds to the media-type
attribute of xsl:output
omitXMLDeclaration - corresponds to the
omit-xml-declaration attribute of
xsl:output
standalone - corresponds to the standalone
attribute of xsl:output
CDATASectionElements - corresponds to the
cdata-section-elements attribute of
xsl:output
replace
- specifier for how the information returned after submit should be
applied.
Note:
Many of these attributes correspond to XSLT attributes [XSLT]. Note that the XSLT attributes
doctype-system and doctype-public are not
supported in XForms processing.
Note:
Note also that attribute mediaTypeExtension is
useful in cases where a media type alone is not sufficiently
precise. For instance, a SOAP envelope would not be adequately
described simply by "text/xml", additional information would be
required.
4.3.5 bind
The bindings element is a container for
bind elements.
Example: XML Representation:
<bindings>
<bindings
>
<!-- Content: (bind+) -->
</bindings>
Additional details, including the definition of the <bind>
element are found in the chapter .
| Editorial
note |
|
|
As above, we need to find a place to discuss
the defaulted XLink attributes.
|
4.3.6 privacy
Element privacy is used to associate a P3P [P3P 1.0] policy reference with a particular
form.
Example: XML Representation:
<privacy>
<privacy
xlink:href = xsd:anyURI
>
<!-- Content: (##empty) -->
</privacy>
xlink:href = xsd:anyURI - Optional link to an externally
defined P3P policyref file (not an actual policy).
| Editorial
note |
|
|
As above, we need to find a place to discuss
the defaulted XLink attributes.
|
4.4 XForms
and XLink
XForms use XLink [XLink] features for
linking, or defining an explicit
relationship between resources (or portions of resources), which
may be either local or remote.
To that end, the XForms schema
references the XLink namespace with
the majority of the sensible defaults., including those based on XLink roles defined
later. Other than
xlink:href attributes, form authors in most cases will not
be required to explicitly write XLink-specific elements or
attributes. To emphasize this design, the
unprefixed attribute href is explicitly
prohibited.
XLink allows users to provide arc-type elements to specify
traversal rules. The integration of arc-type elements in XForms
would require additional elements in the model element
that are otherwise not necessary. Hence, for children of the
model element, the traversal rule is to traverse
xlink:from the current document xlink:to the
document pointed to by the external resource. The processor should
behave as if xlink:actuate="onLoad" was specified. The
xlink:show attribute is meaningless in this context,
anyway.
4.4.1 XLink
Conformance and Examples
An XForms processor is not required to implement full
XLink—correct behavior of the xlink:href
attribute (as defined in this chapter) is sufficient. For example,
an XForms Processor must accept and correctly process the schema in
both of the following:
Example: External schema constraints
<xforms:model>
<xforms:schema xlink:href="URI-to-remote-schema.xsd" />
</xforms:model>
Example: Inline schema constraints
<xforms:model>
<xforms:schema>
<xsd:schema ...>
<!-- Content: ... -->
</xsd:schema>
</xforms:schema>
</xforms:model>
This second example is unusual in that the
xforms:schema element defaults an attribute
xlink:type="simple" but lacks an xlink:href
attribute to make the link meaningful. In this situation, the
XForms Processor should switch from simple mode to
none mode for the element lacking attribute
xlink:href. For compatibility with XLink, the second example
should be explicitly authored as follows:
Example: Inline schema constraints, with
explicit xlink:type
<xforms:model>
<xforms:schema xlink:type="none">
<xsd:schema...>
<!-- Content: ... -->
</xsd:schema>
</xforms:schema>
</xforms:model>
Manual override of the xlink:type attribute.
It is permissible to construct the additional information from
the semantics of the elements. An XForms Processor can not be
XForms compliant, however, if it attempts to implement XLink and
the implementation does not conform to XLink specification with
respect to the attributes used by XForms.
Note that the XLink support uses a
well-defined XLink failure mode: If an XLink attribute is not
provided, the element looses its XLink specific meaning. We use
this feature in order to allow application developers to either
provide the model and instance via an external reference (via an
xlink:href attribute) or to provide the data inline
without the attribute. In the latter case, the XLink-specific
meaning of the element is lost and the inline content used.
If both inline content and external reference is provided, a
processor must use the external reference and ignore the inline
content.
For the purposes of XForms, we suggest that XLink aware
processors switch from the xlink:type="locator" mode
to the xlink:type="resource" mode. This should be
specified in the document by setting
xlink:type="resource", though a processing agent may not
depend on it. In other words, the first two of the following
examples must be treated identically:
6
Constraints
6.1 XForms Constraints
XForms constraints, which occur as attributes on element
bind in XForms 1.0, fall into two categories:
-
Computed expressions are XPath expressions that provide a value
to the XForms Processor. The value is recomputed at certain times,
according to the XForms Processing Model (see 11
Processing Model).
-
All other constraints are fixed, static values that the XForms
Processor evaluates only once.
The following constraints are available for all model items, using syntax
explained throughout this section. For each constraint the
following information is provided:
Description
Computed Expression (yes or no)
Applies to children (instance data child
elements and attributes)
Legal Values
Default Value
Additional descriptive text
6.1.1 type
Description: associates a Schema datatype.
Computed Expression: No
Legal Values: Any xsd:QName representing an
in-scope datatype.
Default Value: xsd:string
The concept of typed data is important to forms. The assignment
of a particular datatype to a model item affects validation of the
data it can accept, as well as affecting which form controls to
which it can bind.
The meaning of this constraint is the same as placing an
xsi:type attribute on the instance data.
6.1.2 readOnly
Description: describes whether the value is restricted from
changing. The ability of form controls to have focus and appear in
the navigation order is unaffected by this constraint.
Computed Expression: Yes
Legal Values: Any expression that is convertible to
boolean
Default Value: false
When evaluating to true, this constraint indicates
that the XForms Processor should not allow any changes to the bound
instance data node.
In addition to restricting value changes, the
readOnly constraint provides a hint to the XForms User
Interface. Form controls bound to instance data with the
readOnly constraint should indicate that entering or
changing the value is not allowed. This
specification does not define any effect on visibility, focus, or
navigation order.
6.1.3 required
Description: describes whether a value is required before the
instance data is submitted.
Computed Expression: Yes
Legal Values: Any expression that is convertible to
boolean
Default Value: false
Often forms require certain values to be entered. This may be a
static requirement, or may only be the case if some condition is
satisfied. When evaluating to true, this constraint
indicates that a non-empty instance data node is required before a
submission of instance data can occur. Non-empty is defined as:
-
If the bound instance data node is an element, the element must
not have the xsi:nil attribute set to
true.
-
The value of the bound instance data node must be convertible to
an XPath string with a length greater than zero.
Except as noted below, the required constraint does
not provide a hint to the XForms User Interface regarding
visibility, focus, or navigation order. XForms authors are strongly
encouraged to make sure that form controls that accept
required data are visible. An XForms Processor may provide a
unique indication that a form control is required, and may provide
immediate feedback, including limiting navigation.
The chapter 11 Processing Model
contains details on how the XForms Processor enforces required
values.
6.1.4 relevant
Description: indicates whether the model item is currently
relevant to the rest of the XForms Model. Instance data nodes with
relevant=false, are not serialized for
submission.
Computed Expression: Yes
Legal Values: Any expression that is convertible to
boolean
Default Value: true
Many forms have data entry dependent on other conditions. For
example, a form might ask whether the respondent owns a car. It is
only appropriate to ask for further information about their car if
they have indicated that they own one.
When evaluating to true, this constraint indicates
that the XForms Processor should render a form control, and
conversely, when evaluating to false, indicates that
the form control should be rendered specially (grayed out, hidden,
etc.).
The relevant constraint provides hints to the
XForms User Interface regarding visibility, focus, and navigation
order. In general, when true, associated form controls
should be made visible. When false, associated form
controls should be made unavailable, removed from the navigation
order, and not allowed focus.
The following table shows the user interface interaction between
required and relevant.
|
required="true" |
required="false" |
relevant="true" |
The form control (and any children)
should be visible or available to the user. The XForms User
Interface may indicate that a value is required. |
The form control (and any children)
should be visible or available to the user. The XForms User
Interface may indicate that a value is optional. |
relevant="false" |
The form control (and any children)
should be hidden or unavailable to the user. Entering a value or
obtaining focus should not be allowed. The XForms User Interface
may indicate that should the form control become relevant, a value
would be required. |
The form control (and any children)
should be hidden or unavailable to the user. Entering a value or
obtaining focus should not be allowed. |
6.1.5 calculate
Description: supplies an expression used
to calculate the value of the associated instance data
node.
Computed Expression: Yes
Legal Values: Any XPath expression that
is convertible to an XPath datatype compatible with the associated
XML Schema datatype
Default Value: none
An XForms Model may include model items that are computed from
the other values elsewhere. For example, the sum over line items
for quantity times unit price, or the amount of tax to be paid on
an order. The computed value can be represented as a computed
expression using the values of other model items. The XForms
Processing Model indicates how and when the calculation is
recomputed.
6.1.6 isValid
Description: specifies a predicate that needs to be satisfied
for the associated instance data node to be considered valid.
Computed Expression: Yes
Legal Values: Any expression that is convertible to
boolean
Default Value: true
An XForms Model may include model items
that need to be revalidated. When
evaluating to false, the associated model item is not
valid; the converse is not necessarily true. Chapter 11 Processing Model describes details such
as immediate validation versus validation upon submit.
Computed expressions used here are not restricted to examining
the instance data node they are invoked on. XPath, plus the
extensions in this specification, provide the means to traverse the
instance data, as well as call-outs to external script, enabling
potentially complex validations.
The XForms User Interface may indicate whether a form control is
currently valid or invalid.
Issue
(issue-cascade):
Will the isValid constraint be evaluated on all the
parent or child model items whenever a value changes? We need to
make sure that inter-model item constraints will get evaluated.MJD
- Is this still an issue?
6.1.7 maxOccurs
Description: for repeating structures, indicates the maximum
number of allowed child elements.
Computed Expression: No
Legal Values: xsd:integer or
"unbounded"
Default Value: "unbounded"
For model item elements that are repeated, this optional
constraint specifies a maximum number of allowed child elements.
This only applies to element nodes selected as part of a
repeat sequence (10.3 Repeating
Structures).
6.1.8 minOccurs
Description: for repeating structures, indicates the minimum
number of allowed child elements.
Computed Expression: No
Legal Values: xsd:integer
Default Value: 0.
For model item elements that are repeated, this optional
constraint specifies a minimum number of allowed child elements.
This only applies to element nodes selected as part of a
repeat sequence (10.3 Repeating
Structures).
6.2 Schema Constraints
Chapter 5 Datatypes described
how XForms adopts the XML Schema datatyping system, which can
constrain the value
space of datatypes that can be used in data collection. This section draws the connection between Schema
features and Schema Constraints, which can occur directly via a
schema or indirectly by annotating an instance with
instance-specific type constraints.
Datatypes used in XForms are either those predefined in chapter
5 Datatypes, or simpleTypes defined
in a Schema.
Attributes xsi:schemaLocation and
xsi:noNamespaceSchemaLocation are ignored for purposes for
locating a Schema.
XForms Basic processors have restricted Schema processing
requirements; full details are at
12.1.1 XForms Basic.
6.2.1 Atomic Datatype
The XForms Processing Model applies XML Schema facets as part of
the validation process. At the simplest level, it is necessary to
associate a set of facets (through a Schema datatype) with a model
item. This has the effect of restricting the allowable values of
the associated instance data node to valid representations of the
lexical space of the datatype.
The set of facets may be associated with a model item in one of
the following ways (only the first that applies is used, and if multiple datatypes apply to the same node,
the first definition in document order is used):
-
An XML Schema xsi:type attribute (restricted to simpleTypes in XForms Basic) in
the instance data.
-
(XForms Full only) An XML Schema
associated with the instance data.
-
An XForms type constraint associated with the
instance data node.
-
Otherwise, the datatype is treated as xsd:string
(default to string rule).
Example Schema Syntax: declaring a datatype based on an
xsd:string plus an additional constraining facet would be
accomplished by the following in a Schema:
<xsd:simpleType name="nonEmptyString">
<xsd:restriction base="xsd:string">
<xsd:minLength value="1"/>
</xsd:restriction>
</xsd:simpleType>
This new datatype would then be associated with one or more
model items through one of the methods outlined here:
<!-- Datatype through Schema xsi:type -->
<my:first-name xsi:type="nonEmptyString"/>
The above shows element <first-name>
annotated with type
xsi:type="nonEmptyString"—this specifies that the
element first-name is of type
nonEmptyString.
<!-- Datatype through XForms constraint -->
<instance>
<my:first-name />
</instance>
<bind type="nonEmptyString" ref="/my:first-name"/>
Here, element first-name has attached type
information via element bind. This enables the XForms
author annotate and extend external Schemas that she does not have
the ability to change.
6.3 Additional Schema
Examples
The following non-normative sections illustrate mapping between
Schema concepts and data structures commonly used in form
authoring.
6.3.1 Closed Enumeration
Often it is necessary to restrict the allowable values of the
associated instance data node to a closed list of alternatives.
Declaring a datatype allowing enumerated values of an
xsd:string would be accomplished with the following in an
external Schema:
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Mustercard"/>
<xsd:enumeration value="Donor's Club"/>
<xsd:enumeration value="World Express"/>
</xsd:restriction>
</xsd:simpleType>
6.3.2 Open Enumeration
A special case of enumerated datatypes is the common form design
pattern of a list, with an 'other, please specify' choice. This is
referred to as an open enumeration.
Declaring an open enumeration is possible through a combination
of union and enumeration features, with the following in an
external Schema:
<xsd:simpleType>
<xsd:union memberTypes="xsd:string">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Mustercard"/>
<xsd:enumeration value="Donor's Club"/>
<xsd:enumeration value="World Express"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:union>
</xsd:simpleType>
6.3.3 Union
It may be desirable for data collection purposes to allow an
instance data item to be a valid lexical value of one among several
datatypes. Unions are defined in XML Schema.
Example Schema Syntax: declaring a datatype allowing either a
creditCardType or bonusProgramType value
would be accomplished with the following in a Schema:
<xsd:simpleType>
<xsd:union memberTypes="creditCardType bonusProgramType"/>
</xsd:simpleType>
Some form controls, such as selectMany, have the
notion of collecting more than one value at any given time. This
corresponds to Schema list datatypes.
Declaring a list-derived datatype would be accomplished with the
following in a Schema:
<xsd:simpleType name="listOfMyIntType">
<xsd:list itemType="xsd:int"/>
</xsd:simpleType>
Note:
The pre-defined datatype xforms:listItems can also
be used.
6.4 Binding
Binding is the glue
that connects the separate pieces of XForms—directly
associating nodes in the instance data with model item
constraints.
Binding is specified via binding expressions, which select
nodes from the instance data. The syntax and details of binding
expressions are based on XPath, and defined in the chapter 7 XPath Expressions in XForms. This section
describes the wider topic of how binding expressions are used
within XForms.
6.4.1 bind
The bind element represents a node-set selected
from the instance data. A series of attributes on the element
correspond to individual XForms constraints to be applied to each
node in the node-set.
Example: XML Representation:
<bind>
<bind
ref = binding-expression
type = xsd:QName
readOnly = model-item-constraint
required = model-item-constraint
relevant = model-item-constraint
isValid = model-item-constraint
calculate = model-item-constraint
maxOccurs = xsd:nonNegativeInteger or "unbounded"
minOccurs = xsd:nonNegativeInteger
>
<!-- Content: (##empty) -->
</bind>
ref - A binding expression that selects which node or
nodes have the associated constraints applied
type - reference to an in-scope Schema simpleType
readOnly - model item constraint
required - model item constraint
relevant - model item constraint
isValid - model item constraint
calculate - model item constraint
maxOccurs - model item constraint
minOccurs - model item constraint
Each bind element selects a node-set from the instance data, and
applies the specified constraints. When additional nodes are added
through the insert action, the newly added nodes are
included in any node-sets matched by binding expressions.
6.4.2 Binding
Constraints
Not every possible XPath expression is acceptable as a binding
expression. The following constraints are placed upon binding
expressions:
-
No dynamic predicates. Predicates are permitted, but any
predicates used must not alter the returned node-set based on other
form settings. For example:
permitted: elem
permitted: elem[1]
permitted: elem[last()]
permitted: elem[@id="zip"] if @id is not bound to a form control
forbidden: elem[@attr="xy"] if @attr is bound to a form control
-
No dynamic variables. The XForms specification does not
provide any variables.
-
No invocation of any function that returns a node-set.
Function calls are permitted, but not any that return a
node-set.
-
No invocation of any function with side-effects. All
functions defined in the XForms specification are side-effect-free.
Any extension functions should also be side-effect-free.
Upon detecting a binding expression that violates any of the
above constraints, an form processing
terminates with a fatal error.
6.4.3 Binding References
References to node-sets are attached to form controls through
binding references, described in 8.12.2
Single Node Binding Attributes and 8.12.3 Nodeset Binding Attributes.
Different attribute names, ref vs.
nodeset, distinguish between a single node and a node-set
respectively.
First node rule: When a single-node binding expression
selects a node-set of size > 1, the first node in the node-set
is used. This has no effect on the individual nodes nor the set of
nodes selected by any particular bind element.
Consider a document with the following XForms declarations:
<xforms:model id="orders">
<xforms:instance xmlns="">
<orderForm>
<shipTo>
<firstName>John</firstName>
</shipTo>
</orderForm>
</xforms:instance>
<xforms:bind ref="/orderForm/shipTo/firstName"
id="fn" type="xsd:string"
required="true"/>
</xforms:model>
The following examples show three ways of binding user interface
control xforms:input to instance element
firstName declared in the model shown above.
Example: UI Binding Using Attribute
ref
<xforms:input ref="/orderForm/shipTo/firstName">...
Example: UI Binding Using Attribute
bind
<xforms:input bind="fn">...
Example: UI Binding Using Explicit
Model
<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...
The XForms binding mechanism allows other XML vocabularies to
bind user interface controls to an XForms model using any of the
techniques shown here. As an example, XForms binding attribute
bind might be used within legacy HTML user interface
controls as shown below.
Example: XForms Binding In Legacy HTML
User Interface Controls
<html:input type="text" name="..." xforms:bind="fn"/>
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 (such as XForms UI
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 in conjunction with the Internationalization Working
Group and 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 (which are not defined in XForms but come from an
external document type) 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. , for all mediaTypes 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.
when the mediaType is "image/*. Other
mediaTypes besides image/png may share this input
method.
Note:
Commonly, people have trouble drawing recognizable figures or
signatures with a conventional pointing device like a mouse or
track ball. Hence, a reasonable implementation of XForms might not
want this feature, hence the "may" here for generic pointing
devices
-
Implementations with specific audio recording capabilities
should support record audio—in-place recording of an
audio clip. when the mediaType is "audio/*"
or "audio/basic" . Other mediaTypes besides "audio/basic" may share
this input method.
-
Implementations with a digital camera/scanner interface or screen capture should support
acquire image—in-place upload of images from an attached
device. when the mediaType is "image/*" or
"image/jpeg". Other mediaTypes besides "image/jpeg" may share this
input method.
-
Implementations with video recording capability should provide a
record video option. for video/*
mediaTypes.
-
Implementations with 3d capabilities should provide a 3d
interface option for model/*
mediaTypes.
-
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.
Issue
(enum-range):
Should an enumeration be allowed to bind to this form control?
If yes, how should it be ordered?
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. The
value given in the user interface shown above may be
used in constructing a default schema for
the data item being populated if no schema is provided by
the XForms author.
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.
value = lexical-representation - the "storage value" for the
item, to be placed in the instance data when this item is
chosen.
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.11.5 itemref
This element is used within the selection form controls to
represent a single item of the list, where the following conditions
apply:
There is an XForms Model available
And the author wishes to point at a node in an instance
tree where the choice is stored. This element is also used when
authoring forms where the available choices are only known at
runtime.
Notice that in the case where element itemref is
used, the storage value does not have the limitations that
exist when using element item.
Note:
Form authors should be aware that instance data selected by is
directly placed into the instance data. For example selecting an
element node with /node makes the entire node element
the storage value, while an expression such as
/node/text() selects just the text content. Combinations
that produce mixed content in the instance data are forbidden.
Example: XML Representation:
<itemref>
<itemref id = xsd:ID
ref = xpath-expression >
<!-- unordered: (caption, help?, hint?, alert?, action?) -->
</itemref>
id = xsd:ID - optional unique identifier.
ref = xpath-expression - XPath locator of the the "storage
value" for the item, to be placed in the instance data when this
item is chosen.
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.
CSS properties for controlling the look and feel of XForms user
interface controls are being defined in conjunction with the CSS
Working Group. The CSS Working Group has agreed to help us develop
a default CSS stylesheet capable of producing the sample default
renderings illustrated in this working draft. The results of the
above will be used to document the use of CSS properties within
XForms user interface elements for the final version of the XForms
specification.
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.
Platform-specific user actions for selecting e.g.,
mouse focus, implicitly invoke handler setRepeatCursor
on the item that got the selection.
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.
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.
9.13 toggle
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
inline 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
In CSS-based layout systems, groups lay out their children using
a constraint-based system that supports both relative flexible
sizing and intrinsic sizing. Through CSS, an inline box can be
specified using the display property with a value of
inline. A block-level group can be specified with a
value of block, which is the default.
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 appearing within
form controls 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
default = xsd:IDREF
- 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.
Issue
(issue-switch-scroll):
In addition to toggle, the XForms Action
scroll might be used within switch to cycle
through the various contained case clauses.
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. These, along with cursor, can be thought of
as the markup equivalent of limited DOM access to the XML instance
being populated.
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. But as a consequence, the user interface cannot bind to
an element from the underlying collection out of sequence
except by using an absolute XPath expression.
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. In combination with the
facilities provided by element group and CSS layout,
this allows document authors to customize the positioning of
controls for standard actions such as insert or delete.
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 attributes
startIndex and number provide hints to the user
interface as to which elements should be displayed
initially. 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.
-
-
If the selected content of the instance data corresponds to a
multiply-rooted data structure (such as a general parsed entity),
an the above serialization takes place, after which the serialized
instance data is inserted as child elements of the unqualified
element <Body>, which is in turn inserted as a
child of the unqualified element <Envelope>.
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.
