YUI recommends YUI 3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

Yahoo! UI Library

AutoComplete Widget  2.3.1

Yahoo! UI Library > autocomplete > YAHOO.widget.AutoComplete

Show Private Show Protected

Class YAHOO.widget.AutoComplete

The AutoComplete class provides the customizable functionality of a plug-and-play DHTML auto completion widget. Some key features:
  • Navigate with up/down arrow keys and/or mouse to pick a selection
  • The drop down container can "roll down" or "fly out" via configurable animation
  • UI look-and-feel customizable through CSS, including container attributes, borders, position, fonts, etc

Constructor

YAHOO.widget.AutoComplete ( elInput , elContainer , oDataSource , oConfigs )
Parameters:
elInput <HTMLElement> DOM element reference of an input field.
elInput <String> String ID of an input field.
elContainer <HTMLElement> DOM element reference of an existing DIV.
elContainer <String> String ID of an existing DIV.
oDataSource <YAHOO.widget.DataSource> DataSource instance.
oConfigs <Object> (optional) Object literal of configuration params.

Properties

allowBrowserAutocomplete - Boolean

Whether or not to allow browsers to cache user-typed input in the input field. Disabling this feature will prevent the widget from setting the autocomplete="off" on the input field. When autocomplete="off" and users click the back button after form submission, user-typed input can be prefilled by the browser from its cache. This caching of user input may not be desired for sensitive data, such as credit card numbers, in which case, implementers should consider setting allowBrowserAutocomplete to false.
Default Value: true

alwaysShowContainer - Boolean

Whether or not the results container should always be displayed. Enabling this feature displays the container when the widget is instantiated and prevents the toggling of the container to a collapsed state.
Default Value: false

animHoriz - Boolean

Whether or not to animate the expansion/collapse of the results container in the horizontal direction.
Default Value: false

animSpeed - Number

Speed of container expand/collapse animation, in seconds..
Default Value: 0.3

animVert - Boolean

Whether or not to animate the expansion/collapse of the results container in the vertical direction.
Default Value: true

autoHighlight - Boolean

Whether or not the first item in results container should be automatically highlighted on expand.
Default Value: true

dataSource - YAHOO.widget.DataSource

The DataSource object that encapsulates the data used for auto completion. This object should be an inherited object from YAHOO.widget.DataSource.

delimChar - String | String[]

Query delimiter. A single character separator for multiple delimited selections. Multiple delimiter characteres may be defined as an array of strings. A null value or empty string indicates that query results cannot be delimited. This feature is not recommended if you need forceSelection to be true.

forceSelection - Boolean

Whether or not to force the user's selection to match one of the query results. Enabling this feature essentially transforms the input field into a <select> field. This feature is not recommended with delimiter character(s) defined.
Default Value: false

highlightClassName - String

Class name of a highlighted item within results container.
Default Value: "yui-ac-highlight"

maxResultsDisplayed - Number

Maximum number of results to display in results container.
Default Value: 10

minQueryLength - Number

Number of characters that must be entered before querying for results. A negative value effectively turns off the widget. A value of 0 allows queries of null or empty string values.
Default Value: 1

prehighlightClassName - String

Class name of a pre-highlighted item within results container.

queryDelay - Number

Number of seconds to delay before submitting a query request. If a query request is received before a previous one has completed its delay, the previous request is cancelled and the new request is set to the delay. Implementers should take care when setting this value very low (i.e., less than 0.2) with low latency DataSources and the typeAhead feature enabled, as fast typers may see unexpected behavior.
Default Value: 0.2

typeAhead - Boolean

Whether or not the input field should be automatically updated with the first query result as the user types, auto-selecting the substring that the user has not typed.
Default Value: false

useIFrame - Boolean

Whether or not to use an iFrame to layer over Windows form elements in IE. Set to true only when the results container will be on top of a <select> field in IE and thus exposed to the IE z-index bug (i.e., 5.5 < IE < 7).
Default Value: false

useShadow - Boolean

Whether or not the results container should have a shadow.
Default Value: false

Methods

destroy

void destroy ( )
Nulls out the entire AutoComplete instance and related objects, removes attached event listeners, and clears out DOM elements inside the container. After calling this method, the instance reference should be expliclitly nulled by implementer, as in myDataTable = null. Use with caution!
Returns: void

doBeforeExpandContainer

Boolean doBeforeExpandContainer ( oTextbox , oContainer , sQuery , aResults )
Overridable method called before container expands allows implementers to access data and DOM elements.
Parameters:
oTextbox <HTMLElement> The text input box.
oContainer <HTMLElement> The container element.
sQuery <String> The query string.
aResults <Object[]> An array of query results.
Returns: Boolean
Return true to continue expanding container, false to cancel the expand.

doBeforeSendQuery

String doBeforeSendQuery ( sQuery )
Overridable method gives implementers access to the query before it gets sent.
Parameters:
sQuery <String> Query string.
Returns: String
Query string.

