WMultiSelect
WMultiSelect is a component for creating a multi-select list control. WMultiSelect is almost identical to WSingleSelect.
WMultiSelect allows for implicit null selection (unlike WDropdown or WRadioButtonSelect).
- Why use WMultiSelect
- Creating WMultiSelect
- Accessibility
- Selection constraints
- Appearance
- HTML output
- Read-only
- Disabling
- Hiding
- Custom design and behaviour
- Related components
- Further information
WMultiSelect allows a user to select zero or more options from a list of (potentially grouped) options. WMultiSelect is a common UI artefact and is moderately easy for people to use on a variety of platforms. It provides the best user experience for selecting zero to several options from a small to moderate list of options.
WMultiSelect may be the best option for mobile web.
WMultiSelect uses a built-in UI widget and is usable on all platforms. Some users may have difficulty selecting non-contiguous options and a large set of options may make it difficult for a user to keep abreast of their selections.
Applications which do not have a user base which includes iOS users may find WMultiSelectPair can be a better user experience for selecting non-contiguous options from a moderate to large list.
There are four constructors for WMultiSelect. The default constructor will create a WMultiSelect with no options. A WMultiSelect may also be created with default options based on a List, Object Array or table Object.
// default constructor - no options
WMultiSelect field = new WMultiSelect();
// creating a WMultiSelect using a named table
field = new WMultiSelect(TABLE_NAME);The performance of WMultiSelects (or other list-based selection components such as WSingleSelect 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.
WMultiSelect may have one or more options 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(s) are set using a List.
// With WMultiSelect field which has options from a List `optionList`
// set the second option as selected. Why? this is just a wiki example!
List selected = new ArrayList<>();
// Using get(index) is just for show - normally one would have a
// sensible way to get a selected option.
selected.add(optionList.get(1));
// ... could obviously add others ...
field.setSelected(selected);Each option in a WMultiSelect 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 WMultiSelect 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 WMultiSelect 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 WMultiSelects 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 of WMultiSelect.
When designing a UI containing a WMultiSelect the WLabel must be placed immediately before or above the control.
// If WFieldLayout is not used then the label must precede the control
WMultiSelect field = new WMultiSelect();
WLabel selectLabel = new WLabel("Select something", field);
// ...
add(selectLabel);
add(field);A WMultiSelect which is not appropriately labelled may display an unlabelled control warning.
If the WMultiSelect has selection constraints then there must be an indication of these constraints somewhere in the UI and available to all users. The appropriate place for this information is in the WLabel hint.
If the control is mandatory this indication is automatically generated within the legend element and the legend (if visible) and pseudo-label (if present) are both decorated accordingly.
See toolTip. A WMultiSelect may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// with WMultiSelect field
field.setToolTip("Some further context to this selection.");WMultiSelect 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 WMultiSelect field
field.setAccessibleText("Some further context to this selection.");A WLabel for a WMultiSelect may be given an access key to provide rapid keyboard access.
A WMultiSelect 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 WMultiSelect supported the notion of SubmitOnChange. This should be avoided as much as possible.
A WMultiSelect 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 WMultiSelect `field` mandatory
field.setMandatory(true);The minimum number of selected options which constitutes a valid selection, if any selection is made at all may be set on any WMultiSelect in an interactive state.
This property is set as an integer. It should not be specified as 1; if the component must have a selection then the mandatory state should be used, if the component is optional and the minimum number of selections, if any are made, is 1 then setting the min property is superfluous and merely adds unnecessary testing overhead. If this property is set then the minimum number of options which are to be selected should be indicated in the WLabel for the component. This could be done in the label text or as a label hint.
// with WMultiSelect `field`
field.setMinSelect(3);
// set the label hint...
fieldLabel.setHint("select at least three options");Setting a minimum number of selected options will not automatically make the component mandatory. The number selected is validated only if the user has made a selection. To make a component mandatory use the mandatory state. These may be used in conjunction to enforce a required minimum selection by the user.
The maximum number of selected options which constitutes a valid selection may be set on any WMultiSelect in an interactive state. If set then an indication of this should be included in the component's WLabel.
// with WMultiSelect `field`
field.setMaxSelect(3);
// set the label hint...
fieldLabel.setHint("select no more than least three options");It is usually inappropriate to use a WMultiSelect with its maximum allowed selections set to one. For this purpose WSingleSelect or WDropdown may be more appropriate. There is an edge case where this could be useful: if a selection is optional and it is desired that the user be able to deselect a selected option then WMultiSelect will allow this. WSingleSelect allows for no selection until a selection is made but once made the selection can be changed but not removed. WDropdown does not allow for no selection. This is a very contrived use-case.
WMultiSelect outputs a browser-determined HTML select element with the multiple attribute set. Its appearance is determined by the user agent. The illustrations in this document were all created using Google Chrome on OS X.
-
WMultiSelect and WSingleSelect are identical with no (or one) selection
-
WMultiSelect with several selected options
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 WMultiSelect `field`
// set 12 visible rows
field.setRows(12);The minimum allowed rows is 2 which was determined to remove usability problems which occur if only one row is specified.
-
WMultiSelect with size 10
-
WMultiSelect with size 1 (no longer possible in WComponents)
The width of a WMultiSelect 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.
WMultiSelect outputs a HTML select element. This is a labelable, interactive form-bound control and may not be placed in any context which forbids this content type. WMultiSelect has the HTML select element's multiple attribute set.
When in a read-only state the WMultiSelect's selected options are output in a HTML ul element. Only the selected options (if any) are output.
The read-only state changes the output rendering of the component so that it appears as a appears as text output of the value(s) of the selected options. The control is not able to be interacted with by the user and does not return any value back to the application. WMultiSelect will output a list of all selected values.
-
A WMultiSelect 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.
WMultiSelect 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 WMultiSelect has no selections.
-
A disabled WMultiSelect with no selections
-
A disabled WMultiSelect with no selections
A WMultiSelect 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 a read-only state.
WMultiSelect 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 WMultiSelect is hidden a WLabel associated with it is also hidden.
WMultiSelect's limited palate of appearance options are designed to ensure a high degree of consistency, accessibility and usability. The design and even behaviour of WMultiSelect 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.
WMultiSelect field = new WMultiSelect();
// to set class attribute values on the HTML output
field.setHtmlClass("myMagicClass anotherMagicClass");