Web Accessibility Properties and Actions (WAPA) Explainer

5.1 Performance improvement with Just-in-Time loading of accessibility information

• Pre-loading all information is costly

  It can be very costly to pre-load all the accessibility information and get it added to all the relevant elements, especially if no one will ever ask for it. For example, populating all the names with aria-label takes time to load all the strings and add them to the markup, or to download them as part of a static markup.

• Updating ARIA state is costly

  Imagine a list with 100 items. If an item is added or removed from the list, every other item must update their aria-setsize and (potentially) aria-posinset attributes.

The developer wants to provide accessibility information only when it is requested by AT via the Accessibility API, and not at the time the DOM is filled in.

This mechanism works with the @role attribute and any @aria- attribute.

JavaScript Sample

        <div id="listbox1" role="listbox" onariarequest="HandleRequest(event);">
            <div role="listitem">Item 1</div>
            <div role="listitem">Item 2</div>
            <div role="listitem">Item 3</div>
                …
            <div role="listitem">Item 100</div>
        </div>
        <script>
            function manageList(event) {
                var listbox = document.getElementById('listbox1');
                if (event.target.parentNode == listbox) {
                    if (event.attributeName === "posinset") {
                        event.attributeValue = GetChildId(event.target);
                    }
                    else if (event.attributeName === "setsize") {
                        event.attributeValue = "100";
                    }
                }
            }
      </script>
                

        

5.2 Accessibility information Stored outside DOM

An application uses javascript objects to store all of its state (accessibility and other state), and only uses the DOM as a drawing surface. The goal is to treat accessibility state the same way as other state, and to manage it directly from script.

element.onariarequest is a new event that gets fired when an AT requests makes an Accessibility API request that maps to aria information

element.oncommand is a User Intention Event

event.attributeName is the attribute that changed as part of the event. This is a new attribute we are proposing to add to the DOM Event Object

event.preventDefault(); stops the default processing of the event.

element.NotifyAriaStateChange(string) toggles a boolean aria state. It is equivalent to element.setAttribute("aria-"+string, true) or element.setAttribute("aria-"+string, false)

JavaScript Sample

        <script>
            var toggleState = false;
            function HandleRequest(event) {
                var myCheckbox = document.getElementById("myDiv");
                if (event.attributeName === "checked" && event.target === myCheckbox) {
                    event.attributeValue = (toggleState ? "true" : "false";
                }
            }
            function HandleCommand(event) {
                var myCheckbox = document.getElementById("myDiv");
                if (event.target === myCheckbox && event.commandName === "toggle") {
                    toggleState = !toggleState;
                    UpdateUI();
                    event.preventDefault();
                }
                function ToggleMe(){
                    toggleState = !toggleState;
                    var myCheckbox = document.getElementById("myDiv");
                    myCheckbox.NotifyAriaStateChange("checked");
                }
            }
        </script>
        <div id="myDiv" role="checkbox" oncommand="HandleCommand(event)" onariarequest="HandleRequest(event);" onclick="ToggleMe();">
        

5.3 Virtualized Content

A user opens a large document in the Word web app. Word adds the first page or two to the DOM, but not the whole document. When the user reaches the end of the loaded portion of the document, more content is loaded.

How will a screen-reader user know:

• Position in the document
• Position within a list or table that spans document chunks
• When there is more content to load and when there is not
• When content has been loaded
• When there has been a network or other error preventing content loading

How will an AT product signal to the app that it needs to load more content?

How will an app let AT products know that more content is loading and that focus should not move out of the content container?

Not all content is in the DOM, or the DOM contains little actual meaning for the content (the DOM is just a view). Requiring that the information be available on the DOM objects is hard to impossible depending on the app. This is used by apps like Office Online, where the content is stored in the backend and only a specific view (such as the current page of a document) is actually available in the DOM.

JavaScript Sample

            <script>
            function HandleCommand(event) {
                var myContainer = document.getElementById(" content");
                if (event.target == myContainer && event.commandname == "contentLoaded" ) {
                appendcontent(mycontainer);
                event.preventdefault();
            }
            function handlecommand(event) {
                var mycontainer=document.getElementById("content");
                if (event.target == myContainer && event.commandname == "contentRequested" ) {
                mycontainer.setattribute("aria-busy","true");
                event.preventdefault();
            }
            function handlecommand(event) {
                var mycontainer=document.getElementById("content");
                if (event.target == myContainer && event.commandname == "contentTimeout" ) {
                displayerror();
                event.preventdefault(); />
            }
            function HandleCommand(event) {
                var myContainer = document.getElementById("content");
                if (event.target == myContainer && event.commandName == "contentEnd") {
                    //do Nothing
                    event.preventDefault();
                }
        </script>
<body>
<div id=toolbar>
                <!-- some UI for the page, which is not virtualized -->
            </div>
            <!--
             This area is the content of the page, only part of which is loaded.
             More will be loaded when the user reaches the bottom of the page.
             aria-async is a proposed new aria attribute that marks the area that
             contains virtualized content
            -->
<div id=content aria-async="true" oncommand="HandleCommand(event);">
                <!-- the first 'chunk' of content.  A page, a set of images, etc. -->
            </div>
<div id=sidebar>
                <!-- content which is not virtualized -->
            </div>
        </body>
        
            

aria-async is new aria-attribute which means that the content is may be virtualized.

Four new User Intentation Events:

• ContentRequested is fired when the application makes a server call to get additional content. This will often be in response to the user reaching the end of the currently loaded content, but could be in response to custom UI.
• ContentLoaded is fired when the content has been returned from the server and added to the DOM.
• ContentTimeOut is fired after n time if no content is returned.
• ContentEnd is fired when the async call returns with no more content

5.4 Custom Elements (Future)

A developer encapsulates functionality in a control that can be called using a custom element tag. Using DARIA, the developer can define default ARIA roles, states and properties, so that those will be mapped to UIA (and other accessibility APIs) in the same way that the default roles, states and properties of native HTML elements are mapped.

Custom Elements

WAPA allows more direct communication with accessibility APIS via script, including the ability to intercept accessibility API actions. We believe that this can be used to hook up custom elements to web accessibility APIs and allow AT products to interact with them.

5.5 WebDriver testing of accessibility (Future)

Because WAPA is an in-browser javascript API, rather than a platform accessibility API, we may be able to simulate the effect of an AT acting on content by sending the same command events that the browser would send based on AT action. This would allow WebDriver to exercise accessibility functionality in web apps.