XForms 1.0

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 provide easy navigation.

The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.

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 XForms and how XForms Processors must interpret the various components in order to claim conformance.

Appendixes

Appendixes contain a normative description of XForms described in XML Schema, information on references, and other useful information.

1.4 Documentation Conventions

The following highlighting and typography is used to present technical material in this document:

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, though typically only on introductory usage or when special attention needs to be directed toward the term.

The XML representations of various elements within XForms are presented as follows: Listed are the element name, names of all attributes, allowed values of attributes appearing after a "=" character, default values of attributes appearing after a ":" character, and allowed content. One or more headings below the table provide additional explanatory information.

<example
  count = xsd:integer
  size = (small | medium | large) : medium
>
  <!-- Content: (allowed-content) -->
</example>

Non-normative short examples are set off typographically:

Example Item

or

Example Item

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:

2.1 Purpose and Presentation

For explanatory purposes, a form can be considered to consist of 'purpose', 'presentation', and 'data'. Some examples:

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:

<?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">
<head>
  <title>eCommerce Form</title>
</head>
<body>
<form action="http://example.com/submit" method="post">
  <table>
    <tr>
      <td><p>Select Payment Method:</p></td>
      <td><label><input type="radio" name="as" value="cash"/>Cash</label>
      <label><input type="radio" name="as" value="credit"/>Credit</label></td>
    </tr>
    <tr>
      <td><label for="cc">Credit Card Number:</label></td>
      <td><input type="text" name="cc" id="cc"/></td>
    </tr>
    <tr>
       <td><label for="exp">Expiration Date:</label></td>
       <td><input type="text" name="exp" id="exp"/></td>
    </tr>
    <tr>
       <td colspan="2"><input type="submit"/></td>
    </tr>
  </table>
</form>
</body>
</html>

A browser might render this form as follows:

This form makes no effort to separate purpose (data collection semantics) from presentation (the <input> form controls), and offers no control over the basic name/value pair serialization of the resulting data. XForms greatly improve 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 .../>
</xform:xform>

With these changes to the containing document, the previous example could be rewritten like this:

<xform:selectOne ref="as">
  <xform:caption>Select Payment Method</xform:caption>
  <xform:choices>
    <xform:item value="cash"><xform:caption>Cash</xform:caption></xform:item>
    <xform:item value="credit"><xform:caption>Credit</xform:caption></xform:item>
  </xform:choices>
</xform:selectOne>
<xform:input ref="cc">
  <xform:caption>Credit Card Number</xform:caption>
</xform:input>
<xform:input ref="exp">
  <xform:caption>Expiration Date</xform:caption>
</xform:input>
<xform:submit>
  <xform:caption>Submit</xform:caption>
</xform:submit>

Notice the following features of this design:

• The user interface is not hard-coded to use radio buttons. Different devices (such as a voice browser) can render the concept of "selectOne" as appropriate.

• Form controls always have captions directly associated with them, as child elements.

• There is no need for an enclosing form element.

• Markup for specifying form controls has been simplified: <xform:input> rather than <input type="text">; and <xform:selectOne> instead of <html:select multiple="multiple>

• 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 would look like this:

<!-- envelope, generated separately -->
<Envelope>
  <Body>

    <!-- serialized instance data -->
    <as>Credit</as>
    <cc>1235467789012345</cc>
    <exp>2001-08</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 processing 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 thexform element, defined as follows:

<xform:xform>
  <xform:submitInfo action="http://example.com/submit" method="..."/>
  <xform:instance>
    <payment as="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 XML namespaces are now used, and thata wrapper element of the author's choosing wraps the instance data.

• Empty elements pay:cc and pay:exp serve as placeholders in the XML structure, and will be filled in with form data provided by the user.

• An initial value ("credit") for the form control is provided through the instance data, in this case an attribute as. In the submitted XML, this initial value will be replaced by the user input, if any.

To connect this instance data with form controls, therefattributes on the form controls need to point to the proper part of the instance data, using binding expressions:

... xmlns:pay="http://commerce.example.com/payment"...
  <xform:selectOne ref="pay:payment/@as">
  ...
  <xform:input ref="pay:payment/pay:cc">
  ...
  <xform:input ref="pay:payment/pay: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

