Child pages
  • Keyboard Accessibility Plugin API

Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Skip to end of metadata
Go to start of metadata

The jQuery Keyboard Accessibility Plugin makes it easy for developers to add keyboard handlers to their code without a lot of extra overhead.

Please note that, when used as a jQuery plugin, the Keyboard Accessibility API currently handles only two parameters. This is a bug in the current implementation that will be addressed in a future release. If more than two parameters are required, any parameters beyond the function name must be be enclosed in an array.


activatable

jQuery().fluid("activatable", customHandler);
jQuery().fluid("activatable", parameterArray);  // parameterArray = [customHandler, options]

Makes all matched elements activatable with the Spacebar and Enter keys. A handler function may be provided to trigger custom behaviour.

Arguments:

Name

Description

customHandler

A function that will be called when the element is activated.
In v1.0: The function should accept the element to be activated as a parameter: myHandler(element);
In v1.1 and beyond: The function should accept the browser event as a parameter: myHandler(event);

options

(Optional) A collection of name-value pairs that allow you to active elements using other keystrokes (see below).

Example:

var handler = function (evt) {
   $(evt.target).addClass("activated");
};
menu.items.fluid("activatable", handler);

options:

Name

Description

Values

Default

additionalBindings

An array of keycode options to use for activation.

An array of objects of the form

{
  modifier: <a modifier keycode>, // e.g. $.ui.keyCode.SHIFT
  key: <a keycode>,   // e.g. $.ui.keyCode.DOWN
  activateHandler: <a function>
}

none

Example with options:

var handler = function (evt) {
   $(evt.target).addClass("activated");
};
/ Bind the Space, Enter, and Down Arrow keys to the activate event. 
// Notice the use of "additionalBindings," which is required only for the Down Arrow Key.
// By default, Space and Enter are set up for you.
var opts = {
    additionalBindings: {
        modifier: null,
        key: $.ui.keyCode.DOWN,
        activateHandler: alternateActivate
    }
};
menu.items.fluid("activatable", [handler, opts]);
On This Page
Still need help?

Join the infusion-users mailing list and ask your questions there.


activate

jQuery().fluid("activate");

Activates all matched elements using the default activation handler. Note that if the user has made the elements "activatable" using activatable(), that is the handler that will be used.

Example:

menu.items[selectedIndex].fluid("activate");

selectable

jQuery().fluid("selectable", options)

Invoked on a JQuery which is a "container" node: makes all matched elements descended from the container selectable with the arrow keys. Custom handlers can be provided to inject custom styling and logic.

Arguments:

Name

Description

options

(Optional) A collection of name-value pairs that let you modify the plugin's default selection behaviour (see below).

options:

Name

Description

Values

Default

selectableElements

The set of nodes (a JQuery) which are to form the selectable set (these should all be nested within the DOM element representing the "container")

jQuery

selectableElements: null

selectableSelector

A selector which will be used to locate the selectableElements if they are not set manually, by matching nodes within the container

string

selectableSelector: ".selectable"

onSelect

A function to be invoked when an element is selected

function

onSelect: null

onUnselect

A function to invoked when an element is unselected

function

onUnselect: null

onLeaveContainer

A function to be invoked when focus leaves the container

function

onLeaveContainer: null

direction

Indicates the orientation of the selectable elements. This value will be used to determine the appropriate mapping for next and previous.

fluid.a11y.orientation.HORIZONTAL
fluid.a11y.orientation.VERTICAL

direction: fluid.a11y.orientation.VERTICAL

autoSelectFirstItem

Indicates whether or not focus should be moved to the first child of the container (or to the last selected child, depending on rememberSelectionState)

boolean

autoSelectFirstItem: true

rememberSelectionState

Indicates whether or not to keep track of which child element was most recently selected.

boolean

rememberSelectionState: true

New in v1.3:
noBubbleListeners

Useful in cases where the selectable items may have keystrokes swallowing default handlers. If this option is true, the arrow key handler will be bound to the selectables themselves instead of their container.

boolean

noBubbleListeners: false

Example:

