Skip to content

WCheckBox

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 41 revisions

WCheckBox is a component used to make a checkbox form control. A CheckBox is a binary selection control which is able to be both selected and deselected by the user independent of any other control in the view.

Creating a WCheckBox

WCheckBox is a simple input control and is created by calling one of its constructors. The default constructor creates an unselected checkbox control.

// A simple checkbox
WCheckBox cb = new WCheckBox();
// ...
// add the checkbox to the UI using WFieldLayout 'layout'
layout.addField("I agree", cb);

// A check box which is initially selected
WCheckBox cbSelected = new WCheckBox(true);
// ...
// add this check box to your UI using WFieldLayout 'layout'
layout.addField("Send me spam", cbSelected);

Accessibility

Labeling a WCheckBox

All WCheckBoxes 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 WCheckBox 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 WCheckBox.

When designing a UI containing a WCheckBox the WLabel must be placed immediately after the checkbox:

A selected check box with its label

A WCheckBox which is not appropriately labelled may display an unlabelled control warning.

Setting a toolTip

See toolTip. A WCheckBox may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.

// with WCheckBox cb
cb.setToolTip("Some further context to this selection.");

Additional labelling text

WCheckBox 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 WCheckBox cb
cb.setAccessibleText("Some further context to this selection.");

Access Keys

A WLabel for a WCheckBox may be given an access key to provide rapid keyboard access.

Default focus

A WCheckBox 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.

// given WCheckBox cb
// set as default focus point
cb.setFocussed();

HTML output

A WCheckBox will output a HTML input element in the checkbox state wrapped in a HTML span element.

A check box with its label

When a WCheckBox is in a read-only state the output is a span element decorated to indicate the selected state of the control and with appropriate exposure of the state to assistive technologies.

WCheckBoxes in the read-only state

Read-only

WCheckBox appears as a graphical representation of the control when in a read-only state. This representation will be of the state set when last updated. The control is not able to be interacted with by the user and does not return any value back to the application.

A WCheckBox 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.

WCheckBoxes in the read-only state

Mandatory selection

A WCheckBox may be a mandatory field in the UI, though this is considered harmful: a mandatory single checkbox is not a selection at all, merely a confirmation and almost all confirmations are pointless. The WLabel for the component is decorated with a visual indicator that the component is mandatory. The primary UI indicator of a mandatory input is the required attribute on the HTML input element.

WCheckBoxes in the mandatory state

If a WCheckBox is marked as mandatory then its only valid state which will allow completion of a form submission is that it is checked. If a WCheckBox is added to a component group then it should not be individually marked as required unless it is always required: not if any one checkbox in the group is required. WCheckBoxSelect allows a group of check boxes to be marked as required in a way which conforms with WCAG 2.0, WCheckBox does not.

To indicate that at least one of a group of WCheckBox components is required all of the WCheckBoxes must be placed into a single WFieldSet. The WFieldSet may then be set as mandatory. This indicates that at least one control within that WFieldSet must be complete.

Selected state

The selected state of a WCheckBox may be set programatically. This state is most usually set based on the state of the control in the underlying data system and should only be specified if the initial state of a WCheckBox is to be selected when presented to a new user for the first time. This must, therefore, be explicitly specified.

A selected check box with its label

// Creating a WCheckBox selected by default:
WCheckBox cbSelected = new WCheckBox(true);

// Setting the selected state of an existing WCheckBox 'cb':
cb.setSelected(true);
// Unsetting the selected state of existing WCheckBox 'cb':
cb.setSelected(false);

The selected state of a WCheckBox may be interrogated to undertake conditional actions.

// given WCheckBox 'cb'
if (cb.isSelected()) {
  // do stuff
}

Change action

A WCheckBox may be used to trigger an Action which runs if the field's selected state changes.

// with WCheckBox `field`
field.setActionOnChange(new Action() {
  @Override
  public void execute(final ActionEvent event) {
    // do something
  }
});

Grouping WCheckBoxes