Referring to the earlier XHTML form in 2.2 Current Approach: XHTML, 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 as field.

• The credit card information fields cc and exp should be required when the "credit" option is chosen in the as 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.

An XForms Model consists of model items, which include XML Schema datatype facet information [XML Schema part 2] as well as properties specific to XForms.

... xmlns:pay="http://commerce.example.com/payment"...
<xform:bind ref="pay:payment/pay:cc"
  relevant="pay:payment/@as == 'credit'"
  required="true"
  type="pay:cc"/>

<xform:bind ref="pay:payment/pay:exp"
  relevant="pay:payment/@as == 'credit'"
  required="true"
  type="xsd:gYearMonth"/>

<!-- Plus the following in an external Schema -->
...
  <xsd:simpleType name="cc">
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="\d{14,16}"/>
    </xsd:restriction>
  </xsd:simpleType>
...

2.6 Multiple Forms per Document

XForms processing places no limits on the number of individual forms that can be placed in a single containing document. When multiple forms share the same containing document, multiple 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 anxformattribute alongside the ref attribute. The default for thexform attribute is to refer to the firstxformelement 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 action="http://example.com/submit" method="..."/>
  <xform:instance>
     ...payment instance data...
  </xform:instance>
</xform:xform>

<xform:xform id="poll">
  <xform:submitInfo .../>
</xform:xform>

Additionally, the following form control markup in the body:

<xform:selectOne ref="pollOption" xform="poll">
  <xform:caption>How useful is this page to you?</xform:caption>
  <xform:choices>
    <xform:item value="0"><xform:caption>Not at all helpful</xform:caption></xform:item>
    <xform:item value="1"><xform:caption>Barely helpful</xform:caption></xform:item>
    <xform:item value="2"><xform:caption>Somewhat helpful</xform:caption></xform:item>
    <xform:item value="3"><xform:caption>Very helpful</xform:caption></xform:item>
  </xform:choices>
</xform:selectOne>
<xform:submit xform="poll">
  <xform:caption>Submit</xform:caption>
</xform:submit>

The main difference to note here is the use of xform="poll", which identifies which form the form control binds to.

2.7 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,parallel to the opening example document, presented in one segment.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:xform="http://www.w3.org/2001/08/xforms"
      xmlns:pay="http://commerce.example.com/payment"
      xml:lang="en">
<head>
  <title>XForms in XHTML</title>

  <xform:xform>
    <xform:submitInfo action="http://example.com/submit"
      method="post"
      encType="xml"/>
    <xform:instance>
      <pay:payment as="credit">
        <pay:cc/>
        <pay:exp/>
      </pay:payment>
    </xform:instance>
    <xform:model href="payschema.xsd"/>
    <xform:bindings>
      <xform:bind ref="pay:payment/pay:cc"
        relevant="pay:payment/@as == 'credit'"
        required="true" type="pay:cc"/>
      <xform:bind ref="pay:payment/pay:exp"
        relevant="pay:payment/@as == 'credit'"
        required="true" type="xsd:gYearMonth"/>
    </xform:bindings>
  </xform:xform>
</head>
<body>
    ...
<xform:selectOne ref="pay:payment/@as">
  <xform:caption>Select Payment Method</xform:caption>
  <xform:choices>
    <xform:item value="cash"><xform:caption>Cash</xform:caption></xform:item>
    <xform:item value="credit"><xform:caption>Credit</xform:caption></xform:item>
  </xform:choices>
</xform:selectOne>
<xform:input ref="pay:payment/pay:cc">
  <xform:caption>Credit Card Number</xform:caption>
</xform:input>
<xform:input ref="pay:payment/pay:exp">
  <xform:caption>Expiration Date</xform:caption>
</xform:input>
<xform:submit>
  <xform:caption>Submit</xform:caption>
</xform:submit>
...
</body>
</html>

4.1 XML Schema Datatypes

XForms includes all XML Schema datatypes, including the concepts of value space and lexical space, and all constraining facets, as specified in [XML Schema part 2]. These are further divided into two modules, called Basic and Full, and are as follows (the Basic module contains only those datatypes with an asterisk*):

