-
Notifications
You must be signed in to change notification settings - Fork 17
WComponents accessibleText property
The accessibleText property is an optional piece of text which can be used to provide an 'accessible' label which is not visible in the UI. This is done using the aria-label attribute.
Some form control components may be able to use a accessibleText instead of a label if it is impossible to place a WLabel into the UI. If this is the case it will be noted in the documentation for each individual WComponent.
Use of accessibleText is controversial as it may be seen to discriminate against some users. The accessibleText property is output as the aria-label attribute on the input control. This attribute is not exposed to many users and is not fully supported by assistive technologies. If the accessibleText property is used the purpose of the control must be apparent to users without access to this attribute.
In some circumstances it may be more appropriate to use the toolTip property (see H65: Using the title attribute to identify form controls when the label element cannot be used) and it is almost always better to label a form control with a WLabel.
As a general rule of thumb the accessibleText property should not contain information vital to the understanding of the function or use of a control. It should, rather, be used to provide additional context to users who may have trouble determining all aspects of the function by sight.
Accessible text may only be a simple (internationalisable) string with no mark up or extended character entities (such as "). It is used to set an attribute on a HTML element and should comply with the restrictions thereof.
// usually internationalised rather than hard coded...
private static final String LABEL_TEXT =
"Enter your given name as it appears on your birth certificate."
// ...
// later ...
WTextField givenNameField = new WTextField();
// The accessibleText property can give context to the field.
givenNameField.setAccessibleText(LABEL_TEXT);