Yahoo! UI Library

AutoComplete Widget  2.5.0

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

Show Private Show Protected

Class YAHOO.widget.DataSource

Known Subclasses:
YAHOO.widget.DS_XHR YAHOO.widget.DS_JSFunction YAHOO.widget.DS_JSArray YAHOO.widget.DS_ScriptNode
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.