WRadioButtonSelect
WRadioButtonSelect is a component for creating a set of related radio buttons based on a list of options. The radio buttons then form a single selection component. The individual radio buttons in the set are generated from options. WRadioButtonSelect does not allow for implicit null selection.
- Why use WRadioButtonSelect
- Creating a WRadioButtonSelect
- Accessibility
- Appearance
- Mandatory selection
- Read-only
- HTML output
- Disabling
- Hiding
- Default submit button
- Testing
- Related components
- Further information
WRadioButtonSelect is most useful for choosing 1 of n options where n is quite small (a rough rule of thumb would be below 10 but this may be increased if using a columnar layout).
WRadioButtonSelect is not optimal for scenarios where the number of choices is large. In this case it may be better to use WSingleSelect or WDropdown. WRadioButtonSelect does not allow the options to be sub-divided into groups. If this is required then WSingleSelect, WDropdown or WTree should be used.
WRadioButtonSelect is the preferred tool for creating a single coherent set of radio button controls. The output of a WRadioButtonSelect will always form a single block in the UI. In addition the options used to create the individual radio buttons and their labels are limited to string values.
These two restrictions mean that sometimes it is necessary to use a group of WRadioButton components instead of a WRadioButtonSelect. Some situations where you may need to do this are:
- the radio buttons are dispersed in the UI note, however, that this will cause usability and accessibility issues which need to be carefully managed;
- individual radio buttons in the group need to be hidden or disabled;
- the label for one or more radio buttons must contain other than text content, such as an image or an abbreviation.
WRadioButtonSelect may be instantiated using an Object Array, a table Object or a List. After instantiation the options may be added as a List or Object Array.
// a WRadioButtonSelect with no options
WRadioButtonSelect rbSelect = new WRadioButtonSelect();
// given a list<?> options
rbSelect = new WRadioButtonSelect(options);
// or given an Object[] optionArray
rbSelect = new WRadioButtonSelect(optionArray);
// or using a lookupTable table
rbSelect = new WRadioButtonSelect(table);The output of the WRadioButtonSelect limits each option to a simple String which is XML escaped. The options are used to report what values were selected by the user and to produce the label for each individual radio button. The options may not contain markup. If your UI has a requirement for labels which contain HTML markup (for example to add an image) then a group of WRadioButton components should be used wrapped in a WFieldSet (see compared with RadioButtonGroup).
Each option in a WRadioButtonSelect must be a string which indicates the option being selected to the user. This means the options' values must be understandable such as "apple", "banana", "cumquat" rather than representational of application data such as 0, 1, 2.
The WRadioButtonSelect, if not read-only, must itself be labelled. This represents the "question" to which the options represent possible "answers". This may be done using:
- WLabel or by using the WRadioButtonSelect 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.
If the WRadioButtonSelect has a visible label and is not in a WField then the WLabel should be added to the UI immediately before or above the WRadioButtonSelect.
A WRadioButtonSelect which is not appropriately labelled may display an unlabelled control warning.
WRadioButtonSelect rbSelect = new WRadioButtonSelect();
WLabel rbSelectLabel = new WLabel("Select something", rbSelect);
// ...
add(rbSelectLabel);
add(rbSelect);A label for a WRadioButtonSelect is implemented as a legend element immediate child of the WRadioButtonSelect's fieldset. This legend is always rendered out of viewport. If the WRadioButtonSelect 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 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).
This arrangement allows the use of semantically correct and specification compliant grouping using a fieldset as well as design and usability consistency for complex UIs where a compound control such as a WRadioButtonSelect is arranged in a layout which also includes simple form controls and their labels.
Where a WRadioButtonSelect has its toolTip property set but is not associated with a WLabel the content of the toolTip is placed in the legend and rendered out of viewport.
The interaction model for a set of radio buttons makes it extremely problematic to specify a WRadioButtonSelect with no default selection. Please consult the documentation on implicit null selection for the conditions which a WRadioButtonSelect must comply with before it may be specified to have no default selection.
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. This is strongly discouraged for complex multi-input components like WRadioButtonSelect and should probably be avoided.
rbSelect.setToolTip("Some further context to this selection.");WRadioButtonSelect may have accessible text applied as information additional to the visible legend/pseudo-label text. This should be used with care and restraint as it may result in less accessible applications.
rbSelect.setAccessibleText("Some further context to this selection.");A WLabel for a WRadioButtonSelect may be given an access key to provide rapid keyboard access.
A WRadioButtonSelect 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. When the component is set as focussed the first available radio button will be focussed or the selected radio button if a selection is made. See Setting focus for more information.
// given WRadioButtonSelect rbSelect
// set as default focus point
rbSelect.setFocussed();WRadioButtonSelect will render a group of radio buttons and their labels. The actual appearance of the radio buttons is platform and (to a less extent) browser dependent. The arrangement of checkboxes is determined by then layout. The group of checkboxes are wrapped in a fieldset element; the fieldset border can be turned on and off.
The illustration below shows a typical output on OS X.
The radio buttons (and their label) may be laid out in several ways using a WRadioButtonSelect.Layout property. There are three options:
-
WRadioButtonSelect.Layout.FLATin which the options are laid out horizontally
-
WRadioButtonSelect.Layout.STACKEDin which the options are laid out vertically -
WRadioButtonSelect.Layout.COLUMNin which the options are laid out in one or more columns according to the layoutColumnCount property.
This property is required and will default to WRadioButtonSelect.Layout.STACKED. The property is set using the Java method setButtonLayout(WRadioButtonSelect.Layout).
WRadioButtonSelect rbSelect = new WRadioButtonSelect();
// to set Layout.FLAT
rbSelect.setButtonLayout(WRadioButtonSelect.Layout.FLAT);If layout is WRadioButtonSelect.Layout.COLUMN then the number of columns may be specified. The number of options in each column is the ceiling of the number of options divided by the number of columns. If the number of options is not a multiple of the number of columns then the last column will have fewer options than the other columns. If this is not set then all of the options are placed into a single column equivalent to WRadioButtonSelect.Layout.STACKED.
// To set a layot using three columns:
WRadioButtonSelect rbSelect = new WRadioButtonSelect();
rbSelect.setButtonLayout(WRadioButtonSelect.Layout.COLUMN);
rbSelect.setButtonColumns(3);The output when the column count is set to three will be something like:
WRadioButtonSelect (when not in a read-only state) is wrapped in a HTML fieldset element. This element may have a border or other default styling (dependent on your theme). This border/default styling may then be enabled or disabled using the setFrameless(boolean) method.
WRadioButtonSelect rbSelect = new WRadioButtonSelect();
// to set frameless
rbSelect.setFrameless(true);-
A WRadioButtonSelect with a frame
-
A frameless WRadioButtonSelect
Default responsive design for WRadioButtonSelect applies if the layout is WRadioButtonSelect.Layout.COLUMN. When viewed on a narrow viewport the column count is ignored and all radio button/label pairs are displayed in a single column. See Responsive Design for more information.
WRadioButtonSelect's limited palate of appearance options are designed to ensure a high degree of consistency, accessibility and usability. The design and even behaviour of WRadioButtonSelect may be amended on an instance-by instance or application-by-application basis using custom CSS and/or custom JavaScipt. This display/behaviour is then attached to a class-name added using the htmlClass property. For more information see WComponents HTML class property.
WRadioButtonSelect rbSelect = new WRadioButtonSelect();
// to set class attribute values on the HTML output
rbSelect.setHtmlClass("myMagicClass anotherMagicClass");A WRadioButtonSelect may be set as a mandatory field in the UI. The WLabel for the component is also decorated with a visual indicator that the component is mandatory. When a WRadioButtonSelect is marked as mandatory all individual radio buttons are marked as mandatory. All current, conforming user agents will ensure that if any selected radio button in a set is selected then the required state is met. Mandatory indicates that exactly one option from the set must be selected.
// given WRadioButtonSelect rbSelect ...
rbSelect.setMandatory(true);WRadioButtonSelect appears as a text representation of the control when in a read-only state. The control is not able to be interacted with by the user and does not return any value back to the application. Only the selected option, according to the last submitted state of the control, is output in the read-only state.
A WRadioButtonSelect 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 readOnly setting.
In the following illustration the first WRadioButtonSelect has no selection and the second has a selection. Both are in the read-only state.
WRadioButtonSelect is a compound form control, therefore it outputs a fieldset element. The arrangement of the radio buttons within the fieldset is determined by the layout property and (optionally) the layoutColumnCount property.
WRadioButtonSelect outputs non-phrasing content and form-related interactive content and must not be used in any context which forbids these content categories.
When in read-only mode the WRadioButtonSelect will output a HTML span element containing the selected option's label output. Unlike WRadioButton no graphic marker is used to indicate the selected state of read-only option. This is because only the selected option is output and the label for each radio button is inextricably linked with the radio button and cannot appear without its label string.
A WRadioButtonSelect may be disabled on page load. When disabled the WRadioButtonSelect will not respond to user input or interaction and all radio buttons will be disabled.
This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call. When a WRadioButtonSelect is enabled all of its radio buttons are enabled.
A WRadioButtonSelect 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 disabled radio button has no rational checked state: a checked, disabled radio button is the same as an unchecked disabled radio button and both will be considered unchecked.
A WRadioButtonSelect may be hidden on page load. When hidden the WRadioButtonSelect 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 WRadioButtonSelect is hidden a WLabel associated with it is also hidden.
A WRadioButtonSelect may be associated with a WButton in a way that if the user hits the ENTER key whilst any radio button in the WRadioButtonSelect has focus then the nominated WButton will be deemed to be the control which submits the form to the server. This is discussed in more detail in Implicit form submission.
// given WRadioButtonSelect rbSelect and WButton button
// set as button as the default submit button
rbSelect.setDefaultSubmitButton(button);This setting is not used if the WRadioButtonSelect is in a read-only state or is a trigger for a WAjaxControl.
WRadioButtonSelect may be manipulated in Selenium tests using the com.github.bordertech.wcomponents.test.selenium.element.SeleniumWRadioButtonSelectWebElement extension of WebElement.
The best way to get a WRadioButtonSelect from a test view is by using SeleniumWComponentsWebDriver which has a method findWRadioButtonSelect(By). This can be used in conjunction with com.github.bordertech.wcomponents.test.selenium.ByLabel, for example, to find a WRadioButtonSelect using its WLabel's text.
@Test
public void testFindByLabel() {
SeleniumWComponentsWebDriver driver = getDriver();
String labelText = "Select one of these";
SeleniumWRadioButtonSelectWebElement rbSelect =
driver.findWRadioButtonSelect(new ByLabel(labelText, false));
}SeleniumWRadioButtonSelectWebElement extends SeleniumCheckableGroupInputWebElement. Options may be interacted with based on their index, label text or by accessing the option's WebElement obtained from one of the getOption methods. See SeleniumCheckableGroupInputWebElement for information regarding accessing, selecting, clicking and determining the selected state of options.
To access the radio button input for an option within a WRadioButtonSelect one may use ByLabel using the label but it may be more efficient to get the radio button using its index using WebElement getRadioButton(final int idx).
// With WRadioButtonSelect rbSelect (see above to get)
// to get the 'nth' option's radio button (int n)
WebElement realRadioButton = rbSelect.getRadioButton(n);
}