The Focus Manager Node Plugin makes it easy to manage focus among * a Node's descendants. Primarily intended to help with widget development, * the Focus Manager Node Plugin can be used to improve the keyboard * accessibility of widgets.
* ** When designing widgets that manage a set of descendant controls (i.e. buttons * in a toolbar, tabs in a tablist, menuitems in a menu, etc.) it is important to * limit the number of descendants in the browser's default tab flow. The fewer * number of descendants in the default tab flow, the easier it is for keyboard * users to navigate between widgets by pressing the tab key. When a widget has * focus it should provide a set of shortcut keys (typically the arrow keys) * to move focus among its descendants. *
* *
* To this end, the Focus Manager Node Plugin makes it easy to define a Node's
* focusable descendants, define which descendant should be in the default tab
* flow, and define the keys that move focus among each descendant.
* Additionally, as the CSS
* :focus
* pseudo class is not supported on all elements in all
* A-Grade browsers,
* the Focus Manager Node Plugin provides an easy, cross-browser means of
* styling focus.
*
plug method of Node
* and should not be instantiated directly.
* @namespace plugin
* @class NodeFocusManager
*/
NodeFocusManager = function () {
NodeFocusManager.superclass.constructor.apply(this, arguments);
};
NodeFocusManager.ATTRS = {
/**
* Boolean indicating that one of the descendants is focused.
*
* @attribute focused
* @readOnly
* @default false
* @type boolean
*/
focused: {
value: false,
readOnly: true
},
/**
* String representing the CSS selector used to define the descendant Nodes
* whose focus should be managed.
*
* @attribute descendants
* @type Y.NodeList
*/
descendants: {
getter: function (value) {
return this.get(HOST).all(value);
}
},
/**
* Node, or index of the Node, representing the descendant that is either
* focused or is focusable (tabIndex attribute is set to 0).
* The value cannot represent a disabled descendant Node. Use a value of -1
* to remove all descendant Nodes from the default tab flow.
* If no value is specified, the active descendant will be inferred using
* the following criteria:
tabIndex attribute of each descendant and
* using the first descendant whose tabIndex attribute is set
* to 0{ next: "down:40", previous: "down:38" }. The value for the
* "next" and "previous" properties are used to attach
* key event listeners. See
* the Using the key Event section of
* the Event documentation for more information on "key" event listeners.
*
* @attribute keys
* @type Object
*/
keys: {
value: {
next: null,
previous: null
}
},
/**
* String representing the name of class applied to the focused active
* descendant Node. Can also be an object literal used to define both the
* class name, and the Node to which the class should be applied. If using
* an object literal, the format is:
* { className: "focus", fn: myFunction }. The function
* referenced by the fn property in the object literal will be
* passed a reference to the currently focused active descendant Node.
*
* @attribute focusClass
* @type String|Object
*/
focusClass: { },
/**
* Boolean indicating if focus should be set to the first/last descendant
* when the end or beginning of the descendants has been reached.
*
* @attribute circular
* @type Boolean
*/
circular: {
value: true
}
};
Y.extend(NodeFocusManager, Y.Plugin.Base, {
// Protected properties
// Boolean indicating if the NodeFocusManager is active.
_stopped: true,
// NodeList representing the descendants selected via the
// "descendants" attribute.
_descendants: null,
// Object literal mapping the IDs of each descendant to its index in the
// "_descendants" NodeList.
_descendantsMap: null,
// Reference to the Node instance to which the focused class (defined
// by the "focusClass" attribute) is currently applied.
_focusedNode: null,
// Number representing the index of the last descendant Node.
_lastNodeIndex: 0,
// Array of handles for event handlers used for a NodeFocusManager instance.
_eventHandlers: null,
// Protected methods
/**
* @method _initDescendants
* @description Sets the tabIndex attribute of all of the
* descendants to -1, except the active descendant, whose
* tabIndex attribute is set to 0.
* @protected
*/
_initDescendants: function () {
var descendants = this.get("descendants"),
descendantsMap = {},
nFirstEnabled = -1,
nDescendants,
nActiveDescendant = this.get(ACTIVE_DESCENDANT),
oNode,
sID,
i = 0;
if (Lang.isUndefined(nActiveDescendant)) {
nActiveDescendant = -1;
}
if (descendants) {
nDescendants = descendants.size();
for (i = 0; i < nDescendants; i++) {
oNode = descendants.item(i);
if (nFirstEnabled === -1 && !oNode.get(DISABLED)) {
nFirstEnabled = i;
}
// If the user didn't specify a value for the
// "activeDescendant" attribute try to infer it from
// the markup.
// Need to pass "2" when using "getAttribute" for IE to get
// the attribute value as it is set in the markup.
// Need to use "parseInt" because IE always returns the
// value as a number, whereas all other browsers return
// the attribute as a string when accessed
// via "getAttribute".
if (nActiveDescendant < 0 &&
parseInt(oNode.getAttribute(TAB_INDEX, 2), 10) === 0) {
nActiveDescendant = i;
}
if (oNode) {
oNode.set(TAB_INDEX, -1);
}
sID = oNode.get(ID);
if (!sID) {
sID = Y.guid();
oNode.set(ID, sID);
}
descendantsMap[sID] = i;
}
// If the user didn't specify a value for the
// "activeDescendant" attribute and no default value could be
// determined from the markup, then default to 0.
if (nActiveDescendant < 0) {
nActiveDescendant = 0;
}
oNode = descendants.item(nActiveDescendant);
// Check to make sure the active descendant isn't disabled,
// and fall back to the first enabled descendant if it is.
if (!oNode || oNode.get(DISABLED)) {
oNode = descendants.item(nFirstEnabled);
nActiveDescendant = nFirstEnabled;
}
this._lastNodeIndex = nDescendants - 1;
this._descendants = descendants;
this._descendantsMap = descendantsMap;
this.set(ACTIVE_DESCENDANT, nActiveDescendant);
// Need to set the "tabIndex" attribute here, since the
// "activeDescendantChange" event handler used to manage
// the setting of the "tabIndex" attribute isn't wired up yet.
if (oNode) {
oNode.set(TAB_INDEX, 0);
}
}
},
/**
* @method _isDescendant
* @description Determines if the specified Node instance is a descendant
* managed by the Focus Manager.
* @param node {Node} Node instance to be checked.
* @return {Boolean} Boolean indicating if the specified Node instance is a
* descendant managed by the Focus Manager.
* @protected
*/
_isDescendant: function (node) {
return (node.get(ID) in this._descendantsMap);
},
/**
* @method _removeFocusClass
* @description Removes the class name representing focus (as specified by
* the "focusClass" attribute) from the Node instance to which it is
* currently applied.
* @protected
*/
_removeFocusClass: function () {
var oFocusedNode = this._focusedNode,
focusClass = this.get(FOCUS_CLASS),
sClassName;
if (focusClass) {
sClassName = Lang.isString(focusClass) ?
focusClass : focusClass.className;
}
if (oFocusedNode && sClassName) {
oFocusedNode.removeClass(sClassName);
}
},
/**
* @method _detachKeyHandler
* @description Detaches the "key" event handlers used to support the "keys"
* attribute.
* @protected
*/
_detachKeyHandler: function () {
var prevKeyHandler = this._prevKeyHandler,
nextKeyHandler = this._nextKeyHandler;
if (prevKeyHandler) {
prevKeyHandler.detach();
}
if (nextKeyHandler) {
nextKeyHandler.detach();
}
},
/**
* @method _preventScroll
* @description Prevents the viewport from scolling when the user presses
* the up, down, left, or right key.
* @protected
*/
_preventScroll: function (event) {
if (scrollKeys[event.keyCode] && this._isDescendant(event.target)) {
event.preventDefault();
}
},
/**
* @method _fireClick
* @description Fires the click event if the enter key is pressed while
* focused on an HTML element that is not natively clickable.
* @protected
*/
_fireClick: function (event) {
var oTarget = event.target,
sNodeName = oTarget.get("nodeName").toLowerCase();
if (event.keyCode === 13 && (!clickableElements[sNodeName] ||
(sNodeName === "a" && !oTarget.getAttribute("href")))) {
oTarget.simulate("click");
}
},
/**
* @method _attachKeyHandler
* @description Attaches the "key" event handlers used to support the "keys"
* attribute.
* @protected
*/
_attachKeyHandler: function () {
this._detachKeyHandler();
var sNextKey = this.get("keys.next"),
sPrevKey = this.get("keys.previous"),
oNode = this.get(HOST),
aHandlers = this._eventHandlers;
if (sPrevKey) {
this._prevKeyHandler =
Y.on(KEY, Y.bind(this._focusPrevious, this), oNode, sPrevKey);
}
if (sNextKey) {
this._nextKeyHandler =
Y.on(KEY, Y.bind(this._focusNext, this), oNode, sNextKey);
}
// In Opera it is necessary to call the "preventDefault" method in
// response to the user pressing the arrow keys in order to prevent
// the viewport from scrolling when the user is moving focus among
// the focusable descendants.
if (UA.opera) {
aHandlers.push(oNode.on("keypress", this._preventScroll, this));
}
// For all browsers except Opera: HTML elements that are not natively
// focusable but made focusable via the tabIndex attribute don't
// fire a click event when the user presses the enter key. It is
// possible to work around this problem by simplying dispatching a
// click event in response to the user pressing the enter key.
if (!UA.opera) {
aHandlers.push(oNode.on("keypress", this._fireClick, this));
}
},
/**
* @method _detachEventHandlers
* @description Detaches all event handlers used by the Focus Manager.
* @protected
*/
_detachEventHandlers: function () {
this._detachKeyHandler();
var aHandlers = this._eventHandlers;
if (aHandlers) {
Y.Array.each(aHandlers, function (handle) {
handle.detach();
});
this._eventHandlers = null;
}
},
/**
* @method _detachEventHandlers
* @description Attaches all event handlers used by the Focus Manager.
* @protected
*/
_attachEventHandlers: function () {
var descendants = this._descendants,
aHandlers,
oDocument,
handle;
if (descendants && descendants.size()) {
aHandlers = this._eventHandlers || [];
oDocument = this.get(HOST).get("ownerDocument");
if (aHandlers.length === 0) {
aHandlers.push(oDocument.on("focus", this._onDocFocus, this));
aHandlers.push(oDocument.on("mousedown",
this._onDocMouseDown, this));
aHandlers.push(
this.after("keysChange", this._attachKeyHandler));
aHandlers.push(
this.after("descendantsChange", this._initDescendants));
aHandlers.push(
this.after(ACTIVE_DESCENDANT_CHANGE,
this._afterActiveDescendantChange));
// For performance: defer attaching all key-related event
// handlers until the first time one of the specified
// descendants receives focus.
handle = this.after("focusedChange", Y.bind(function (event) {
if (event.newVal) {
this._attachKeyHandler();
// Detach this "focusedChange" handler so that the
// key-related handlers only get attached once.
handle.detach();
}
}, this));
aHandlers.push(handle);
}
this._eventHandlers = aHandlers;
}
},
// Protected event handlers
/**
* @method _onDocMouseDown
* @description "mousedown" event handler for the owner document of the
* Focus Manager's Node.
* @protected
* @param event {Object} Object representing the DOM event.
*/
_onDocMouseDown: function (event) {
var oHost = this.get(HOST),
oTarget = event.target,
bChildNode = oHost.contains(oTarget),
node,
getFocusable = function (node) {
var returnVal = false;
if (!node.compareTo(oHost)) {
returnVal = this._isDescendant(node) ? node :
getFocusable.call(this, node.get("parentNode"));
}
return returnVal;
};
if (bChildNode) {
// Check to make sure that the target isn't a child node of one
// of the focusable descendants.
node = getFocusable.call(this, oTarget);
if (node) {
oTarget = node;
}
else if (!node && this.get(FOCUSED)) {
// The target was a non-focusable descendant of the root
// node, so the "focused" attribute should be set to false.
this._set(FOCUSED, false);
this._onDocFocus(event);
}
}
if (bChildNode && this._isDescendant(oTarget)) {
// Fix general problem in Webkit: mousing down on a button or an
// anchor element doesn't focus it.
// For all browsers: makes sure that the descendant that
// was the target of the mousedown event is now considered the
// active descendant.
this.focus(oTarget);
}
else if (UA.webkit && this.get(FOCUSED) &&
(!bChildNode || (bChildNode && !this._isDescendant(oTarget)))) {
// Fix for Webkit:
// Document doesn't receive focus in Webkit when the user mouses
// down on it, so the "focused" attribute won't get set to the
// correct value.
// The goal is to force a blur if the user moused down on
// either: 1) A descendant node, but not one that managed by
// the FocusManager, or 2) an element outside of the
// FocusManager
this._set(FOCUSED, false);
this._onDocFocus(event);
}
},
/**
* @method _onDocFocus
* @description "focus" event handler for the owner document of the
* Focus Manager's Node.
* @protected
* @param event {Object} Object representing the DOM event.
*/
_onDocFocus: function (event) {
var oTarget = this._focusTarget || event.target,
bFocused = this.get(FOCUSED),
focusClass = this.get(FOCUS_CLASS),
oFocusedNode = this._focusedNode,
bInCollection;
if (this._focusTarget) {
this._focusTarget = null;
}
if (this.get(HOST).contains(oTarget)) {
// The target is a descendant of the root Node.
bInCollection = this._isDescendant(oTarget);
if (!bFocused && bInCollection) {
// The user has focused a focusable descendant.
bFocused = true;
}
else if (bFocused && !bInCollection) {
// The user has focused a child of the root Node that is
// not one of the descendants managed by this Focus Manager
// so clear the currently focused descendant.
bFocused = false;
}
}
else {
// The target is some other node in the document.
bFocused = false;
}
if (focusClass) {
if (oFocusedNode && (!oFocusedNode.compareTo(oTarget) || !bFocused)) {
this._removeFocusClass();
}
if (bInCollection && bFocused) {
if (focusClass.fn) {
oTarget = focusClass.fn(oTarget);
oTarget.addClass(focusClass.className);
}
else {
oTarget.addClass(focusClass);
}
this._focusedNode = oTarget;
}
}
this._set(FOCUSED, bFocused);
},
/**
* @method _focusNext
* @description Keydown event handler that moves focus to the next
* enabled descendant.
* @protected
* @param event {Object} Object representing the DOM event.
* @param activeDescendant {Number} Number representing the index of the
* next descendant to be focused
*/
_focusNext: function (event, activeDescendant) {
var nActiveDescendant = activeDescendant || this.get(ACTIVE_DESCENDANT),
oNode;
if (this._isDescendant(event.target) &&
(nActiveDescendant <= this._lastNodeIndex)) {
nActiveDescendant = nActiveDescendant + 1;
if (nActiveDescendant === (this._lastNodeIndex + 1) &&
this.get(CIRCULAR)) {
nActiveDescendant = 0;
}
oNode = this._descendants.item(nActiveDescendant);
if (oNode) {
if (oNode.get("disabled")) {
this._focusNext(event, nActiveDescendant);
}
else {
this.focus(nActiveDescendant);
}
}
}
this._preventScroll(event);
},
/**
* @method _focusPrevious
* @description Keydown event handler that moves focus to the previous
* enabled descendant.
* @protected
* @param event {Object} Object representing the DOM event.
* @param activeDescendant {Number} Number representing the index of the
* next descendant to be focused.
*/
_focusPrevious: function (event, activeDescendant) {
var nActiveDescendant = activeDescendant || this.get(ACTIVE_DESCENDANT),
oNode;
if (this._isDescendant(event.target) && nActiveDescendant >= 0) {
nActiveDescendant = nActiveDescendant - 1;
if (nActiveDescendant === -1 && this.get(CIRCULAR)) {
nActiveDescendant = this._lastNodeIndex;
}
oNode = this._descendants.item(nActiveDescendant);
if (oNode) {
if (oNode.get("disabled")) {
this._focusPrevious(event, nActiveDescendant);
}
else {
this.focus(nActiveDescendant);
}
}
}
this._preventScroll(event);
},
/**
* @method _afterActiveDescendantChange
* @description afterChange event handler for the
* "activeDescendant" attribute.
* @protected
* @param event {Object} Object representing the change event.
*/
_afterActiveDescendantChange: function (event) {
var oNode = this._descendants.item(event.prevVal);
if (oNode) {
oNode.set(TAB_INDEX, -1);
}
oNode = this._descendants.item(event.newVal);
if (oNode) {
oNode.set(TAB_INDEX, 0);
}
},
// Public methods
initializer: function (config) {
this.start();
},
destructor: function () {
this.stop();
this.get(HOST).focusManager = null;
},
/**
* @method focus
* @description Focuses the active descendant and sets the
* focused attribute to true.
* @param index {Number} Optional. Number representing the index of the
* descendant to be set as the active descendant.
* @param index {Node} Optional. Node instance representing the
* descendant to be set as the active descendant.
*/
focus: function (index) {
if (Lang.isUndefined(index)) {
index = this.get(ACTIVE_DESCENDANT);
}
this.set(ACTIVE_DESCENDANT, index, { src: UI });
var oNode = this._descendants.item(this.get(ACTIVE_DESCENDANT));
if (oNode) {
oNode.focus();
// In Opera focusing a