Classes

Files

Class YAHOO.widget.AutoComplete

Object

   |

   +--YAHOO.widget.AutoComplete
class YAHOO.widget.AutoComplete
Quick Links:  Field Summary | Constructor Summary | Method Summary | Method Details

Field Summary [top]

boolean allowBrowserAutocomplete
Whether or not to allow browsers to cache user-typed input in the input field. 
boolean alwaysShowContainer
Whether or not the auto complete container should always be displayed. 
boolean animHoriz
Whether or not to animate the expansion/collapse of the auto complete container in the horizontal direction. 
number animSpeed
Speed of container expand/collapse animation, in seconds. 
boolean animVert
Whether or not to animate the expansion/collapse of the auto complete container in the vertical direction. 
boolean autoHighlight
Whether or not the first item in the auto complete container should be automatically highlighted on expand. 
Object containerCollapseEvent
Fired when the auto complete container is collapsed. 
Object containerExpandEvent
Fired when the auto complete container is expanded. 
Object dataErrorEvent
Fired when the auto complete instance does not receive query results from the data source due to an error. 
Object dataRequestEvent
Fired when the auto complete instance makes a query to the data source. 
Object dataReturnEvent
Fired when the auto complete instance receives query results from the data source. 
object dataSource
The data source object that encapsulates the data used for auto completion. 
string or array delimChar
Query delimiter. 
boolean forceSelection
Whether or not to force the user's selection to match one of the query results. 
string highlightClassName
Class name of a highlighted item within the auto complete container. 
boolean iFrameSrc
Configurable iFrame src used when useIFrame = true. 
Object itemArrowFromEvent
Fired when result item has been arrowed away from. 
Object itemArrowToEvent
Fired when result item has been arrowed to. 
Object itemMouseOutEvent
Fired when result item has been moused out. 
Object itemMouseOverEvent
Fired when result item has been moused over. 
Object itemSelectEvent
Fired when an item is selected via mouse click, ENTER key, or TAB key. 
number maxResultsDisplayed
Maximum number of results to display in auto complete container. 
number minQueryLength
Number of characters that must be entered before querying for results. 
string prehighlightClassName
Class name of a pre-highlighted item within the auto complete container. 
number queryDelay
Number of seconds to delay before submitting a query request. 
Object 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. 
Object textboxBlurEvent
Fired when the auto complete text input box loses focus. 
Object textboxFocusEvent
Fired when the auto complete text input box receives focus. 
Object textboxKeyEvent
Fired when the auto complete text input box receives key input. 
boolean typeAhead
Whether or not the auto complete 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. 
Object typeAheadEvent
Fired when the auto complete textbox has been prefilled by the type-ahead feature. 
Object unmatchedItemSelectEvent
Fired when an user selection does not match any of the displayed result items. 
boolean useIFrame
Whether or not to use an iFrame to layer over Windows form elements in IE. 
boolean useShadow
Whether or not the auto complete container should have a shadow. 

Constructor Summary [top]

YAHOO.widget.AutoComplete
Class providing the customizable functionality of a plug-and-play DHTML auto complete widget. 

Method Summary [top]

string formatResult (<object> oResultItem, <string> sQuery)
Overridable method that converts a result item object into HTML markup for display. 
object or array getListItemData (oListItem)
Public accessor to the data held in an <li> element of the auto complete container. 
array getListItems ()
Public accessor to the internal array of DOM <li> elements that display query results within the auto complete container. 
void sendQuery (<string> sQuery)
Makes query request to the data source. 
void setBody (sBody)
Sets HTML markup for the auto complete container body. 
void setFooter (<string> sFooter)
Sets HTML markup for the auto complete container footer. 
void setHeader (<string> sHeader)
Sets HTML markup for the auto complete container header. 
string toString ()
Public accessor to the unique name of the auto complete instance. 

Field Detail [top]

allowBrowserAutocomplete

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 auto complete 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: true.

alwaysShowContainer

boolean   alwaysShowContainer
Whether or not the auto complete container should always be displayed. Enabling this feature prevents the toggling of the container to a collapsed state. Default: false.

animHoriz

boolean   animHoriz
Whether or not to animate the expansion/collapse of the auto complete container in the horizontal direction. Default: false.

animSpeed

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

animVert

boolean   animVert
Whether or not to animate the expansion/collapse of the auto complete container in the vertical direction. Default: true.

autoHighlight

boolean   autoHighlight
Whether or not the first item in the auto complete container should be automatically highlighted on expand. Default: true.

containerCollapseEvent

Object   containerCollapseEvent
Fired when the auto complete container is collapsed. If alwaysShowContainer is enabled, then containerCollapseEvent will be fired when the container is cleared of results. Subscribers receive the following array:
- args[0] The auto complete object instance

containerExpandEvent

Object   containerExpandEvent
Fired when the auto complete container is expanded. If alwaysShowContainer is enabled, then containerExpandEvent will be fired when the container is populated with results. Subscribers receive the following array:
- args[0] The auto complete object instance

dataErrorEvent

