ZK Developer's Reference/Accessibility

Since 9.5.0

• Available for ZK:
• 

Overview

To meet accessibility, it requires semantic information about widgets, structures, and behaviors for assistive technologies. ZK widgets already render semantic information based on their purposes according to WAI-ARIA. Overall speaking, ZK conforms the level of AA (Double-A) of WCAG 2.0.

But as a UI framework, we make widgets be flexible for multiple user scenarios. A widget might play a different role in a different page. It depends on the application developers' design. Therefore, we need the application developer's cooperation to achieve complete accessibility. This chapter tells you what ZK framework has done, and how you can add more application-specific accessibility information.

The za11y (zk-accessibility) module (currently in preview) enables developers to create WCAG 2 compliant applications. Key features include keyboard interaction and screen reader support. An accessibility-ready theme (wcag*) should be used along with the module to deliver sufficient contrast.

Enable Accessibility Support

ZK accessibility module is a separate, optional jar, you have to include it manually to enable it.

		<dependency>
			<groupId>org.zkoss.zk</groupId>
			<artifactId>za11y</artifactId>
			<version>${zk.version}</version>
		</dependency>

To ensure za11y.jar running as expected at run-time, you can simply inspect a textbox. If you see ARIA attributes rendered in the element, that means the module works successfully. Please see Built-in Support

Built-in Support

To know what ZK already renders which ARIA attributes by default, please open the developer tool to inspect a widget.

textbox.zul

<textbox />

Visit the zul page and Inspect the textbox with a browser developer tool, you will see:

<input id="h5AP0" class="z-textbox" type="text" 
       aria-disabled="false" aria-readonly="false">

Specify ARIA Attributes

You can specify arbitrary ARIA attribute on a component with namespace "client/attribute" like:

<zk  xmlns:ca="client/attribute">
    <div ca:aria-hidden="true"/>
    <textbox ca:aria-label="${field}"/>
    <intbox ca:aria-labelledby="${price}"/>
</zk>

Label with an Input Component

There are 3 ways to label it:

Enclose with a label

<zk xmlns:h="native" xmlns:ca="client/attribute">
    <h:label>Address
        <textbox/>
    </h:label>

Specify at aria-label

<zk xmlns:h="native" xmlns:ca="client/attribute">
    <custom-attributes field="Account:"/>
    ${field}
    <textbox ca:aria-label="${field}"/>

Specify at aria-labelledby

<zk xmlns:h="native" xmlns:ca="client/attribute">
    <label value="price" id="priceLabel"/>
    <textbox ca:aria-labelledby="${priceLabel.uuid}"/>