menu.container.fluid("selectable", {
    selectableSelector: ".menuItem",
    onSelect: function (evt) {
        <function to show sub menu>
    },
    onUnselect: function (evt) {
        <function to hide sub menu>
    },
    autoSelectFirstItem: false,
    rememberSelectionState: false
});

currentSelection

jQuery().fluid("selectable.currentSelection");

Gets the currently selected element (invoked on the container element)

Example:

var currentMenuItem = menu.container.fluid("selectable.currentSelection");

select, selectNext, selectPrevious

jQuery().fluid("selectable.selectNext");
jQuery().fluid("selectable.selectPrevious");
jQuery().fluid("selectable.select", elementToSelect);

Selects the next, previous, or specified element in the list of selectables (invoked on the jQuery for the container element)

Arguments:

Name

Description

elementToSelect

The element to select

Examples:

menu.container.fluid("selectable.select", secondMenuElement);
menu.container.fluid("selectable.selectNext");  // will select third item
menu.container.fluid("selectable.selectPrevious");  // will select second item again

tabbable

jQuery().fluid("tabbable")

Adds all matched elements to the tab order by giving them a tabindex attribute of "0." Note that if a matched element already has a tabindex value that places it in the tab order, the value is unchanged.

Example:

menu.container.fluid("tabbable");

tabindex

Deprecated. This code is now available in jQuery core. Use jQuery.attr("tabindex") instead.

jQuery().fluid("tabindex")

Gets the tabindex value of the first matched element. If the element doesn't have a tabindex attribute, undefined is returned. The value returned is normalized to a Number, since browser implementations vary.

jQuery().fluid("tabindex", value)

Sets the tabindex value on all matched elements. value can be either a String or a Number, but valid tabindex attributes need to be integers.

Arguments:

Name

Description

value

The desired integer tabindex value. Can be either a String or a Number.


Dependencies

The Keyboard Accessibility Plugin dependencies can be met by including the minified InfusionAll.js file in the header of the HTML file:

<script type="text/javascript" src="InfusionAll.js"></script>

Alternatively, the individual file requirements are:

In v1.2 and earlier:

<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script>

As of v1.3:

<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="framework/core/js/FluidDocument.js"></script> <!-- New in v1.3 -->
<script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script>

2 Comments

  1. Hi,

    I found an issue with this plugin. The plugin has a method called makeElementsTabFocussable but that function does not follow the w3c html specification for tabindex (http://www.w3.org/TR/html401/interact/forms.html#adef-tabindex) which causes issues with tabbing. According to the W3C, the tabindex of a foccusable elements should be a positive integer but in the code, a focussable element is given a vale of 0 (line 260 of the jquery.keyboard.a11y.js)

    Changing the value 0 to 1 significantly improves the keyboard navigation of pages using this plugin.

  2. Hi Laurent,

    Giving an element a tabindex of 0 informs the browser that it should be part of the natural tab order of the document. You can see from the HTML 4 specification link you provided that the tabindex &quot;value must be a number between 0 and 32767."

    We use this technique to enable elements that otherwise wouldn&#39;t naturally receive focus (divs and spans, for example) to be part of the natural tab order of the document. It&#39;s standard practice, compliant with the specification, and heavily QA tested across all A-Grade browsers and a wide variety of real-world applications.

    Your change to make the plugin set the tabindex to 1 has quite a different meaning, and would cause bugs in many applications. A tabindex value of 1 says &quot;make this element the very first thing that is focused by the Tab key, regardless of its position in the DOM.&quot;

    Here&#39;s an overview of DHTML accessibility techniques, which should provide some background information about how keyboard navigation works:

    http://wiki.fluidproject.org/display/fluid/An+Overview+of+DHTML+Accessibility

    I&#39;m thinking that perhaps the issues you&#39;re experiencing with keyboard navigation are due to something else. I&#39;d be happy to help you troubleshoot the issue if you&#39;ll post specific details about the problem to the infusion-users list. Here&#39;s the link to subscribe to the list:

    http://fluidproject.org/mailman/listinfo/infusion-users

    Hope this helps,

    Colin