Object   dataErrorEvent
Fired when the auto complete instance does not receive query results from the data source due to an error. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The query string

dataRequestEvent

Object   dataRequestEvent
Fired when the auto complete instance makes a query to the data source. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The query string

dataReturnEvent

Object   dataReturnEvent
Fired when the auto complete instance receives query results from the data source. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The query string - args[2] Results array

dataSource

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

delimChar

string or array   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. Default: null.

forceSelection

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

highlightClassName

string   highlightClassName
Class name of a highlighted item within the auto complete container. Default: "yui-ac-highlight".

iFrameSrc

boolean   iFrameSrc
Configurable iFrame src used when useIFrame = true. Implementations over SSL should set this parameter to an appropriate https location in order to avoid security-related browser errors. Default:"about:blank".

itemArrowFromEvent

Object   itemArrowFromEvent
Fired when result item has been arrowed away from. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The <li> element item arrowed from

itemArrowToEvent

Object   itemArrowToEvent
Fired when result item has been arrowed to. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The <li> element item arrowed to

itemMouseOutEvent

Object   itemMouseOutEvent
Fired when result item has been moused out. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The <li> element item moused from

itemMouseOverEvent

Object   itemMouseOverEvent
Fired when result item has been moused over. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The <li> element item moused to

itemSelectEvent

Object   itemSelectEvent
Fired when an item is selected via mouse click, ENTER key, or TAB key. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The selected <li> element item - args[2] The data returned for the item, either as an object, or mapped from the schema into an array

maxResultsDisplayed

number   maxResultsDisplayed
Maximum number of results to display in auto complete container. Default: 10.

minQueryLength

number   minQueryLength
Number of characters that must be entered before querying for results. Default: 1.

prehighlightClassName

string   prehighlightClassName
Class name of a pre-highlighted item within the auto complete container. Default: null.

queryDelay

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. Default: 0.5.

selectionEnforceEvent

Object   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 receive the following array:
- args[0] The auto complete object instance

textboxBlurEvent

Object   textboxBlurEvent
Fired when the auto complete text input box loses focus. Subscribers receive an array of the following array:
- args[0] The auto complete object instance

textboxFocusEvent

Object   textboxFocusEvent
Fired when the auto complete text input box receives focus. Subscribers receive the following array:
- args[0] The auto complete object instance

textboxKeyEvent

Object   textboxKeyEvent
Fired when the auto complete text input box receives key input. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The keycode number

typeAhead

boolean   typeAhead
Whether or not the auto complete 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: false.

typeAheadEvent

Object   typeAheadEvent
Fired when the auto complete textbox has been prefilled by the type-ahead feature. Subscribers receive the following array:
- args[0] The auto complete object instance - args[1] The query string - args[2] The prefill string

unmatchedItemSelectEvent

Object   unmatchedItemSelectEvent
Fired when an 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 receive the following array:
- args[0] The auto complete object instance - args[1] The user selection

useIFrame

boolean   useIFrame
Whether or not to use an iFrame to layer over Windows form elements in IE. Set to true only when the auto complete 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:false.

useShadow

boolean   useShadow
Whether or not the auto complete container should have a shadow. Default:false.

Constructor Detail [top]

YAHOO.widget.AutoComplete

YAHOO.widget.AutoComplete ()
Class providing the customizable functionality of a plug-and-play DHTML auto complete 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
requires YAHOO.util.Dom Dom utility requires YAHOO.util.Event Event utility requires YAHOO.widget.DataSource Data source class see YAHOO.util.Animation Animation utility see JSON JSON library
Parameters:
element - | string} inputEl DOM element reference or string ID of the auto complete input field
element - | string} containerEl DOM element reference or string ID of the auto complete <div> container
oDataSource - Instance of YAHOO.widget.DataSource for query/results
oConfigs - Optional object literal of config params

Method Detail [top]

formatResult

string formatResult (<object> oResultItem, <string> 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 - Result item object representing one query result
sQuery - The current query string
Returns:
HTML markup of formatted result data

getListItemData

object or array getListItemData (oListItem)
Public accessor to the data held in an <li> element of the auto complete container.
Returns:
Object or array of result data or null

getListItems

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

sendQuery

void sendQuery (<string> sQuery)
Makes query request to the data source.
Parameters:
sQuery - Query string.

setBody

void setBody (sBody)
Sets HTML markup for the auto complete container body. This markup will be inserted within a <div> tag with a class of "ac_bd".
Parameters:
sHeader - HTML markup for container body

setFooter

void setFooter (<string> sFooter)
Sets HTML markup for the auto complete container footer. This markup will be inserted within a <div> tag with a class of "ac_ft".
Parameters:
sFooter - HTML markup for container footer

setHeader

void setHeader (<string> sHeader)
Sets HTML markup for the auto complete container header. This markup will be inserted within a <div> tag with a class of "ac_hd".
Parameters:
sHeader - HTML markup for container header

toString

string toString ()
Public accessor to the unique name of the auto complete instance.
Returns:
Unique name of the auto complete instance