WDropdown
WDropdown is a component used to make a space-limited (usually single line) single-select component. WDropdown does not support implicit null selection. To provide for a null selection to be returned from WDropdown an application must provide an explicit null option.
WDropdown may be used to create combo-boxes but this is better implemented using WTextField with WSuggestions.
- Why use WDropdown
- Creating WDropdown
- Selection constraints
- Accessibility
- Read only
- Appearance
- COMBO form
- Disabling
- Hiding
- Related components
- Further information
WDropdown allows a user to select exactly one option from a list of (potentially grouped) options. It will always provide a selection even if the user has not interacted with the control. WDropdown 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 a single option from a large list of options. The use and appearance of WDropdown is quite consistent over various platforms, it is reasonably accessible for users who do not use a mouse and it is well implemented on all common mobile OSs (unlike WSingleSelect which is quirky on iOS).
WDropdown always enforces a selection, unlike WSingleSelect. If a WDropdown is optional it may be more appropriate to use a WSingleSelect.
There are four constructors for WDropdown. The default constructor will create a WDropdown with no options. A WDropdown may also be created with default options based on a List, Object Array or table Object.
// default constructor - no options
WDropdown dd = new WDropdown();The performance of WDropdown (or other list-based selection components such as WMultiSelect and WSingleSelect) which share a common list of selectable options can be significantly improved by specifying that the options be supplied using a caching data list.
If the WDropdown has many options (for example a list of countries) then it is usually worth caching the data list as even a single subsequent load will have improved performance.
A WDropdown 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 WDropdown `field` mandatory
field.setMandatory(true);WDropdown does not support implicit null selection therefore it is not practical to determine 'incompleteness'. To overcome this an option may be marked as being a null option which, if selected, is deemed to be the equivalent of no selection being made.
When a null option is specified this is still a valid complete state for the component but will trigger a validation error (including client validation if enabled).
An option of value null will be deemed to be a null option.
When in an interactive mode WDropdown will use the browser's native select unless in the COMBO form.
A custom control set is provided in the COMBO form which is completely keyboard driveable and implemented in accordance with WAI-ARIA guidelines.
When in an interactive mode, and not a COMBO, WDropdown 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 WDropdown has focus, and not in a COMBO form, 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 WDropdowns 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 WDropdown 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 WDropdown.
When designing a UI containing a WDropdown the WLabel must be placed immediately before or above the control.
A WDropdown which is not appropriately labelled may display an unlabelled control warning.
If the WDropdown 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 label.
See toolTip. A WDropdown may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// with WDropdown field
field.setToolTip("Some further context to this selection.");WDropdown 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 WDropdown field
field.setAccessibleText("Some further context to this selection.");A WLabel for a WDropdown may be given an access key to provide rapid keyboard access.
A WDropdown 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 WDropdown supported the notion of SubmitOnChange. This should be avoided.
In a read-only state the output rendering of the WDropdown changes so that it appears as a 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 WDropdown 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.
WDropdown outputs a HTML select element, unless in Combo form, and the appearance is determined by the user agent. The illustrations in this document were all created using Safari on OS X.
-
Editable
-
Editable with
COMBOform:
-
Disabled:
-
Open with many options:
The width of a WDropdown 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.
WDropdown's limited palate of appearance options are designed to ensure a high degree of consistency, accessibility and usability. The design and even behaviour of WDropdown may be amended on an instance-by instance or application-by-application basis.
WDropdown 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.
For more information see WComponents HTML class property.
A WDropdown will occupy a content box with height determined by the user agent but which is usually slightly larger than the content box of a line of text. The baseline and text-top of a line of text in a select element correspond with the baseline and text-top of text content in the same line and block.
The width of a WDropdown in its normal interactive state is determined by the width of the longest option in that WDropdown and the widget set of the user agent displaying the dropdown. In modern browsers this width is limited to the width of the parent container's content box. This is not possible in Internet Explorer before version 9 due to creating significant usability flaws.
This feature is deprecated and WDropdown with Type.COMBO should be replace with WTextField and WSuggestions.
A WDropdown may be disabled on page load. When disabled the WDropdown 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 WDropdown has no selection.
A WDropdown 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.
A WDropdown may be hidden on page load. When hidden the WDropdown 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 WDropdown is hidden a WLabel associated with it is also hidden.