Progress® Telerik® Reporting R3 2017

Accessibility

Telerik Reporting aims to provide a reporting solution accessible to a wider user audience. This includes users with motor control restrictions and ones working with assistive technologies. In our product we follow the recommended practices in Section 508 of the Rehabilitation Act and Web Content Accessibility Guidelines (WCAG) 2.0, building our web content according to standards set by WAI-ARIA.

Setting up accessibility features in HTML5-based viewers

The accessibility features are enabled or disabled using an optional boolean parameter named enableAccessibility (the exact letter casing varies among the HTML5-based viewers). The default value of this property is false (no additional accessibility markup is emitted).

The accessibility codebase is part of the telerikReportViewer.{product version}.js file. This file can be found in the \bin\js subfolder of the Telerik Reporting installation folder. The product also provides a minified version of the script, which can be used in production environments.

The accessibility script operates using the DOM elements from the viewer template, so if you have modified the template, you will probably need to apply changes to the accessibility part of the script as well.

The accessibility script captures the keyboard events to provide shortcut key access to the viewer areas. It is possible some of these shortcuts to interfere with the default browser behavior. In this case the keys mapping can be changed through the accessibilityKeyMap(keyMap) method or by editing the telerikReportViewer.{product version}.js file manually.

The accessibility script supports localization. You can modify its message and label strings, following the procedure, described here.

Note Note

Please note that all the dynamically provided markup, added when the accessibility is enabled, might result in a small performance penalty, especially on machines with outdated hardware. For best experience we recommend to enable the accessibility features conditionally according to your user's needs.

Supported accessibility features in HTML5-based viewers

Our HTML5-based report viewers support the following important accessibility features:

Comprehensive keyboard support

Includes navigation between and into report viewer areas (menu, parameters, document map, contents) using shortcut keys, TAB or arrow keys where possible. The menu commands and expandable menu items are toggled on ENTER. The same key mapping is applied to document map and parameters areas.

The default shortcut keys for navigation between the viewer areas are:

  • Ctrl+Alt+M - menu area

  • Ctrl+Alt+P - parameters area (if visible)

  • Ctrl+Alt+D - document map area (if visible)

  • Ctrl+Alt+C - report viewer contents area (the report currently rendered in the viewer)

If needed, the default key mapping can be changed, using the report viewer's API method accessibilityKeyMap(keyMap).

Dynamically generated descriptions for report viewer areas

The report viewer areas provide additional textual details that reflect the currently presented information. This applies to the state of the menu buttons (enabled, disabled, expandable, etc.), the parameters state and their selected values, the currently selected node from document map and the rendered report. This information refreshes dynamically with every change that occurs in the viewer - for example when a new page is loaded or when an exception is thrown while processing the report.

Textual description to a non-textual items

In a rendered report all graphic items like images, maps and charts provide additional information about their contents. Tables and crosstabs provide such information about the currently focused cell, marking the current row, column and value. These details are visible and recognizable by the most popular screen readers to help users with visual disabilities better understand the presented report. A comprehensive list with the supported report items features can be found in the next section.

Supported accessibility features in HTML5-rendered report contents

All the report items have a property called AccessibleDescription. The property value is an expression and it determines what will be the accessibility label when the report is rendered. Its value is set as an alternate text for images in PictureBox items and as an accessible label for the other elements. According to ARIA specifications , the attribute that should be used in scenarios, where no text labeling element is available, is aria-label.

The value of aria-label attribute is created using the following pattern: {type} {additional information} {description} :

  • {type} is a placeholder that contains the type name of the currently rendered element - "Details section", "Text box", "Table", etc. The report item names are localizable and can be substituted with any appropriate strings, even with empty values, if there is no need to include the report item name in the label.

  • {additional information} is intended to give some meaningful information about the context where the current item is in, or about its additional properties. The cases where it is most useful, are:

    • - if the current item has some interactive action set, this token will contain the type of the action.

    • - if the current item is Table or Crosstab, the token will contain information about the row and column count.

    • - if the current item is nested in a Table or Crosstab, the token will contain information about the current cell's row and column zero-based index. Additionally, if the cell is used as a header, this information will be also included in the label.

    • - if the current item is a CheckBox, the token will contain information about the current checkbox status (checked/unchecked).

  • {description} provides relevant information about the current item contents. Its value is evaluated using the item's AccessibleDescription property and if it is empty, falls back to the item's Value or Text property, whichever is available.

For example, if a report contains a TextBox with Value = "Sorts by Category", that performs a sorting action and is nested in a table's first (header) row and third column, the generated aria-label value will be: Text box. Performs a sorting action. Column header. Column 2 Row 0. Sorts by Category.

Known issues

Most of the currently known issues are due to the fact that the widely used screen readers behave differently with different browsers. Additionally, the most common browsers support accessible content to a various extent. The following table shows the known issues by browser and screen reader (where applicable):

Browser

Screen reader

Description

Firefox 55.0.3+

-

Export menu item cannot be toggled through keyboard.

Chrome

JAWS

After exporting a document, JAWS stops reading the content.

Chrome

JAWS

Page number editor text is not read.

Chrome

JAWS

Document map items are not read.

Chrome

JAWS

Toggle visibility actions are not executed.

Internet Explorer, Edge

Narrator

Document map items are not read.

Note that software vendors consistently upgrade and improve their products, so any of the above issues can be fixed by a third-party program update.