WShuffler
WShuffler is a component designed to provide a mechanism for a user to set the order of a list of options. Its use is limited but is used, for example, to set the preferred order of columns in a user-configurable WTable.
- Why use WShuffler
- Accessibility
- Height
- Disabling
- Hiding
- HTML output
- Read-only
- Related components
- Further information
WShuffler should be used when a fixed set of options may have a user-determined order. This may be, for example, to set the order of appearance of columns in a WTable.
If the use case allows for the options to be deselected as well as re-ordered then WMultiSelectPair should be used with its shuffle property set.
WShuffler is a compound control consisting of a multi-selectable select element and a set of buttons used to move the options within the select.
One should note that WShuffler works but is not really usable on iOS due to the stupid implementation of multi-row select elements. This is not really under review as WShuffler is not often used.
All WShufflers 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 WShuffler in a WFieldLayout (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 WShuffler and a visible label the WLabel must be placed immediately before the WShuffler. This is done automatically by WField.
A WShuffler which is not appropriately labelled may display an unlabelled control warning.
See toolTip. This property may be used to create an accessible label equivalent for the component if the application design precludes the presentation of a visible label.
A WLabel for a WShuffler may be given an access key to provide rapid keyboard access.
The height of the shuffler may be set using an integer which translates as the height of the select element in ems. It is an optional property with no default value. If this property is not set then WShufflers's height will be determined by the theme and defaults to 8em to be similar to the height of the set of buttons.
The control height is set using setRows(int)
// why one would want this is beyond me.
tallShuffler.setRows(20);
A WShuffler may be disabled on page load. When disabled the WShuffler 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.
shuffler.setDisabled(true);
A WShuffler may be hidden on page load. When hidden the WShuffler 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 WShuffler is hidden a WLabel associated with it is also hidden.
WShuffler outputs a fieldset element containing a select element and a group of button elements. It outputs non-phrasing content] and interactive form-bound controls and therefore must not be placed in any context which forbids these content categories.
When in a read-only state the WShuffler outputs a ol element with a li element for each option.
When readOnly the output rendering of the WShuffler changes so that it appears as a appears as text output of the list of options available to 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 WShuffler 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.
shuffler.setReadOnly(true);