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 XHTML 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, and an index provide easy
navigation, in both the electronic and printed versions.
The specification has been written with two modes of presentation in
mind: electronic and printed. In case of a discrepancy, the electronic version
is considered the authoritative version of the document.
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 behind XForms.
- Chapters 3 and up
-
XForms reference manual. The bulk of the reference manual consists
of the specification of XForms. This reference defines what may go into 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 optional function libraries, references, a change
history, and other useful information.
1.4 Documentation Conventions
The following highlighting and typography is used to present technical
material in this document and other documents from the XForms Working
Group:
Special terms are defined in their own chapter; hyperlinks connect uses
of the term to the definition.
Throughout this document, the namespace prefixes "xform:",
"xsd:", and "xsi:" are used to denote the XForms,
XML Schema, and XML Schema for Instances namespaces
respectively. 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.
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 = integer
size = (small | medium | large) : medium
>
<!-- Content: (allowed-content) -->
</example> |
count = integer - description of this attribute
size = (small | medium | large) : medium - description of
this attribute
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. |
Issue (issue-id):
Issue-Name
A specific issue to which input from readers is requested.
2 Concepts
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 existing Web forms didn't separate the purpose from the presentation
of a form, and additionally offered only a restricted representation for data captured through the form. This is the primary difference between XForms and previous form technologies.
2.2 Current Approach: XHTML
Take for instance a simple eCommerce form authored in XHTML 1.0:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<body>
<form action="http://example.com/submit" method="post">
<span>Select Payment Method: </span>
<input type="radio" name="paytype" value="cash">Cash</input>
<input type="radio" name="paytype" value="credit">Credit</input><br/>
<label>Credit Card Number: <input type="text" name="cc"/></label><br/>
<label>Expiration Date: <input type="text" name="exp"/></label><br/>
<input type="submit"/>
</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 formatting of the resulting data. XForms greatly
improves the expressive capabilities of electronic forms.
2.3 Stepping Up to XForms
XForms are comprised of separate sections that describe what the form does, and how
the form is to be presented. This allows for flexible presentation options, making it possible for classic XHTML
form controls, as well as other form control sets such as WML to be leveraged, as
shown here.
The simplest case involves authoring only the new XForms
form controls, leaving out the other sections of the form. To convert the previous form into
XForms this way, an xform element is needed in the head section of
the document:
<xform:xform>
<xform:submitInfo target="http://example.com/submit" method="..."/>
</xform:xform> |
With these changes to the containing document, the previous example could be rewritten
like this:
<selectOne xmlns="http://www.w3.org/2001/06/xforms" ref="paytype">
<caption>Select Payment Method</caption>
<choices>
<item value="cash">Cash</item>
<item value="credit">Credit</item>
</choices>
</selectOne>
<textbox xmlns="http://www.w3.org/2001/06/xforms" ref="cc">
<caption>Credit Card Number</caption>
</textbox>
<textbox xmlns="http://www.w3.org/2001/06/xforms" ref="exp">
<caption>Expiration Date</caption>
</textbox>
<submit xmlns="http://www.w3.org/2001/06/xforms"/> |
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.
There is no need for an enclosing form element.
Element names for form controls have been changed: textbox is a specific
element, rather than a type attribute on input, as in XHTML.
Data entered through the form controls ends up 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 given to each form control. For instance,
the submitted data might look like this:
<!-- envelope, generated separately -->
<Envelope>
<Body> |
<!-- serialized instance data -->
<paytype>Credit</paytype>
<cc>12354677890123456</cc>
<exp>04-2001</exp> |
<!-- envelope, generated separately -->
</Body>
</Envelope> |
2.4 Providing XML Instance Data
Understandably, authors will often desire greater control over exact construction of the
submitted instance data. One common case might be submitting to a server XML data that is
validated against a predefined DTD or XML Schema.
XForms keeps track of the state of the partially filled form through
instance data, which provides an outline
of the desired XML data, including namespace information. The instance data starts
off with the initial values for the form, is updated as the user fills the form, and
eventually is serialized and submitted. The initial instance data is taken from the
instance element inside the xform element, defined as follows:
<xform:xform>
<xform:submitInfo target="http://example.com/submit" method="..."/>
<xform:instance>
<payment type="credit" xmlns="http://commerce.example.com/payment">
<cc/>
<exp/>
</payment>
</xform:instance>
</xform:xform> |
This design has features worth calling out:
There is complete flexibility in the structure of the XML. Notice that the item
paytype is now expressed as an attribute type of the element
payment.
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
type attribute in the instance data. In the submitted XML, this initial value will
be replaced by the user input, if any.
The instance data provides a unique namespace, which will be used when the XML gets
submitted.
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:
<selectOne ref="payment/@type">
...
<inputText ref="payment/cc">
...
<inputText ref="payment/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 The XForms Model
The earlier XHTML form in 2.2 Current Approach: XHTML. Even in this short form,
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 fields cc and exp are
only relevant if the "Credit" option is chosen in the paytype field.
The credit card information fields cc and exp should be
required when the "Credit" option is chosen in the paytype field.
The field cc should accept digits only, and should have exactly 14,
15, or 16 digits.
The field exp should accept only valid month/date combinations.
By specifying a 3rd component, the XForms Model,
authors can include rich declarative datatype and validation information in forms.
| Editorial note: MJD | |
| The examples here are sketchy out of necessity; this section
will need to be rewritten after the Schema Basic task force delivers its syntax recommendations. |
An XForms Model consists of model items, which
include XML Schema datatype information [XML Schema part 2] as well as properties
specific to XForms.
<!-- add to the cc model item the following: -->
relevant="value('payment/@type') == 'credit'"
required="true"
datatype of "xform:string"
facet pattern of "\d{14,16}"
<!-- add to the exp model item the following: -->
relevant="value('payment/@type') == 'credit'"
required="true"
datatype of "xform:gYearMonth" |
2.6 Multiple Forms per Document
XForms 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
xform elements are needed. The first xform element may skip a unique id
attribute (as have all the examples above), but subsequent xform 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 xform element is associated with the instance data to which they bind. This is
accomplished through an xform attribute alongside the ref attribute. The
default for the xform attribute is to refer to the first xform 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 XHTML:
<xform:xform>
<xform:submitInfo target="http://example.com/submit" method="..."/>
<xform:instance>
...payment instance data...
</xform:instance>
</xform:xform>
<xform:xform id="poll">
<xform:submitInfo target="http://example.com/poll" method="..."/>
</xform:xform> |
Additionally, the following form control markup in the body:
<selectOne ref="pollOption" xform="poll" xmlns="http://www.w3.org/2001/06/xforms">
<caption>How useful is this page to you?</caption>
<choices>
<item value="0">Not at all helpful</item>
<item value="1">Barely helpful</item>
<item value="2">Somewhat helpful</item>
<item value="3">Very helpful</item>
</choices>
</selectOne>
<submit xform="poll" xmlns="http://www.w3.org/2001/06/xforms"/> |
The main difference to note here is the use of xform="poll",
which identifies which form the form control binds to.
2.7 Additional User Interface Capabilities
The visual layout appearance of the initial XHTML forms such as the above example
(2.2 Current Approach: XHTML) leaves much to be desired.
Need extended UI example here |
2.8 Complete Document
This chapter presented various bits and pieces of XForms as a tool to help readers
understand the design. Presented here is the entire XHTML+XForms document presented
in one segment.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:xform="http://www.w3.org/2001/06/xforms"
xml:lang="en">
<head>
<title>XForms in XHTML</title>
<xform:xform>
<xform:submitInfo target="http://example.com/submit" method="..."/>
<xform:instance>
<payment type="credit" xmlns="http://commerce.wizard">
<cc/>
<exp/>
</payment>
</xform:instance>
</xform:xform>
<xform:xform id="poll">
<xform:submitInfo target="http://example.com/poll" method="..."/>
</xform:xform>
</head>
<body>
... include advanced UI markup here ...
</body>
</html> |
6 XPath Expressions in XForms
XPath is used within XForms to address instance data, as well as to perform basic operations, such as declaratively stating when a form control
needs to be filled out, or defining a computation over other values such as unit prices, quantities, discounts, and tax and shipping costs. This chapter describes how XForms uses XPath, and additional XForms functions for use in forms.
6.1 Datatypes
In general, XPath uses a smaller set of datatypes than XML Schema. XForms allows arbitrary Schema datatypes, including those defined in 4 Datatypes, while XPath datatypes are limited to boolean, string, number, and node-set. (For completeness, XPath additionally has external objects and result tree fragments, but there is no special treatment for these types in the XForms specification.)
Note:
Resource-limited XForms Processors may define implementation
limits on the maximum size of a node-set.
The XForms specification is defined such that it is always clear whether XPath or XML Schema datatypes are used within a particular context. Binding expressions and computed expressions always use XPath datatypes, while everything else uses XML Schema datatypes.
Note:
A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes, which will make the above distinction moot.
6.2 Instance Data
Every form has a current state, representing the values entered at any particular point in time. Within XForms, for each xform element, the XForms Processor must behave as if it internally maintains an XML data structure modeled as a tree to represent the state of the form. This data structure is called instance data and conforms to the XPath Data Model [XPath 1.0]. Additionally, each node in the tree contains a boolean "dirty" flag, which is referenced elsewhere by the XForms Processing Model. In this context, "dirty" indicates that the data value might need to be refreshed in the presentation.
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. Instance data elements and attributes may not belong to the XForms namespace.
Issue (issue-instance-data-access):
Should there be specified a DOM form of access (perhaps a document fragment), that maps to the instance data? If so, should it be read-only or read-write access? What are possible security
implications here?
The rules for defining the root and context nodes of the instance data are found in in the following section.
6.3 Evaluation Context
Applied to XForms, XPath references abstract instance data (using the "path" portion of XPath), instead of a discrete XML document. This reference is called a binding expression in this specification.
The following context is used for evaluating all XPath expressions in XForms:
The context node for outermost binding elements (such as XForms UI elements)
is the XPath root (/). A "binding element"
is any element that is explicitly allowed to have an xform:ref
attribute. An XForms element is "outermost" when the node-set returned by the XPath expression
ancestor::* includes no binding element nodes.
Note:
The contents of the instance data below the XPath root node (/) are dependent on how the instance data was constructed, which is defined in 11.4.2 Instance Data Construction.
The context node for non-outermost binding elements
is determined by evaluating 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 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:
<repeat ref="element1/foo/bar">
<selectOne ref="element2" ... />
<selectOne ref="@attr" ... />
</repeat> |
In this example, the repeat has a binding expression
of element1/foo/bar. 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 element1 element. Both of the selectOnes then inherit a context node from
their parent, the context node being /element1/foo/bar. Based on this,
the selectOne binding expressions evaluate respectively to
/element1/foo/bar/element2 and /element1/foo/bar/@attr.
Matching instance data follows:
<element1>
<foo>
<bar attr="xyz">
<element2>xyz</element2>
</bar>
</foo>
</element1> |
6.4 Canonical Binding Expressions
As with XPath, it is possible to construct many different binding
expressions that end up returning the same node-set. That said, it is
often useful to express a binding expression in a standard, compact representation,
defined as a canonical binding expression.
Canonical binding expressions are represented as an AbsoluteLocationPath as
defined in [XPath 1.0]. Additionally, canonical binding expressions use
only default abbreviated axis-specifiers (for elements) or the '@' abbreviation
(for attributes). Examples:
(canonical) /a/b/c
(canonical) /a/b/@c
(non-canonical) a/b/c (not an absolute path)
(non-canonical) child::a/child::b/child::c
(non-canonical) /a/b/c/d/ancestor::c
6.5 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.
Issue (xpath-core-lib):
Further input is required on the ability for resource-constrained
devices to implement the complete XPath Core Function Library.
6.5.1 Number Methods
number average(node-set)
The average function returns the arithmetic
average value, for each node in the argument node-set, of the result of converting
the string-values of each node to a number. The sum is computed with sum(), and divided with div by the value computed with count().
number min(node-set)
The min function returns the minimum value,
for each node in the argument node-set, of the result of converting the string-values of the node
to a number. "Minimum" is determined with the < operator.
number max(node-set)
The max function returns the maximum value,
for each node in the argument node-set, of the result of converting the string-values of the node
to a number. "Maximum" is determined with the < operator.
number count-non-empty(node-set)
The count-non-empty function returns the number of non-empty
nodes in the argument node-set. A node is considered non-empty if it is convertible
into a string with a greater-than zero length.
Note:
The following core functions are defined within [XPath 1.0]
- number(), sum(), floor(), ceiling(), and round()
Note:
The following useful numeric and boolean operators are defined within [XPath 1.0]
- "+", "-", "*", "div", "mod",
unary "-" ,"=", "!=", "<", ">",
"<=", ">=", "or", "and".
6.5.2 String Methods
string now()
The now function returns the current system
time as a string value, in the canonical format defined within the XForms specification.
If local time zone information is available, it is included in the string.
Note:
Note: the following are defined within [XPath 1.0]
- string(), concat(), starts-with(), contains(), substring-before(), substring-after(),
substring(), string-length(), normalize-space(), and translate().
6.5.3 Miscellaneous Methods
boolean submit()
The submit function immediately submits
the instance data bound to the node that contains the expression by triggering an xforms-submit event.
boolean reset()
The reset function immediately resets the
instance data bound to the node that contains the expression by triggering an xforms-reset event.
string xforms-property(string)
The xforms-property function accesses the XForms Property (defined in
11 Processing Model) named by the string parameter, and returns the value of the property.
6.6 Extensibility
Issue (user-extensions):
This section will be expanded in future revisions, to cover extension functions
and methods for calling out to script, perhaps something along the lines of element-available and function-available.
7 Form Controls
7.1 Introduction
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 style properties that can be set
using CSS stylesheets to deliver a customized look
and feel. Form controls defined
here are bound to the underlying instance data
using the binding attributes as defined in the
chapter 9 Binding.
The XForms form controls enable
accessibility by taking a uniform approach to such
features as captions, help text, tabbing and keyboard
shortcuts. Internationalization issues are being
addressed in conjunction with the Internationalization
Working Group and are addressed by following the same
design principles as within the rest of XHTML. All form controls defined here are suitable for implementation as Aural CSS (ACSS) form controls.
Several XForms form controls are of a general class that represent the concept of
selecting from available choices. Such selection
controls can be characterized along a presentational
dimension that is completely orthogonal to the
functional distinction. Distinguishing the
presentational from the
functional dimension allows the
expression of the meaning of a
particular form control--see [AUI97] for a definition
of such high-level user interaction primitives.
This chapter includes non-normative graphical
examples of many form controls.
The CSS Working Group is providing assistance with creating
default CSS rules for producing visual renderings
of standard XForms form controls. This
specification will also include non-normative rules for
how these same controls might be rendered to alternative
access modalities.
Issue (control-names):
All form control names listed here should be considered advisory until further consensus is reached in the Working Group.
For each form control, the following aspects will be defined:
Description
Examples
Data Binding Restrictions
Implementation Hints
XML Representation
The form controls defined here use common attributes and elements that are defined later in this chapter (7.13 Common Markup).
7.2 textbox
Description: This form control enables free-form data entry.
Examples:
<textbox ref="order/shipTo/street" style="width:xx; height:xx">
<caption>Street<caption>
<help>Please enter the number and street name</help>
</textbox> |
In the above, CSS style attributes height
and width
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: The entered value of the form control (after processing as described in 11 Processing Model) is treated as a lexical value. A datatype bound to this form control will be treated as a restriction upon the allowed entered value.
Implementation Hints: Implementations may represent this form control with more than one native user interface control, for example a form control that appears to be three separate smaller entry fields for "day", "month", and "year" for a date datatype. Further, for date datatypes, a calendar system for data entry may be used, including non-Gregorian calendar systems. For numeric datatypes, additional features might include spin buttons or other conveniences. When bound to a datatype that accepts newline characters, this form control should accept multi-line input.
Example: XML Representation: <textbox>
<textbox
(common attributes)
>
<!-- caption, help?, hint?, onevent? -->
</textbox> |
common attributes defined in
7.13.1 Common Attributes
7.3 secret
Description: This form control is used for obtaining 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:
<secret ref="/login/password" style="width:xx; height:xx">
<caption>Please enter your password --it will not be visible as you type.<caption>
</secret> |
In the above, CSS style attributes
height and width 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 this form control
as follows:
Data Binding Restrictions: Identical to textbox.
Implementation Hints: In general, implementations, including accessibility aids, would render a "*" or similar character instead of the actual characters entered, and thus would 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
(common attributes)
>
<!-- caption, help?, hint?, onevent? -->
</secret> |
common attributes defined
in 7.13.1 Common Attributes
7.4 uploadMedia
Description: This form control enables the common feature of 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:
<uploadMedia 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 Hints:
-
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
uploadMedia form control and one of the xform: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 PNG image data, when the mediaType
is "image/*" or "image/png". 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--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 SHOULD support
send image--in-place upload of images from an attached device, when the
mediaType is "image/*" or "image/jpeg". Other mediaTypes besides "image/jpg" MAY
share this input method.
-
Implementations with video recording capability SHOULD provide a "record"
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.
Example: XML Representation: <uploadMedia>
<uploadMedia
(common attributes)
mediaType = list of content types
>
<!-- caption, help?, hint?, onevent? -->
</uploadMedia> |
common attributes defined in 7.13.1 Common Attributes
mediaType = list of media types - list of suggested media types, used by the XForms Processor to determine which input methods apply.
7.5 selectOne
Description: This form control allows the user to make a single selection from multiple choices.
Typically, a stylesheet would be used to determine
the exact appearance of form controls, though a
means is provided to make a concrete selection
through an attribute. The value of the attribute
consists of one of the following values, each of
which may have a platform-specific behavior:
radioGroup
checkboxGroup
pulldown
listbox
comboGroup
Example:
<selectOne ref="icecream/flavor">
<caption>Flavor</caption>
<choices>
<item value="vanilla">Vanilla</item>
<item value="strawberry">Strawberry</item>
<item value="chocolate">Chocolate</item>
</choices>
</selectOne> |
In the above example, selecting one of the choices will result in the associated value
given by attribute value on the selected item being set in the underlying data instance at the location icecream/flavor.
The values given in the user interface shown above may be used in constructing a default schema if no schema is provided by the XForms author.
A graphical browser might render this form control as any of the following:
| listbox | checkboxGroup | radioGroup | pulldown |
|---|
 |  |  |  |
