![\"Generated](\"guides/accessibility/generated-app.png\")
Contents
\nExt JS 4.2.1 makes it possible to create accessible JavaScript applications by providing\nthe tools that developers need to achieve Section 508 and\nARIA compliance. These brand new features make it\neasier than ever before for application developers to create user interfaces that are\nusable by people with disabilities and by those who use assistive technologies to navigate\nthe web.
\n\nWhat does it mean for a software application to be Accessible? In general accessibility means\nthat the functionality and content of an application is available to people with disabilities\nespecially the visually impaired, those who rely on a screen reader to use a computer, and\nthose who cannot use a mouse to navigate the screen. In 1998, the United States Congress\npassed the \"Section 508 Amendment to the Rehabilitation Act of 1973\"\nmore commonly referred to as just \"Section 508\", requiring Federal agencies to make all\ninformation that is electronically available accessible to people with disabilities. Because\nof Section 508 accessibility is a requirement for anyone producing software applications\nthat will be used by U.S. government agencies, however, applications not designed for\ngovernment use may also benefit since accessibility features will enable them to reach a\nlarger number of users. Web applications can make significant steps toward achieving\ncompliance with Section 508 by following the guidelines spelled out in the\nWeb Accessibility Initiative's \"Accessible Rich Internet\nApplications Suite\", otherwise known as WAI-ARIA or\njust \"ARIA\".
\n\nAccessibility support in Ext JS is designed with three major goals in mind:
\n\nDOM attributes - A Component's DOM elements should use attributes that provide semantic\ninformation regarding the elements' type, state, and description. These attributes\nare used by screen readers to provide verbal cues to the user and can be categorized into\ntwo separate groups:
\n\na. ARIA Roles are the main indicator of a\n Component's or Element's type. Roles are constant and do not change as the user\n interacts with a Component. The most commmonly used ARIA Roles in Ext JS are\n Widget Roles, many of which\n directly correspond to Ext JS components. Some examples of widget roles are:
\n\n - button\n - checkbox\n - tabpanel\n - menuitem\n - tooltip\n b. ARIA States and Properties\n are DOM attributes that may change in response to user interaction or application state.\n An example of an ARIA State is the \"aria-checked\" attribute that is applied to a\n checkbox component when it is checked by the user. An example of an ARIA Property is\n the \"aria-readonly\" property of a form field which may be dynamically changed based\n on validation or user input.
Accessibility support in Ext JS is implemented in three major pieces:
\n\nrenderTpl.\"ext-aria\" package - \"ext-aria\" is a separate Sencha Cmd Package\nthat provides improved keyboard navigation, focus management, and support for\nARIA States and Properties. It is\nusually not necessary to directly require the \"ext-aria\" package in an application because\nit is already required by the \"ext-theme-aria\" theme.\"ext-theme-aria\" theme - A high-contrast theme makes applications easier for visually\nimpaired users to view. \"ext-theme-aria\" can be used out of the box, or extended to\ncreate a customized look and feel.Lets start by building an new application from scratch that uses the Accessibility features\nof Ext JS 4.2.1.
\n\nThe first step is to download the Ext JS SDK.\nUnzip the SDK to a location of your choosing. For this tutorial, we assume that you\nunzipped the SDK to your home directory: \"~/extjs-4.2.1/\".
To build an Ext JS Application with accessibility features enabled you need to have at least\nversion 3.1.2 of Sencha Cmd installed. For installation instructions see:\nIntroduction to Sencha Cmd.
\n\nNow that you have Sencha Cmd and the Ext JS SDK installed, you are ready to begin building\nthe application. From the command line, enter the following command, and replace\n\"~/ext-4.2.1\" with the path where you unzipped the Ext JS SDK.
sencha -sdk ~/ext-4.2.1 generate workspace my-workspace\nThis generates a Sencha Cmd workspace that will contain your application and copies the\nExt JS SDK into the workspaces \"ext\" directory. For more information on workspaces see:\nWorkspaces in Sencha Cmd.
Sencha Cmd makes generating an application easy. Navigate into the workspace you just\ncreated:
\n\ncd my-workspace\nThen run:
\n\nsencha -sdk ext generate app MyAriaApp my-aria-app\nThis tells Sencha Cmd to generate an application named \"MyAriaApp\" in a directory named\n\"my-aria-app\" and to find the Ext JS SDK in the workspace's \"ext\" directory. You\ncan build the application by running the following command from the newly created\n\"my-aria-app\" directory:
sencha app build\nAfter building the application you can run it by opening\n\"my-workspace/build/MyAriaApp/production/index.html\" in a browser.
The easiest way to enable ARIA support in your application is to use the \"ext-theme-aria\"\ntheme. To do this, find following line in \"my-aria-app/.sencha/app/sencha.cfg\":
app.theme=ext-theme-classic\nAnd replace it with this:
\n\napp.theme=ext-theme-aria\nIf you want to be able to run your app in development mode, you will need to refresh the\nbootstrap files now (for more info see Single-Page Ext JS Apps):
\n\nsencha app refresh\nNow build your app again by running the following command:
\n\nsencha app build\nRun your app by opening the index.html page in a browser. You should see an empty\napplication shell with a viewport and a few components that Sencha Cmd generaated for you:
\n\n
With ARIA support turned on, an Ext JS Application should be navigable using only the keyboard,\nwith no mouse input required. The visual indicator of which component currently has focus\nis referred to as the \"focus frame\". In \"ext-theme-aria\" the focus frame is rendered\nwith an orange border. You will notice when you load the index page of the app you just\ncreated that this border appears around the edge of the Viewport.\nThis is because the Viewport is automatically recognized as the application's main container.\nIt is the starting point of all navigation and so receives focus by default when the page\nis loaded. If your application does not use a Viewport, you need to set the ariaRole\nconfig of the top-level container in your application to 'application'. For example:
Ext.create('Ext.panel.Panel', {\n renderTo: Ext.getBody(),\n title: 'Main Panel',\n ariaRole: 'application',\n ...\n});\nIn the application there is currently only one focusable Component - the Viewport.\nLet's add some more focusable Components so we can see how keyboard navigation works.\nModify \"my-aria-app/app/view/Viewport.js\" to contain the following code:
Ext.define('MyAriaApp.view.Viewport', {\n extend: 'Ext.container.Viewport',\n requires: [\n 'Ext.layout.container.Border'\n ],\n\n layout: 'border',\n\n defaults: {\n split: true\n },\n\n items: [{\n region: 'west',\n width: 200,\n title: 'West Panel',\n ariaRole: 'region',\n items: [{\n xtype: 'textfield'\n }, {\n xtype: 'textfield'\n }, {\n xtype: 'button',\n text: 'Toggle Me',\n enableToggle: true\n }]\n }, {\n xtype: 'tabpanel',\n region: 'center',\n title: 'Center Panel',\n ariaRole: 'region',\n items: [{\n title: 'Tab 1'\n }, {\n title: 'Tab 2'\n }, {\n title: 'Tab 3'\n }]\n }, {\n region: 'east',\n width: 200,\n title: 'East Panel',\n ariaRole: 'region'\n }]\n});\nHere we create a viewport that uses a Border Layout\nand has three child panels laid out as east, west, and center regions. Each region is\nmade focusable and navigable via the keyboard by configuring it with an ariaRole of\n'region'. The center panel is a Tab Panel and has three tabs.\nTabs are focusable by default and so no special code is needed to enable keyboard navigation.\nWe've added some Text Fields and a\nToggle Button to the \"west\" region, and these\ncomponents are also focusable by default.
Let's rebuild the application and view the result:
\n\nsencha app build\n![\"ARIA](\"guides/accessibility/app.png\")
By default the Viewport is the focused Component. Press the enter key to navigate into\nThe Viewport and cycle through it's children (the west, center, and east regions) using\nthe tab key. Try pressing the enter key while the west region is focused and using\nthe tab key to cycle through the items. When the toggle button is focused use the enter\nor space key to toggle its pressed state. You can move back out of the west region by\npressing the \"esc\" key. To navigate the tabs, move the focus to the center panel and\npress \"enter\", then use the arrow keys to navigate the tabs and the enter key to activate\na tab.
\n\nYou can verify that the correct ARIA Roles, States and Properties have been applied to\ncomponents by inspecting the DOM using the development tools in your browser of choice.\nFor example, inspect the Button component in your app. In\nChrome Developer Tools the Button's\nmain \"A\" element looks something like this:
\n\n![\"Button](\"guides/accessibility/button-element.png\")
Notice how it has the ARIA Role of \"button\" (role=\"button\"), and an ARIA State of\naria-pressed=\"false\". If you toggle the button either by clicking it or by pressing\nthe space or enter key while the button is focused you should see the value of the\naria-pressed attribute change to \"true\".
The best way to create a customized ARIA Theme is to create a theme package that extends\n\"ext-theme-aria\". For instructions on theme creation see the\nTheming Guide. The \"ext-theme-aria\" theme automatically includes\nall of the required JavaScript overrides from the \"ext-aria\" package, and themes that\nextend \"ext-theme-aria\" will as well.
If for some reason extending \"ext-theme-aria\" will not work for you, then you need to\nmake sure that you correctly require the \"ext-aria\" package, either in your theme, or in\nyour application. This ensures that the JavaScript overrides from the \"ext-aria\"\npackage are included in your app, and is done by adding the following JSON property to\neither your custom theme package's \"package.json\" file, or your application's \"app.json\"\nfile.
\"requires\": [\n \"ext-aria\"\n]\nWe've been over how to create a new Ext JS Application with ARIA support, but adding\nARIA support to an existing application is just as easy. First make sure your application\nis using Ext JS 4.2.1 or later. You can upgrade an app that uses an older 4.x version of\nthe framework by downloading the Ext JS SDK\nand then running the following command from your application's root directory:
\n\nsencha app upgrade /path/to/sdk\nThen modify the application's \".sencha/app/sencha.cfg\" file and make sure the\n\"app.theme\" property is set to \"ext-theme-aria\":
app.theme=ext-theme-aria\nRefresh your application's bootstrap files if you want to use development mode:
\n\nsencha app refresh\nThen build your app by running the following command from the application's root directory:
\n\nsencha app build\nYou may also set the theme from the command line if, for example, you want to build\nyour application with multiple themes:
\n\nsencha config -prop app.theme=ext-theme-aria then app build\nTo enable keyboard navigation, add the appropriate \"ariaRole\" configs to your application's\nComponents as described above in the section on \"Navigating an ARIA-Enabled Ext JS Application\".
You may find yourself in the position of maintaining an older Ext JS application that\ndoes not build using Sencha Cmd. It is a beneficial to update these applications so that\nthey can build using Sencha Cmd; however, if using Sencha Cmd to build the app is not an\noption, the application can still use the ARIA features of Ext JS by including the \"all\"\nJavaScript and CSS files of the \"ext-aria\" package and the \"ext-theme-aria\" theme.
To use the ARIA features you will need to upgrade your application to use at least\nExt JS 4.2.1. The next step is to\ndownload the \"ext-aria\" and \"ext-theme-aria\" packages. The easiest way to do this\nis using Sencha Cmd. If you don't have Sencha Cmd 3.2.1 or later already installed,\nuse the instructions found in the Introduction to Sencha Cmd Guide,\nThen from the command line, run the following two command from your application's root\ndirectory:
sencha pacakge extract -todir . ext-aria\nsencha package extract -todir . ext-theme-aria\nYou can change the directory where the packages are extracted to by replacing the \".\"\nin the \"sencha package\" command with the path to the directory where you want the packages\nto be extracted. After running this command you should see the following 2 directories in\nyour application root directory or the directory you specified:
\"ext-aria\"\"ext-theme-aria\".An older Ext JS application typically has an index.html page that has the following structure:
\n\n<html>\n<head>\n <title>My Application</title>\n\n <link rel=\"stylesheet\" type=\"text/css\" href=\"ext/resources/css/ext-all.css\">\n <script src=\"ext/ext-all.js\"></script>\n <script src=\"app.js\"></script>\n</head>\n<body></body>\n</html>\nReplace the href value for the \"ext-all.css\" link tag with\n\"ext-theme-aria/build/resources/ext-theme-aria-all.css\", and add a script tag that includes\n\"ext-aria/build/ext-aria-debug.js\" after \"ext-all.js\". In the end your upgraded\nindex.html page should look something like this:
<html>\n<head>\n <title>My Application</title>\n\n <link rel=\"stylesheet\" type=\"text/css\" href=\"ext-theme-aria/build/resources/ext-theme-aria-all.css\">\n <script src=\"ext/ext-all.js\"></script>\n <script src=\"ext-aria/build/ext-aria.js\"></script>\n <script src=\"app.js\"></script>\n</head>\n<body></body>\n</html>\nTo enable keyboard navigation, add the appropriate \"ariaRole\" configs to your application's\nComponents as described above in the section on \"Navigating an ARIA-Enabled Ext JS Application\".