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 HTML forms, and benefit from the lessons learned in the years of HTML forms implementation experience.

Further background information on XForms can be found at http://www.w3.org/MarkUp/Forms.

1.2 Reading the Specification

This specification has been written with various types of readers in mind—in particular XForms authors and XForms implementors. We hope the specification will provide authors with the tools they need to write efficient, attractive, and accessible documents, without overexposing them to the XForms implementation details. Implementors, however, should find all they need to build conforming XForms Processors. The specification begins with a general presentation of XForms and becomes more and more technical and specific towards the end. For quick access to information, a general table of contents, specific tables of contents at the beginning of each section provide easy navigation.

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

This document uses the terms may, must, and should in accord with RFC 2119.

1.3 How the Specification is Organized

The specification is organized into the following chapters:

Chapters 1 and 2

An introduction to XForms. The introduction includes a brief tutorial on XForms, and a discussion of design principles.

Chapters 3 and up

XForms reference manual. The bulk of the reference manual consists of the specification of XForms. This reference defines XForms and how XForms Processors must interpret the various components in order to claim conformance.

Appendices

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

1.4 Documentation Conventions

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

Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:

xforms: The XForms namespace 4.1 The XForms Namespace
html: The XHTML namespace [XHTML 1.0]
xsd: The XML Schema namespace [XML Schema part 1]
xsi: The XML Schema for instances namespace [XML Schema part 1]
xlink: The XLink namespace [XLink]
ev: The XML Events namespace [XML Events]
my: Any user defined namespace

This is by convention only; any namespace prefix may be used in practice.

Official terms are defined in the following manner: [Definition: You can find most terms in the chapter 3 Terminology]. Links to terms may be specially highlighted in the text, though typically only on introductory usage or when special attention needs to be directed toward the term.

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

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

Certain common attributes 4.2 Horizontally Applicable Markup are not shown in the syntax representations except when special attention needs to be called to their presence.

Non-normative short examples are set off typographically:

Example Item

or

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:

For diff-marked formatted text, note that newly added text appears like this, changed text appears like this, and deleted text appears like

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 HTML forms didn't separate the purpose of a form from its presentation; additionally, they only offered a restricted representation for data captured through the form.

Here is a summary of the primary benefits of using XForms:

Strong typing

Submitted data is strongly typed and can be checked using off-the-shelf tools. Type validation rules help client-side validation.

Re-use existing schema.

This obviates duplication, and ensures that updating the validation rules as a result of a change in the underlying business logic does not require re-authoring validation constraints within the XForms application.

Annotate external schema

This enables the XForms author go beyond the basic set of constraints available from the back-end. Providing such additional constraints as part of the XForms Model enhances the overall usability of the resulting web application.

Submit XML.

This obviates the need for custom server-side logic to marshall the submitted data to the application back-end. The received XML instance document can be directly validated and processed by the application back-end.

Internationalization

Using XML 1.0 ensures that the submitted data is internationalized.

Enhanced accessibility.

XForms separates content and presentation. User interface controls encapsulate all relevant metadata such as labels, thereby enhancing accessibility of the application when using different modalities.

Multiple device support.

The high-level nature of the user interface controls, and the consequent intent-based authoring of the user interface makes it possible to re-purpose the user interaction to different devices.

Declarative event handlers.

By defining XML-based declarative event handlers such as setFocus, message, and setValue that cover common use cases, the majority of XForms documents remain statically analyzable as opposed to imperative program code.

2.2 Current Approach: HTML

Consider a simple eCommerce form authored in HTML:

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

A browser might render this form as follows:

This form makes no effort to separate purpose (data collection semantics) from presentation (the input form controls), and offers no control over the basic name/value pair serialization of the resulting data. The XForms standard greatly improve the expressive capabilities of electronic forms.

2.3 Transition to XForms

With the XForms approach, forms are comprised of a section that describes what the form does, called the XForms Model, and another section that describes how the form is to be presented. The only presentation option defined in the XForms 1.0 specification is the XForms User Interface, which is a device-independent, platform-neutral set of form controls suitable for general-purpose use. This flexible architecture, however, allows others to attach user interfaces to an XForms Model, as illustrated here:

The simplest case involves authoring the new XForms form controls, leaving out the other sections of the form. To convert the previous form into XForms this way, a model element is needed in the head section of the document:

<xforms:model>
  <xforms:submitInfo action="http://examples.com/submit" id="submit"/>
</xforms:model>

With these changes to the containing document, the previous example could be rewritten like this (note that we have intentionally defaulted the XForms namespace prefix in this example):

<selectOne ref="as">
  <caption>Select Payment Method</caption>
  <choices>
    <item>
      <caption>Cash</caption>
      <value>cash</value>
    </item>
    <item>
      <caption>Credit</caption>
      <value>credit</value>
    </item>
  </choices>
</selectOne>

<input ref="cc">
  <caption>Credit Card Number</caption>
</input>

<input ref="exp">
  <caption>Expiration Date</caption>
</input>

<submit>
  <caption>Submit</caption>
</submit>

Notice the following features of this design:

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

• Form controls always have captions directly associated with them, as child elements—this is a key feature designed to enhance the accessibility of forms.

• There is no need for an enclosing form element, as in HTML. See (See 2.6 Multiple Forms per Document for details on how to author multiple forms per page)

• Markup for specifying form controls has been simplified

• Data gets submitted as XML.

With these changes, the XForms Processor will be able to directly submit XML instance data. The XML is constructed by creating a root element with child elements reflecting the names specified in each form control via attribute ref. In this example, the submitted data would look like this:

<instanceData>
  <as>Credit</as>
  <cc>1235467789012345</cc>
  <exp>2001-08</exp>
</instanceData>

2.4 Providing XML Instance Data

Authors will often desire greater control over exact construction of the submitted instance data. XForms allows data to be checked for validity interactively as the form is being filled.

XForms processing keeps track of the state of the partially filled form through instance data, which provides an outline of the desired XML data in the form of a skeleton XML instance, including namespace information. The instance data starts off with any initial values for the form, is updated as the user fills the form, and eventually is serialized and submitted. The initial instance data is defined in the instance element inside the model element, as follows:

<xforms:model>
  <xforms:instance>
    <payment as="credit" xmlns="http://commerce.example.com/payment">
      <cc/>
      <exp/>
    </payment>
  </xforms:instance>
  <xforms:submitInfo action="http://example.com/submit" method="post"/>
</xforms:model>

This design has features worth calling out:

• There is complete flexibility in the structure of the XML. Notice that XML namespaces are now used, and that a wrapper element of the author's choosing wraps the instance data.

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

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

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

.. xmlns:my="http://commerce.example.com/payment"...
  <xforms:selectOne ref="my:payment/@as">
    ...
  <xforms:input ref="my:payment/my:cc">
    ...
  <xforms:input ref="my:payment/my:exp">

Binding expressions are based on XPath [XPath 1.0], including the use of the @ character to refer to attributes, as seen here.

2.5 Constraining Values

Referring to the earlier HTML form in 2.2 Current Approach: HTML, there are several aspects that would be desirable to express, but would only be possible through the addition of unstructured script code:

• The credit card information form controls cc and exp are only relevant if the "credit" option is chosen in the as form control.

• The credit card information form controls cc and exp should be required when the "credit" option is chosen in the as form control.

• The form control cc should accept digits only, and should have between 14 and 18 digits.

• The form control exp should accept only valid month/date combinations.

By specifying an additional component, model item constraints, authors can include rich declarative datatype and validation information in forms, taken from XML Schema datatypes and also XForms-specific constraints, such as relevant.

XForms constraints appear on bind elements, while Schema constraints are expressed in an XML Schema fragment, either inline or external. For example:

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

<xforms:bind ref="my:payment/my:exp"
    relevant="my:payment/[@as == 'credit']"
    required="true"
    type="xsd:gYearMonth"/>

<xforms:schema>
  <xsd:schema ...>
    ...
    <xsd:simpleType name="cc">
      <xsd:restriction base="xsd:string">
        <xsd:pattern value="\d{14,18}"/>
      </xsd:restriction>
    </xsd:simpleType>
    ...
  </xsd:schema>
</xforms:schema>

2.6 Multiple Forms per Document

XForms processing places no limits on the number of individual forms that can be placed in a single containing document. When multiple forms share the same containing document, multiple model elements are needed. The first model element may omit a unique id attribute (as have all the examples above), but subsequent model elements require an id so that they can be referenced from elsewhere in the containing document.