Data Binding Restrictions: This form control will select the lexical value from the value attribute (or in the absence of such an attribute, the text content of the item element) of the single item selected. If the datatype bound to this form control does not permit the selected value (for instance a datatype of xsd:decimal with an attribute value="abc"), the form control with that selection will be perpetually considered invalid and it will not be possible to submit the form. Authors are encouraged to avoid this situation.
If the datatype bound to this form control includes a non-enumerated value space (for instance xsd:string, or xsd:string as part of a union), or if the "comboGroup" UI hint is specified, the form control then should allow free data entry, as described in 7.2 textbox, in addition to the behavior defined here.
Issue (items-specified-elsewhere):
Yet to be decided is allowing display and/or storage values located elsewhere to be retrieved from a binding expression.
Some user interface combinations may allow a state of zero selected items, in which case the lexical value of a zero-length string is selected.
Implementation Hints:
User interfaces may choose to render selectOne
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.
Example: XML Representation: <selectOne>
<selectOne
(common attributes)
selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "comboGroup")
>
<!-- caption, help?, hint?, onevent?, choices* -->
</selectOne> |
common attributes defined
in 7.13.1 Common Attributes
selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "comboGroup") - appearance
override
7.6 selectMany
Description: This form control allows the user to make multiple selections from multiple choices.
Example:
<selectMany ref="icecream/flavors">
<caption>Flavors</caption>
<choices>
<item value="v">Vanilla</item>
<item value="s">Strawberry</item>
<item value="c">Chocolate</item>
</choices>
</selectMany> |
In the above example, more than one flavor can be
selected, populating the instance data with multiple selections.
A graphical browser might render form control
selectMany as any of the following:
| listbox | checkboxGroup | radioGroup | pulldown |
|---|
 |  |  | N/A |
