XForms Input Element

Introduction

This element is an important and oft-used xforms element to show and change the instance data to which this xforms control is bound (see the spec).

Attributes

• UI Common
  • appearance - the value of this attribute gives a hint to the xforms processor as to which type of widget(s) to use to represent this control
  • accesskey - used to specify the keyboard shortcut for focusing this control
• Single-Node Binding
• Special
  • inputmode - not supported for this control
  • incremental - supported. The default value is 'false'.
• Mozilla Extensions
  • labelposition - only for boolean types: show the label before or after the checkbox (see below)

Type restrictions

The input element can be bound to a node containing simple content of any data type except xsd:base64Binary, xsd:hexBinray or any data type derived from these.

Representations

The xforms input element can be represented by the following widgets for the spcified data types (or types derived from these data types):

• text field - the default widget when no type is specified or the data is of type xsd:string (xhtml/xul)
• checkbox - used for xsd:boolean instance data. (xhtml/xul)
• datepicker - used to represent data of type xsd:date (xhtml/xul)
• calendar - used to represent data of type xsd:date when appearance attribute also has the value 'full' (xhtml/xul)
• month list - used to represent data of type xsd:gMonth (xhtml only)
• days list - used to represent data of type xsd:gDay (xhtml only)
• number field - used to represent data of numeric type (fx 3.0 only, xul only)

More detail about each of these widgets follows below.

text field

Displaying a text field is the default presentation. XForms inputs are most often used when a form author needs to allow for the input/output of simple text into an instance node. Allows for free-form data entry (xhtml/xul).

Characteristics

• A text field is presented to the user when there is no type given for the bound node or a type is specified that is not handled by one of the other widgets (as documented below).
• analogous widgets are <xhtml:input type="text"/> and <xul:textbox/>

Specific handling of attributes

• incremental - if "true", the bound instance node will be updated on each character typed by the user. If "false", or the incremental attribute is omitted on this element then the bound instance node will be updated when the control loses the focus.

checkbox

Most often used when the form author only needs a simple 'true', 'false', '1', or '0' response from the user (xhtml/xul).

Characteristics

• used when the instance node is of type xsd:boolean or a type derived from it
• analogous widgets are <xhtml:input type="checkbox"/> and <xul:checkbox/>
• The corresponding label can be displayed before or after the checkbox by using the labelposition attribute.

Specific handling of attributes

• incremental - if "true" or this attribute is omitted from this element, then the instance node will be updated when the user checks or un-checks the checkbox. If "false" then the instance node will be updated when the checkbox loses the focus.
• labelposition - a Mozilla XForms extension in the namespace http://www.mozilla.org/projects/xfor...009/extensions. This attribute is optional, possible values are before and after. The default value if omitted is after. It controls the display of the label relative to the checkbox. before shows the label first, then the checkbox, after shows the checkbox, than the label.
  labelposition was introduced with Mozilla XForms 0.8.8. Before that, the default behavior was to display the label first, then the checkbox. Since the introduction of labelposition, the behavior changed as described above to better match other implementations as well as commonly used GUI guidelines.

datepicker

This widget is similar to a combobox. It consists of a text field for direct user input next to a button that when activated will 'drop down' a calender widget that the user can also interact with (xhtml/xul).

Characteristics

• used when the instance node is of type xsd:date or a type derived from it.
• will not work with xsd:dateTime (behavior defaults to text input).

Specific handling of attributes

• incremental - if "true", the bound instance node will be updated on each character typed by the user or when the user clicks on a date from the calendar widget. If "false" or the incremental attribute is omitted on this element then the bound instance node will be updated when the control loses focus.

calendar

A form author may notice a xforms input element represented by a calendar widget in the Mozilla XForms processor if the control meets the following criteria (xhtml/xul).

Characteristics

• the bound instance node is of type xsd:date or a type derived from it
• appearance attribute also contains the value "full"
• firefox 2.0 doesn't currently contain any similar XHTML or XUL widgets.

months list

This widget is similar to a combo box populated with the sequence of the 12 month names that comprise a year. The names are localized (xhtml only).

Characteristics

• used when the instance node is of type xsd:gMonth or a type derived from it. The lexical representation for xsd:gMonth is the left and right truncated lexical representation for xsd:date: --MM. For example, the value --01 means the month of January.

Specific handling of attributes

• incremental - if "true", the bound instance node will be updated when the user selects a value from the list. If "false" or the incremental attribute is omitted on this element then the bound instance node will be updated when the control loses the focus.

days list

This widget is similar to a combo box populated with the sequence of the possible days in a month. In short, the values of 1-31 (xhtml only).

Characteristics

• used when the instance node is of type xsd:gDay or a type derived from it. The lexical representation for xsd:gDay is the left truncated lexical representation for xsd:date: ---DD. For example, the value ---03 means the third day of the month. This widget allows the user to omit --- when a value is typed into control (xhtml only).

Specific handling of attributes

• incremental - if "true", the bound instance node will be updated when the user selects a value from the list. If "false" or the incremental attribute is omitted on this element then the bound instance node will be updated when the control loses the focus.

number field

This widget is similar to a spin button widget. Allows the user to only input numerical values (fx 3.0, xul only).

Characteristics

• used when the instance node is of type xsd:decimal or a type derived from it. For several of the schema data types that inherit from xsd:decimal, this numberfield widget will allow the user to only type those values that are allowed by the type. These inheriting types are:
  • xsd:integer
  • xsd:nonPositiveInteger
  • xsd:negativeInteger
  • xsd:long
  • xsd:int
  • xsd:short
  • xsd:byte
  • xsd:nonNegativeInteger
  • xsd:unsignedLong
  • xsd:unsignedInt
  • xsd:unsignedShort
  • xsd:unsignedByte
  • xsd:positiveInteger
• analogous widget is <xul:textbox type="number"/> (will be available in fx 3.0)

Specific handling of attributes

• incremental - if "true", the bound instance node will be updated when the user clicks on the up or down spin buttons or directly edits the field and then sets focus elsewhere. If "false" or the incremental attribute is omitted on the element then the bound instance node will be updated when the control loses the focus.