A WCheckBox may be placed into a group. A Group of WCheckBoxes is a multi-selection (0...n of n options) tool which supports implicit null selection. Check boxes would be grouped because:

  1. The check boxes form a set of non-mutually-exclusive responses to a given "question"; and (optionally)
  2. The check boxes may be controlled by another component to select and deselect all of them in a single action in which case they should be added to a WComponentGroup.

If a set of check boxes are grouped then the appropriate grouping mechanisms are:

  1. a fieldset; or
  2. a headed row or column of a table; or
  3. as the only content following a heading.

A logical group of check boxes should be grouped even if they are not the target of a WSelectToggle. In most cases a logical group of check boxes is best implemented through WCheckBoxSelect.

To add a WCheckBox to a group for targeting by a WSelectToggle:

// a WComponentGroup
WComponentGroup<WCheckBox> group = new WComponentGroup<>();
// WCheckBox cb
cb.setGroup(group);
// ... add more WCheckBoxes to the group

// WSelectToggle to target group
WSelectToggle toggle = new WSelectToggle(group);

When to use a group of WCheckBoxes

Logical groups of check boxes should be usually implemented using a WCheckBoxSelect which is a significantly lighter component for this purpose. The following circumstances are when a WCheckBoxSelect is not appropriate:

  • The check boxes are not visually grouped within a single section of the UI which can contain a HTML fieldset element. For example if the check boxes occupy a column of a WTable or are dispersed in the UI (though this last case is problematic for usability and accessibility).
  • The labels of the check boxes contain content other than plain text. In this case each WCheckBox will have to be associated with a WLabel as WCheckBoxSelect allows for only plain text labels of each option.

If a group of WCheckBoxes must be used then they must be grouped in the UI as described above.

Disabling

A WCheckBox may be disabled on page load. When disabled the WCheckBox will not respond to user input or interaction. This property may be used in conjunction with WSubordinateControl to enable or disable content without making another server call. In this case the state is managed by the WSubordinateControl and does not have to be set explicitly. The disabled state is ignored if the WCheckBox is in a read-only state.

WCheckBox in the disabled state

UI designer note

A disabled check box has no rational checked state: a checked, disabled check box is the same as an unchecked disabled check box and both are considered unchecked.

Hiding

A WCheckBox may be hidden on page load. When hidden the WCheckBox 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 WCheckBox is hidden a WLabel associated with it is also hidden.

Default submit button

A WCheckBox may be associated with a WButton in a way that if the user hits the ENTER key whilst the WCheckBox 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 WCheckBox cb and WButton button
// set as button as the default submit button
cb.setDefaultSubmitButton(button);

This setting is not used if the WCheckBox is in a read-only state or is a trigger for a WAjaxControl.

Testing

Prior to WComponents v1.4 WCheckBox could be tested as a regular HTML element using a simple org.openqa.selenium.WebElement or a SeleniumWComponentWebElement. From v1.4 it is recommended that WCheckBox be tested using the com.github.bordertech.wcomponents.test.selenium.element.SeleniumWCheckBoxWebElement extension of WebElement.

The best way to get a WCheckBox from a test view is by using SeleniumWComponentsWebDriver which has a method findWCheckBox(By). This can be used in conjunction with com.github.bordertech.wcomponents.test.selenium.ByLabel, for example, to find a WCheckBox using its label's text.

@Test
public void testFindByLabel() {
  SeleniumWComponentsWebDriver driver = getDriver();
  String labelText = "Pick me!";
  SeleniumWCheckBoxWebElement checkBox =
    driver.findWCheckBox(new ByLabel(labelText, false));
  Assert.assertNotNull("Unable to find checkbox by label text", checkBox);
}

The SeleniumWCheckBoxWebElement extension provides:

Related Selenium components

Custom design and behaviour

WCheckBox's limited palate of appearance options are designed to ensure a high degree of consistency, accessibility and usability. The design and even behaviour of a WCheckBox 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.

// given WCheckBox cb
// to set class attribute values on the HTML output
cb.setHtmlClass("myMagicClass anotherMagicClass");

Related components

Further information

Some start pages

Clone this wiki locally