Introducing an Accessible Accordion Widget

At the dawn of the millennium, a blind gentleman successfully sued the Sydney Organizing Committee of the Olympic Games as they had failed to make the official website of the Olympic Games adequately accessible to blind users. Over the years, many such cases have come to light, and numerous acts have been passed in various countries which make it mandatory for you to make your website adequately accessible. Many JavaScript libraries today provide a variety of widgets like sliders and menu bars, but developers often choose to ignore accessibility. One such example is the jQuery Accordion widget. The accordion is a useful widget which solves the problem of presenting content in an area with space constraints.

The Problem

Using jQuery 1.9.1, jQuery UI 1.10.4, and Chrome 32, it is not possible to tab through the accordion headers. However, once the accordion is active, you can use the up and down arrow keys to navigate through the headers and press the Enter Key to uncollapse one (which in itself is not intuitive). Secondly, there is no way for a screen reader (NVDA in this case) to read what is within the just uncollapsed area. During the Google Summer of Code 2013, I was working on the ATutor project of the Inclusive Design Institute. ATutor is an open source learning content management system, which complies completely with the accessibility specifications. We had a significant problem – the data in the courses page. It typically listed all courses and their corresponding information, which made it difficult for someone using assistive technologies (AT) to navigate easily. A solution was an accordion, but one which met the high accessibility standards set by ATutor.

The a11yAccordion

My mentor for the project, Alexey Novak, had developed something similar for AContent, a content authoring system used to create web based learning content. A standalone version was then developed and open sourced so that it could be used in the ATutor project, as well as in any other project. There were two prime objectives for the project – keyboard only users must be able to tab through the widget with relative ease, and screen readers must be able to read out all the content within the widget. In the current version, you can tab through the whole widget using just your keyboard, and the screen reader reads through the content as well. If you use the search bar, the title is changed dynamically, which makes a screen reader read it out to update you about the number of results of your search.

Quick Start

The project is hosted on GitHub and you can download the source code. There is also a demo you can view before downloading. Note that you would need to include the CSS (dist/css/a11yAccordion.css) and JavaScript (dist/js/a11yAccordion-0.2.2.min.js) files. Alternatively, you can compile it using grunt. The markup for an example accordion is shown below.

<ul class="a11yAccordion" id="Accordion1">
  <li class="a11yAccordionItem">
    <div class="a11yAccordionItemHeader">
      <strong>Random Months</strong>
    </div>
    <div class="a11yAccordionHideArea">
      <ul>
        <li>January</li>
        <li>June</li>
        <li>February</li>
        <li>November</li>
      </ul>
    </div>
  </li>
  <li class="a11yAccordionItem">
    <div class="a11yAccordionItemHeader">
      <strong>Dummy Text</strong>
    </div>
    <div class="a11yAccordionHideArea">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
    </div>
  </li>
  <li class="a11yAccordionItem">
    <div class="a11yAccordionItemHeader">
      <strong>Header with image</strong>
    </div>
    <div class="a11yAccordionHideArea">
      <img src="https://www.google.co.in/images/srpr/logo11w.png" alt="Google Logo">
    </div>
  </li>
</ul>

The JavaScript code needed to manipulate the previously defined accordion is shown below.

var myAccordion = a11yAccordion({
  parentSelector: '#Accordion1'
});

The resulting accordion is shown in the following figure.

Using the Widget

The latest version of the a11yAccordion can be found on GitHub. Clone the repository or download it as a zip file to get started. As the widget is built on jQuery 1.10 0, you would need to include jQuery before initiating the widget. As you’ve already seen, an options object is passed to the accordion’s JavaScript constructor. a11yAccordion supports the following options.

• parentSelector – The selector for the parent container which has accordion markup. This defaults to undefined.
• accordionItemSelector – The selector for rows which contain headers and hidden areas. This defaults to .a11yAccordionItem.
• headerSelector – The selector for a header within the row. This defaults to .a11yAccordionItemHeader.
• hiddenAreaSelector – The selector for hidden areas within the accordion row. Defaults to .a11yAccordionHideArea.
• visibleAreaClass – The class which is added to every row which will be uncollapsed/visible to the user. Defaults to .visibleA11yAccordionItem.
• colorScheme – The color scheme for the accordion. Defaults to .light.
• speed – The speed of animation in milliseconds. Defaults to 300.
• hiddenLinkDescription – A description for every Show/Hide link that is provided for users who use assistive technology.
• showSearch – A Boolean option which will tell the accordion to render search options.
• showOne – A Boolean value that defines if the accordion can uncollapse only one row to the user at a time.
• overallSearch – A Boolean option which will tell search to look not only in headers but within collapsed areas as well.

The API

The a11yAccordion also comes with a JavaScript API, which allows for programmatic manipulation. The API functions are described below.

• collapseRow(rowIndex) – This function hides the hidden area under the row with corresponding rowIndex.
• uncollapseRow(rowIndex) – This function shows the hidden area under the row with corresponding rowIndex.
• toggleRow(rowIndex) – This function toggles the state of the row between collapsed and uncollapsed.
• getRowEl(rowIndex) – This function returns the jQuery row element with the corresponding rowIndex.
• showOne – This is a Boolean value with shows the user only one uncollapsed row at a time.

The Future

Although we have come quite a long way from a simple accordion, there are a lot of things left to do. The issues page tracks our immediate plans. To name one, we plan to add a function that helps in disabling rows programmatically.

Contributing to the Project

This project has a lot of potential, but it needs the help of developers and designers. Fork and clone the GitHub repository to contribute. Developers need to install Grunt and run npm install to set up the system locally. Designers can also directly add themes to the LESS file.

Frequently Asked Questions (FAQs) about Accessible Accordion Widget