API: autocomplete YAHOO.widget.DataSource (YUI Library)

# Yahoo! UI Library

### AutoComplete Widget 2.2.2

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

## Class YAHOO.widget.DataSource

Known Subclasses:
  YAHOO.widget.DS_JSFunction YAHOO.widget.DS_XHR YAHOO.widget.DS_JSArray

The DataSource classes manages sending a request and returning response from a live database. Supported data include local JavaScript arrays and objects and databases accessible via XHR connections. Supported response formats include JavaScript arrays, JSON, XML, and flat-file textual data.

### Constructor

YAHOO.widget.DataSource `( )`

### Properties

#### _aCache `- private Object[]`

Local cache of data result objects indexed chronologically.

#### _nIndex `- private static Number`

Internal class variable to index multiple DataSource instances.

#### _sName `- private String`

Name of DataSource instance.

#### ERROR_DATANULL `- static final String`

Error message for null data responses.

#### ERROR_DATAPARSE `- static final String`

Error message for data responses with parsing errors.

#### maxCacheEntries `- Number`

Max size of the local cache. Set to 0 to turn off caching. Caching is useful to reduce the number of server connections. Recommended only for data sources that return comprehensive results for queries or when stale data is not an issue.
Default Value: 15

#### queryMatchCase `- Boolean`

Enables case-sensitivity in the matching algorithm used against JS Array types of DataSources and DataSource caches. If queryMatchCase is true, only case-sensitive matches will return.
Default Value: false

#### queryMatchContains `- Boolean`

Use this to fine-tune the matching algorithm used against JS Array types of DataSource and DataSource caches. If queryMatchContains is true, then the JS Array or cache returns results that "contain" the query string. By default, queryMatchContains is set to false, so that only results that "start with" the query string are returned.
Default Value: false

#### queryMatchSubset `- Boolean`

Enables query subset matching. If caching is on and queryMatchSubset is true, substrings of queries will return matching cached results. For instance, if the first query is for "abc" susequent queries that start with "abc", like "abcd", will be queried against the cache, and not the live data source. Recommended only for DataSources that return comprehensive results for queries with very few characters.
Default Value: false

### Methods

#### _addCacheElem

`private void _addCacheElem ( oResult )`
Adds a result object to the local cache, evicting the oldest element if the cache is full. Newer items will have higher indexes, the oldest item will have index of 0.

Parameters:
  `oResult <Object>` Data result object, including array of results.

Returns: `void`

#### _doQueryCache

`private Object[] _doQueryCache ( oCallbackFn , sQuery , oParent )`
Queries the local cache for results. If query has been cached, the callback function is called with the results, and the cached is refreshed so that it is now the newest element.

Parameters:
  `oCallbackFn <HTMLFunction>` Callback function defined by oParent object to which to return results.
  `sQuery <String>` Query string.
  `oParent <Object>` The object instance that has requested data.

Returns: `Object[]`
  aResults Array of results from local cache if found, otherwise null.

#### _init

`private void _init ( )`
Initializes DataSource instance.

Returns: `void`

#### doQuery

`void doQuery ( oCallbackFn , sQuery , oParent )`
Abstract method implemented by subclasses to make a query to the live data source. Must call the callback function with the response returned from the query. Populates cache (if enabled).

Parameters:
  `oCallbackFn <HTMLFunction>` Callback function implemented by oParent to which to return results.
  `sQuery <String>` Query string.
  `oParent <Object>` The object instance that has requested data.

Returns: `void`

#### flushCache

`void flushCache ( )`
Flushes cache.

Returns: `void`

#### getResults

`void getResults ( oCallbackFn , sQuery , oParent )`
Retrieves query results, first checking the local cache, then making the query request to the live data source as defined by the function doQuery.

Parameters:
  `oCallbackFn <HTMLFunction>` Callback function defined by oParent object to which to return results.
  `sQuery <String>` Query string.
  `oParent <Object>` The object instance that has requested data.

Returns: `void`

#### toString

`String toString ( )`
Public accessor to the unique name of the DataSource instance.

Returns: `String`
  Unique name of the DataSource instance

### Events

#### cacheFlushEvent

`cacheFlushEvent ( oSelf )`
Fired when the local cache is flushed.

Parameters:
  `oSelf <Object>` The DataSource instance

#### cacheQueryEvent

`cacheQueryEvent ( oSelf , oParent , sQuery )`
Fired when a query is made to the local cache.

Parameters:
  `oSelf <Object>` The DataSource instance.
  `oParent <Object>` The requesting object.
  `sQuery <String>` The query string.

#### dataErrorEvent

`dataErrorEvent ( oSelf , oParent , sQuery , sMsg )`
Fired when an error is encountered with the live data source.

Parameters:
  `oSelf <Object>` The DataSource instance.
  `oParent <Object>` The requesting object.
  `sQuery <String>` The query string.
  `sMsg <String>` Error message string

#### getCachedResultsEvent

`getCachedResultsEvent ( oSelf , oParent , sQuery , aResults )`
Fired when data is retrieved from the local cache.

Parameters:
  `oSelf <Object>` The DataSource instance.
  `oParent <Object>` The requesting object.
  `sQuery <String>` The query string.
  `aResults <Object[]>` Array of result objects.

#### getResultsEvent

`getResultsEvent ( oSelf , oParent , sQuery , aResults )`
Fired when data is retrieved from the live data source.

Parameters:
  `oSelf <Object>` The DataSource instance.
  `oParent <Object>` The requesting object.
  `sQuery <String>` The query string.
  `aResults <Object[]>` Array of result objects.

#### queryEvent

`queryEvent ( oSelf , oParent , sQuery )`
Fired when a query is made to the live data source.

Parameters:
  `oSelf <Object>` The DataSource instance.
  `oParent <Object>` The requesting object.
  `sQuery <String>` The query string.

Copyright © 2007 Yahoo! Inc. All rights reserved.