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 for enabling interactive web applications. Web
applications and electronic commerce solutions have sparked the
demand for better web forms with richer interactions. XForms are
the response to this demand and provide a new platform-independent
markup language for online interaction between an XForms
Processor and a remote user agent. XForms are the successor to
HTML forms, and benefit from the lessons learned from HTML
forms.
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 before specifying the technical
details of the various XForms components.
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 outlines the design
principles and includes a brief tutorial on XForms.
- 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.
- Appendixes
-
Appendixes contain a normative description of XForms described
in XML Schema, information on references, and other useful
information.
1.4 Documentation
Conventions
Throughout this document, the following namespace prefixes and
corresponding namespace identifiers are used:
xforms: The XForms namespace 3.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 only a convention; any namespace prefix may be used in
practice.
The following typographical conventions are used to present
technical material in this document.
Official terms are defined in the following manner: [Definition: You can find
most terms in chapter 12 Glossary Of
Terms]. Links to terms may be specially highlighted
where necessary.
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
listing 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 3.2
Horizontally Applicable Markup are not shown in the syntax
representations except when special attention needs to be called to
their presence.
Examples are set off typographically:
References to external documents appear as follows: [Sample Reference] with links to the references
section of this document.
- Sample
Reference
- Reference - linked to from above.
The following typesetting convention is used for non-normative
commentary:
Note:
A gentle explanation or 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.
Resolution:
None recorded.
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 chapter provides an easily approachable description of
XForms. Not every feature of XForms is covered here. For a complete
and normative description of XForms, refer to the remainder of this
document. The following subsections develop a complete example of
an XForms application that is hosted in an XHTML document. The
complete example is found in E.1
XForms In XHTML.
2.1 Separating
Purpose From Presentation
A typical form starts off with a purpose, e.g., data
collection. This purpose is realized by creating an interactive
presentation that allows the user to provide the requisite
information. The resulting data is the result of
completing the form.
| Purpose |
Presentation |
Data |
| Data collection |
Arrangement of form controls |
Registration information |
| List hours worked |
UI for collecting dates and times
worked |
Days and hours worked |
| Shopping application |
Present shopping user interface |
Order, shipping, and payment info |
| Information collection |
Integrate forms user interface into WWW
page |
User contact information |
HTML forms failed to 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, and such validation code can be automatically
generated.
- Existing schema re-use
-
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.
- External schema augmentation
-
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.
- XML submission
-
This obviates the need for custom server-side logic to marshal
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 for instance data ensures that the submitted data
is internationalization ready.
- 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. XForms user interface controls are generic and suited
for device-independence.
- 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-target 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 can be statically analyzed; contrast this with the
present practice of using imperative scripts for event
handlers.
2.2 Current Approach: HTML
Consider a simple electronic commerce form authored in HTML:
Example: HTML Form
<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 user agent 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 pair serialization of the
resulting data as name-value pairs. In contrast, XForms greatly
improve the expressive capabilities of electronic forms.
2.3 Transition to XForms
In 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. XForms 1.0 defines the
XForms User Interface, which is a device-independent,
platform-neutral set of form controls suitable for general-purpose
use. The user interface is bound to the XForms model via
the XForms binding mechanism; This flexible architecture 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 submitInfo="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 accessibility.
-
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 document)
-
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
XForms processing keeps track of the state of the partially
filled form through instance data. Initial values for the
instance may be provided via element instance. Element
instance holds a skeleton XML document that gets
updated as the user fills out the form. Element
instance gives the author full control on the
structure of the submitted XML data, including namespace
information. When the form is submitted, the instance data is
serialized as an XML document. 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 contains the instance data.
-
Empty elements cc and exp serve as
place-holders 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.
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.
Example: Binding Expression
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
XForms allows data to be checked for validity as the form is
being filled. Referring to the earlier HTML form in 2.2 Current Approach: HTML, there are
several desirable aspects that would only be possible to ensure
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
validation information in forms. Such information can be taken from
XML Schemas as well as XForms-specific constraints, such as
relevant. XForms constraints appear on
bind elements, while Schema constraints are expressed
in an XML Schema fragment, either inline or external. For
example:
... xmlns:my="http://commerce.example.com/payment"...
<xforms:bind ref="my:payment/my:cc"
relevant="../my:payment/@as = 'credit'"
required="true"
type="my:cc"/>
<xforms:bind ref="my:payment/my:exp"
relevant="../my:payment/@as = 'credit'"
required="true"
type="xsd:gYearMonth"/>
<xforms:schema>
<xsd:schema ...>
...
<xsd:simpleType name="cc">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{14,18}"/>
</xsd:restriction>
</xsd:simpleType>
...
</xsd:schema>
</xforms:schema>
2.6 Multiple Forms per
Document
XForms processing places no limits on the number of individual
forms that can be placed in a single containing document. When a
single document contains multiple forms, each form needs a separate
model element. 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.
In addition, form controls need to specify the
model element contains the instance data to which they
bind. This is accomplished through a model attribute
alongside the ref attribute. The default for the
model attribute is the first model
element in document order.
The next example adds an opinion poll to our electronic commerce
form.
<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 here is the use of
model="poll", which identifies the instance.
3 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 within XHTML [XHTML 1.0]. This chapter discusses the
structure of XForms that allow this specification to be used with
other document types.
3.1 The XForms Namespace
The XForms namespace has the URI:
http://www.w3.org/2002/01/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.
3.2 Horizontally Applicable
Markup
Every element defined in this specification declares attribute
id of type xsd:ID—see the schema
for XForms—this allows these elements to be referenced via
attributes of type xsd:idref.
Foreign-namespaced attributes are allowed
on any XForms element. The XForms Processor must ignore any
foreign-namespaced elements or attributes that are
unrecognized.
Note that except where specifically allowed by the Schema for
XForms, foreign-namespaced elements are not allowed as content of
elements in the XForms namespace.
3.3 Model
This section describes XForms element model used as
a container for XForms elements defining the XForms model. The containing document may contain one
or more model elements. Element model
defines the underlying model to which the XForms document
binds user interaction. Hence, model elements
occur before the user interaction markup. The content of element
model is typically not rendered. As an example,
model elements occur within element
html:head of an XHTML document, whereas XForms user
interface markup appears within element html:body.
XML Representation:
<model>
<model
extensionFunctions = list of QNames
>
<!-- Content: instance?, schema?, (privacy|submitInfo|bind|action|extension)* -->
</model>
extensionFunctions - Optional list of XPath extension
functions used by this XForms Model. It is an error to use an
undeclared extension function.
Element model can contain the following
elements.
- Instance
-
Defines skeleton instance document and holds initialization data
if any—see 3.4
instance.
- Schema
-
Defines schema for the instance—see 3.5 schema
- submitInfo
-
Holds submit details—see 3.6 submitInfo
- Bindings
-
Elements bind that establish one or more XForms
bindings to define model item constraints—see
6 Constraints.
- Privacy
-
Establishes P3P properties—see 3.7 privacy
- Action
-
Event handlers—see 10.16 action. This allows
the author to handle events that arrive at node
model—see the processing model 4 Processing Model.
- Extension
-
Extension elements if any—see 8.12.4.5 extension
Example: Model
<model xmlns="http://www.w3.org/2002/01/xforms" id="Person">
<instance xlink:href="http://example.com/cgi-bin/get-instance" />
<schema xlink:href="Schema-Questionnaire.xsd" />
...
</model>
3.4 instance
Element instance contains a skeleton instance
document that provides initial instance data. The instance data may
be defined inline or obtained from an external URI.
XML Representation:
<instance>
<instance xlink:href = xsd:anyURI >
<!-- Content: (##any) -->
</instance>
xlink:href - Optional link to externally defined instance
data
The content of the instance element is arbitrary
XML in any namespace. other than the XForms
namespace. The content of this
element is treated as opaque data. Authors must ensure that
proper namespace declarations are used for content within the
instance element.
3.5 schema
Element schema contains the schema defining the
instance. The schema may be defined inline or obtained from an
external URI.
XML Representation:
<schema>
<schema xlink:href = xsd:anyURI >
<!-- Content: ##other (though typically <xsd:schema>) -->
</schema>
xlink:href - Optional link to an externally defined
schema.
3.6 submitInfo
Element submitInfo encodes how, where and what to
submit.
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: XForms Actions -->
</submitInfo>
single node binding attributes - optional selector
enabling submission of a portion of the instance data
action - Required destination for submitting instance
data.
mediaTypeExtension - Optional information describing the
serialization format. This is in addition to the mediaType.
method - Optional indicator as to the protocol to be used to
transmit 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.
3.7 privacy
Element privacy is used to associate a P3P [P3P 1.0] policy reference with a particular
form.
XML Representation:
<privacy>
<privacy
xlink:href = xsd:anyURI
>
<!-- Content: (##empty) -->
</privacy>
xlink:href - Optional link to an externally defined P3P
policyref file (not an actual policy).
3.8 XForms and XLink
XForms uses XLink [XLink] for linking
and for defining an explicit relationship between resources that
may be either local or remote. To this end, the XForms schema
references the XLink namespace with sensible defaults. Other than
in the case of attribute xlink:href, form authors will
not be required to explicitly write XLink-specific elements or
attributes.
All XLinks in XForms are simple links. For further details, see
3.8.1 XLink Conformance
and Examples.
3.8.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:
External schema constraints
<xforms:model>
<xforms:schema xlink:href="URI-to-remote-schema.xsd" />
</xforms:model>
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:
Inline schema constraints, with explicit
xlink:type
<xforms:model>
<xforms:schema xlink:type="none">
<xsd:schema...>
<!-- Content: ... -->
</xsd:schema>
</xforms:schema>
</xforms:model>
Notice the explicit override of the xlink:type
attribute.
If both inline content and external reference is provided, a
processor must use the external reference and ignore the inline
content.
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 XPath 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.
If the instance data is multiply rooted, the returned document
has unqualified element instanceData as the
documentElement, with the content of the XForms Model
as children.
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 elements containing binding expressions in
XForms:
-
The context node for outermost binding elements is the XPath
root (/). A " binding element" is any element
other than bind that is
explicitly allowed to have a binding expression attribute. A
binding element is "outermost" when the node-set returned by
the XPath expression ancestor::* includes no binding
element nodes.
-
The context node for non-outermost binding elements is the first
node of the binding expression of the immediately enclosing
element. An element is "immediately enclosing" when it is
the first binding 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 computed expressions (occurring on element
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, plus any
function names declared in attribute
extensionFunctions on element model.
-
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 XForms 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 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 9.3
repeat 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 11 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).
7.4.4 Extension Functions
XForms documents may use additional XPath extension functions
beyond those described here. The names of any such extension
functions must be declared in attribute
extensionFunctions on element model. Such
declarations are used by the XForms processor to check against
available extension functions. XForms processors perform this check
at the time the document is loaded, and stop processing by
signalling a fatal error if the XForms document declares an
extension function for which the processor does not have an
implementation.
Note:
Explicitly declaring extension functions enables XForms
processors detect the use of unimplemented extension functions at
document load-time, rather than throwing a fatal error during user
interaction. Failure by authors to declare extension functions will
result in an XForms processor potentially halting processing during
user interaction with a fatal error.
8 Form Controls
XForms User Interface controls—form controls—are declared using
markup elements, and their behavior refined via markup attributes.
This markup may be decorated with class attributes
that can be used in CSS stylesheets to deliver a customized look
and feel. XForms user interface controls are bound to the
underlying instance data using binding attributes as defined in the chapter 6 Constraints.
Form controls enable accessibility by taking a uniform approach
to such features as captions, help text, tabbing and keyboard
shortcuts. Internationalization issues are addressed by following
the same design principles as in XHTML. All form controls are
suitable for styling using Aural CSS (ACSS) style properties.
Form controls encapsulate high-level semantics without
sacrificing the ability to deliver real implementations. For
instance, form controls selectOne and
selectMany enable the user select one or more
items from a set. These 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.
Form controls when rendered display the underlying data values
to which they are bound. While the data presented to the user
through a form control must directly correspond to the bound
instance data, the display representation is not required to
exactly match the lexical value. For example, user agents should
apply appropriate conventions to the display of dates, times,
durations and numeric values including separator characters.
XForms user interface controls use common attributes and
elements that are defined in (8.12 Common
Markup ). Sections in this chapter define the various form
controls by specifying the following:
Description
Examples
Data Binding Restrictions
Implementation Requirements
XML Representation
8.1 input
Description: This form control enables free-form data entry.
<input ref="order/shipTo/street" class="streetAddress">
<caption>Street</caption>
<hint>Please enter the number and street name</hint>
</input>
In the above, the class attribute can be used by a
stylesheet to specify the display size of the form control. Note
that the constraints on how much text can be input are obtained
from the underlying XForms Model definition and not from these
display properties.
A graphical browser might render the above example as
follows:
Data Binding Restrictions: Binds to any simpleContent (except
xsd:base64Binary, xsd:hexBinary or any
datatype derived from these).
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.
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 in 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. D Input Modes
Note:
Notice that not binding any user interface to a piece of
instance data results in an hidden form control in XForms;
consequently, there is no need to explicitly define input form
controls with type="hidden" as in HTML.
8.2 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.
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 in 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. D Input Modes
8.3 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.
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 in 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. D 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.
XML Representation:
<output>
<output
(single node binding attributes)
>
<!-- empty content -->
</output>
(single node binding attributes) - Selection of instance
data node, defined in 8.12.2 Single
Node Binding Attributes
8.5 upload
Description: This form control enables the common feature found
on Web sites to upload a file from the local file system, as well
as accepting input from various devices including microphones,
pens, and digital cameras.
Example: Uploading An Image
<upload ref="mail/attach1" mediaType="image/*">
<caption>Select image:</caption>
</upload>
A graphical browser might render this form control as
follows:
Data Binding Restrictions: This form control can only be bound
to datatypes xsd:base64Binary or
xsd:hexBinary, or types derived by restriction from
these.
Implementation Requirements: For suitable mediaTypes:
-
Implementations with a file system should support file
upload—selecting a specific file. The types of files
presented by default must reflect the mediaType specified in the
XForms Model, for example defaulting to only audio file types in
the file dialog when the mediaType is "audio/*". In XForms 1.0,
there is a 1:1 binding between a upload form control and one of the
binary datatypes, although that single file may be
compound (e.g. application/zip).
-
Implementations with specific pen/digitizer hardware should (and
implementations with other pointing devices may) support
scribble—allowing in-place creation of pen-based
data.
-
Implementations with specific audio recording capabilities
should support record audio—in-place recording of an
audio clip.
-
Implementations with a digital camera/scanner interface or
screen capture should support acquire image—in-place
upload of images from an attached device.
-
Implementations with video recording capability should provide a
record video option.
-
Implementations with 3d capabilities should provide a 3d
interface option.
-
Implementations may provide proprietary implementations (for
example, a mediaType of text/rtf could invoke an edit window with a
proprietary word processing application)
-
Implementations are encouraged to support other input devices
not mentioned here.
-
Implementations which cannot support upload for the given
mediaType must make this apparent to the user.
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 in 8.12.2 Single
Node Binding Attributes
common attributes defined in 8.12.1 Common Attributes
mediaType - list of suggested media types, used by the
XForms Processor to determine which input methods apply.
8.6 range
Description: This form control allows selection from a
continuous range of values.
Example: Picking From A Range
<range ref="/stats/balance" start="-2.0" end="2.0" stepSize="0.5">
<caption>Balance</caption>
</range>
A graphical browser might render this as follows:
Data Binding Restrictions: Binds only the following list of
datatypes, or datatypes derived by restriction from those in the
list: xsd:duration, xsd:date,
xsd:time, xsd:dateTime,
xsd:gYearMonth, xsd:gYear,
xsd:gMonthDay, xsd:gDay,
xsd:gMonth, xsd:float,
xsd:decimal, xsd:double.
Implementation Requirements: Must allow input of a value
corresponding to the bound datatype. Implementations should inform
the user of the upper and lower bounds, as well as the step size,
if any. In graphical environments, this form control may be
rendered as a "slider" or "rotary control".
Notice that the attributes of this element encapsulate
sufficient metadata that in conjunction with the type information
available from the XForms Model proves sufficient to produce
meaningful prompts when using modalities such as speech, e.g., 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.
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 in 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—a legal value for the underlying data.
end - optional hint for the ending bound for the
range—a legal value for the underlying data.
stepSize - optional hint to use for incrementing or
decrementing the value. Should be of a type capable of expressing
the difference between two legal values of the underlying data.
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: 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.
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: 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 event
xforms:submit to the submitInfo element
specified by required attribute
submitInfo. If not specified,
the first submitInfo element in document order is
used.
XML Representation:
<submit>
<submit
(common attributes)
submitInfo = xsd:IDREF #REQUIRED
>
<!-- caption, (help|hint|alert|action|extension)* -->
</submit>
submitInfo - Required reference to element
submitInfo
common attributes defined in 8.12.1 Common Attributes
8.9 selectOne
Description: This form control allows the user to make a single
selection from multiple choices.
Example: Pick A Flavor
<selectOne ref="my:icecream/my:flavor">
<caption>Flavour</caption>
<item>
<caption>Vanilla</caption>
<value>v</value>
</item>
<item>
<caption>Strawberry</caption>
<value>s</value>
</item>
<item>
<caption>Chocolate</caption>
<value>c</value>
</item>
</selectOne>
In the above example, selecting one of the choices will result
in the associated value given by element value on the
selected item being set in the underlying data instance at the
location icecream/flavor.
A graphical browser might render this form control as any of the
following:
| listbox |
checkbox |
radio |
menu |
|
|
|
 |
Data Binding Restrictions: Binds to any simpleContent.
Implementation Requirements: The caption for each choice must be
presented, allowing at all times exactly one selection. This form
control stores the value corresponding to the selected choice in
the location addressed by attribute ref. The value to
be stored is either directly specified as the contents of element
value, or specified indirectly through attribute
ref on element value.
Note that the datatype bound to this form control may include a
non-enumerated value space, e.g., xsd:string. In this
case, control selectOne may have attribute
selection="open". The form control should then allow
free data entry, as described in 8.1
input.
For closed selections:If the initial instance value matches the
storage value of one of the given items, that item is selected. If
there is no match, the first item is initially selected.
For open selections: If the initial instance value matches the
storage value specified by one of the items, the first such
matching item is selected. Otherwise, the selected value is the
initial lexical value. 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 attribute selectUI. 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
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 in 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.
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 in 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.
XML Representation:
<choices>
<choices>
<!-- caption?, (choices|item|itemset)+ -->
</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.
XML Representation:
<item>
<item>
<!-- caption, value, (help|hint|alert|action|extension)* -->
</item>
id = xsd:ID - optional unique identifier.
8.11.3 itemset
Element itemset allows the creation of dynamic
selections within controls selectOne and
selectMany, where the available choices are determined
at run-time. The node-set that holds the available choices is
specified via attribute nodeset. Child elements
caption and value indirectly specify the
caption and storage values. Notice that the run-time effect of
itemset is the same as using element
choices to statically author the available
choices.
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.
XML Representation:
<value>
<value
(single node binding attributes)
>
<!-- ##any -->
</value>
single node binding attributes - optional binding
selector that specifies a location from where the storage value is
to be fetched.
If inline content and a ref attribute are both
specified, the ref attribute is used.
8.12 Common Markup
The preceding form control definitions make reference to child
elements and attributes that are common to several of the form
controls. This section defines these common markup components.
8.12.1 Common
Attributes
The following attributes are common to many user-interface
related XForms elements.
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
4 Processing Model.
accessKey - Optional attribute defines a shortcut for
moving the input focus directly to a particular form control. The value
of this is typically a single character which when pressed together
with a platform specific modifier key (e.g., the alt key)
results in the focus being set to this form control.
8.12.2 Single Node Binding
Attributes
The following attributes define a binding between a form control
and an instance data node.
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.
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.
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 in 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">.
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 in 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">.
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 in 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">.
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 in 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
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.
XML Representation:
<extension>
<extension>
<!-- ##other -->
</extension>
For example, RDF 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 rdf:about="#email-input">
<my:addressBook>personal</my:addressBook>
</rdf:Description>
</rdf:RDF>
</extension>
</input>
9 XForms User Interface
This chapter covers XForms features for combining form controls into user
interfaces.
All form controls defined in 8 Form
Controls are treated as individual units for purposes of
visual layout e.g., in XHTML processing. Aggregation of form
controls with markup defined in this chapter provides semantics
about the relationship among user interface controls; such
knowledge can be useful in delivering a coherent UI to small
devices. For example, if the user interface needs to be split up
over several screens, controls appearing inside the same
aggregation would typically be rendered on the same screen or
page.
9.1 group
The group element is used as a container for
defining a hierarchy of form controls. Groups can be nested to
create complex hierarchies.
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.
9.2 switch
The XForms model allows the authoring of dynamic user interfaces
that vary based on the current state of the instance data being
populated—see model item property relevant 6.1.4 relevant. 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 example is when the underlying XForms model contains
conditional structures.
This section defines construct switch that allows
the creation of user interfaces where the user interface can be
varied based on user actions and events. Element
switch contains one or more case
elements. Markup contained within element case
specifies the user interface that is displayed when that
case is selected. Boolean attribute
selected of element case determines the
selected state and can be manipulated programmatically via
the DOM, or declaratively via XForms action toggle.
Attribute id of case is used within
action toggle for this purpose. The following example
demonstrates the use of switch.
Example: switch
<switch id="sw">
<case id="in" selected="true">
<input ref="yourname">
<caption>Please tell me your name</caption>
<action ev:event="activate">
<toggle case="out"/>
</action>
</input>
</case>
<case id="out" selected="false">
<html:p>Hello <output ref="yourname" />.
<button id="editButton">
<caption>Edit</caption>
<action id="editAction" ev:event="activate">
<toggle case="in"/>
</action>
</button>
</html:p>
</case>
</switch>
The above results in the portion of the user interface contained
in the first case being displayed initially. This
prompts for the user's name; filling in a value and
activating the control e.g., by pressing
return results in XForms event activate.
Event activate is handled by the attached
handler—element action. This handler uses XForms
action toggle to select the case with
id="out". This sets attribute selected on
case id="out" to true. The markup
contained in the selected case displays the name the
user entered along with an edit button. Activating the
edit button in turn results in the attached handler selecting
case id="in".
XML Representation:
<switch>
<switch
(common attributes)
>
<!-- case+ -->
</switch>
(common attributes) - defined in 8.12.1 Common Attributes
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.
9.3 repeat
The XForms Model allows the definition of repeating structures
such as multiple items within a purchase order. When defining the
XForms Model, such higher-level collections are constructed out of
basic building blocks; similarly, this section defines user
interface construct repeat 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.
Example: Shopping Cart
<repeat nodeset="/cart/items/item">
<input ref="." .../><html:br/>
</repeat>
Element repeat operates over a homogeneous
collection by binding the encapsulated user interface
controls to each element of the collection. Attributes on element
repeat specify how many members of the collection are
presented to the user at any given time. XForms actions
insert, delete and
setRepeatCursor can be used to operate on the
collection—see 10 XForms
Actions. 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):
Example: Repeat Unrolled
<!-- 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 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.
Example: Homogeneous Collection
<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="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="activate" nodeset="my:lines/my:line"
at="cursor('lineset')"/>
</button>
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 in 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.
9.3.1 Repeat Processing
The markup contained within the body of element
repeat specifies the user interface to be generated
for each member of the underlying collection. During user interface
initialization (see 4.2.4
xforms:UIInitialize), the following steps are performed for
repeat:
-
Attribute nodeset is evaluated to locate the
homogeneous collection to be operated on by this
repeat.
-
The corresponding nodes in element instance in the
source document are located—these nodes provide initial
values and also serve as a prototypical instance for
constructing members of the repeating collection.
-
The cursor for this repeating structure is initialized
to point at the head of the collection.
-
The user interface template specified within element
repeat is bound to this prototypical
instance. If there is a type mismatch between the prototypical
instance and the binding restrictions for the user interface
controls, an error is signaled and processing stops.
-
User interface as specified by the repeat is
generated for the requisite number of members of the collection as
specified by attributes on element repeat, and model
item constraints minOccurs and
maxOccurs.
The user interface markup for repeating structures adds
encapsulation metadata about the collection being populated. The
processing model for repeating structures uses a cursor
that points to the current item in the data instance. This
repeat cursor is accessed via XForms extension functions
cursor 7.4.2.5
cursor() and manipulated via XForms action
setRepeatCursor 10.10 setRepeatCursor. This
cursor is used as a reference point for insert and
delete operations. Notice that the contained XForms
form controls inside element repeat do not explicitly
specify the index of the collection entry being populated. This is
intentional; it keeps both authoring as well as the processing
model simple.
The binding expression attached to the repeating sequence
returns a node-set of the collection being populated, not an
individual node. Within the body of element repeat,
binding expressions are evaluated with a context node of the node
determined by the repeatCursor. Repeat processing uses XPath
expressions to address the collection over which element
repeat operates. The XPath expression used as the
value of attribute nodeset must select a node-set of
contiguous child element nodes, with the same local name and
namespace name of a common parent node—this ensures that the
node-set represent a homogeneous collection. The behavior of
element repeat with respect to other XPath node-sets
is undefined. The initial instance data supplies the prototypical
member of the homogeneous collection, and this is used during UI
initialization—4.2.4
xforms:UIInitialize—to construct the members of the
homogeneous collection. This prototypical instance is also used by
action insert when creating new members of the
collection. To create homogeneous collections, the initial instance
data must specify at least one member of the collection;
this requirement is similar to requiring instance data in
addition to a schema, and the same justification applies.
The form controls appearing inside repeat need to
be suitable for populating individual items of the collection. 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.
9.3.2 Nested Repeats
It is possible to nest repeat elements to create more powerful
user interface for editing structured data. E.2 Editing Hierarchical Bookmarks
Using XForms is an example of a form using nested repeats
to edit hierarchical data consisting of bookmarks within multiple
sections. Notice that an inner repeat's cursor always starts from
1. Consider the following insert
statement that appears as part of that example.
Example: Repeat Cursor And Nested
Repeats
<xforms:insert
nodeset="/bookmarks/section[cursor('repeatSections')]/bookmark"
at="cursor('repeatBookmarks')"
position="after"/>
The above insert statement is used in that example
to add new bookmark entries into the currently selected
section. The inner (nested) repeat operates on bookmarks in this
selected section; The cursor—as returned by XForms function
cursor—for this inner repeat starts at
1. Hence, after a new empty section of bookmarks is
created and becomes current, the first insert
bookmark operation adds the newly created bookmark at the
front of the list.
9.3.3 User Interface
Interaction
Element repeat enables the binding of user
interaction to a homogeneous collection. The number of displayed
items might be less than the total number available in the
collection. In this case, the presentation would render only a
portion of the repeating items at a given time. For example, a
graphical user interface might present a scrolling table. The
current item indicated by the repeat cursor should be presented at
all times, for example, not allowed to scroll out of view. The
XForms Actions enumerated at 10 XForms
Actions may be used within event listeners to manipulate
the homogeneous collection being populated by scrolling, inserting
and deleting entries.
Notice that the markup encapsulated by element
repeat acts as the template for the user interaction
that is presented to the user. As a consequence, it is not possible
to refer to portions of the generated user interface via statically
authored idref attributes. A necessary consequence of
this is that XForms 1.0 does not specify the behavior of construct
switch within element repeat. Future
versions of XForms may specify the behavior of switch
inside repeat based on implementation experience and
user feedback.
10 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.
XForms actions are declarative XML event handlers that capture
high-level semantics. As a consequence, they significantly enhance
the accessibility of XForms-based applications in comparison to
previous web technologies that relied exclusively on scripting.
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].
10.1 dispatch
This action dispatches an XForms Event to a specific element
identified by the target attribute. Two kinds of event
can be dispatched:
One of the predefined XForms events (i.e., xforms:event-name),
in which case the bubbles and cancelable attributes are ignored and
the standard semantics as defined in the Processing model
apply.
An event created by the XForms author with no predefined XForms
semantics and as such not handled by default by the XForms
processor.
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.
10.2 refresh
This action dispatches an xforms:refresh event.
This action results in the XForms user interface being
refreshed, and the presentation of user interface controls
being updated to reflect the state of the underlying instance data
--see 4.3.15 xforms:refresh
XML Representation:
<refresh>
10.3 recalculate
This action dispatches an xforms:recalculate event.
As a result, instance data nodes whose values need to be recomputed
are updated as specified in the processing model --see 4.3.17 xforms:recalculate.
XML Representation:
<recalculate>
10.4 revalidate
This action dispatches an xforms:revalidate event.
This results in the instance data being revalidated as specified by
the processing model --see 4.3.16
xforms:revalidate
XML Representation:
<revalidate>
10.5 setFocus
This action 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.
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.
10.6 loadURI
This action traverses the specified XLink.
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.
10.7 setValue
This action explicitly sets the value of the specified instance
data node.
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 ("").
10.8 submitInstance
This action initiates submit processing by dispatching an
xforms:submit event. Processing of event
xforms:submit is defined in the processing
model—see 4.4.1
xforms:submit.
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"/>
10.9 resetInstance
This action initiates reset processing by dispatching an
xforms:reset event to the specified
model. Processing of event xforms:reset
is defined in the processing model—see 4.3.18 xforms:reset.
XML Representation:
<resetInstance>
<resetInstance
model = xsd:IDREF
/>
model = xsd:IDREF - Selection of instance data for reset,
defined in 8.12.3 Nodeset Binding
Attributes
10.10 setRepeatCursor
This action marks a specific item as current in a repeating
sequence (within 9.3 repeat).
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.
10.11 insert
This action is used to insert new entries into a homogeneous
collection, e.g., a set of items in a shopping cart. Attributes of
action insert specify the insertion in terms of the
collection in which a new entry is to be inserted, and the position
within that collection where the new node will appear. The new node
is created by cloning the final member of the homogeneous
collection specified by the initialization instance data. In this
process, nodes of type xsd:ID are not copied. The
rules for insert processing are as follows:
-
The homogeneous collection to be updated is determined by
evaluating binding attribute nodeset.
-
The corresponding node-set of the initial instance data is
located to determine the prototypical member of the collection. The
final member of this collection is cloned to produce the node that
will be inserted. Finally, this newly created node is inserted into
the instance data at the position specified by attributes
position and at.
Attribute at is evaluated to determine the
insertion index—a numerical value that is the index into the
node-set. Attribute position specifies whether the new
node is inserted before or after this index.
The rules for selecting the 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 either 1 or the size of the node-set,
whichever is closer.
-
Finally, the cursor for any repeat that is bound to
the homogeneous collection where the node was added is updated to
point to the newly added node.
This action results in the insertion of newly created data nodes
into the XForms data instance. Such nodes are constructed as
defined in the initialization section of the processing
model—see 4.2 Initialization
Events. Following the insertion of the newly created node
into the instance data, events xforms:recalculate,
xforms:revalidate and xforms:refresh are
triggered in sequence. As an example, this causes the instantiation
of the necessary user interface for populating a new entry in the
underlying collection when used in conjunction with repeating
structures 9.3 repeat.
XML Representation:Action
<insert>
<insert
(node-set binding attributes)
at = XPath expression
position = "before" | "after"
/>
(nodeset binding attributes) - Selection of instance data
nodes, defined in 8.12.3 Nodeset
Binding Attributes
at - required XPath expression evaluated to determine insert
location.
position - required selector if insert before/after
behavior.
An example of using insert with a repeating
structure is located at 9.3 repeat.
Note that XForms Action setValue can be used in
conjunction with insert to provide initial values for
the newly inserted nodes.
10.12 delete
This action deletes nodes from the instance data. The rules for
delete processing are as follows:
-
The homogeneous collection to be updated is determined by
evaluating binding attribute nodeset. If the
collection is empy, the delete action has no effect.
-
The n-th node is deleted from the instance data,
where n represents the number returned from node-set
index evaluation, defined in 10.11
insert.
-
If the last item in the collection is removed, the cursor
position becomes 0. Otherwise, the cursor will point to the new
n-th item.
This action results in deletion of nodes in the instance data.
Following the specified deletion, events
xforms:recalculate, xforms:revalidate and
xforms:refresh are triggered in sequence. As an
example, this causes the destruction of the necessary user
interface for populating a deleted entry in the underlying
collection when used in conjunction with repeating structures 9.3 repeat.
XML Representation:Action
<delete>
<delete
(node-set binding attributes)
at = XPath expression
/>
(nodeset binding attributes) - Selection of instance data
nodes, defined in 8.12.3 Nodeset
Binding Attributes
at - XPath expression evaluated to determine insert
location.
An example of using delete with a repeating
structure is located at 9.3
repeat.
10.13 toggle
This action selects one possible case from an exclusive list of
choices e.g., encapsulated by switch see 9.2 switch, by:
-
Dispatching an xforms:deselect event to the
currently selected item.
-
Dispatching an xform:select event to the item to be
selected.
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.
10.14 script
This action encapsulates an event handler authored in the
specified scripting language. The handler
may be inline, i.e., as PCDATA content of element
script; alternatively it may be contained in an
external resource and referred to via XML-events attribute
ev:handler. Optional attribute role
serves as documentation for the handler.
XML Representation: Action
<script>
<script
type = xsd:string
role=xsd:string
>
<!-- #CDATA -->
</script>
type = xsd:string - required mime-type identifier of
scripting language.
role = xsd:string - Optional descriptive text documenting
the contained script.
10.15 message
This action encapsulates a message to be displayed to the
user.
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:
10.16 action
Action action is used to group multiple
actions.
XML Representation:
<action>
<action
>
<!-- Action handlers -->
</action>
When using element action to group actions, care
should be taken to list the event on element action,
rather than on the contained actions.
Example: Grouping Actions
<button>
<caption>Click me</caption>
<action ev:event="xforms:activate">
<resetInstance/>
<setValue/>
</action>
</button>
Notice that in the above example,
ev:event="xforms:activate" occurs on element
action. Placing
ev:event="xforms:activate" on either or both of the
contained actions will have no effect. This is because the above
example relies on the defaulting of XML-Event attributes
observer and handler. As defined in the
XML-Events specification, if both observer and handler attributes
are omitted, then the parent is the observer. Placing
ev:event="xforms:activate" on the children of element
action therefore causes element action to
become the observer for the individual actions.
Consequently, these actions will never be triggered since events
arrive at element button, not element
action.
