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> |
9 Binding
9.1 Introduction
Binding is the glue that connects the
separate pieces of XForms--the XForms Model,
instance data, and form controls.
The binding is independent of the user interface language used.
Binding is specified through the use of
binding expressions. The syntax
and details of binding expressions are defined in the chapter 6 XPath Expressions in XForms.
This chapter describes the wider topic of how binding expressions are used within XForms.
A future revision of this chapter will address binding
across XForms Models, for instance declaring an "address" in one XForms Model
and referencing it from another.
9.2 Binding Attributes
XForms defines an attribute ref that can be placed on any form
control. Note that when placed on form
controls outside of XForms, it must be appropriately namespace-qualified. The value
of the attribute is a binding expression,
based on 6 XPath Expressions in XForms, that links the form control
to a particular location in the instance data (and therefore a particular model
item). For example:
Example: XForms User Interface Markup with Binding Attributes
<xform:textbox ref="binding-expression">
<xform:caption>Your first name</xform:caption>
</xform:textbox> |
The ref attribute links the form
control to the instance data and XForms Model declared elsewhere
in the containing document.
This can also be used on non-XForms form controls, for instance XHTML:
Example: XHTML with Binding Attributes
<html:input type="text" name="..." xform:ref="binding-expression"/> |
Here the ref attribute links an XHTML form
control to the instance data and XForms Model contained elsewhere
in the containing document. Note that the html: prefix is
used here to represent the XHTML namespace.
Details on the operation of binding expressions are given throughout the rest of this chapter.
9.3 Direct Binding
When a containing document has only a single XForms
Model and only a single set of instance data, binding is simpler because there
is no possibility of ambiguity as to which XForms
Model and instance data will participate. The following syntax can be used for the
binding expression:
A binding expression that evaluates to a node-set in the instance
data. If the node-set contains more than one node, only the first node is used. If the
node-set contains zero nodes, the binding expression is invalid.
For example:
Example: Binding Expression
<xform:textbox ref="orderForm/shipTo/firstName">
... |
Here the ref attribute specifies a path through the instance data to the desired location.
<orderForm>
<shipTo>
<firstName>value</firstName>
</shipTo>
</orderForm> |
Here is the matching instance data for the above example.
A special case applies when binding to
an element in the instance data that
contains an attribute of type xsd:ID. In this case, an XPath function
id(), can be used:
Example: Binding Expression with XPath id() Syntax
<xform:textbox ref="id('myfirstname')">
... |
Here the ref attribute specifies a link to an instance
data element with an id of myfirstname.
<a>
<b id="myfirstname">value</b>
</a> |
Here is the instance data for the above example.
For this syntax to be valid, the following conditions must be true:
The instance data must be included
in the same document as the XForms User Interface
Every referenced element in the instance
data must be marked with a valid ID (i.e. the ID is unique throughout
the whole document)
Note also that:
this method is limited, because it requires exactly one instance, decorated
with ID attributes.
It is still legal to have elements without ID attributes in the instance data.
Only elements can be addressed
9.4 Indirect Binding
In situations where a form is designed by collaboration (such as between a
graphic designer and a database/XML specialist) it is desirable to locate all
binding expressions in a single area in the containing document. XForms allows
the binding expression to appear
in a separate element bind, a child of the xform element.
The attributes of bind are id of type xsd:ID
and ref which takes a binding expression. When a binding expression
is defined this way, the form control
can reference the id of the bind element,
as seen here:
Example: Binding Expression Using Indirection
<xform:textbox ref="id('myfirstname')">
... |
Here the ref attribute specifies a link to a binding
expression defined elsewhere.
<xform:bind id="myfirstname" ref="orderForm/shipTo/firstName"/>
<xform:instance>
<orderForm>
<shipTo>
<firstName>value</firstName>
</shipTo>
</orderForm>
</xform:instance> |
Here is the instance data for the above example.
This accomplishes the following:
9.5 Multiple Forms per Page
One design goal of XForms is to support multiple forms per page. This is accomplished
by having multiple xform elements within a containing document.
Each xform element might have a separate XForms Model or
instance data defined. This makes binding slightly more complex, because
the correct xform element needs to be referenced.
By default, binding expressions are based on the instance data
associated with the first xform element in document
order. To refer to the contents of subsequent xform elements,
these must be decorated with id attributes of type xsd:ID.
Attached to the form control element, an additional attribute xform
serves to set the context node for the attached binding expression to the
instance data or XForms Model associated with
the xform element with the matching id.
For example:
Example: Binding Expression Specifying Non-default xform Element
<xform:textbox xform="b" ref="/orderForm/shipTo/firstName">
... |
Here the xform and ref attributes specify
a binding to the instance data and XForms Model.
<xform:xform id="b">
<xform:model>
...
</xform:model>
<xform:instance>
<orderForm xmlns="...">
<shipTo>
<firstName>value</firstName>
</shipTo>
</orderForm>
</xform:instance>
</xform:xform> |
Scoped resolution of binding expressions, as defined in the chapter
6 XPath Expressions in XForms can in some cases be used to avoid repetitive
uses of the xform attribute.
10 Document Structure
XForms are an application of XML [XML 1.0], and have been designed for
use within other XML vocabularies, in particular XHTML [XHTML 1.0].
This chapter discusses some of the high-level features of XForms that
allow this specification to be used with other document types.
10.1 The XForms Namespace
The XForms namespace has the URI: http://www.w3.org/2001/06/xforms.
Future revisions are expected to use a different identifier. This document uses
the convention of an xform: prefix to represent elements and attributes
that are part of the XForms Namespace.
XForms Processors must use the XML namespaces mechanism [XML Names]
to recognize elements and attributes from this namespace. Except where specifically allowed
by the Schema for XForms, foreign-namespaced elements are not allowed as content of elements
in the XForms namespace. Foreign-namespaced attributes are, however, allowed on any XForms
element. The XForms Processor must ignore any foreign-namespaced elements or attributes
that are unrecognized.
10.2 XForms Elements
10.2.1 xform
The xform element is used as a container for other XForms
elements, and can serve as the root element of a standalone document or be embedded
in other document types such as XHTML. A single containing document
may contain any number of xform elements.
| Editorial note | |
under discussion are XLink attributes on the xform element. These are: xlink:type="extended" and xlink:role="http://www.w3.org/2001/06/xforms" - and they should be defaulted or even fixed in the Schema/DTD. |
Example: XML Representation: <xform>
<xform
xmlns = namespace-identifier
id = xsd:ID
>
<!-- Content: (submitInfo | bind)*, model, instance -->
</xform> |
xmlns = namespace-identifier - Optional standard XML attribute
for identifying an XML namespace. It is often useful to include this standard
attribute at this point.
id = xsd:ID - Optional unique identifier used to refer to this
particular xform element.
For example:
<xform xmlns="http://www.w3.org/2001/06/xforms" id="Person">
<model xlink:href="Schema-Questionnaire.xform" />
<instance xlink:href="URL-to-retrieve-defaults" />
...
</xform> |
10.2.2 model
The model element is used to define the XForms Model. The content of the
XForms Model may be defined inline or obtained from a external URI.
Example: XML Representation: <model>
<model
id = xsd:ID
xlink:href = xsd:anyURI
>
<!-- Content: ( schema subset syntax ) -->
</model> |
id = xsd:ID - Optional unique identifier.
xlink:href = xsd:anyURI - Optional link to an externally
defined XForms Model.
| Editorial note | |
As above, we need to find a place to discuss the defaulted attributes. Here they are xlink:role="http://www.w3.org/2001/06/xforms-model" xlink:type="locator" |
10.2.3 instance
The instance element is used to define initial instance data.
The instance data may be defined inline or obtained from a external URI.
Example: XML Representation: <instance>
<instance
id = xsd:ID
xlink:href = xsd:anyURI
>
<!-- Content: (##other) -->
</instance> |
id = xsd:ID - Optional unique identifier.
xlink:href = xsd:anyURI - Optional link to externally
defined instance data
The content of the instance element is arbitrary XML in
any namespace other than the XForms namespace. Authors must ensure that proper
namespace declarations are used for content within the instance
element.
| Editorial note | |
As above, we need to find a place to discuss the defaulted attributes. Here they are xlink:role="http://www.w3.org/2001/06/xforms-instance" xlink:type="locator" |
Issue (issue-schemalocation):
Should a schemaLocation attribute,
linking the instance data with a schema definition, be present here?
10.2.4 submitInfo
The submitInfo element provides information on how and
where to submit the instance data.
Example: XML Representation: <submitInfo>
<submitInfo
id = xsd:ID
xlink:href = xsd:anyURI
method = xsd:string
>
<!-- Content: (##empty) -->
</submitInfo> |
id = xsd:ID - Optional unique identifier.
xlink:href = xsd:anyURI - Required destination for submitted
instance data.
method = xsd:string - Optional indicator to provide details on
the submit protocol. With HTTP, the default is "POST".
Issue (submit-method-values):
The possible values for method, and their respective meanings, still need to be defined.
10.2.5 bind
The bind element represents a connection between the different
parts of XForms.
Example: XML Representation: <bind>
<bind
id = xsd:ID
ref = XForms binding expression
>
<!-- Content: (##empty) -->
</bind> |
id = xsd:ID - Required unique identifier.
ref = XForms binding expression - A link to an externally
defined XForms Model.
Additional details are found in the chapter 9 Binding.
10.3 Integration with XLink
XForms make good use of XLink [XLink] features. To that end, the XLink namespace is integrated in the DTD/Schema, the majority of the attributes have sensible defaults, including those based on XLink roles defined below.
This document uses the convention of an xlink: prefix for the XLink namespace (informationally: as of this writing, the XLink namespace identifier is http://www.w3.org/1999/xlink - this may change when XLink reaches W3C Recommendation state. Please verify at [XLink])
Note that the XLink support uses a well-defined XLink failure mode: If an XLink attribute is not provided, the element looses its XLink specific meaning. We use this feature in order to allow application developers to either provide the model and instance via an external reference (via an xlink:href attribute) or to provide the data inline without the attribute. In the latter case, the XLink-specific meaning of the element is lost and the inline content used. If both inline content and external reference is provided, a processor must use the external reference and ignore the inline content.
For the purposes of XForms, we suggest that XLink aware processors switch from the xlink:type="locator" mode to the xlink:type="resource" mode. This should be specified in the document by setting xlink:type="resource", though a processing agent may not depend on it. In other words, the first two of the following examples must be treated identically:
Example: Inline XForms Model, without explicit change to the xlink:type
<model>
<!-- Content: ( schema subset syntax ) -->
</model> |
Example: Inline XForms Model, with explicit change to the xlink:type
<model xlink:type="resource">
<!-- Content: ( schema subset syntax ) -->
</model> |
Example: External XForms Model
<model xlink:href="URI" /> |
XLink as originally specified allows users to provide arc-type elements to specify traversal rules. The integration of arc-type elements in XForms would require additional elements in the xform element that are otherwise not necessary for XForms. Hence, for children of the xform element, the traversal rule is to traverse xlink:from the current document xlink:to the document pointed to by the external resource. The processor should behave as if xlink:actuate="onLoad" was specified. The xlink:show attribute is meaningless in this context, anyway.
An XForms processor is not required to implement full XLink--correct behavior of the xlink:href attribute (as defined above) is sufficient. It is permissible to construct the additional information from the semantics of the elements. An XForms Processor can not be XForms compliant, however, if it attempts to implement XLink and the implementation does not conform to XLink specification with respect to the attributes used by XForms.
The following definition of the XLink roles defines the relationship between the various resources participating in a XForms-based form, not properties that are inherent to the resources. It is perfectly permissible for the same resource to participate in various XForms-based forms in different roles.
10.3.1 XLink role for XForms
The xlink-role for XForms Models is http://www.w3.org/2001/06/xforms. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/06/xforms" must assume that the arcs associated with the other XLink roles for XForms (see below) behave as above. In other words, this XLink role is an additional hint beyond the element names for an XLink processor to identify the arcs. For all roles, if element names and XLink behavior conflict, XLink role behavior prevails.
10.3.2 XLink role for the XForms Model
The xlink-role for XForms Models is http://www.w3.org/2001/06/xforms-model. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/06/xforms-model" must assume that the referenced resource relates to the other resources as XForms Model as defined in 5 The XForms Model.
10.3.3 XLink role for the Instance Data
The xlink-role for XForms Instances is http://www.w3.org/2001/06/xforms-instance. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/06/xforms-instance" must assume that the referenced resource is the initialization data of a form.
10.3.4 XLink role for the XForms User Interface
The xlink-role for XForms User Interfaces is http://www.w3.org/2001/06/xforms-ui. This means that XLink processors encountering a link with a xlink:role="http://www.w3.org/2001/06/xforms-ui" must assume that the referenced resource is the user interface of a form. Note that this role does not make an assertion about the content type of the referenced resource other than that it is an XML format. For example, it can be XHTML+XForms, pure XForms, SVG+XForms or pure SVG any other combination. This role does not correspond to any element defined in XForms; it is defined so that XLink linkbases [XLink] can be established containing all the information about a XForms document.
11 Processing Model
11.1 Introduction
The XForms Reference Processing Model is a normative explanation of the components,
predictive behavior, and mechanisms of XForms Processors. It is not intended to
constrain implementations. XForms Processors may be implemented in any manner, so
long as the end results are identical to that described in this chapter.
This chapter uses the terms may, must, and
should (when rendered as in this paragraph) in
accord with RFC 2119.
Issue (issue-processing):
This chapter is still at an early phase and may contain errors or omissions.
Feedback on this chapter is especially appreciated.
11.1.1 Design Rationale
The Reference Processing Model set out in this chapter will:
Be simple enough to implement across a wide range of devices, including
resource-constrained handhelds and appliances.
Define a predictive processing model with enough detail for implementors
to create interoperable software.
Define a well-ordered system for calculations and dependencies independent
of processor speed or threading.
Provide a unified addressing scheme for binding expressions, independent
of how the structure of the instance data is defined.
Be simple enough for the existing base of HTML authors to quickly get up
to speed.
Be compatible (to the extent reasonably possible) with existing form processing.
11.2 XForms Properties
For each xform element, the XForms Processor maintains
a set of read-write properties, as described here. These properties are available to all
expressions in the containing document.
immediate-refresh
immediate-revalidate
immediate-recalculate
use-nil
immediate-refresh controls whether changes in the
instance data are immediately updated in the UI
immediate-revalidate controls whether changes in
the instance data immediately trigger a validation
immedate-recalculate controls whether changes in
the instance data immediately trigger a recalculation
use-nil controls whether XML Schema Instance nils
are placed in the instance data
Additionally, the following properties are available for reading (but not modification). These properties are available to all expressions in the containing document.
version
conformance-level
timezone
version is defined as the string "1.0" for
XForms 1.0
conformance-level strings are defined later in this chapter
timezone strings are signed integers representing the
number of minutes offset from GMT
11.3 Events
XForms uses an events system as defined in [DOM2 Events],
with a Capture phase, arrival at the Event Target, and then a Bubbling Phase.
Events fall into different groupings. One class of events indicates that some
processing is about to happen. That processing may be halted by the event handler:
Another class of events indicates that some processing has already happened
or is in progress. Such processing can not be halted by the event hander:
xforms-construct
xforms-destruct
xforms-initialize
xforms-exception
Finally, certain events are used by the author or the XForms Processor to cause
processing to happen:
xforms-recalculate
xforms-refresh
Unless otherwise noted, the target node for all events is the xform
element. When a containing document has multiple xform
elements, the binding is used to determine which xform
element is used.
The Working Group is using pre-defined generic event handling, defined in [XHTML Events], additionally defining a set of XForms-specific actions.
11.4 XForms Processing
11.4.1 Initialization/Resume
The following describes the initialization process for XForms. Initialization
must occur before any other processing. For each xform
element in the containing document, in document order, the following processing
occurs:
An xforms-construct event is fired; this is the place for
authors to handle any initialization tasks.
Instance data is constructed (11.4.2 Instance Data Construction).
An xforms-initialize event is fired. A handler for this event could perform form initialization tasks such as a database lookup.
A recalculation (11.4.5 Recalculation Algorithm) takes place.
A UI refresh (11.4.6 UI Refresh Algorithm) takes place.
11.4.2 Instance Data Construction
The following steps describe how the instance data associated with each xform element is constructed. Of the following options, the first applicable option is chosen. Only one of the following applies:
If an instance element is present and contains non-whitespace child nodes, the contents of the instance element are copied into the instance data tree, based on the infoset mappings defined in the XPath [XPath 1.0]data model.
If an instance element is present and contains a reference to non-local
initial instance data, it is retrieved by traversing the link to it, then copied into the instance data as described above. A remote instance that
is unretrievable for any reason is ignored, in which case an
XForms Processor may issue a warning.
If an instance element is not present, then a default instance data configuration is produced, according to the following rules:
Each form control bound to the
xform element currently being processed is visited
in document order. Each form control's binding expression is
evaluated.
If the instance data item
result of evaluating the binding expression doesn't already exist, it is
created, and if the use-nil
property is true, populated with a nil value (an xsi:nil="true" attribute). Note that only
elements can hold nil values. The form control receives a default
blank value. The algorithm for creating instance data items is
as follows: For each location step in the canonical binding expression,
from left to right, where no matching node exists in the
instance data, a new node is inserted.
Issue (creating-instance-nodes):
The algorithm for creating instance nodes is under discussion, with one possibility being ignoring the path information, using only the local name, in a flat list.
If none of the above options are fulfilled, this is an error condition, and the XForms Processor must stop processing with an error message.
11.4.3 Navigation Sequence Algorithm
Navigation is determined on a containing document-wide basis. The navigation sequence
is determined as follows:
Those form controls that support navindex and assign a positive
value to it are navigated first. Navigation proceeds from the form control
with the lowest navindex value to the form control with the highest
value. Values need not be sequential nor must they begin with any particular
value. form controls that have identical
navindex values should be navigated in document order.
Those form controls that do not supply navindex or supply
a value of "0" are navigated next. These form controls are navigated in document
order.
Those form controls that are disabled, hidden, or on a non relevant
subtree are assigned a relative order in the overall sequence but do not participate
as navigable controls.
The navigation sequence past the the last form control (or before the first)
is undefined. XForms Processors may cycle back to the first/last control,
remove focus from the form, or other possibilities.
11.4.4 Interactivity
XForms provides similar processing to the HTML onChange event.
As users indicate completion of a form control by navigating away the following
occurs:
If the display value has changed since the user last navigated to the form
control, an xforms-value-changing event is fired. If the
display value hasn't changed, processing for this event ends.
Any listener may prevent default processing (one option under consideration
provides a <stopevent/> action), which will end event
processing immediately after the Capture and Bubbling phases. Alternatively,
a listener may perform a custom translation from display value to canonical
value. Any listener may have side-effects that modify any instance data item,
in which case the modified instance data items must be marked "dirty".
Default processing is to convert the display value of the form control
to the canonical value as specified in the Datatypes chapter. Default processing
should automatically take into account regional settings (if any), such
as decimal character symbol, date formats, etc.
If the immediate-revalidate property is true, all validations
(11.4.7 Revalidation Algorithm) bound to the form control are run. Note that validation is performed against
the canonical value, not the display value.
If any validation fails, the user must be notified, and
may not be allowed to navigate away from the control. The
invalid entry in the form control should be preserved.
The associated instance data item is left unchanged, thereby ending processing
for this event.
The instance data item is updated with the new value, and marked "dirty".
If the immediate-recalculate property is true, a recalculate
(11.4.5 Recalculation Algorithm) occurs to perform any defined calculations.
If the immediate-refresh property is true, a refresh (11.4.6 UI Refresh Algorithm)
occurs to update any form controls that might be dependent on this newly changed
value.
Certain form controls allow interactive response without finalizing on a value.
Examples of this include edit boxes (users can type various characters before
"tabbing out") and slider controls (users can be continuously adjusting
the value before releasing at a certain value). Interactive temporary values
such as this are expressly allowed to be "invalid", that is outside
the permissible value space. This is because incomplete data may be present
while the user is entering transitional values.
Example: A partially entered currency value of "U" is not valid because
it doesn't (yet) have 3 characters. This is permitted temporarily, as long as
the user remains on the form control. XForms Processors with sufficient processing
resources would typically update/refresh on every character. Resource-constrained
XForms Processors would typically only update/refresh on the final value.
Any time the display value of a form control changes (such as through character
or cut/paste activities), even without indication that this is a final value,
an xforms-interactive-value-changing event is fired. Resource-constrained
XForms Processor implementations may choose to ignore all
such events.
Event listeners may prevent default processing.
Otherwise, default handling is as follows: The current form control is
revalidated (11.4.7 Revalidation Algorithm). This is for internal purposes only,
and happens regardless of the immediate-revalidate setting.
If all validations on the form control are successful, the instance data item
is updated, and marked "dirty". If any validations fail (indicating
a transitional value) all form controls bound to the same instance data item
may be directly updated with the display value. Otherwise,
the following occurs:
If the immediate-recalculate property is true, a recalculation
(11.4.5 Recalculation Algorithm) occurs to perform any defined calculations.
If the immediate-refresh property is true, a refresh (11.4.6 UI Refresh Algorithm)
occurs to update any form controls that might be dependent on this newly
changed value.
Implementations that choose to respond xforms-interactive-value-changing
are expected optimize processing (for instance not flashing the entire screen
for each character entered, etc.).
11.4.5 Recalculation Algorithm
XForms Processors are free (and encouraged) to skip or change any steps in
this algorithm, as long as the end result is the same. Each form control may
have a model item property priority value, which is the main factor
in determining calculation order.
Following is the default handling for an xforms-recalculate event:
Each model item with a bound calculate model item property
is visited in calculation order, which is defined as follows:
Those model items that are bound to a priority and assign
a positive integer to it are computed first. Computation proceeds from the
model item with the lowest bound priority to the model item
with the highest bound priority. Values need not be sequential
nor must they begin with any particular value. Model items with the same bound
priority value are computed in document order.
Those model items not bound to a priority or bound to one with the value
"0" are computed next. These model items are computed in document
order.
For each model item, the expression in the calculate model item
property is evaluated. Any instance data item changes as a result of
this are marked with a "dirty" flag.
The instance data item bound to the model item is updated with the result
of the calculate expression, and the "dirty" flag is set.
11.4.6 UI Refresh Algorithm
Following is the default handling for an xforms-refresh event:
For purposes of UI refresh, the instance data as it exists at the
beginning of processing the xforms-refresh event is used.
Each form control is visited in refresh order, which is defined as follows:
Those form controls that have a given or computed navigation sequence
value are visited first, in the navigation sequence.
Those form controls outside the navigation sequence are visited next.
These form controls are visited in document order.
For each form control, the relevant constraint is evaluated,
which might result in the form control being disabled/hidden/etc. as specified
in the chapter 5 The XForms Model.
For each form control, the binding expression is evaluated. If the
instance data indicates that the instance data item is not "dirty", processing for
that particular form control completes.
Otherwise, if the instance data item is "dirty", an xforms-instance-changed
event is fired.
Listeners to the xforms-instance-changed event are free to
compute a new display value.
Listeners to the xforms-instance-changed event are prohibited
from directly updating any form controls present.
Listeners to the xforms-instance-changed event are prohibited
from altering any portion of the instance data. To attempt to do so
results in an xforms-exception being fired.
Listeners may prevent the default processing of the xforms-instance-changed
event.
Default processing is to convert the canonical value into a display value,
taking into account regional settings (if any) such as decimal separator
character, etc.
The form control is updated with the display value.
After all form controls have been updated, all "dirty" flags in
the instance data are cleared.
Note:
Editor's Note: Still to be addressed is the processing when a datatype facet
or model item property are changed--what gets marked "dirty"?; what
gets recalculated?; what gets revalidated?; what gets refreshed?
11.4.7 Revalidation Algorithm
Revalildation always occurs within the scope of a context form control.
Following is the revalidation process:
The bound instance data item is checked against any bound XForms Datatype
constraining facets. If any fail, the context form control is considered invalid.
The bound instance data item is checked against any bound Schema Datatype
constraining facets. If any fail, the context form control is considered invalid.
If a validate model item property is bound to the context
form control, the expression within is evaluated. If it evaluates to false,
the context form control is considered invalid.
If the context form control is invalid, the XForms Processor must
notify the user. The XForms Processor may combine messages
before presentation to the user.
11.5 Submit and Reset
The form filling experience ends with submitting the form,
or starting over. The XForms processing for these events are covered here. The following sections describe how to instance data is prepared for submission.
11.5.1 Submit
In response to an xforms-submit event, the following takes place:
Event listeners may prevent default processing of the submit request. Otherwise,
default handling as described below occurs.
Every form control is revalidated (11.4.7 Revalidation Algorithm). Any invalid
values must be reported to the user and submit processing
must not continue.
A subset or all of the instance data is selected based on
the binding expression used to invoke the submit request. The selected nodes and all children are selected for serialization as submitted data.
If no ref attribute is specified, all nodes in the instance data are selected by default.
If the instance data selection results in an empty node-set, the submit
must be aborted and submit processing must
not continue.
Instance data is serialized according to one of the processes defined below.
Instance data is delivered over the network as an HTTP POST.
Upon successful delivery of the submit data, an xforms-destruct event is fired and form processing shuts down.
The response page sent by the server replaces the current containing document.
Issue (method-strings):
We have yet to define the method strings (e.g. method="post" in XHTML)
11.5.2 Reset
In response to an xforms-reset event, the following takes place:
Event listeners may prevent default processing of the reset request. Otherwise,
default handling as described below occurs.
A subset or all of the instance data is selected based on the
binding expression used to invoke the suspend request.
The selected nodes and all children are selected for resetting.
If no ref attribute is specified, all nodes in the instance data are selected by default.
If the instance data selection results in an empty node-set, the reset
has no effect.
New instance data for the selected instance data is prepared, based on the instance element associated with the current xform element, according to
the rules for initialization above.
The selected instance data is replaced with the new instance data.
11.6 Serialization Formats for Instance Data
11.6.1 application/x-www-form-urlencoded
This format is intended to facilitate the integration of XForms into HTML forms
processing environments, and represents an extension of the [XHTML 1.0]
form content type of the same name with extensions to expresses the hierarchical
nature of instance data.
This format is not suitable for the persistence of binary content. Therefore,
it is recommended that XForms capable of containing binary content use either
the multipart/form-data (11.6.2 multipart/form-data) or text/xml (11.6.3 text/xml) formats.
Issue (issue-urlencoding-mods):
Modifications to urlencoding process
The urlencoding technique given here does not exactly match how legacy
implementations produce urlencoded data. (In particular, we are adding contextual
information with slashes and multiple location-steps) Will this approach interfere
with legacy implementations?
Issue (issue-utf8-encoding):
Under discussion
is the intent to have the data be UTF8 encoded; however, this is dependent upon
IETF developments. Would UTF8 meet the needs of the forms community?
The steps for building this persistence format is as follows:
Prepare a new UTF-8 encoded string buffer to hold the persisted instance
data.
Beginning with the root element of the instance data, iterate
over the selected content of the instance data in document order and build an ordered set of
strings by performing the following steps:
For each element with an attribute, append to the set a string of the
format "path=value" where
path is the canonical binding expression that refers to each
attribute, and value is the character content of each attribute
(urlencoded if necessary).
For each element enclosing character content, append to the set a string
of the format "path=value" where path is
the canonical binding expression that refers to the element, and
value is the character content of the element (urlencoded if
necessary).
For each element enclosing element content, continue the iteration.
Append the strings from the ordered set together, delimiting the strings
with an ampersand '&' character, and place the result of the append into
the UTF-8 encoded string buffer.
Example:
Example: application/x-www-form-urlencoded
/PersonName/@title=Mr&/PersonName/FirstName=Roland |
This format consists of sets of a canonical binding expression paired with a value.
<PersonName title="Mr">
<FirstName>Roland</FirstName>
</PersonName> |
Here is the instance data for the above example.
11.6.2 multipart/form-data
This format is intended to facilitate the integration of XForms into HTML forms
processing environments, and represents an extension of the [XHTML 1.0]
form content type of the same name that expresses the hierarchical
nature of instance data. Unlike the application/x-www-form-urlencoded (11.6.1 application/x-www-form-urlencoded)
format, this format is suitable for the persistence of binary content.
This format follows the rules of all multipart MIME data streams for form data as outlined
in [RFC 2388], with the "name" of each part being the canonical binding expression that references the selected instance data item.
Example:
Example: multipart/form-data
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="/PersonName/@title"
Mr
--AaB03x
Content-Disposition: form-data; name="/PersonName/FirstName"
Roland
--AaB03x
...Possibly more data...
--AaB03x- |
This format consists of sets of a canonical binding expression paired
with a value.
<PersonName title="Mr">
<FirstName>Roland</FirstName>
</PersonName> |
Here is the instance data for the above example.
11.6.3 text/xml
This format permits the expression of the instance data as an XML-based format
that is straightforward to process with off-the-shelf XML processing tools.
In addition, this format is suitable for the persistence of binary content.
The steps for building this persistence format is as follows:
Prepare a new empty XML document to hold the persisted instance data.
If the selected content of the instance data corresponds to a singly-rooted data
structure, serialize, into the XML document the entire content of the selected instance
data, beginning at the root node.
If the selected content of the instance data corresponds to a multiply-rooted data
structure (such as a general parsed entity), an unqualified root element of <Envelope>,
with an unqualified element <Body> is inserted into the XML document, and the
selected instance data serialized into the content of the <Body> element.
11.6.3.1 Binary Content
Instance data items of the types xsd:base64Binary and xsd:hexBinary are specifically
allowed, and are included in the serialized data according to the rules defined in
[XML Schema part 2]
Issue (issue-instance-metadata):
Where a value
within the instance data represents binary content, can we store meta-information
with an xform:mediaType attribute reflecting the appropriate content
type (e.g., "image/jpg")?
11.7 Conformance
XForms are being designed for use on hardware platforms of all sizes, from tiny handheld devices to high-powered servers. Clearly, a one-size-fits-all approach has its drawbacks. For this reason, the XForms Working Group has begun specifying two conformance levels for XForms Processors, documents, and authoring tools.
11.7.1 XForms Basic
This conformance level will be suitable for devices with limited computing power, such as mobile phones, handheld computers, and appliances. This conformance level will depend on a subset of XML Schema, and will not include any resource-intensive features. Implementations of XForms Basic should return "basic" for the conformance-level property.
11.7.2 XForms Full
This conformance level will be suitable for more powerful forms processing, such as might be found on a standard desktop browser or a server. Implementations of XForms Full should return "full" for the conformance-level property.
Additional details will be provided in future revisions of this chapter.