Print Friendly

Class YAHOO.widget.AutoComplete

Package:YAHOO.widget
Class:AutoComplete
Extends:Object
Defined In:autocomplete.js
The AutoComplete class provides the customizable functionality of a plug-and-play DHTML auto completion widget. Some key features:

Public Properties

Property Defined By
  allowBrowserAutocomplete : Boolean AutoComplete
Whether or not to allow browsers to cache user-typed input in the input field. Disabling this feature will prevent th...
  alwaysShowContainer : Boolean AutoComplete
Whether or not the results container should always be displayed. Enabling this feature displays the container when th...
  animHoriz : Boolean AutoComplete
Whether or not to animate the expansion/collapse of the results container in the horizontal direction.
  animSpeed : Number AutoComplete
Speed of container expand/collapse animation, in seconds..
  animVert : Boolean AutoComplete
Whether or not to animate the expansion/collapse of the results container in the vertical direction.
  autoHighlight : Boolean AutoComplete
Whether or not the first item in results container should be automatically highlighted on expand.
  dataSource : Object AutoComplete
The DataSource object that encapsulates the data used for auto completion. This object should be an inherited object ...
  delimChar : String AutoComplete
Query delimiter. A single character separator for multiple delimited selections. Multiple delimiter characteres may b...
  forceSelection : Boolean AutoComplete
Whether or not to force the user's selection to match one of the query results. Enabling this feature essentially tra...
  highlighClassName : String AutoComplete
Class name of a highlighted item within results container.
  maxResultsDisplayed : Number AutoComplete
Maximum number of results to display in results container.
  minQueryLength : Number AutoComplete
Number of characters that must be entered before querying for results. A negative value effectively turns off the wid...
  prehighlightClassName : String AutoComplete
Class name of a pre-highlighted item within results container.
  queryDelay : Number AutoComplete
Number of seconds to delay before submitting a query request. If a query request is received before a previous one h...
  typeAhead : Boolean AutoComplete
Whether or not the input field should be automatically updated with the first query result as the user types, auto-se...
  useIFrame : Boolean AutoComplete
Whether or not to use an iFrame to layer over Windows form elements in IE. Set to true only when the results containe...
  useShadow : Boolean AutoComplete
Whether or not the results container should have a shadow.

Public Methods

Method Defined By
  AutoComplete(elInput {HTMLElement}, elInput {String}, elContainer {HTMLElement}, elContainer {String}, oDataSource {Object}, [oConfigs {Object}]) AutoComplete
  doBeforeExpandContainer() : Boolean AutoComplete
Overridable method called before container expands allows implementers to access data and DOM elements.
  formatResult(oResultItem {Object}, sQuery {String}) : String AutoComplete
Overridable method that converts a result item object into HTML markup for display. Return data values are accessible...
  getListItemData() : Object AutoComplete
Public accessor to the data held in an <li> element of the results container.
  getListItems() : HTMLElement[] AutoComplete
Public accessor to the internal array of DOM <li> elements that display query results within the results contai...
  isContainerOpen() : Boolean AutoComplete
Returns true if container is in an expanded state, false otherwise.
  sendQuery(sQuery {String}) : void AutoComplete
Makes query request to the DataSource.
  setBody(sHeader {String}) : void AutoComplete
Sets HTML markup for the results container body. This markup will be inserted within a <div> tag with a class o...
  setFooter(sFooter {String}) : void AutoComplete
Sets HTML markup for the results container footer. This markup will be inserted within a <div> tag with a class...
  setHeader(sHeader {String}) : void AutoComplete
Sets HTML markup for the results container header. This markup will be inserted within a <div> tag with a class...
  toString() : String AutoComplete
Public accessor to the unique name of the AutoComplete instance.

Public Events

Event Defined By
  containerCollapseEvent : (oSelf {Object}) AutoComplete
Fired when the results container is collapsed.
  containerExpandEvent : (oSelf {Object}) AutoComplete
Fired when the results container is expanded.
  dataErrorEvent : (oSelf {Object}, sQuery {String}) AutoComplete
Fired when the AutoComplete instance does not receive query results from the DataSource due to an error.
  dataRequestEvent : (oSelf {Object}, sQuery {String}) AutoComplete
Fired when the AutoComplete instance makes a query to the DataSource.
  dataReturnEvent : (oSelf {Object}, sQuery {String}, aResults {Array}) AutoComplete
Fired when the AutoComplete instance receives query results from the data source.
  itemArrowFromEvent : (oSelf {Object}, elItem {HTMLElement}) AutoComplete
Fired when result item has been arrowed away from.
  itemArrowToEvent : (oSelf {Object}, elItem {HTMLElement}) AutoComplete
Fired when result item has been arrowed to.
  itemMouseOutEvent : (oSelf {Object}, elItem {HTMLElement}) AutoComplete
