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>

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>
  <caption>Click here</caption>
</button>

Data Binding Restrictions:

Implementation Hints: Graphical implementations would typically render this form control as a push-button.

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

7.10 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>
  <true>Married</true>
  <false>Single</false>
</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 must be of type xsd:boolean. It is left to the rendering user agent to decide whether to display this control as a single button/checkbox or as a pair of mutually exclusive buttons.

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 true and false child elements, which can contain display values.

<selectBoolean
  (single node binding attributes)
  (common attributes)
  selectUI = ("radioGroup" | "checkboxGroup" )
>
  <!-- unordered: (caption, help?, hint?, alert?, action?, true?, false?) -->
</selectBoolean>

7.11 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 suggest an appearance through an attribute. The value of the attribute consists of one of the following values, each of which may have a platform-specific look and feel:

radioGroup
checkboxGroup
pulldown
listbox
combo

Example:

<selectOne ref="icecream/flavor">
  <caption>Flavor</caption>
  <choices>
    <item value="vanilla"><caption>Vanilla</caption></item>
    <item value="strawberry"><caption>Strawberry</caption></item>
    <item value="chocolate"><caption>Chocolate</caption></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 stores the storage value corresponding to the selected choice at the location pointed to by attribute ref. If the list of choices uses item elements to list the choices, this storage value is found as the lexical value of attributevalue of the selected item element; if the list of choices uses element itemref then the storage value is found at the location pointed to by the XPath value found as the value of attributeref of the selected itemref element. If the datatype of the location being populated by 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 "combo" UI hint is specified, the form control then should allow free data entry, as described in7.2 input, in addition to the behavior defined here.

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 this form control as a pulldown list or group of radio buttons, among other options. The selectUI attribute offers a hint as to which rendering might be most appropriate, although any styling information (such as CSS) should take precedence.

<selectOne
  (single node binding attributes)
  (common attributes)
  selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "combo")
>
  <!-- unordered: (caption, help?, hint?, alert?, action?, choices?) -->
</selectOne>

7.12 selectMany

Description: This form control allows the user to make multiple selections from a set of choices.

Example:

<selectMany ref="icecream/flavors">
  <caption>Flavors</caption>
  <choices>
    <item value="v"><caption>Vanilla</caption></item>
    <item value="s"><caption>Strawberry</caption></item>
    <item value="c"><caption>Chocolate</caption></item>
  </choices>
</selectMany>

In the above example, more than one flavor can be selected.

A graphical browser might render form control selectMany as any of the following:

listbox	checkboxGroup	radioGroup	pulldown
		This configuration is not recommended.	N/A

Data Binding Restrictions: The portion of the instance bound to by this form control must be capable of holding multiple selections, i.e. it must be a schema list type, (in which case the selected values are stored as a space separated list ) or an XML element capable of holding the selected choices as child elements. When no item is selected, the instance contains an empty list.

<item value="United States of America">...</item>

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.

<selectMany
  (single node binding attributes)
  (common attributes)
  selectUI = ("radioGroup" | "checkboxGroup" | "pulldown" | "listbox" | "comboGroup")
>
  <!-- unordered: (caption, help?, hint?, alert?, action?, choices?) -->
</selectMany>

7.13 Common Markup forselectOneand selectMany

<item
  id = xsd:ID
  value = lexical-representation
> 
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</item>

<itemref
  id = xsd:ID
  ref = xpath-expression
> 
  <!-- unordered: (caption, help?, hint?, alert?, action?) -->
</itemref>

<choices
  id = xsd:IDREF
>
  <!-- (item | itemref | choices)+ -->
</choices>

7.14 Common Markup

The preceding form control definitions make reference to several child elements and attributes that are common to several of the form controls. This section defines these common markup components.

xml:lang = xsd:language
id = xsd:ID
class = space separated list of classes
navIndex = xsd:nonNegativeInteger : 0
accessKey = xsd:token

ref = binding-expression
xform = xsd:IDREF
bind = xsd:IDREF

nodeset = binding-expression
xform = xsd:IDREF
bind = xsd:IDREF

<caption
  (common attributes)
>
  <!-- mixed content -->
</caption>

<help
  (common attributes)
>
  <!-- mixed content -->
</help>

<hint
  (common attributes)
>
  <!-- mixed content -->
</hint>

<alert
  (common attributes)
>
  <!-- mixed content -->
</alert>

<action
  id = xsd:ID
  evt:event = event-name
>
  <!-- Action handlers -->
</action>

<extension
  id = xsd:ID
>
  <!-- ##other -->
</extension>