WMultiDropdown
WMultiDropdown is a component for creating a multi-select tool from a sequence of single-select dropdowns (using HTML select elements). WMultiDropdown does not support implicit null selection. If a null option is a valid selection then it must be explicitly added to the Selectable Options.
- Why use WMultiDropdown
- Creating a WMultiDropdown
- Accessibility
- Selection constraints
- HTML output
- Disabling
- Hiding
- Read only
- Appearance
- Related components
- Further information
WMultiDropdown exists for backwards compatibility and is not recommended for continued use. It has the following failings:
- it applies a custom interaction paradigm to undertake a task for which there are existing commonly used tools;
- it requires users to undertake several processes to undertake a single multiple-selection task;
- it does not prevent multiple selection of the same option;
- unlike other multi-select tools it does not allow for no selection;
- it occupies a lot of screen space and does not scale well on small viewports.
It is recommended that:
- WMultiSelect is used for multiple selection from a list where the common use case is to select a small number of options or to make selections from a small list;
- WCheckBoxSelect is used for making selections from a small number of options;
- WMultiSelectPair is used for making selections from a list where the expected use case is to select options from a large list.
There are four constructors for WMultiDropdown. The default constructor will create a WMultiDropdown with no options. A WMultiDropdown may also be created with default options based on a List, Object Array or table Object.
// default constructor - no options
WMultiDropdown field = new WMultiDropdown();
// creating a WMultiDropdown using a named table
field = new WMultiDropdown(TABLE_NAME);The performance of WMultiDropdown (or other list-based selection components such as WMultiSelect and WMultiSelectPair) which share a common list of selectable options can be significantly improved by specifying that the options be supplied using a caching data list.
WMultiDropdown 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 WMultiDropdown 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 WMultiDropdown has visible text ad an optional programatic value. The visible text 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 WMultiDropdown will use the browser's native select element which should be the optimum tool for this type of selection for all common assistive technologies. Adding and removing dropdowns is undertaken using focusable buttons.
When a WMultiDropdown's selection element 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 WMultiDropdowns 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 WMultiDropdown.
When designing a UI containing a WMultiDropdown the WLabel must be placed immediately before or above the control.
// If WFieldLayout is not used then the label must precede the control
WMultiDropdown field = new WMultiDropdown();
WLabel selectLabel = new WLabel("Select something", field);
// ...
add(selectLabel);
add(field);A WMultiDropdown which is not appropriately labelled may display an unlabelled control warning.
A label for a WMultiDropdown is implemented as a HTML legend element immediate child of the WMultiDropdown's fieldset.
If the WMultiDropdown is associated with a WLabel (including by being added to a WField) then the content of the label is also output in-situ as a HTML span element. This span is then marked as aria-hidden="true" to prevent double reading in PC mode but has scripted helpers to ensure it behaves in a manner equivalent to a legend (for access key support) and a label (for mouse users).
Under most circumstances the pseudo-label will be hidden from all users and the legend will be visible. When in a WFieldLayout with LAYOUT_FLAT, however, this is changed and the pseudo-label is made visible and the legend moved out of viewport (not hidden). This keeps the label for a WMultiDropdown consistent with WLabels for simple inputs.
Where a WMultiDropdown has its toolTip property set but is not associated with a WLabel the content of the toolTip is placed in the legend and may be rendered out of viewport.
If the WMultiDropdown 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 WMultiDropdown may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// with WMultiDropdown field
field.setToolTip("Some further context to this selection.");WMultiDropdown 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 WMultiDropdown field
field.setAccessibleText("Some further context to this selection.");A WLabel for a WMultiDropdown may be given an access key to provide rapid keyboard access.
A WMultiDropdown 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. When focussed the first select element in the component will receive focus.
Up to and including WComponents 1.4.x WMultiDropdown supported the notion of SubmitOnChange. This should be avoided as much as possible.
A WMultiDropdown may be constrained to accept a minimum or maximum number of selected options and/or to be mandatory.
A WMultiDropdown 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 WMultiDropdown `field` mandatory
field.setMandatory(true);The minimum number of selected options which constitutes a valid selection may be set on any WMultiDropdown 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 WMultiDropdown `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. 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 WMultiDropdown in an interactive state. If set then an indication of this should be included in the component's WLabel. It is entirely inappropriate to set the maximum selection to 1: for this use case use WDropdown and stop being silly.
// with WMultiDropdown `field`
field.setMaxSelect(3);
// set the label hint...
fieldLabel.setHint("select no more than least three options");WMultiDropdown outputs a HTML fieldset element. The select elements are then placed inside this fieldset. WMultiDropdown outputs non-phrasing content and form-related interactive content and must not be used in any context which forbids these content categories. The WLabel (or content of the toolTip) for a WMultiDropdown is output as the fieldset's legend element.
When in read-only state WMultiDropdown outputs non-phrasing content.
A WMultiDropdown may be disabled on page load. When disabled the WMultiDropdown will not respond to user input or interaction and all dropdowns will be disabled. This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call.
A WMultiDropdown may be hidden on page load. When hidden the WMultiDropdown 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 WMultiDropdown is hidden a WLabel associated with it is also hidden.
The read-only state changes the output rendering of the WMultiDropdown so that it appears as a text representation 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. Only those options which are selected according to the last submitted state of the control are output.
A WMultiDropdown in a read-only 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 read-only setting.
WMultiDropdown looks like a normal select element followed by a button to add another option. When more than one option is selected the appearance is a vertical list of select elements and all but the first are followed by a button to remove the selection.
WMultiDropdown may have one or more values to be added to the component's wrapper element. This can be used for fine-grain styling of specific components but should be used with care and is not recommended for any input control.
For more information see WComponents HTML class property.