WSingleSelect
WSingleSelect is a component for creating a single select list which is (usually) scrollable rather than "dropdown".
WSingleSelect allows for implicit null selection (unlike WDropdown).
- Why use WSingleSelect
- Creating WSingleSelect
- Accessibility
- Selection constraints
- Appearance
- HTML output
- Read-only
- Disabling
- Hiding
- Custom design and behaviour
- Related components
- Further information
WSingleSelect allows a user to select zero or one option from a list of (potentially grouped) options. The main difference between WSingleSelect and WDropdown is that WSingleSelect allows for zero selections until any selection is made. In this it is similar to WRadioButtonSelect.
WSingleSelect is a common UI artefact and is moderately easy for people to use on a variety of platforms. It may provide an easier selection tool than WDropdown for some users. WSingleSelect may occupy more vertical space than WDropdown and some users may find this makes understanding the range of options easier.
WSingleSelect is the best available option, from usability and accessibility point of view, for selecting one from a large number of options. It provides an easier user experience than WDropdown for almost all users.
WSingleSelect does not enforce a selection, unlike WDropdown but once a selection is made it cannot be undone. If a WSingleSelect is mandatory it may be more appropriate to use a WDropdown. WSingleSelect may occupy more vertical space than WDropdown and some designers may find this less appealing.
There are four constructors for WSingleSelect. The default constructor will create a WSingleSelect with no options. A WSingleSelect may also be created with default options based on a List, Object Array or table Object.
// default constructor - no options
WSingleSelect field = new WSingleSelect();
// creating a WSingleSelect using a named table
field = new WSingleSelect(TABLE_NAME);The performance of WSingleSelects (or other list-based selection components such as WMultiSelect and WDropdown) which share a common list of selectable options can be significantly improved by specifying that the options be supplied using a caching data list.
WSingleSelect may have one option selected by default. This would normally be determined by the current application state or data read from a database but may be set manually.
The selected option is set by passing the selected option object.
// With WSingleSelect `field` which has options from a List `optionList`
// set the second option as selected. Why? this is just a wiki example!
// Using get(index) is just for show - normally one would have a
// sensible way to get a selected option.
field.setSelected(optionList.get(1));Each option in a WSingleSelect must be a string which indicates, to the user, the option being selected. This means the options' values must be understandable such as "apple", "banana", "cumquat" rather than representational of application data such as 0, 1, 2.
When in an interactive mode WSingleSelect will use the browser's native select element which should be the optimum tool for this type of selection for all common assistive technologies.
When a WSingleSelect has focus typing will result in an attempt to match the keys pressed to an option. This used front-of-string matching in early version of WComponents but from 1.4 onwards allows for in-string matching of the text value of an option.
All WSingleSelects in a UI must be associated with a label or otherwise have their usage and intent exposed to all users. This may be done using (in order of preference):
- WLabel or by using the component in a WField (preferred) this is required if the label must be visible in the UI; or
- using the toolTip property if the label does not have to be visible in the UI; or
- using the accessibleText property.
When designing a UI containing a WSingleSelect the WLabel must be placed immediately before or above the control.
// If WFieldLayout is not used then the label must precede the control
WSingleSelect field = new WSingleSelect();
WLabel selectLabel = new WLabel("Select something", field);
// ...
add(selectLabel);
add(field);A WSingleSelect which is not appropriately labelled may display an unlabelled control warning.
See toolTip. A WSingleSelect may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// with WSingleSelect `field`
field.setToolTip("Some further context to this selection.");WSingleSelect may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.
// with WSingleSelect `field`
field.setAccessibleText("Some further context to this selection.");A WLabel for a WSingleSelect may be given an access key to provide rapid keyboard access.
A WSingleSelect in an enabled, interactive state may be set as the default focus point for a page. If this is specified it must comply with accessibility principles regarding focus and not put users into a position where they may skip content required for full understanding of the current view. See Setting focus for more information.
Up to and including WComponents 1.4.x WSingleSelect supported the notion of SubmitOnChange. This should be avoided as much as possible.
A WSingleSelect may be marked as being a mandatory field in the UI. The primary indicator of this is the presence of the required attribute on the HTML select element. The WLabel for the component is decorated with a visual indicator that the component is mandatory as a secondary indicator.
// make WSingleSelect `field` mandatory
field.setMandatory(true);WSingleSelect outputs a HTML select element and the appearance is determined by the user agent. The illustrations in this document were all created using Google Chrome on OS X.
-
WSingleSelect with no (or one) selection
-
WSingleSelect with a selected option
The only appearance option is the number of rows to show in the select (i.e. the height of the component). If this is not set it is determined by the browser and is commonly 4 rows. Note that this constraint is not applied when the component is in a read-only state and is not implemented by Apple in iOS for reasons known only to them.
// with WSingleSelect `field`
// set 12 visible rows
field.setRows(12);-
WSingleSelect with size 1 identical to WDropdown
-
WSingleSelect or with size 10
The width of a WSingleSelect is determined by the visible width of the characters in its longest option. This width may be constrained by the component's container, for example by a WColumn width or an inputWidth setting on a WField.
Other customisations are available within an individual application.
WSingleSelect both outputs a select element. This is a labelable, interactive form-bound control and may not be placed in any context which forbids this content type.
When read-only the WSingleSelect's selected option is output in a span element. Only the selected option (if any) is output.
The read-only state property changes the output rendering of the component so that it appears as a appears as text output of the value of the control. The control is not able to be interacted with by the user and does not return any value back to the application.
-
A WSingleSelect in the read-only state
When in a read-only state the component may be the target of a WSubordinateControl or WAjaxControl. If it is the target of an AJAX action its state may be changed to remove the read-only setting.
WSingleSelect may be disabled on page load. When disabled the component will not respond to user input or interaction. This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call.
The selected state of all options in this case is the same as if they were all deselected. This is important: a disabled WSingleSelect has no selection.
-
A disabled WSingleSelect with no selections
A WSingleSelect should not be output in a disabled state if the intent is to not allow the user to enable the control through the use of a WSubordinateControl. In this case it is more appropriate to use the read-only state.
WSingleSelect may be hidden on page load. When hidden the component is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WSingleSelect is hidden a WLabel associated with it is also hidden.
WSingleSelect's limited palate of appearance options are designed to ensure a high degree of consistency, accessibility and usability. The design and even behaviour of WSingleSelect may be amended on an instance-by instance or application-by-application basis using custom CSS and/or custom JavaScipt. This display/behaviour is then attached to a class-name added using the htmlClass property. For more information see WComponents HTML class property.
WSingleSelect field = new WSingleSelect();
// to set class attribute values on the HTML output
field.setHtmlClass("myMagicClass anotherMagicClass");