Getting Started

To include the source files for FocusManager Node Plugin and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.8.0/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('node-focusmanager', function (Y) {
    // FocusManager Node Plugin is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using the Focus Manager Node Plugin

To use the Focus Manager Node Plugin, start by identifying the parent element of the elements whose focus is to be managed. For example, consider the following toolbar HTML:

<div id='toolbar'>
    <input type='button' name='btn-add' value='Add'>
    <input type='button' name='btn-edit' value='Edit'>
    <input type='button' name='btn-print' value='Print'>
    <input type='button' name='btn-delete' value='Delete'>
    <input type='button' name='btn-open' value='Open'>
    <input type='button' name='btn-save' value='Save'>
</div>

To manage the focus of each button in the toolbar, start by retrieving a Node instance representing the toolbar's root element (<div id='toolbar'>). Next, call the Node's plug method, passing in a reference to the Focus Manager Node Plugin (Y.Plugin.NodeFocusManager) as the first argument, followed by an object literal of configuration attributes as the second.

Use the descendants configuration attribute to specify the child nodes of the root node whose focus is to be managed. The descendants configuration attribute accepts a string representing a CSS selector, making it very easy to identify the elements whose focus should be managed. For the toolbar, a value of 'input' will be passed as the value of the descendants configuration attribute.

Use the keys configuration attribute to identify which keys move focus between each of the specified descendant Nodes. The keys configuration attribute accepts an object literal, the format of which is { next: 'down:40', previous: 'down:38' }. The value for the next and previous sub attributes are used to attach keys event listeners. Each value represents the type of event ('down' for mousedown, 'up' for mouseup, and 'press' for keypress) and key codes ('40' for the down arrow key) to use to navigate to the next/previous descendant. For the toolbar the keys configuration attribute will be set to a value of { next: 'down:39', previous: 'down:37' }, enabling the user to move focus among each button using the left and right arrows keys. (See the Using the key Event section of the Event documentation for more information on 'key' event listeners.)

//  Retrieve the Node instance representing the toolbar
//  (<div id='toolbar'>) and call the 'plug' method
//  passing in a reference to the Focus Manager Node Plugin.

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    // CSS Selector indicating the descendant Nodes whose focus to manage
    descendants: 'input',

    //  Move focus the buttons in the toolbar by pressing the left and
    //  right arrow keys
    keys: { 
        next: 'down:39', 
        previous: 'down:37' 
    }
});

Use the circular configuration attribute to indicate that focus should be directed to the first or last descendant when the user has navigated to the first or last descendant.

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    descendants: 'input',
    keys: { next: 'down:39', previous: 'down:37' },

    circular: true
});

The activeDescendant Attribute

The activeDescendant attribute represents which of the Focus Manager's descendants is either currently focused or is focusable (tabIndex attribute is set to 0). As the user moves focus among the Focus Manager's defined descendants, the activeDescendant configuration attribute is updated to remain in sync with the currently focused descendant.

The activeDescendant configuration attribute can be set two different ways: via markup or via script. To set the activeDescendant configuration attribute via markup, simply set the tabIndex attribute to 0 for the element that should be considered the active descendant. If the tabIndex attribute isn't set on any of the descendants the active descendant will be set to 0, or the index of the first enabled descendant. The following example shows how to make the second button in the toolbar the active descendant.

<div id='toolbar'>
    <input type='button' name='btn-add' value='Add'>
    <input type='button' tabindex='0' name='btn-edit' value='Edit'>
    <input type='button' name='btn-print' value='Print'>
    <input type='button' name='btn-delete' value='Delete'>
    <input type='button' name='btn-open' value='Open'>
    <input type='button' name='btn-save' value='Save'>
</div>

The activeDescendant configuration attribute can also be set via the object literal of configuration attributes passed to the plug method.

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    descendants: 'input',
    keys: { next: 'down:39', previous: 'down:37' },

    //  Make the second button in the toolbar the active descendant
    activeDescendant: 1
});

The activeDescendant configuration attribute can also be set at runtime via the set method.

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    descendants: 'input',
    keys: { next: 'down:39', previous: 'down:37' }

});

toolbar.focusManager.set('activeDescendant', 1);

Styling Focus

One of the challenges to styling the focus state of HTML elements is that support for the CSS :focus pseudo class is limited to the a element in Internet Explorer. To fix this problem, the Focus Manager Node Plugin provides a focusClass configuration attribute that makes it easy to style focus across all elements in all browsers.

The focusClass configuration attribute can be used one of two ways. The first way is to simply pass a string representing the class name to be applied to the currently focused descendant Node instance. For example, to apply a class of 'focus' to each button in the toolbar, set the the focusClass configuration attribute to a value of 'focus':

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    descendants: 'input',
    keys: { next: 'down:39', previous: 'down:37' },
    focusClass: 'focus'
});

Often styling focusable elements such as <input>s requires wrapping them in decorator elements, since <input> elements cannot have children. In such cases, it is likely the class name used to style focus would be applied to the element decorating the focused descendant, rather than the descendant itself. For this reason, it is also possible to pass an object literal as the value of the focusClass configuration attribute that defines not only the class name to be used to indicate focus, but a function used to retrieve the Node instance to which the class name should be applied. For example, if each button in the toolbar where decorated by a <span>, the 'focus' class could be applied to the parent <span> of the focused <input> using the following code:

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    descendants: 'input',
    keys: { next: 'down:39', previous: 'down:37' },
    focusClass: {
        className: 'focus', //  The class name to use
        fn: function (node) {
            //  The Node instance to which the class should be applied
            return node.get('parentNode');
        }
    }
});

As demonstrated in the example, the function passed as the value of the fn property is passed a reference to the currently focused descendant. That Node reference is then used to return the Node to which the class name is to be applied.

Managing Focus

The Focus Manager Node Plugin manages focus among its defined descendants as an atomic operation: the Focus Manager's focused configuration attribute is set to true the first time any descendant is focused, and is set to false the first time no descendant is focused. The focused configuration attribute is read only, and is set either via user interaction (the user focuses one of the defined descendant elements using either the keyboard or the mouse), or programmatically via the focus and blur methods, as illustrated in the following example:

var toolbar = Y.one('#toolbar');

toolbar.plug(Y.Plugin.NodeFocusManager, {
    descendants: 'input',
    keys: { next: 'down:39', previous: 'down:37' }
});


//  Listen for when the 'focused' attribute changes

toolbar.focusManager.after('focusedChange', function (event) {
    if (event.newVal) {
        Y.log('The toolbar has focus');
    }
    else {
        Y.log('The toolbar has lost focus');
    }
});

//  Focus the current active descendant, setting the 'focused' attribute to true
toolbar.focusManager.focus();

//  Focus the second descendant in the toolbar, making it the active descendant
//  (this won't change the 'focused' attribute, meaning the 'focusedChange'
//  event handler won't be called.)
toolbar.focusManager.focus(1);


//  Blur the current active descendant, setting the 'focused' attribute to false
//  and causing the 'focusedChange' event handler to be called.
toolbar.focusManager.blur();

Best Practices

While it is possible to use the Focus Manager Node Plugin to manage focus among descendants of any type, it is recommended to use it with elements that are natively in the the browser's default tab flow. Doing so provides two primary benefits: The first is that your code will work in all popular browsers, since some browsers don't support the tabIndex attribute on all elements. Sticking with the elements that natively support tabIndex as defined in the HTML 4.01 specification will ensure better cross-browser keyboard support.

The second benefit is that by using the set of natively focusable HTML elements, users of screen readers will still perceive the Focus Manager's defined descendants as actionable/clickable elements.