WSelectToggle
WSelectToggle is a component which creates a tool for selecting all or none of a set of WCheckBox and/or WCheckBoxSelect components.
- Why use WSelectToggle
- Creating WSelectToggle
- Accessibility
- Display modes
- Disabling
- HTML output
- Related components
- Further information
If a UI involves a coherent group of check boxes (either individual WCheckBox components or as a WCheckBoxSelect) and it is reasonable for a user to select or deselect all of the check boxes within a specified part of the UI then it is appropriate to provide a WSelectToggle to allow them to do this.
WSelectToggle's appearance is determined by the display mode.
-
A WSelectToggle in text-like display mode (no selection)
-
A WSelectToggle in check-box-like display mode (no selection)
WSelectToggle is not appropriate if the target contains only a single (interactive) checkbox (either a single WCheckBox or a WCheckBoxSelect with one option) or if the target does not contain any toggleable components.
If the overwhelmingly most common use-case is for the user to select a very small number (maybe around 0-3) checkboxes from a rather large group; or commonly select several to many (with a reasonably large proportion left in the other state) of the available options then it may not be appropriate to use a WSelectToggle as in this case it may be less effort to select the individual options.
If the use case requires a user to make explicit selection of options in an attempt to "enforce" a business rule then WSelectToggle should not be used.
WSelectToggle has two constructors: the default constructor and one which accepts a WComponent argument. WSelectToggle toggles the state of WCheckBox, WCheckBoxSelect or multi-selectable rows in a WTable (under review) but the target WComponent may be any identifiable container component (such as a WPanel) which contains some or all of these.
// default constructor
WSelectToggle toggle = new WSelectToggle();
// accept a target component
WFieldSet selectableFieldSet = new WFieldSet("Select some...");
WSelectToggle panelToggle = new WSelectToggle(selectableFieldSet);
// the individual selectable components can be added to the
// WFieldSet at any time.If the WComponent target does not contain any items which can have their selected state changed by WSelectToggle the WSelectToggle will still be in the UI but it will be useless. So don't do this!
// WMultiSelectPair is not affected by WSelectToggle (yet)
WMultiSelectPair target = new WMultiSelectPair();
// This will not do anything but look "pretty"
WSelectToggle toggle = new WSelectToggle(target);More subtly, if the target WComponent does not have an id then WSelectToggle will not be able to target it even if it contains toggleable components. Therefore WContainer cannot be used as the WSelectToggle target WComponent.
WSelectToggle acts on any of the following when they are in an interactive state:
- WCheckBox;
- WCheckBoxSelect; and/or
- rows of a WTable which has multiple row selection (though this is under review as WTable has its own in-built equivalent control).
WSelectToggle has a WComponent target. It is expected that this target will, at the very least, be or include a toggleable component and the target should include more than one individual interactive checkbox (or row). If the WSelectToggle does not target a toggleable component nor contains one or more toggleable component then the WSelectToggle is still outputinto the UI but is useless.
If the WSelectToggle targets a component which is or contains exactly one interactive checkbox (or row) then it is almost useless: the same effect is obtained by the user simply toggling the control directly.
Perhaps the most useful target WComponent is a WCheckBoxSelect.
// given WCheckBoxSelect cbSelect and
// WSelectToggle toggle
toggle.setTarget(cbSelect);The target could be an identifiable container component such as WFieldSet, WSection or WPanel.
// given WPanel panel and
// WSelectToggle toggle
toggle.setTarget(panel);If the target is not a toggleable component and does not contain any interactive toggleable components then the WSelectToggle will simply do nothing. WSelectToggle must have a target with an id to be able to work therefore one cannot set a WContainer as the target even if it contains toggleable controls.
// given WContainer container and WSelectToggle toggle
// this will result in a WSelectToggle which does not work
toggle.setTarget(container);WSelectToggle is output as either a single button element with role="checkbox" or a pair of buttons with role="radio" (based on display mode). In both cases the buttons are also marked as controlling the target component(s). Even with this, though, the purpose of the control may not be obvious, therefore the WSelectToggle may be labelled.
WSelectToggle should be labelled but this is not mandatory. The default state of an unlabelled WSelectToggle is arguably accessible (certainly if in [text-like display mode][display-mode]) but this can be improved by associating the WSelectToggle with a WLabel. This can be done directly or through using the WSelectToggle as the input control in a WField.
// with WSelectToggle toggle
WLabel selectAllNoneLabel = new WLabel("I WANT IT ALL", toggle);
// OR
// if we already have a WLabel `label`
label.setForComponent(toggle);
//OR
// Using WFieldLayout.addField with WFieldLayout layout
layout.addField("Everything please", toggle);This association can certainly improve usability since whilst when in [text-like display mode][display-mode] it may be a little more clear to users what these controls do; when in [check-box-like display mode][display-mode] a WSelectToggle without a Wlabel is simply a control which looks like an unlabelled check box.
The effect of associating a WSelectToggle with a WLabel is as follows:
- when in [text-like display mode][display-mode] the WLabel is placed within the WSelectToggle replacing the word "Select" (or equivalent).
- when in [check-box-like display mode][display-mode] the WLabel is placed immediately after the WSelectToggle as for a check box.
When a WSelectToggle has a [check-box-like display mode][display-mode] it may be appropriate to use the toolTip or accessibleText instead of being associated with a WLabel, though these may result in other accessibility issues.
In general a WSelectToggle should be placed immediately before or above the controlled component/container. At the very least it is strongly recommended that the WSelectToggle should be in the UI in visual order before or above the controlled component and should be associated with the controlled component by context. The aria-controls attribute set on the interactive control(s) output from WSelectToggle is not available to users not reliant on specific AT.
When a WLabel is associated with a WSelectToggle is does not matter where the WLabel is placed in the UI except that caution must be used when using WPanel Layouts as the WLabel may leave an empty container. See WComponents without UI artefacts for more information.
A WLabel for a WSelectToggle may be given an access key to provide rapid keyboard access.
WSelectToggle may appear as a single tri-state check-box-like control or a pair of text-like controls. The default appearance is as a tri-state check-box. To leverage the text-like appearance one would use setRenderAsText(true).
// to set display mode to text-like
mySelectToggle.setRenderAsText(true);
// to revert to check-box-like:
mySelectToggle.setRenderAsText(false);-
A WSelectToggle in 'text-like' display mode with no selected controlled components
-
A WSelectToggle in 'text-like' display mode with some selected controlled components
-
A WSelectToggle in 'text-like' display mode with all selected controlled components
-
A WSelectToggle in 'check-box-like' display mode with no selected controlled components
-
A WSelectToggle in 'check-box-like' display mode with some selected controlled components
-
A WSelectToggle in 'check-box-like' display mode with all selected controlled components
A WSelectToggle may be disabled on page load. When disabled the WSelectToggle 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 output of WSelectToggle depends upon the value of its display mode. When this is 'text-like' the WSelectToggle outputs a span element wrapper containing a span element with the term "Select" (or the content of an associated WLabel) and two button elements; otherwise the output is a single button element. In both cases the output includes interactive, form bound control(s) and therefore may not be used in any context where the content model forbids this content category.