WMultiSelectPair
WMultiSelectPair is a component for creating a multi select tool which allows for implicit null selection. It also contains the ability to have the user determine the order of the selected options.
- Sample appearance
- Why use WMultiSelectPair
- Accessibility
- HTML output
- UI Properties
- Related components
- Further information
WMultiSelectPair consists of a pair of select lists separated by a column of buttons used to change selections.
WMultiSelectPair is a good tool for selecting multiple disconnected options from a large list. It implements a selection paradigm which is complex but not unusual and therefore is generally a better option than WMultiDropdown. WMultiSelectPair does support no selection and is therefore a better choice for mandatory selection than WMultiDropdown.
WMultiSelectPair does have problems:
- it occupies a lot of horizontal space, especially when the options are long as the width of each list will potentially be the length of the longest option plus scroll bars;
- it is almost unusable on iOS (see below for more details).
At the time of writing (WComponents 1.2.x) it is recommended that WMultiSelectPair is not used in any application which may have an audience which includes iOS users. iOS takes an interesting approach to rendering select elements in the multiple state which causes significant usability problems.
It is proposed that WMultiSelectPair be completely rewritten in WComponents v2 to overcome this limitation.
See alternate multi-select components listed below for possible alternatives. WCheckBoxSelect may be a better choice for making selections from a small number of options. If the primary use case is to make one or few (fewer than four) selections from a moderate list or selections which are often contiguous then WMultiSelect is a significantly better option.
All aspects of WMultiSelectPair are operable from a keyboard:
- switching between the "available" and "selected" lists is done using the LEFT and RIGHT arrow keys;
- moving within a list is done using the UP and DOWN arrow keys;
- moving an option to the other list is done using the RETURN key;
- moving from a list to the buttons or from button to button is done using TAB and SHIFT + TAB as they are in standard focus order.
All WMultiSelectPair in a UI must be associated with a label. This may be done using:
- WLabel (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 WMultiSelectPair.
The WLabel should be added to the UI before the WMultiSelectPair. The best way to add a WMultiSelectPair and its WLabel to a UI is to add it to a WFieldLayout.
A WMultiSelectPair which is not appropriately labelled may display an unlabelled control warning.
The two option lists are labelled using the fromListName and toListName properties. If these are set they must have a value which adequately describes the purpose of the list.
WMultiSelectPair outputs a HTML fieldset element. The select elements are then placed inside this fieldset. The selection tools consist of two internally labelled selection lists, a set of buttons for moving options from one list to the other and an optional set of buttons for adjusting the order of selected options. The WLabel (or content of the toolTip property) for a WMultiSelectPair is output as the fieldset's legend element.
WMultiSelectPair outputs non-phrasing content and form-related interactive content and must not be used in any context which forbids these content categories.
The following are the properties of WMultiSelectPair which are available for manipulation within an application and which have a UI or interaction consequence.
This property specifies the number of rows to show in the select. It is an optional property with no default value. If this property is not set then WMultiSelectPair's height will be determined by the theme and is commonly large enough to roughly equal the height of the selection buttons. The minimum setting for this property is 2 which is determined to remove usability problems which occur if only one row is specified.
These are each a string which is used to label the list of selectable and selected options. If not specified the default values are "Available" and "Selected".
This Boolean property is used to turn on the ability to allow the user to set the order of options in the selected list.
A WMultiSelectPair may be disabled on page load. When disabled the WMultiSelectPair 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 hidden property
A WMultiSelectPair may be hidden on page load. When hidden the WMultiSelectPair 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 WMultiSelectPair is hidden a WLabel associated with it is also hidden.
This property marks a WMultiSelectPair as being a mandatory field in the UI. The WLabel for the component is also decorated with a visual indicator that the component is mandatory. The implication of this is that at least one option must be added to the selected list.
The readOnly property changes the output rendering of the WMultiSelectPair so that it appears as a appears as text output of the selected options 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 WMultiSelectPair in a readOnly state 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 readOnly setting.
This property is an integer and is used to set a minimum number of options which should be selected if any selection is made. It should not be specified as 1; if the component must have a selection then the required property 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.
Setting a min will not automatically make the component mandatory. The min is validated only if the user has made any selection. To make a component mandatory use the required property. These properties may be used in conjunction to enforce a required minimum selection by the user.
This property is an integer and is used to set a maximum number of options which may be selected. Whilst undertaking selection the user may select more than max so long as no more than max is selected at the time of form submission. This allows a user to, for example, use the "Add All" button to select all options then deselect those which are not required. This makes selection quicker if more than half of the available options are to be selected.
If this property is set then an indication of the maximum number of allowed selections should be given to the user within the associated WLabel.