Data Binding Restrictions: When zero or one items are selected, this form control behaves exactly like selectOne with regard to the lexical value that is selected. When multiple items are selected, the lexical value is a space-separated list of the selected values. The datatype bound to this form control must be capable of supporting this format, typically a Schema list type. Cases where each of the multiple selections appear in the instance data attached to a separate element are handled through the repeat construction (8.2 Repeating Structures).
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.
For instance, the following incorrect item declaration:
<item value="United States of America">USA</item> |
when selected, 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
(common attributes)
selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "comboGroup")
>
<!-- caption, help?, hint?, onevent?, choices* -->
</selectMany> |
common attributes defined
in 7.13.1 Common Attributes
selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "comboGroup") - appearance override
7.7 selectBoolean
Description: This form control represents an on/off or true/false or yes/no (or similar) choice.
Example:
<selectBoolean ref="questionnaire/married">
<caption>Are you married?</caption>
<help>We need this to determine your tax allowance</help>
<choices>
<item value="true">Yes</item>
<item value="false">No</item>
</choices>
</selectBoolean> |
Data Binding Restrictions: This form control produces only two possible lexical values: true or false. To be considered valid, the datatype bound to this form control (typically xform:boolean) must be able to accept these two lexical values.
Note:
Scenarios where the desired lexical value is anything other than 'true'/'false' are not suitable for the selectBoolean form control.
For example, if the values placed into the instance data were required to be either "male" or "female", the selectOne form control should be used instead.
Implementation Hints: Visual implementations would typically render this as a checkbox. In some cases, like the above example or in aural environments, it may be helpful to provide labels for the respective choices. This is accomplished through the choices mechanism, similar to the other select... form controls.
Example: XML Representation:
<selectBoolean>
<selectBoolean
(common attributes )
selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "comboGroup")
>
<!-- caption, help?, hint?, onevent?, choices* -->
</selectBoolean> |
common attributes defined
in 7.13.1 Common Attributes
selectUI = (TBD)
7.8 range
Description: This form control allows selection from a continuous range of values.
Example:
<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: Only datatypes which represent a continuous range where
it is possible to express a difference value can be bound to this form control.
(For instance, xform:decimal would be fine, while xform:string
or xform:..Binary would not). In terms of Schema datatypes, the datatype must
be either 1) have a total order relationship, or 2) an overall partial order relationship,
but totally ordered within the range specified between the start and end
attributes.
Issue (enum-range):
Should an enumeration be allowed to bind to this form control?
If yes, how should it be ordered?
Implementation Hints: In graphical environments, this form control would typically be
rendered as a "slider" or "volume 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 like speech,
e.g., when using an accessibility aid.
Thus, an Aural CSS enabled 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
(common attributes)
start = datavalue
end = datavalue
stepSize = datavalue-difference
>
<!-- caption, help?, hint?, onevent? -->
</range> |
common attributes defined in
7.13.1 Common Attributes
start = datavalue -
Lexical starting bound for the range, of the
same datatype bound to the form control
end = datavalue - Lexical ending bound for the range, of the same datatype bound to the form control
stepSize = datatype-difference - Prefered step-size 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
7.9 button
Description: This form control is similar to the XHTML
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:
<button>
Example unavailable at time of publication
</button> |
Data Binding Restrictions:
Note:
Binding a model item has no direct effect on a button, but provides a context for any event handlers that are attached.
Implementation Hints: Graphical implementations would typically render this form control as a push-button.
Example: XML Representation: <button>
<button
(common attributes)
>
<!-- caption, help?, hint?, onevent? -->
</button> |
common attributes defined in
7.13.1 Common Attributes
7.10 output
Description: This form control renders a value from the instance data, but provides no means for entering or changing data.
This form control may be used in a caption,
for instance, when authors want to say: "I charged you value - and here is
why.
Example:
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: The lexical value of the datatype bound to this form control is displayed, after processing as described in 11 Processing Model.
Implementation Hints: An audio browser might apply properties to this form control to
aurally highlight
the displayed value to provide audio formatted output.
Example: XML Representation: <output>
<output
id = xsd:ID
ref = binding-expression
xform = instance data selector
format = formatting-expression
>
<!-- empty content -->
</output> |
id = xsd:ID - Optional unique identifier used for linking.
ref = binding-expression - Binding expression
xform = xsd:IDREF - Optional instance data selector. Details in the chapter 9 Binding.
format = formatting-expression - Optional format specifier
| Editorial note | |
We need to decide on how we define attribute
format on form control
output.
The functionality needed is similar to what
functions like printf typically
take. |
7.11 submit
Description: This form control submits all or part of the instance data to which it is bound.
Example:
<submit xform="timecard">
<caption>Submit</caption>
</submit> |
Implementation Hints: The default handling for this controls is equivalent to the submit() method.
Example: XML
Representation: <submit>
<submit
(common attributes)
>
<!-- caption, help?, hint?, onevent? -->
</submit> |
common attributes defined in 7.13.1 Common Attributes
7.12 reset
Description: This form control resets to the initial values all or part of the instance data to which it is bound.
Example:
<reset ref="/tcard/data" xform="timecard">
<caption>Reset totals</caption>
</reset> |
Implementation Hints: The default handling for this controls is equivalent to the reset() method.
Example: XML Representation:
<reset>
<reset
(common attributes)
>
<!-- caption, help?, hint?, onevent? -->
</reset> |
common attributes defined in
7.13.1 Common Attributes
7.13 Common Markup
The preceding form control definitions make reference to several child elements and attributes that are common to several of the XForms form controls. This section defines these common markup components.
7.13.1 Common Attributes
Issue (XHTML-attrs):
XHTML defines two attributes on element
html:form--accept
and accept-charset. Additionally, attribute
accept-charset also appears on element
html:input.
We need to bring the equivalent to these into the XForms specification.
Example: XML Representation: Common Attributes
xmlns = xsd:anyURI
xml:lang = xsd:language
id = xsd:ID
class = space separated list of classes
style = associated style info
ref = binding-expression
xform = xsd:IDREF
navIndex = xsd:nonNegativeInteger : 0
accessKey = xsd:token |
xmlns = xsd:anyURI - Optional standard XML attribute for identifying an XML namespace.
xml:lang = xsd:language - Optional standard XML attribute to specify a human language for this element.
id = xsd:ID - Optional unique identifier used for linking.
class = space separated list of classes - Optional selector for a style rule.
style = associated style info - Optional inline style specification.
ref = binding-expression - Binding expression. Details in the chapter 9 Binding.
xform = xsd:IDREF - Optional instance data selector. Details in the chapter 9 Binding.
navIndex = xsd:nonNegativeInteger : 0 - 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 = xsd:string - 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 form controls are being defined in
conjunction with the CSS Working Group. This version
of the XForms working draft defines the XForms form controls independent of visual
presentation. Additionally, sample default
visual presentations are shown for each form control
defined in this Working Draft. 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.
7.13.2 Common Child Elements
Child elements caption, help and
hint detailed below provide the ability to attach human-readable
metadata to XForms 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 element caption (or hint or help).
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.
7.13.2.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)
>
<!-- mixed content -->
</caption> |
common attributes defined in
7.13.1 Common Attributes
An accessibility aid would typically speak the metadata
encapsulated in element caption when the
containing form control gets focus.
7.13.2.2 help
The optional element help provides a longer
description that will help users understand how
to fill out this form control.
The help text will be shown only
on request.
Example: XML Representation: <help>
<help
(common attributes)
>
<!-- mixed content -->
</help> |
common attributes defined
in 7.13.1 Common Attributes
A graphical browser might render help as follows:
An accessibility aid might speak this
information upon request.
7.13.2.3 hint
The optional element hint provides a short
hint for the user, typically represented as a
tooltip by graphical user agents. The tooltip
text will normally be shown when the user remains
on the form control for more than a certain length
of time. Accessibility aids might render such
tooltips using speech. This element is optional,
and its content model is mixed.
Example: XML Representation:
<hint>
<hint
(common attributes)
>
<!-- mixed content -->
</hint> |
common attributes defined in 7.13.1 Common Attributes
A graphical browser might render hints as follows:
7.13.2.4 onevent
This element can be used to bind event handlers to
form controls. It is defined in [XHTML Events]. Details on XForms events
can be found in the chapter
11 Processing Model.
Example: XML Representation: <onevent>
<onevent
(attributes defined in XHTML Events)
>
<!-- Action handlers -->
</onevent> |
Element onevent is defined in the XHTML Events
module.
It declares an event listener
by specifying the event to handle and the event handler to
invoke.
7.13.2.5 item
This element is used within list form controls to represent a single item of the list.
Issue (onevent-for-item):
Should onevent handlers be allowed here for individual items in a list?
Example: XML Representation: <item>
<item
value = lexical-representation
>
<!-- #PCDATA -->
</item> |
value = lexical-representation - the "storage value" for the item, to be placed in the instance data when this item is chosen.
7.13.2.6 choices
This element is used within list form controls to group items. This provides the same functionality as element optgroup in HTML 4.0.
Example: XML Representation: <choices>
<choices>
<!-- (item | choices)+ -->
</choices> |