The other side of the equation is that form controls throughout the document need to specify which model element contains the instance data to which they bind. This is accomplished through a model attribute alongside the ref attribute. this. The default for the model attribute is to refer to the first model element in document order.

To add a second form, an opinion poll, to our commerce example, the following would be authored in the head section of the document:

<xforms:model>
  <xforms:instance>
    ...payment instance data...
  </xforms:instance>
  <xforms:submitInfo action="http://example.com/submit" method="post"/>
</xforms:model>

<xforms:model id="poll">
  <xforms:submitInfo .../>
</xforms:model>

Additionally, the following markup would appear in the body section of the document:

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

<xforms:submit submitInfo="poll">
  <xforms:caption>Submit</xforms:caption>
</xforms:submit>

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

2.7 Complete Document

This chapter has presented various bits and pieces of XForms as a tool to help readers understand the design. For convenience, the entire document is given here in one piece..

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:xforms="http://www.w3.org/2001/12/xforms"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:my="http://commerce.example.com/payment"
      xml:lang="en">
<head>
<title>XForms in XHTML</title>

<xforms:model>
  <xforms:instance>
    <payment as="credit" xmlns="http://commerce.example.com/payment">
      <cc/>
      <exp/>
    </payment>
  </xforms:instance>
  <xforms:schema xlink:href="payschema.xsd"/>
  <xforms:submitInfo action="http://example.com/submit" method="post"/>
  <xforms:bind ref="my:payment/my:cc"
      relevant="my:payment/@as == 'credit'"
      required="true" type="my:cc"/>
  <xforms:bind ref="my:payment/my:exp"
      relevant="my:payment/@as == 'credit'"
      required="true" type="xsd:gYearMonth"/>
</xforms:model>
</head>
<body>
...
<group xmlns="http://www.w3.org/2001/12/xforms" ref="my:payment">
  <selectOne ref="@as">
    <caption>Select Payment Method</caption>
    <choices>
      <item>
        <caption>Cash</caption>
        <value>cash</value>
      </item>
      <item>
        <caption>Credit</caption>
        <value>credit</value>
      </item>
    </choices>
  </selectOne>

  <input ref="my:cc">
    <caption>Credit Card Number</caption>
  </input>

  <input ref="my:exp">
    <caption>Expiration Date</caption>
  </input>

  <submit>
    <caption>Submit Form</caption>
  </submit>
</group>
...
</body>
</html>

4.1 The XForms Namespace

The XForms namespace has the URI: http://www.w3.org/2001/12/xforms. Any future Working Drafts are expected to use a different identifier, though a final identifier will be allocated before XForms becomes a W3C Recommendation.

XForms Processors must use the XML namespaces mechanism [XML Names] to recognize elements and attributes from this namespace.

4.2 Horizontally Applicable Markup

For cases when a particular element needs to be referred to from another context, every element in the XForms namespace has declared an attribute id of type xsd:ID in the Schema for XForms.

Foreign-namespaced attributes are allowed on any XForms element. The XForms Processor must ignore any foreign-namespaced elements or attributes that are unrecognized.

Except where specifically allowed by the Schema for XForms, foreign-namespaced elements are not allowed as content of elements in the XForms namespace.

4.3 XForms Head Elements

<model
  id = xsd:ID
>
  <!-- Content: instance?, schema?, (privacy|submitInfo|bind|action|extension)* -->
</model>

<model xmlns="http://www.w3.org/2001/12/xforms" id="Person">
   <instance xlink:href="http://example.com/cgi-bin/get-instance" /> 
   <schema xlink:href="Schema-Questionnaire.xsd" />
   ...
</model>

<instance
  xlink:href = xsd:anyURI
