Integrating WCAG structures in a ZK page
Matthieu Duchemin, Engineer, Potix Corporation
Aug. 17, 2021
ZK 9.6.0
Introduction
The Web Content Accessibility Guidelines (WCAG) are a set of specifications for web content creation. Content that follows these rules can be easily browsed by users utilizing accessibility technologies, such as screen readers.
A large part of accessible design relies on marking elements of the page with attributes to inform the content reader of the nature of each object, as well as their relationship with other elements of the page.
In this small talk, we will discuss how to utilize these guidelines in ZK to design accessible web content quickly and easily.
Basics of WCAG attributes and page structure
The main goal of assistive technologies is to provide information in addition to the visual page in a web browser. This additional information can be processed by a screen reader, highlighted, or used to provide a page outline for easier navigation.
In this example, we will use the case of a screen reader, but the same principle applies regardless of the accessibility tools employed by the end-user.
We will focus on a specific aspect of accessible design: headings and landmarks. Headings are specific elements that can be interpreted by a screen reader to organize the page content. This can be seen like an automatically generated table of content.
By introducing elements that have a natural heading level (h1, h2, etc.), or by marking elements with the role="heading" and aria-level attributes, we can organize the page content in a way that can be traversed by the screen reader.
Here's a screenshot of how a screen reader software will parse the headings of the page (screenshot). If the user open the headings panel, they will be able to browse the headings, organized by level.
In a similar manner, landmarks create a list of zones by “function”. In both cases, the screen reader will be able to pick up on these hints, and to provide convenient tools for the end-user. With these tools, the end-user will be able to navigate through the page to locations of interest, and to quickly move through the different sections of the page.
Here's a screenshot of how a screen reader software will parse the landmarks of the page (screenshot). If the user open the landmarks panel, they will be able to browse the landmarks, organized by functionality.
WCAG in ZK Framework
ZK has built-in accessibility support for out-of-the-box components, with the ZA11Y package. This dependency adds automatic aria attributes generated from the component values and automates a lot of accessibility design building.
Complex ZK components, such as Grids or Dateboxes, will automatically add accessibility labels based on the component state when using the ZA11Y dependency. For example Grids will add information regarding the paging and row navigation. Datebox will add information such as labels for the selected day of the month. Since this is part of standard operation, the default values will more often than not be appropriate for the use case.
This said, designing for a specific goal often requires deliberate choices, and the ability to go further than the default use cases.
This is the case for headings and landmarks. We want to add additional information on top of the default generated labels and attribute. We also want to be fully in control of where this information is added, in order to better guide the user through our UI.
See example of the searchbox component (screenshot). The component automatically generates relevant attributes based on its state and on user actions.
For further reading on accessibility design in ZK, please refer to the dedicated documentation page.
Basic UI composing with xhtml elements
The most basic manual WCAG implementation in a zul page is done by simply adding aria-attributes to DOM elements of the resulting page.
This can be done either by using native HTML elements, or XHTML elements in zul. While the default namespace for a zul file is zul (the namespace containing classic out-of-the-box ZK components), it is also possible to generate elements from different namespaces.
In this case, we add a native <h3> node to our page. Native elements will result in a one-to-one html node in the resulting page. As such, any attribute added to this node will be applied to the result node in the page. Adding native node also allows us to benefit from default browser behaviors. Since the <h3> (heading 3 element) is already a heading by browser definition, it will appear in the header list without further action on our part.
1 <zk xmlns:n="native">
2 ...
3 <n:h3 class="demo-content--subtitle z-label">Best seller</n:h3>
Since these elements are transcribed one-to-one in the resulting page’s DOM tree, attributes can be added direction onto the relevant elements.
Supplementing ZA11Y in ZK components
This is good for simple elements such as divs and headings, but we can do better. ZK components from the zul namespace are much more useful than basic DOM elements, so it’s important to have the ability to also mark them with the relevant WCAG information to make our page more readable for screen readers.
For that purpose, we will use the client/attribute namespace. The client/attribute namespace allows us to add arbitrary attributes on ZK components. The structure is simple: Declaring the namespace prefix, then, use the prefix to declare an attribute on a ZK component.
1 <zk xmlns:ca="client/attribute">
2 ...
3 <label ca:role="heading" sclass="subtitle" ca:aria-level="3">Chef's choice</label>
In this case, the attribute name and the attribute value can be any string of characters. The DOM node generated in the page will include it as name=”attribute”, which makes it a great option to quickly add WCAG attributes on existing ZK components.
Reusable designs: easy templating in ZK
Now, to make things reusable. Instead of manually building each individual component with custom WCAG attributes, we can improve on this concept by defining templates and reusing them.
A template is simply a fragment of zul code, which can use variables. It can be applied multiple times, with different values. By building in WCAG attributes when creating the template, we can generate WCAG compliant code without having to add attributes to individual node.
1 <vlayout sclass="pizzaCard">
2 <apply template="pizzaCard"
3 title="Pizza pugliese"
4 subtitle="Recomended discovery"
5 highlight="Pizza pugliese"
6 description="is prepared with tomato, onion, and mozzarella."/>
7 </vlayout>
8 <template name="pizzaCard">
9 <apply template="title" content="${title}"/>
10 <apply template="subtitle" content="${subtitle}"/>
11 <apply template="paragraph" highlight="${highlight}" content="${description}" />
12 </template>
13 <template name="title">
14 <label sclass="title" ca:role="heading" ca:aria-level="2">${content}</label>
15 </template>
Conclusion
You can see a live version of the demo project here.
In addition to ZA11Y out-of-the-box accessibility improvements, we can add simple accessibility information to existing pages by leveraging the ability to add client-attributes to components. This allows us to significantly improve the navigation experience of people browsing the page with the help of a screen reader, or other WCAG based assistive tools.