0.3.1 to 1.0.0 Migration Guide

Work In Progress

Introduction

The 1.0.0 release of CAM finished adding support for all ARIA roles. It also brought in some bug fixes and improvements, some of which are breaking changes that lead to multiple 1.0 pre-release versions of CAM before the 1.0.0 version was released. The purpose of this page is to document the breaking changes and how to address them in consuming projects. This page organizes the breaking changes by category, but all need to be addressed as part of the upgrade to the 1.0.0 version of CAM.

Role Splitting

• ROLES.OPTION has been split into ROLES.SINGLESELECTOPTION and ROLES.MULTISELECTOPTION. This was needed in order to support getting ROLES.SINGLESELECTLISTBOX working visually consistent across browsers combined with CAM's one-to-one role to HTML tag mapping.
  • If an option is being added to a ROLES.SINGLESELECTLISTBOX, then replace ROLES.OPTION with ROLES.SINGLESELECTOPTION.
  • For options added to ROLES.MULTISELECTLISTBOX, then replace ROLES.OPTION with ROLES.MULTISELECTOPTION.

Binding Event Listeners When Registering

• If event listeners are bound after the register function is called, such as by addEventListener or on, then no changes are needed.
• In the 0.x versions of CAM, the object passed to register could contain onFocus and onKeyboardClick callbacks for handling those particular events. In order to handle any event, those fields have been replaced by an events array of objects that allows for binding an event handler for any event. The objects that make up this array have a field of eventName for the string name of the particular event to bind for, and a listener field for specifying the event handler function. A sample of this way of binding event listeners can be seen in the test app at https://github.com/CurriculumAssociates/createjs-accessibility-tester/blob/290d6ab51c49381345b3b831c37c4f5c7ef48c89/src/widgets/ScrollBar.js#L29-L38.
  • For prior onFocus and onKeyboardClick fields, for example:

      onFocus: _focusHandler,
      onKeyboardClick: _keyboardClickHandler,
    

  • Becomes:

      events: [
        {
          eventName: 'focus',
          listener: _focusHandler
        },
        {
          eventName: 'keyboardClick',
          listener: _keyboardClickHandler
        }
      ],
    

Parameter type fixes

• The hasPopUp getter/setter of AccessibilityObject (the base class used to populate a registered DisplayObject's .accessible field) has been updated from a boolean to a string in order to allow for all the valid values that https://www.w3.org/TR/wai-aria-1.1/#aria-haspopup specifies
  • For existing true or false parameter values, add quotes around the value or use another mechanism to convert it to a string
  • For existing undefined parameter values, no change needs to be made

Events Emitted

• ROLES.ROW used to emit a keyboardClick event when used inside a ROLES.TREEGRID to indicate that a row should expand or collapse. That has been replaced by ROLES.TREEGRID emitting collapseRow or expandRow events. To handle this, the keyboardClick event listener on the row DisplayObject should be removed, and event listeners added to the tree grid DisplayObject for the collapse and expand row events.