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

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

<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.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, e.g., 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.

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

<submit submitInfo="timecard">
  <caption>Submit Timecard</caption>
</submit>

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

Implementation Requirements: Upon receiving event xforms:activate, this form control dispatches event xforms:submit to the submitInfo element specified by required attribute submitInfo.

<submit
  (common attributes)
  submitInfo = xsd:IDREF #REQUIRED
>
  <!-- caption, (help|hint|alert|action|extension)* -->
</submit>

8.9 selectOne

Description: This form control allows the user to make a single selection from multiple choices.

<selectOne ref="my:icecream/my:flavor">
  <caption>Flavour</caption>
  <item>
    <caption>Vanilla</caption>
    <value>v</value>
  </item>
  <item>
    <caption>Strawberry</caption>
    <value>s</value>
  </item>
  <item>
    <caption>Chocolate</caption>
    <value>c</value>
  </item>
</selectOne>

In the above example, selecting one of the choices will result in the associated value given by element value on the selected item being set in the underlying data instance at the location icecream/flavor.

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

listbox	checkbox	radio	menu

Data Binding Restrictions: Binds to any simpleContent.

Implementation Requirements: The caption for each choice must be presented, allowing at all times exactly one selection. This form control stores the value corresponding to the selected choice in the location addressed by attribute ref. The value to be stored is either directly specified as the contents of element value, or specified indirectly through attribute ref on element value.

Note that the datatype bound to this form control may include a non-enumerated value space, e.g., xsd:string. In this case, control selectOne may have attribute selection="open". The form control should then allow free data entry, as described in 8.1 input.

For closed selections:If the initial instance value matches the storage value of one of the given items, that item is selected. If there is no match, the first item is initially selected.

For open selections: If the initial instance value matches the storage value specified by one of the items, the first such matching item is selected. Otherwise, the selected value is the initial lexical value. Free entry text is handled the same as form control input 8.1 input.

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.

Typically, a stylesheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute selectUI. The value of the attribute consists of one of the following values, each of which may have a platform-specific look and feel.

radio
checkbox
menu
listbox

<selectOne
  (single node binding attributes)
  (common attributes)
  selectUI = ("radio" | "checkbox" | "menu" | "listbox" )
  selection = "open" | "closed" : "closed"
> 
  <!-- caption, (choices|item|itemset)+, (help|hint|alert|action|extension)* -->
</selectOne>

8.10 selectMany

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

<selectMany ref="my:icecream/my:flavors">
  <caption>Flavours</caption>
  <choices>
    <item>
      <caption>Vanilla</caption>
      <value>v</value>
    </item>
    <item>
      <caption>Strawberry</caption>
      <value>s</value>
    </item>
    <item>
      <caption>Chocolate</caption>
      <value>c</value>
    </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	checkbox	radio	menu
		This configuration is not recommended.

Data Binding Restrictions: any simpleContent capable of holding a sequence.

<item>
  <value>United States of America</value>
  ...
</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 = ("radio" | "checkbox" | "menu" | "listbox")
>
  <!-- caption, (choices|item|itemset)+, (help|hint|alert|action|extension)* -->
</selectMany>

8.11 Common Markup for selection controls

<choices>
  <!-- caption?, (choices|item|itemset)+ --> 
</choices>

<item> 
  <!-- caption, value, (help|hint|alert|action|extension)* -->
</item>

<itemset
  (node-set binding attributes)
> 
  <!-- caption, value, (help|hint|alert|action|extension)* -->
</itemset>

<model id="cone">
  <instance>
    <my:icecream>
      <my:flavours/>
    </my:icecream>
  </instance>
</model>
<model id="flavours">
  <instance>
    <my:flavours>
      <my:flavour type="v">
        <my:description>Vanilla</my:description>
      </my:flavour>
      <my:flavour type="s">
        <my:description>Strawberry</my:description>
      </my:flavour>
      <my:flavour type="c">
        <my:description>Chocolate</my:description>
      </my:flavour>
    </my:flavours>
  </instance>
</model>
<!-- user interaction markup -->
<selectMany model="cone" ref="my:icecream/my:flavours">
  <caption>Flavors</caption>
  <itemset model="flavours" nodeset="my:flavours/my:flavour">
    <caption ref="my:description"/>
    <value ref="@type"/>
  </itemset>
</selectMany>

<value
  (single node binding attributes)
>
  <!-- ##any -->
</value>

8.12 Common Markup

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

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

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

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

<caption
  (common attributes)
  (single node binding attributes)
  xlink:href = xsd:anyURI
>
  <!-- ##any -->
</caption>

<help
  (common attributes)
  (single node binding attributes)
  xlink:href = xsd:anyURI
>
  <!-- ##any -->
</help>

<hint 
  (common attributes)
  (single node binding attributes)
  xlink:href = xsd:anyURI
>
  <!-- ##any -->
</hint>

<alert
  (common attributes)
  (single node binding attributes)
  xlink:href = xsd:anyURI
>
  <!-- ##any -->
</alert>

<extension>
  <!-- ##other -->
</extension>

<input ref="dataset/user/email" id="email-input">
  <caption>Enter your email address</caption>
  <extension>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
      <rdf:Description rdf:about="#email-input">
      <my:addressBook>personal</my:addressBook>
      </rdf:Description>
    </rdf:RDF>
  </extension>
</input>