WButton accessibility
This page discusses some methods which may be used to ensure a WButton is most likely accessible. It is not exhaustive but covers many of the most common issues.
The easiest and best way to ensure a button is accessible is to give it visible String text and button rendering. This is the default for WButton. If an application requires buttons containing only iconography or images then it is the responsibility of both designers and developers to ensure these buttons are accessible.
WButton may appear to contain only an image. This is usually done by adding an image to the WButton but not using setImagePosition to describe the positional relationship between the image and the text content.
When this is done the WButton must still contain some "alternate" text: the text equivalent of the image which describes the purpose of the button.
The following methods describe a way to make an accessible button which contains only an image such as: 
. In general only one of these should ever be employed. It would not be appropriate to set both accessibleText and toolTip (for example) and certainly not to the same text.
Using hidden text
The easiest and best way to ensure the WButton contains an accesssible text equivalent is to instantiate the WButton with a string as if it was not going to have an image. The following code snippet show an example of this.
WButton button = new WButton("Mark as OK");
button.setImage("/image/tick.png");In this case the rendered button will have appropriate and accessible text equivalence for the image which is available to the largest group of users (other than by making the text visible).
The HTML title attribute of the button may be used to provide the text equivalent and retain WCAG 2.0 compliance. This may be sub-optimal for some combinations of browser and assistive technology but is generally supported. The advantage of this method is that the text is exposed to mouse users on hover as well as to users reliant on certain AT. This is done using the setToolTip method.
WButton button = new WButton();
button.setImage("/image/tick.png");
button.setToolTip("Mark as OK");NOTE that a WButton with text content (even if it is not visible) should not usually have a toolTip and the toolTip should never repeat the text content, either directly or in essence.
// NEVER do this:
WButton button = new WButton("Mark OK");
button.setImage("/image/tick.png");
button.setToolTip("Mark as OK");Using setAccessibleText(String) the transformed button element will have an aria-label attribute. This is technically WCAG compliant but is not universally supported; see WComponents accessibleText property. This may be better than using setToolTip for some use cases and support for aria-label is improving. It does not provide a "tooltip" to mouse users so some context may be lost by using this method.
WButton button = new WButton();
button.setImage("/image/tick.png");
button.setAccessibleText("Mark as OK");NOTE that as with toolTip above a WButton with text content (even if it is not visible) should not usually have its accessibleText property set and the aria-label should never repeat the text content, either directly or in essence.
// NEVER do this:
WButton button = new WButton("Mark OK");
button.setImage("/image/tick.png");
button.setAccessibleText("Mark as OK");The image on a WButton may be set using a WImage rather than a string reference to a resource. In this case the WImage should have a description which describes the purpose of the button rather than the appearance of the image. The only reason one would do this is to use a specific WImage (separately) in different contexts or have it instantiated in a separate class and then accessed by the WButton. The need to describe the WImage based on its final intent rather than based on its image content makes this potentially problematic.
WButton button = new WButton();
WImage buttonImage = new WImage("/image/tick.png", "Mark as OK");
// note that the following would not be acceptable for the intended use
// WImage buttonImage = new WImage("/image/tick.png", "tick mark");
button.setImage(buttonImage.getImage());WButton is able to use theme icons (instead of an image, though they are not mutually exclusive). By default these are the icons from the Font Awesome icon library. This is a little more involved than using an image but has several benefits:
- less traffic over the wire - no need to load an image;
- icons will always fit in your button - no need to worry about dimensions;
- icons can reflect the disabled state and actions of WSubordinateControl to change this state in the client;
- icons will be consistent with your theme.
To add a Font Awesome icon to a WButton one has to set HTML class attribute values. A utility enum HtmlClassProperties has been created which includes several commonly requested icons in forms which may be applied as stand-alone content, before text content or after text content. There are also helper methods for applying custom icons provided in HtmlIconUtil.
If the WButton is to display only an icon then some more work has to be done to ensure the button is valid in the Java API (i.e. has text content or an image) and accessible. An example is shown below.
// A Wbutton with a Font Awesome question mark 'help' icon before the word "Help"
WButton helpButton = new WButton("Help");
// Use HtmlClassProperties to add a help icon
iconHelpButton.setHtmlClass(HtmlClassProperties.ICON_HELP_BEFORE);
// A WButton containing only an icon and no visible text.
WButton iconHelpButton = new WButton();
// To have an accessible button we need to setToolTip or setAccessibleText
iconHelpButton.setToolTip("help");
// add the class attribute values
iconHelpButton.setHtmlClass(HtmlClassProperties.ICON_HELP);
// A WButton with the icon to the right of the text
WButton helpButtonIconAfter = new WButton("Help");
iconHelpButton.setHtmlClass(HtmlClassProperties.ICON_HELP_AFTER);The screenshot below shows three buttons each with a (different) icon.
It may seem redundant to have class name wc-icon when Font Awesome has its own mechanism using class name fa. Using fa on a WButton (or WLink) will apply the Font Awesome font metrics to the whole button. This means that if your button contains visible text as well as the icon the text will be visually different from other button text. Using wc-icon overcomes this by applying the Font Awesome styles only to the before pseudo-element of the button.
If a control opens a new window or other pop-up mechanism (such as a WDialog) this must be made known to the user. This is done using the attribute aria-haspopup with the value true.
If a WButton's Action will open a WPopup on the next page load or within the content of an Ajax action then the existence of this pop-up is not apparent to the client code and therefore WButton must be flagged as opening a popup. This is done using setPopupTrigger(true).
// button to open help window:
WButton button = new WButton("Help");
button.setAction(new Action() {
@Override
public void execute(final ActionEvent event) {
// Do something which opens a WPopup...
}
});
button.setPopupTrigger(true);A button which is an immediate trigger to open a WDialog (rather than a WPopup - we find they are often confused) will have the aria-haspopup='true' attribute set and does not need to use setPopupTrigger(true).