>
  <!-- Content: (##other) -->
</instance>

<schema
  xlink:href = xsd:anyURI
>
  <!-- Content: ##other (though typically <xsd:schema>) -->
</schema>

<submitInfo
  (single node binding attributes)
  action = xsd:anyURI
  mediaTypeExtension = "none" | qname-but-not-ncname : "none"
  method = "post" | "get" | qname-but-not-ncname : "post"
  version = xsd:NMTOKEN
  indent = xsd:boolean
  encoding = xsd:string
  mediaType = xsd:string
  omitXMLDeclaration = xsd:boolean
  standalone = xsd:boolean
  CDATASectionElements = list of xsd:QName
  replace = "all" | "instance" | "none" | qname-but-not-ncname : "all"
>
  <!-- Content: (##empty) -->
</submitInfo>

<privacy
  xlink:href = xsd:anyURI
>
  <!-- Content: (##empty) -->
</privacy>

4.4 XForms and XLink

XForms use XLink [XLink] features for linking, or defining an explicit relationship between resources (or portions of resources), which may be either local or remote.

To that end, the XForms schema references the XLink namespace with sensible defaults.Other than xlink:href attributes, form authors in most cases will not be required to explicitly write XLink-specific elements or attributes.

All XLinks in XForms are simple links. For further details, see 4.4.1 XLink Conformance and Examples.

<xforms:model>
  <xforms:schema xlink:href="URI-to-remote-schema.xsd" />
</xforms:model>

<xforms:model>
  <xforms:schema>
    <xsd:schema ...>
      <!-- Content: ... -->
    </xsd:schema>
  </xforms:schema>
</xforms:model>

<xforms:model>
  <xforms:schema xlink:type="none">
    <xsd:schema...>
      <!-- Content: ... -->
    </xsd:schema>
  </xforms:schema>
</xforms:model>

5.1 XML Schema Built-in 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. Base types included in module basic are marked with an asterisk *. Datatypes derived by restriction and derived by list from these base types are included in both Basic and Full modules.

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
NMTOKEN
NMTOKENS
integer *
nonPositiveInteger *
negativeInteger *
long *
int *
short *
byte *
nonNegativeInteger *
unsignedLong *
unsignedInt *
unsignedShort *
unsignedByte *
positiveInteger *

5.2 XForms Datatypes

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

6.1 XForms Constraints

XForms constraints, which occur as attributes on element bind in XForms 1.0, fall into two categories:

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

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

The following constraints are available for all model items, using syntax explained throughout this section. For each constraint the following information is provided:

Description
Computed Expression (yes or no)
Applies to children (instance data child elements and attributes)
Legal Values
Default Value
Additional descriptive text

6.2 Schema Constraints

Chapter 5 Datatypes described how XForms adopts the XML Schema datatyping system, which can constrain the value space of datatypes that can be used in data collection. This section draws the connection between Schema features and Schema Constraints, which can occur directly via a schema or indirectly by annotating an instance with instance-specific type constraints.

Attributes xsi:schemaLocation and xsi:noNamespaceSchemaLocation are ignored for purposes for locating a Schema.

XForms Basic processors have restricted Schema processing requirements; full details are at 12.1.1 XForms Basic.

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

<!-- Datatype through Schema xsi:type -->
<my:first-name xsi:type="nonEmptyString"/>

<!-- Datatype through XForms constraint -->
<instance>
  <my:first-name />
</instance>

<bind type="nonEmptyString" ref="/my:first-name"/>

6.3 Additional Schema Examples

The following non-normative sections illustrate mapping between Schema concepts and data structures commonly used in form authoring.

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="Mustercard"/>
    <xsd:enumeration value="Donor's Club"/>
    <xsd:enumeration value="World Express"/>
  </xsd:restriction>
</xsd:simpleType>

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="Mustercard"/>
        <xsd:enumeration value="Donor's Club"/>
        <xsd:enumeration value="World Express"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

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

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

6.4 Binding

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

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

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

<xforms:model id="orders">
  <xforms:instance xmlns="">
    <orderForm>
      <shipTo>
        <firstName>John</firstName>
      </shipTo>
    </orderForm>
  </xforms:instance>
 <xforms:bind ref="/orderForm/shipTo/firstName"
          id="fn" type="xsd:string"
          required="true"/>
</xforms:model>

<xforms:input ref="/orderForm/shipTo/firstName">...

<xforms:input bind="fn">...

<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...

<html:input type="text" name="..." xforms:bind="fn"/>

7.1 Datatypes

XPath data types are used only in Binding expressions and computed expressions. XForms uses XPath datatypes boolean, string, number and node-set. A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes.

7.2 Instance Data

For each model element, the XForms processor maintains the state in an internal structure called instance data that conforms to the XPath Data Model [XPath 1.0]. Elements and attributes in the instance data may have namespace information associated with them, as defined in the XPath Data Model. Unless otherwise specified, all instance data elements and attributes are unqualified. In addition, XForms processors must provide DOM access to this instance data via the interface defined below.

interface XFormsModelElement : org.w3c.dom.Element

The method getInstanceDocument returns a DOM Document that corresponds to the instance data associated with this XForms Model.

Return value: org.w3c.dom.Document

raises (DOMException); if there is no model with the specified model-id.

7.3 Evaluation Context

Within XForms, XPath expressions reference abstract instance data (using the "path" portion of XPath), instead of a concrete XML document. This reference is called a binding expression in this specification. Every XPath expression requires an evaluation context. The following rules are used in determining evaluation context when evaluating binding expressions in XForms:

1. The context node for outermost form control elements is the XPath root (/). A " form control element" is any element other than bind that is explicitly allowed to have a binding expression attribute. A form control element is "outermost" when the node-set returned by the XPath expression ancestor::* includes no form control element nodes.

2. The context node for non-outermost form control elements is the first node of the binding expression of the immediately enclosing element. An element is "immediately enclosing" when it is the first form control element node in the node-set returned by the XPath expression ancestor::*. This is also referred to as "scoped resolution".

3. The context node for the ref attribute on bind is the XPath root. The context node for other attributes of bind is the first node of the node-set returned from the binding expression in the sibling ref attribute.

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

5. No variable bindings are in place.

6. The available function library is defined below.

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

<group ref="level1/level2/level3">
  <selectOne ref="elem" ... />
  <selectOne ref="@attr" ... />
</group>

In this example, the group has a binding expression of level1/level2/level3. According to the rules above, this outermost element would have a context node of /, which is the root of the instance data, or the parent to the elem element. Both of the selectOnes then inherit a context node from their parent, the context node being /level1/level2/level3. Based on this, the selectOne binding expressions evaluate respectively to /level1/level2/level3/elem and /level1/level2/level3/@attr. Matching instance data follows:

<level1>
  <level2>
    <level3 attr="xyz">
      <elem>xyz</elem>
    </level3>
  </level2>
</level1>

7.4 Forms Core Function Library

The XForms Core Function Library includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans.

This section defines a set of required functions for use within XForms.

<xforms:button>
  <xforms:caption>Add to Shopping Cart</xforms:caption>
  <xforms:insert ev:event="ev:activate" position="after"
          nodeset="items/item" at="cursor('cartUI')"/>
</xforms:button>

<xforms:instance>
  ...
  <xforms:bind ref="info/xforms-version" calculate="property('version')"/>
  ...
</xforms:instance>

8.1 input

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

<input ref="order/shipTo/street" class="streetAddress">
  <caption>Street</caption>
  <hint>Please enter the number and street name</hint>
</input>

In the above, the class attribute can be used by a stylesheet to specify the display size of the form control. Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from these display properties.

A graphical browser might render the above example as follows:

Data Binding Restrictions: Binds to any simpleContent (except xsd:base64Binary, xsd:hexBinary or any datatype derived from those).

Implementation Requirements: Must allow entry of a lexical value for the bound datatype. Implementations should provide the most convenient means possible for entry of datatypes and take into account localization and internationalization issues such as representation of numbers. For example, an input bound to an instance data node of type Date might provide a calendar control to enter dates; similarly, an input control bound to data instance of type boolean might be rendered as a simple checkbox.

<input
  (single node binding attributes)
  (common attributes)
  inputMode = xsd:string
>
  <!-- caption, (help|hint|alert|action|extension)* -->
</input>

8.2 textarea

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

<textarea ref="message/body" class="messageBody">
  <caption>Message Body</caption>
  <hint>Enter the text of your message here</hint>
</textarea>

In the above, the class attribute can be used by a stylesheet to specify the display size of the form control. Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from these display properties.

A graphical browser might render the above example as follows:

Data Binding Restrictions: Binds to xsd:string or any derived simpleContent.

Implementation Requirements: Must allow entry of a lexical value for the bound datatype, including multiple lines of text.

<textarea
  (single node binding attributes)
  (common attributes)
  inputMode = xsd:string
>
  <!-- caption, (help|hint|alert|action|extension)* -->
</textarea>

8.3 secret

Description: This form control is used for entering information that is considered sensitive, and thus not echoed to a visual or aural display as it is being entered, e.g., password entry.

<secret ref="/login/password">
  <caption>Password</caption>
  <hint>Please enter your password --it will not
    be visible as you type.</hint>
</secret>

A graphical browser might render this form control as follows:

Data Binding Restrictions: Identical to input.

Implementation Requirements: In general, implementations, including accessibility aids, must render a "*" or similar character instead of the actual characters entered, and thus must not render the entered value of this form control. Note that this provides only a casual level of security; truly sensitive information will require additional security measures outside the scope of XForms.

<secret
  (single node binding attributes)
  (common attributes)
  inputMode = xsd:string
>
  <!-- caption, (help|hint|alert|action|extension)* -->
</secret>

8.4 output

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

I charged you
<output ref="order/totalPrice"/>
and here is why:

A graphical browser might render an output form control as follows:

Data Binding Restrictions: Binds to any simpleContent.

Implementation Requirements: Must allow display of a lexical value for the bound datatype. Implementations should provide the most convenient means possible for display of datatypes and take into account localization and internationalization issues such as representation of numbers.

<output
  (single node binding attributes)
>
  <!-- empty content -->
</output>

8.5 upload

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

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

A graphical browser might render this form control as follows:

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

Implementation Requirements: For suitable mediaTypes:

• Implementations with a file system should support file upload—selecting a specific file. The types of files presented by default must reflect the mediaType specified in the XForms Model, for example defaulting to only audio file types in the file dialog when the mediaType is "audio/*". In XForms 1.0, there is a 1:1 binding between a upload form control and one of the binary datatypes, although that single file may be compound (e.g. application/zip).

• Implementations with specific pen/digitizer hardware should (and implementations with other pointing devices may) support "scribble"—allowing in-place creation of pen-based data. .

• Implementations with specific audio recording capabilities should support record audio—in-place recording of an audio clip.

• Implementations with a digital camera/scanner interface or screen capture should support acquire image—in-place upload of images from an attached device.

• Implementations with video recording capability should provide a record video option.

• Implementations with 3d capabilities should provide a 3d interface option .

• Implementations may provide proprietary implementations (for example, a mediaType of text/rtf could invoke an edit window with a proprietary word processing application)

• Implementations are encouraged to support other input devices not mentioned here.

• Implementations which cannot support upload for the given mediaType must make this apparent to the user.

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

8.6 range

Description: This form control allows selection from a continuous range of values.

<range ref="/stats/balance" start="-2.0" end="2.0" stepSize="0.5">
  <caption>Balance</caption>
</range>

A graphical browser might render this as follows:

Data Binding Restrictions: Binds only the following list of datatypes, or datatypes derived by restriction from those in the list: xsd:duration, xsd:date, xsd:time, xsd:dateTime, xsd:gYearMonth, xsd:gYear, xsd:gMonthDay, "xsd:gDay", xsd:gMonth, xsd:float, xsd:decimal, xsd:double.

Implementation Requirements: Must allow input of a value corresponding to the bound datatype. Implementations should inform the user of the upper and lower bounds, as well as the step size, if any. In graphical environments, this form control may be rendered as a "slider" or "rotary control".

Notice that the attributes of this element encapsulate sufficient metadata that in conjunction with the type information available from the XForms Model proves sufficient to produce meaningful prompts when using modalities such as speech, when using an accessibility aid. Thus, an aural user agent might speak a prompt of the form Please pick a date in the range January 1, 2001 through December 31, 2001.

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

8.7 button

Description: This form control is similar to the HTML element of the same name and allows for user-triggered actions. This form control may also be used to advantage in realizing other custom form controls.

Example:

<button>
  <caption>Click here</caption>
</button>

Data Binding Restrictions: Binding not possible for this form control.

Implementation Requirements: The user agent must provide a means to generate an xforms:activate event on the form control. Graphical implementations would typically render this form control as a push-button with the caption on the button face. Stylesheets can be used to style the button as an image.

<button
  (common attributes)
>
  <!-- caption, (help|hint|alert|action|extension)* -->
</button>

8.8 submit

Description: This form control initiates submission of all or part of the instance data to which it is bound.

Example:

<submit submitInfo="timecard">
  <caption>Sub