Introduction
This article is a quick reference of the XForms user interface elements. Mainly this is aimed to document how XForms elements will be presented in Mozilla since the XForms specifications give only a hint of how controls might be rendered.
Currently XForms can be hosted by XHTML and XUL in Seamonkey and Firefox. Later we have plans to support XForms hosted by SVG. The XForms specs define two kinds of XForms UI elements, called 'Form Controls' and 'XForms User Interface'. Elements from the "Form Controls" group allows users to interact with instance data. The set of "XForms User Interface" elements exist to aid form authors in combining host language markup and XForms markup together in order to build user interfaces. Some of the 'Form Controls' can have multiple appearances and thus may be rendered in multiple ways. We use the data type of the instance node that the form control is bound to as a clue when making a rendering decision. The form author can also use the 'appearance' attribute on the form control to give us another clue. For example, a XForms input control may appear as a text field or as a datepicker depending on whether it is bound to a xsd:string type or a xsd:date type. When a xf:output binds to a node that has a type of xsd:date, we output the date value as plain text. An output bound to a date and also having @appearance='full' will display as a calendar.
This article uses several notations. If you see Fx 3.0 only, that means that the control will only be available for Firefox 3.0 (Gecko 1.9). There are several possible reasons for this restriction. The first is that the changes required for such controls could not be safely made to Firefox 1.5 or Firefox 2.0. The second is that the control is introduced in XForms 1.1 and we don't feel adding the enhancement would be prudent until the 1.1 spec is more stable. For instance, when the spec reaches 'recommendation'-level status. If you see xhtml/xul then it means the control is available when XForms is hosted in either XHTML or XUL. Similarly, if you see xhtml only or xul only, then it means the control is available only in that host language.
Attribute Sets
This section describes attributes that are often used on XForms elements. These attributes are combined into following logical groups.
UI Common
The UI Common attribute set (see the spec) contains the attributes that are available for the XForms elements that are used to build the user interface presentation in a form.
- appearance - the value provided by the form author gives a hint to the processor as to which widget to use to represent the XForms control. Three possible values are available to the author: minimal, compact and full. Generally speaking, the main purpose for these values is to reflect how much space (screen real estate) the displayed widget will take.
- tabindex - defines the keyboard navigation sequence between controls.
- accesskey - keyboard shortcut for moving focus to an XForms element.
Binding attributes
Single-Node (see the spec) and Node-Set (see the spec) attributes are used to bind XForms elements to instance nodes. These attributes are: ref, nodeset, model and bind.
XForms Elements
Almost every XForms element can be presented as one of serveral different kinds of widgets. This section contains a short description of each XForms element and its representation. The XForms specification offers suggestions for some of the representations, but some of the widgets we use are only available in the Mozilla XForms processor. The choice of widget that we use is often determined by the data type of the instance node that the xforms element is bound to. The form author can also influence the widget by using the appearance attribute on the element.
Form Controls Module
This section contains a short description for each form control element.
input
A key xforms element to show and change the instance data to which it is bound. Usually bound to data that can be well-represented by a string (see the spec). It can have the following representations:
- text field - default representation. Used for most data types, especially text data.
- checkbox - used for boolean instance data
- datepicker - default representation for date data types. Similar to a combobox. Consists of a text field for direct input and a dropdown calendar that can also be used to input the date value.
- calendar - used for date data types when appearance = 'full'.
- days list - used when the data has a data type of day.
- months list - used when the data has a data type of month.
- number field - used for numerical data types.
secret
Used for inputting passwords. Each character typed by the user is represented by an asterisk on the screen (see the spec).
textarea
Serves to show/change multiline text (see the spec).
output
Serves to show the instance data that the element is bound to in a read-only manner (see the spec). It can have the following presentations:
- text - default representation for data of most types, especially static text.
- calendar - used for date data types when appearance = 'full'.
- image - if the instance node contains an image, then an output element can be used in combination with the mediatype element to display the image.
upload
Provides a means for the user to select a file (see the spec).
range
Allows the user to choose a value from within a specific range of values. It is represented by a slider widget (see the spec).
trigger
Allows the user to initiate actions (see the spec). It can have the following representations:
- button - default representation.
- link/clickable text - used when appearance = 'minimal'.
submit
Invokes the submission of the selected instance data to its target destination, which could be local or remote (see the spec). It can have the following representations:
- button - default representation.
- link/clickable text - used when appearance = 'minimal'.
select
List control. Allows the user to choose one or multiple values from a list of pre-defined values (see the spec). It can have the following representations:
- listbox - default representation
- checkbox group - used when appearance = 'full'
select1
Combobox control. Allows the user to choose a single value from a list of pre-defined values (see the spec). It can have the following representations:
- combobox - default representation
- listbox - used when appearance = 'compact'
- radio group - used when appearance = 'full'
Additional Elements
These elements may be used as child elements to the form controls described above.
label
Specifies the label for the xforms control (see the spec). Every form control other than the output element must contain a label element. It is valid for a form control to have an empty label element.
help
Specifies contextual help for the containing form control (see the spec). The help will be displayed if the F1 key is pressed while the containing form control has focus.
hint
Similar to a tooltip (see the spec). The hint is displayed when the mouse moves and pauses over the containing form control.
alert
This message will be shown when the form control cannot properly bind to instance data or when the instance data value is invalid or out of the specified range of selectable values (see the spec).
message
Used in combination with event listeners to display a message to the user when the specified event occurs (see the spec).
XForms User Interface
These elements are mainly used to organize and manage the form's markup.
They can be bound to instance nodes to define context for the xforms controls that they contain, should any of their child nodes happen to use relative xpath expressions. Binding these elements to instance data is also a way to apply Model Item Properties (for example, relevancy) to the elements.
Elements in this section do not have any behaviors that are dependent on the host language.
group
This element is used to logically group xforms elements together (see the spec).
switch
This element is used in conjunction with case and toggle elements (see the spec). The switch element contains case elements which in turn contain markup. Only the contents of a single case may be displayed at one time. The toggle element is used (as an event handler) to make a case visible and thereby hiding all other case elements contained by the same switch.
repeat
A repeat element contains markup and is itself bound to a nodeset in an instance document (see the spec). For each node in the nodeset, the contents of the repeat element will be displayed in the form. That node will serve as the context node for any relative xpath expressions in that set of repeated markup. For example, if a repeat is bound to a nodeset that contains 5 nodes and the repeat contains an output element that echoes the current node, then the user will see 5 outputs in the form. Combined together, these outputs would echo the value of every node in the selected nodeset.