autocomplete-list.js revision c6f34ab5211f002c70255bb7423b57e2bbbf39ff
/**
Traditional autocomplete dropdown list widget, just like Mom used to make.
@module autocomplete
@submodule autocomplete-list
**/
/**
Traditional autocomplete dropdown list widget, just like Mom used to make.
@class AutoCompleteList
@extends Widget
@uses AutoCompleteBase
@uses WidgetPosition
@uses WidgetPositionAlign
@constructor
@param {Object} config Configuration object.
**/
YArray = Y.Array,
// Whether or not we need an iframe shim.
// keyCode constants.
KEY_TAB = 9,
// String shorthand.
_CLASS_ITEM = '_CLASS_ITEM',
_CLASS_ITEM_ACTIVE = '_CLASS_ITEM_ACTIVE',
_CLASS_ITEM_HOVER = '_CLASS_ITEM_HOVER',
_SELECTOR_ITEM = '_SELECTOR_ITEM',
ACTIVE_ITEM = 'activeItem',
ALWAYS_SHOW_LIST = 'alwaysShowList',
CIRCULAR = 'circular',
HOVERED_ITEM = 'hoveredItem',
ID = 'id',
ITEM = 'item',
LIST = 'list',
RESULT = 'result',
RESULTS = 'results',
VISIBLE = 'visible',
WIDTH = 'width',
// Event names.
EVT_SELECT = 'select',
], {
// -- Prototype Properties -------------------------------------------------
ARIA_TEMPLATE: '<div/>',
ITEM_TEMPLATE: '<li/>',
LIST_TEMPLATE: '<ul/>',
// Widget automatically attaches delegated event handlers to everything in
// Y.Node.DOM_EVENTS, including synthetic events. Since Widget's event
// delegation won't work for the synthetic valuechange event, and since
// it creates a name collision between the backcompat "valueChange" synth
// event alias and AutoCompleteList's "valueChange" event for the "value"
// attr, this hack is necessary in order to prevent Widget from attaching
// valuechange handlers.
UI_EVENTS: (function () {
delete uiEvents.valuechange;
delete uiEvents.valueChange;
return uiEvents;
}()),
// -- Lifecycle Prototype Methods ------------------------------------------
initializer: function () {
if (!inputNode) {
Y.error('No inputNode specified.');
return;
}
this._inputNode = inputNode;
this._listEvents = [];
// This ensures that the list is rendered inside the same parent as the
// input node by default, which is necessary for proper ARIA support.
// Cache commonly used classnames and selectors for performance.
/**
Fires when an autocomplete suggestion is selected from the list,
typically via a keyboard action or mouse click.
@event select
@param {Node} itemNode List item node that was selected.
@param {Object} result AutoComplete result object.
@preventable _defSelectFn
**/
this.publish(EVT_SELECT, {
defaultFn: this._defSelectFn
});
},
destructor: function () {
while (this._listEvents.length) {
}
if (this._ariaNode) {
}
},
bindUI: function () {
this._bindInput();
this._bindList();
},
renderUI: function () {
var ariaNode = this._createAriaNode(),
inputNode = this._inputNode,
listNode = this._createListNode(),
'aria-autocomplete': LIST,
'aria-expanded' : false,
});
// ARIA node must be outside the widget or announcements won't be made
// when the widget is hidden.
// Add an iframe shim for IE6.
if (useShim) {
}
// Force position: absolute on the boundingBox. This works around a
// potential CSS loading race condition in Gecko that can cause the
// boundingBox to become relatively positioned, which is all kinds of
// no good.
this._boundingBox = boundingBox;
this._contentBox = contentBox;
this._parentNode = parentNode;
},
syncUI: function () {
// No need to call _syncPosition() here; the other _sync methods will
// call it when necessary.
this._syncResults();
this._syncVisibility();
},
// -- Public Prototype Methods ---------------------------------------------
/**
Hides the list, unless the `alwaysShowList` attribute is `true`.
@method hide
@see show
@chainable
**/
hide: function () {
},
/**
Selects the specified _itemNode_, or the current `activeItem` if _itemNode_
is not specified.
@method selectItem
@param {Node} [itemNode] Item node to select.
@param {EventFacade} [originEvent] Event that triggered the selection, if
any.
@chainable
**/
if (itemNode) {
return this;
}
} else {
if (!itemNode) {
return this;
}
}
this.fire(EVT_SELECT, {
originEvent: originEvent || null,
});
return this;
},
// -- Protected Prototype Methods ------------------------------------------
/**
Activates the next item after the currently active item. If there is no next
item and the `circular` attribute is `true`, focus will wrap back to the
input node.
@method _activateNextItem
@chainable
@protected
**/
_activateNextItem: function () {
if (item) {
} else {
nextItem = this._getFirstItemNode();
}
return this;
},
/**
Activates the item previous to the currently active item. If there is no
previous item and the `circular` attribute is `true`, focus will wrap back
to the input node.
@method _activatePrevItem
@chainable
@protected
**/
_activatePrevItem: function () {
return this;
},
/**
Appends the specified result _items_ to the list inside a new item node.
@method _add
@param {Array|Node|HTMLElement|String} items Result item or array of
result items.
@return {NodeList} Added nodes.
@protected
**/
var itemNodes = [];
}, this);
return itemNodes;
},
/**
Updates the ARIA live region with the specified message.
@method _ariaSay
@param {String} stringId String id (from the `strings` attribute) of the
message to speak.
@param {Object} [subs] Substitutions for placeholders in the string.
@protected
**/
},
/**
Binds `inputNode` events and behavior.
@method _bindInput
@protected
**/
_bindInput: function () {
var inputNode = this._inputNode,
// Null align means we can auto-align. Set align to false to prevent
// auto-alignment, or a valid alignment config to customize the
// alignment.
if (this.get('align') === null) {
// If this is a tokenInput, align with its bounding box.
// Otherwise, align with the inputNode. Bit of a cheat.
this.set('align', {
});
// If no width config is set, attempt to set the list's width to the
// width of the alignment node. If the alignment node's width is
// falsy, do nothing.
}
}
// Attach inputNode events.
this._listEvents.concat([
]);
},
/**
Binds list events.
@method _bindList
@protected
**/
_bindList: function () {
this._listEvents.concat([
this.after({
blur : this._afterListBlur,
focus : this._afterListFocus,
mouseover: this._afterMouseOver,
mouseout : this._afterMouseOut,
resultsChange : this._afterResultsChange,
visibleChange : this._afterVisibleChange
}),
this[_SELECTOR_ITEM], this)
]);
},
/**
Clears the contents of the tray.
@method _clear
@protected
**/
_clear: function () {
this.set(ACTIVE_ITEM, null);
this._set(HOVERED_ITEM, null);
},
/**
Creates and returns an ARIA live region node.
@method _createAriaNode
@return {Node} ARIA node.
@protected
**/
_createAriaNode: function () {
'aria-live': 'polite',
role : 'status'
});
},
/**
Creates and returns an item node with the specified _content_.
@method _createItemNode
@param {Object} result Result object.
@return {Node} Item node.
@protected
**/
_createItemNode: function (result) {
role: 'option'
},
/**
Creates and returns a list node. If the `listNode` attribute is already set
to an existing node, that node will be used.
@method _createListNode
@return {Node} List node.
@protected
**/
_createListNode: function () {
role: 'listbox'
});
return listNode;
},
/**
Gets the first item node in the list, or `null` if the list is empty.
@method _getFirstItemNode
@return {Node|null}
@protected
**/
_getFirstItemNode: function () {
},
/**
Gets the last item node in the list, or `null` if the list is empty.
@method _getLastItemNode
@return {Node|null}
@protected
**/
_getLastItemNode: function () {
},
/**
Synchronizes the result list's position and alignment.
@method _syncPosition
@protected
**/
_syncPosition: function () {
// Force WidgetPositionAlign to refresh its alignment.
this._syncUIPosAlign();
// Resize the IE6 iframe shim to match the list's dimensions.
this._syncShim();
},
/**
Synchronizes the results displayed in the list with those in the _results_
argument, or with the `results` attribute if an argument is not provided.
@method _syncResults
@param {Array} [results] Results.
@protected
**/
_syncResults: function (results) {
if (!results) {
}
this._clear();
this._ariaSay('items_available');
}
this._syncPosition();
}
},
/**
Synchronizes the size of the iframe shim used for IE6 and lower. In other
browsers, this method is a noop.
@method _syncShim
@protected
**/
} : function () {},
/**
Synchronizes the visibility of the tray with the _visible_ argument, or with
the `visible` attribute if an argument is not provided.
@method _syncVisibility
@param {Boolean} [visible] Visibility.
@protected
**/
_syncVisibility: function (visible) {
if (this.get(ALWAYS_SHOW_LIST)) {
visible = true;
}
if (typeof visible === 'undefined') {
}
if (visible) {
this._syncPosition();
} else {
this.set(ACTIVE_ITEM, null);
this._set(HOVERED_ITEM, null);
// Force a reflow to work around a glitch in IE6 and 7 where some of
// the contents of the list will sometimes remain visible after the
// container is hidden.
}
// In some pages, IE7 fails to repaint the contents of the list after it
// becomes visible. Toggling a bogus class on the body forces a repaint
// that fixes the issue.
Y.one('body')
.addClass('yui3-ie7-sucks')
.removeClass('yui3-ie7-sucks');
}
},
// -- Protected Event Handlers ---------------------------------------------
/**
Handles `activeItemChange` events.
@method _afterActiveItemChange
@param {EventFacade} e
@protected
**/
_afterActiveItemChange: function (e) {
var inputNode = this._inputNode,
node;
// The previous item may have disappeared by the time this handler runs,
// so we need to be careful.
}
if (newVal) {
} else {
}
if (this.get('scrollIntoView')) {
}
}
},
/**
Handles `alwaysShowListChange` events.
@method _afterAlwaysShowListChange
@param {EventFacade} e
@protected
**/
_afterAlwaysShowListChange: function (e) {
},
/**
Handles click events on the document. If the click is outside both the
input node and the bounding box, the list will be hidden.
@method _afterDocClick
@param {EventFacade} e
@protected
@since 3.5.0
**/
_afterDocClick: function (e) {
var boundingBox = this._boundingBox,
this.hide();
}
},
/**
Handles `hoveredItemChange` events.
@method _afterHoveredItemChange
@param {EventFacade} e
@protected
**/
_afterHoveredItemChange: function (e) {
if (prevVal) {
}
if (newVal) {
}
},
/**
Handles list blur events.
@method _afterListBlur
@protected
**/
_afterListBlur: function () {
this._listFocused = false;
// Hide the list unless focus switched to the input node.
if (!this._listInputFocused) {
this.hide();
}
},
/**
Handles list focus events.
@method _afterListFocus
@protected
**/
_afterListFocus: function () {
this._listFocused = true;
},
/**
Handles `inputNode` blur events.
@method _afterListInputBlur
@protected
**/
_afterListInputBlur: function () {
this._listInputFocused = false;
// Hide the list on inputNode blur events, unless the mouse is currently
// over the list (which indicates that the user is probably interacting
// with it). The _lastInputKey property comes from the
// autocomplete-list-keys module.
if ((!this._mouseOverList && !this._listFocused)
|| this._lastInputKey === KEY_TAB) {
this.hide();
}
},
/**
Handles `inputNode` focus events.
@method _afterListInputFocus
@protected
**/
_afterListInputFocus: function () {
this._listInputFocused = true;
},
/**
Handles `mouseover` events.
@method _afterMouseOver
@param {EventFacade} e
@protected
**/
_afterMouseOver: function (e) {
this._mouseOverList = true;
if (itemNode) {
}
},
/**
Handles `mouseout` events.
@method _afterMouseOut
@param {EventFacade} e
@protected
**/
_afterMouseOut: function () {
this._mouseOverList = false;
this._set(HOVERED_ITEM, null);
},
/**
Handles `resultsChange` events.
@method _afterResultsChange
@param {EventFacade} e
@protected
**/
_afterResultsChange: function (e) {
this._syncResults(e.newVal);
if (!this.get(ALWAYS_SHOW_LIST)) {
}
},
/**
Handles `visibleChange` events.
@method _afterVisibleChange
@param {EventFacade} e
@protected
**/
_afterVisibleChange: function (e) {
this._syncVisibility(!!e.newVal);
},
/**
Delegated event handler for item `click` events.
@method _onItemClick
@param {EventFacade} e
@protected
**/
_onItemClick: function (e) {
var itemNode = e.currentTarget;
this.selectItem(itemNode, e);
},
// -- Protected Default Event Handlers -------------------------------------
/**
Default `select` event handler.
@method _defSelectFn
@param {EventFacade} e
@protected
**/
_defSelectFn: function (e) {
// TODO: support typeahead completion, etc.
this._inputNode.focus();
this._updateValue(text);
this.hide();
}
}, {
ATTRS: {
/**
If `true`, the first item in the list will be activated by default when
the list is initially displayed and when results change.
@attribute activateFirstItem
@type Boolean
@default false
**/
value: false
},
/**
Item that's currently active, if any. When the user presses enter, this
is the item that will be selected.
@attribute activeItem
@type Node
**/
activeItem: {
value: null
},
/**
If `true`, the list will remain visible even when there are no results
to display.
@attribute alwaysShowList
@type Boolean
@default false
**/
value: false
},
/**
If `true`, keyboard navigation will wrap around to the opposite end of
the list when navigating past the first or last item.
@attribute circular
@type Boolean
@default true
**/
circular: {
value: true
},
/**
Item currently being hovered over by the mouse, if any.
@attribute hoveredItem
@type Node|null
@readOnly
**/
hoveredItem: {
readOnly: true,
value: null
},
/**
Node that will contain result items.
@attribute listNode
@type Node|null
@initOnly
**/
listNode: {
writeOnce: 'initOnly',
value: null
},
/**
If `true`, the viewport will be scrolled to ensure that the active list
item is visible when necessary.
@attribute scrollIntoView
@type Boolean
@default false
**/
value: false
},
/**
Translatable strings used by the AutoCompleteList widget.
@attribute strings
@type Object
**/
strings: {
valueFn: function () {
}
},
/**
If `true`, pressing the tab key while the list is visible will select
the active item, if any.
@attribute tabSelect
@type Boolean
@default true
**/
tabSelect: {
value: true
},
// The "visible" attribute is documented in Widget.
visible: {
value: false
}
},
});
Y.AutoCompleteList = List;
/**
Alias for <a href="AutoCompleteList.html">`AutoCompleteList`</a>. See that class
for API docs.
@class AutoComplete
**/
Y.AutoComplete = List;