Built-in primitive types:

duration *
dateTime *
time *
date *
gYearMonth *
gYear *
gMonthDay *
gDay *
gMonth *
string *
boolean *
base64Binary *
hexBinary
float
decimal *
double
anyURI *
QName
NOTATION

Built-in derived types:

normalizedString
token
language
Name
NCName
ID
IDREF
IDREFS
ENTITY
ENTITIES
integer *
nonPositiveInteger *
negativeInteger *
long *
int *
short *
byte *
nonNegativeInteger *
unsignedLong *
unsignedInt *
unsignedShort *
unsignedByte *
positiveInteger *

4.2 XForms Datatypes

The Schema for XForms derives the following types for use within forms:

5.1 Introduction

Chapter 4 Datatypes described how XForms adopts the XML Schema datatyping system, which can constrain the value space of datatypes that can be used in data collection. This chapter introduces an additional set of properties, called model item properties, which define XForms-specific behaviors and metadata useful for data collection.

5.2 Model Item Properties

Model item properties fall into two basic categories:

• Computed expressions are XPath expressions that provide a value to the XForms Processor. The value is recomputed at certain times, according to the XForms Processing Model (see 11 Processing Model).

• All other properties are fixed, static values that the XForms Processor evaluates only once.

The following properties are available for all model items, and their syntax is explained throughout this chapter. For each property the following information is provided:

Description
Computed Expression (yes or no)
Legal Values
Default Value
Additional descriptive text

5.3 Binding

Binding is the glue that connects the separate pieces of XForms--directly associating nodes in the instance data with model item properties.

Binding is specified through the use of binding expressions, which select nodes from the instance data. The syntax and details of binding expressions are based on XPath, and defined in the chapter 6 XPath Expressions in XForms. This section describes the wider topic of how binding expressions are used within XForms.

<bind
  id = xsd:ID
  ref = binding-expression
  type = xsd:QName
  readOnly = model-item-property
  required = model-item-property
  relevant = model-item-property
  isValid = model-item-property
  calculate = model-item-property
  maxOccurs = xsd:nonNegativeInteger or "unbounded"
  minOccurs = xsd:nonNegativeInteger
>
  <!-- Content: (##empty) -->
</bind>

<xform:input bind="id-of-bind-element">
   <xform:caption>Your first name</xform:caption>
</xform:input>

<xform:input xform="id-of-xform-element" ref="binding-expression">
   <xform:caption>Your first name</xform:caption>
</xform:input>

<html:input type="text" name="..." xform:bind="id-of-bind-element"/>

<xform:instance xmlns="">
  <orderForm>
    <shipTo>
      <firstName>John</firstName>
    </shipTo>
  </orderForm>
</xform:instance>

<xform:bind ref="orderForm/shipTo/firstName"
  id="fn"
  type="xsd:string"
  required="true"/>

<xform:input ref="orderForm/shipTo/firstName">...</xform:input>
<!-- or -->
<xform:input bind="fn">...</xform:input>

5.4 Applying XML Schema Datatypes

Datatypes used in XForms are either those predefined in chapter4 Datatypes, or simpleTypes defined in an external Schema, as defined in [XML Schema part 2].

<xsd:simpleType name="restrictedString">
  <xsd:restriction base="xsd:string">
    <xsd:minLength value="1"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="Mastercard"/>
    <xsd:enumeration value="Diner's Club"/>
    <xsd:enumeration value="American Express"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="Mastercard"/>
        <xsd:enumeration value="Diner's Club"/>
        <xsd:enumeration value="American Express"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

<xsd:simpleType>
  <xsd:union memberTypes="creditCardType bonusProgramType"/>
</xsd:simpleType>

<xsd:simpleType name="listOfMyIntType">
  <xsd:list itemType="xsd:int"/>
</xsd:simpleType>

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.)

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.

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.

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. Every XPath expression requires a context against which to be evaluated.

The following context is used for evaluating all binding expressions in XForms:

1. 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 a binding expression 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.

2. 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".

3. The context size and position are both exactly 1.

4. No variable bindings are in place.

5. The available function library is defined below.

6. Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.

Example:

<group ref="element1/foo/bar">
  <selectOne ref="element2" ... />
  <selectOne ref="@attr" ... />
</group>

In this example, the group 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.

6.6 Extensibility

XForms 1.0 allows extension functions, similar to [XSLT].

This version of XForms does not provide a mechanism for defining implementations of extensions. Therefore, a containing document that must be portable between XForms implementations cannot rely on particular extensions being available. XForms provides mechanisms that allow a containing document to determine whether the XForms processor by which it is being processed has implementations of particular extensions available, and to specify what should happen if those extensions are not available. If a containing document is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still work with any XForms implementation.

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 class attributes 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 5 The XForms Model.

Form controls enable accessibility by taking a uniform approach to such features as captions, help text, tabbing and keyboard shortcuts. Internationalization issues are addressed in conjunction with the Internationalization Working Group and are addressed by following the same design principles as within the rest of XHTML. All form controls defined here are suitable for implementation as Aural CSS (ACSS) form controls.

Form controls are as general and high-level as possible without sacrificing the ability to deliver real implementations. For instance, to select one or more items from a set, use the form controls selectOne or selectMany, respectively. Form controls distinguish the functional aspects of the underlying control, as well as presentational aspects (through class attributes) and behavior (through XForms Action elements). This separation enables 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 form controls. This specification will also include non-normative rules for how these same controls might be rendered to alternative access modalities.

For each form control, the following aspects sections describe:

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.14 Common Markup ).

7.2 input

Description: This form control enables free-form data entry.

Examples:

<input ref="order/shipTo/street" style="width:5cm; height:1.2cm">
  <caption>Street<caption>
  <hint>Please enter the number and street name</hint>
</input>

In the above, CSS style attributes (which are not defined in XForms but rather come from an external document type) 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. Schema facets bound to this form control will be treated as a restriction upon the allowed entered value.

<input
  (single node binding attributes)
  (common attributes)
>
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</input>

7.3 textarea

Description: This form control enables free-form data entry and is intended for use in entering multiline content, e.g., the body of an email message.

Examples:

<textarea ref="message/body" style="width:8cm; height:5cm">
  <caption>Message Body:<caption>
  <hint>Enter the text of your message here</hint>
</textarea>

In the above, CSS style attributes (which are not defined in XForms but rather come from an external document type) 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. Schema facets bound to this form control will be treated as a restriction upon the allowed entered value.

<textarea
  (single node binding attributes)
  (common attributes)
>
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</textarea>

7.4 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">
  <caption>Please enter your password --it will not be visible as you type.<caption>
</secret>

A graphical browser might render this form control as follows:

Data Binding Restrictions: Identical to input.

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.

<secret
  (single node binding attributes)
  (common attributes)
>
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</secret>

7.5 output

Description: This form control renders a value from the instance data, but provides no means for entering or changing data. It is typically used to display values from the instance, and is treated as display:inline for purposes of layout.

Example:

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 (or the result of theformatexpression, if present) is displayed, after processing as described in11 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.

<output
  id = xsd:ID
  (single node binding attributes)
  format = formatting-expression
>
  <!-- empty content -->
</output>

7.6 upload

Description: This form control enables the common feature found on Web sites to upload a file from the local file system, as well as accepting input from various devices including microphones, pens, and digital cameras.

Example:

<upload ref="mail/attach1" mediaType="image/*">
  <caption>Select image:</caption>
</upload>

A graphical browser might render this form control as follows:

Data Binding Restrictions: This form control can only be bound to datatypes xsd:base64Binary or xsd:hexBinary, or types derived by restriction from these.

Implementation 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 upload 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/jpeg" 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.

<upload
  (single node binding attributes)
  (common attributes)
  mediaType = list of content types
>
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</upload>

7.7 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, xsd:decimal would be fine, while xsd:string 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 thestart and end attributes.

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.

<range
  (single node binding attributes)
  (common attributes)
  start = datavalue
  end = datavalue
  stepSize = datavalue-difference
>
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</range>

7.8 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 submitInstance XForms Action.

<submit
  (nodeset binding attributes)
  (common attributes)
>
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</submit>