formatResult

String formatResult ( oResultItem , sQuery )
Overridable method that converts a result item object into HTML markup for display. Return data values are accessible via the oResultItem object, and the key return value will always be oResultItem[0]. Markup will be displayed within <li> element tags in the container.
Parameters:
oResultItem <Object> Result item representing one query result. Data is held in an array.
sQuery <String> The current query string.
Returns: String
HTML markup of formatted result data.

getListItemData

Object | Object[] getListItemData ( )
Public accessor to the data held in an <li> element of the results container.
Returns: Object | Object[]
Object or array of result data or null

getListItems

HTMLElement[] getListItems ( )
Public accessor to the internal array of DOM <li> elements that display query results within the results container.
Returns: HTMLElement[]
Array of <li> elements within the results container.

isContainerOpen

Boolean isContainerOpen ( )
Returns true if container is in an expanded state, false otherwise.
Returns: Boolean
Returns true if container is in an expanded state, false otherwise.

sendQuery

void sendQuery ( sQuery )
Makes query request to the DataSource.
Parameters:
sQuery <String> Query string.
Returns: void

setBody

void setBody ( sBody )
Sets HTML markup for the results container body. This markup will be inserted within a <div> tag with a class of "yui-ac-bd".
Parameters:
sBody <String> HTML markup for results container body.
Returns: void

setFooter

void setFooter ( sFooter )
Sets HTML markup for the results container footer. This markup will be inserted within a <div> tag with a class of "yui-ac-ft".
Parameters:
sFooter <String> HTML markup for results container footer.
Returns: void

setHeader

void setHeader ( sHeader )
Sets HTML markup for the results container header. This markup will be inserted within a <div> tag with a class of "yui-ac-hd".
Parameters:
sHeader <String> HTML markup for results container header.
Returns: void

toString

String toString ( )
Public accessor to the unique name of the AutoComplete instance.
Returns: String
Unique name of the AutoComplete instance.

Events

containerCollapseEvent

containerCollapseEvent ( oSelf )
Fired when the results container is collapsed.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.

containerExpandEvent

containerExpandEvent ( oSelf )
Fired when the results container is expanded.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.

dataErrorEvent

dataErrorEvent ( oSelf , sQuery )
Fired when the AutoComplete instance does not receive query results from the DataSource due to an error.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
sQuery <String> The query string.

dataRequestEvent

dataRequestEvent ( oSelf , sQuery )
Fired when the AutoComplete instance makes a query to the DataSource.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
sQuery <String> The query string.

dataReturnEvent

dataReturnEvent ( oSelf , sQuery , aResults )
Fired when the AutoComplete instance receives query results from the data source.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
sQuery <String> The query string.
aResults <Object[]> Results array.

itemArrowFromEvent

itemArrowFromEvent ( oSelf , elItem )
Fired when result item has been arrowed away from.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
elItem <HTMLElement> The <li> element item arrowed from.

itemArrowToEvent

itemArrowToEvent ( oSelf , elItem )
Fired when result item has been arrowed to.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
elItem <HTMLElement> The <li> element item arrowed to.

itemMouseOutEvent

itemMouseOutEvent ( oSelf , elItem )
Fired when result item has been moused out.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
elItem <HTMLElement> The <li> element item moused from.

itemMouseOverEvent

itemMouseOverEvent ( oSelf , elItem )
Fired when result item has been moused over.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
elItem <HTMLElement> The <li> element item moused to.

itemSelectEvent

itemSelectEvent ( oSelf , elItem , oData )
Fired when an item is selected via mouse click, ENTER key, or TAB key.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
elItem <HTMLElement> The selected <li> element item.
oData <Object> The data returned for the item, either as an object, or mapped from the schema into an array.

selectionEnforceEvent

selectionEnforceEvent ( oSelf )
Fired if forceSelection is enabled and the user's input has been cleared because it did not match one of the returned query results.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.

textboxBlurEvent

textboxBlurEvent ( oSelf )
Fired when the input field loses focus.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.

textboxFocusEvent

textboxFocusEvent ( oSelf )
Fired when the input field receives focus.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.

textboxKeyEvent

textboxKeyEvent ( oSelf , nKeycode )
Fired when the input field receives key input.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
nKeycode <Number> The keycode number.

typeAheadEvent

typeAheadEvent ( oSelf , sQuery , sPrefill )
Fired when the input field has been prefilled by the type-ahead feature.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.
sQuery <String> The query string.
sPrefill <String> The prefill string.

unmatchedItemSelectEvent

unmatchedItemSelectEvent ( oSelf )
Fired when a user selection does not match any of the displayed result items.
Parameters:
oSelf <YAHOO.widget.AutoComplete> The AutoComplete instance.


Copyright © 2007 Yahoo! Inc. All rights reserved.