Fired when result item has been moused out.
  itemMouseOverEvent : (oSelf {Object}, elItem {HTMLElement}) AutoComplete
Fired when result item has been moused over.
  itemSelectEvent : (oSelf {Object}, elItem {HTMLElement}, oData {Object}) AutoComplete
Fired when an item is selected via mouse click, ENTER key, or TAB key.
  selectionEnforceEvent : (oSelf {Object}) AutoComplete
Fired if forceSelection is enabled and the user's input has been cleared because it did not match one of the returned...
  textboxBlurEvent : (oSelf {Object}) AutoComplete
Fired when the input field loses focus.
  textboxFocusEvent : (oSelf {Object}) AutoComplete
Fired when the input field receives focus.
  textboxKeyEvent : (oSelf {Object}, nKeycode {Number}) AutoComplete
Fired when the input field receives key input.
  typeAheadEvent : (oSelf {Object}, sQuery {String}, sPrefill {String}) AutoComplete
Fired when the input field has been prefilled by the type-ahead feature.
  unmatchedItemSelectEvent : (oSelf {Object}, sQuery {String}) AutoComplete
Fired when a user selection does not match any of the displayed result items. Note that this event may not behave as ...

Property Details

allowBrowserAutocomplete

public Boolean allowBrowserAutocomplete
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.
This property is defined by AutoComplete.

alwaysShowContainer

public Boolean alwaysShowContainer
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.
This property is defined by AutoComplete.

animHoriz

public Boolean animHoriz
Whether or not to animate the expansion/collapse of the results container in the horizontal direction.
This property is defined by AutoComplete.

animSpeed

public Number animSpeed
Speed of container expand/collapse animation, in seconds..
This property is defined by AutoComplete.

animVert

public Boolean animVert
Whether or not to animate the expansion/collapse of the results container in the vertical direction.
This property is defined by AutoComplete.

autoHighlight

public Boolean autoHighlight
Whether or not the first item in results container should be automatically highlighted on expand.
This property is defined by AutoComplete.

dataSource

public Object dataSource
The DataSource object that encapsulates the data used for auto completion. This object should be an inherited object from YAHOO.widget.DataSource.
This property is defined by AutoComplete.

delimChar

public String delimChar
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.
This property is defined by AutoComplete.

forceSelection

public Boolean forceSelection
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.
This property is defined by AutoComplete.

highlighClassName

public String highlighClassName
Class name of a highlighted item within results container.
This property is defined by AutoComplete.

maxResultsDisplayed

public Number maxResultsDisplayed
Maximum number of results to display in results container.
This property is defined by AutoComplete.

minQueryLength

public Number minQueryLength
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.
This property is defined by AutoComplete.

prehighlightClassName

public String prehighlightClassName
Class name of a pre-highlighted item within results container.
This property is defined by AutoComplete.

queryDelay

public Number queryDelay
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.
This property is defined by AutoComplete.

typeAhead

public Boolean typeAhead
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.
This property is defined by AutoComplete.

useIFrame

public Boolean useIFrame
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).
This property is defined by AutoComplete.

useShadow

public Boolean useShadow
Whether or not the results container should have a shadow.
This property is defined by AutoComplete.

Constructor Details

AutoComplete

public function AutoComplete(elInput {HTMLElement}, elInput {String}, elContainer {HTMLElement}, elContainer {String}, oDataSource {Object}, [oConfigs {Object}])
Parameters:
  • {HTMLElement} : elInput
    DOM element reference of an input field
  • {String} : elInput
    String ID of an input field
  • {HTMLElement} : elContainer
    DOM element reference of an existing DIV
  • {String} : elContainer
    String ID of an existing DIV
  • {Object} : oDataSource
    Instance of YAHOO.widget.DataSource for query/results
  • {Object} : oConfigs
    (optional) Object literal of configuration params

Method Details

doBeforeExpandContainer

public function doBeforeExpandContainer()
Overridable method called before container expands allows implementers to access data and DOM elements.
Parameters:
  • None.
Returns:
  • Boolean
    Return true to continue expanding container, false to cancel the expand.
This method is defined by AutoComplete.

formatResult

public function formatResult(oResultItem {Object}, sQuery {String})
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:
  • {Object} : oResultItem
    Result item representing one query result. Data is held in an array.
  • {String} : sQuery
    The current query string.
Returns:
  • String
    HTML markup of formatted result data.
This method is defined by AutoComplete.

getListItemData

public function getListItemData()
Public accessor to the data held in an <li> element of the results container.
Parameters:
  • None.
Returns:
  • Object
    | Array} Object or array of result data or null
This method is defined by AutoComplete.

getListItems

public function getListItems()
Public accessor to the internal array of DOM <li> elements that display query results within the results container.
Parameters:
  • None.
Returns:
  • HTMLElement[]
    Array of <li> elements within the results container.
This method is defined by AutoComplete.

isContainerOpen

public function isContainerOpen()
Returns true if container is in an expanded state, false otherwise.
Parameters:
  • None.
Returns:
  • Boolean
    Returns true if container is in an expanded state, false otherwise.
This method is defined by AutoComplete.

sendQuery

public function sendQuery(sQuery {String})
Makes query request to the DataSource.
Parameters:
  • {String} : sQuery
    Query string.
Returns:
  • void
This method is defined by AutoComplete.

setBody

public function setBody(sHeader {String})
Sets HTML markup for the results container body. This markup will be inserted within a <div> tag with a class of "ac_bd".
Parameters:
  • {String} : sHeader
    HTML markup for results container body.
Returns:
  • void
This method is defined by AutoComplete.

setFooter

public function setFooter(sFooter {String})
Sets HTML markup for the results container footer. This markup will be inserted within a <div> tag with a class of "ac_ft".
Parameters:
  • {String} : sFooter
    HTML markup for results container footer.
Returns:
  • void
This method is defined by AutoComplete.

setHeader

public function setHeader(sHeader {String})
Sets HTML markup for the results container header. This markup will be inserted within a <div> tag with a class of "ac_hd".
Parameters:
  • {String} : sHeader
    HTML markup for results container header.
Returns:
  • void
This method is defined by AutoComplete.

toString

public function toString()
Public accessor to the unique name of the AutoComplete instance.
Parameters:
  • None.
Returns:
  • String
    Unique name of the AutoComplete instance.
This method is defined by AutoComplete.

Event Details

containerCollapseEvent

public event containerCollapseEvent
Fired when the results container is collapsed.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
This event is defined by AutoComplete.

containerExpandEvent

public event containerExpandEvent
Fired when the results container is expanded.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
This event is defined by AutoComplete.

dataErrorEvent

public event dataErrorEvent
Fired when the AutoComplete instance does not receive query results from the DataSource due to an error.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {String} : sQuery
    The query string.
This event is defined by AutoComplete.

dataRequestEvent

public event dataRequestEvent
Fired when the AutoComplete instance makes a query to the DataSource.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {String} : sQuery
    The query string.
This event is defined by AutoComplete.

dataReturnEvent

public event dataReturnEvent
Fired when the AutoComplete instance receives query results from the data source.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {String} : sQuery
    The query string.
  • {Array} : aResults
    Results array.
This event is defined by AutoComplete.

itemArrowFromEvent

public event itemArrowFromEvent
Fired when result item has been arrowed away from.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {HTMLElement} : elItem
    The <li> element item arrowed from.
This event is defined by AutoComplete.

itemArrowToEvent

public event itemArrowToEvent
Fired when result item has been arrowed to.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {HTMLElement} : elItem
    The <li> element item arrowed to.
This event is defined by AutoComplete.

itemMouseOutEvent

public event itemMouseOutEvent
Fired when result item has been moused out.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {HTMLElement} : elItem
    The <li> element item moused from.
This event is defined by AutoComplete.

itemMouseOverEvent

public event itemMouseOverEvent
Fired when result item has been moused over.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {HTMLElement} : elItem
    The <li> element item moused to.
This event is defined by AutoComplete.

itemSelectEvent

public event itemSelectEvent
Fired when an item is selected via mouse click, ENTER key, or TAB key.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {HTMLElement} : elItem
    The selected <li> element item.
  • {Object} : oData
    The data returned for the item, either as an object, or mapped from the schema into an array.
This event is defined by AutoComplete.

selectionEnforceEvent

public event selectionEnforceEvent
Fired if forceSelection is enabled and the user's input has been cleared because it did not match one of the returned query results.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
This event is defined by AutoComplete.

textboxBlurEvent

public event textboxBlurEvent
Fired when the input field loses focus.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
This event is defined by AutoComplete.

textboxFocusEvent

public event textboxFocusEvent
Fired when the input field receives focus.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
This event is defined by AutoComplete.

textboxKeyEvent

public event textboxKeyEvent
Fired when the input field receives key input.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {Number} : nKeycode
    The keycode number.
This event is defined by AutoComplete.

typeAheadEvent

public event typeAheadEvent
Fired when the input field has been prefilled by the type-ahead feature.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {String} : sQuery
    The query string.
  • {String} : sPrefill
    The prefill string.
This event is defined by AutoComplete.

unmatchedItemSelectEvent

public event unmatchedItemSelectEvent
Fired when a user selection does not match any of the displayed result items. Note that this event may not behave as expected when delimiter characters have been defined.
Subscribers will be called with the following parameters:
  • {Object} : oSelf
    The AutoComplete instance.
  • {String} : sQuery
    The user-typed query string.
This event is defined by AutoComplete.

Copyright © 2006 Jack Slocum. All rights reserved.