Class YAHOO.widget.DS_XHR

Package:	YAHOO.widget
Class:	DS_XHR
Extends:	DataSource
Defined In:	autocomplete.js

Implementation of YAHOO.widget.DataSource using XML HTTP requests that return query results.

Public Properties

Property		Defined By
	ERROR_DATANULL : String	DataSource
	<static> Error message for null data responses.	DataSource
	ERROR_DATAPARSE : String	DataSource
	<static> Error message for data responses with parsing errors.	DataSource
	ERROR_DATAXHR : String	DS_XHR
	<static> Error message for XHR failure.	DS_XHR
	TYPE_FLAT : Number	DS_XHR
	<static> Flat-file data type.	DS_XHR
	TYPE_JSON : Number	DS_XHR
	<static> JSON data type.	DS_XHR
	TYPE_XML : Number	DS_XHR
	<static> XML data type.	DS_XHR
	connMgr : Object	DS_XHR
	Alias to YUI Connection Manager. Allows implementers to specify their own subclasses of the YUI Connection Manager ut...	DS_XHR
	connTimeout : Number	DS_XHR
	Number of milliseconds the XHR connection will wait for a server response. A a value of zero indicates the XHR connec...	DS_XHR
	maxCacheEntries : Number	DataSource
	Max size of the local cache. Set to 0 to turn off caching. Caching is useful to reduce the number of server connect...	DataSource
	queryMatchCase : Boolean	DataSource
	Enables query case-sensitivity matching. If caching is on and queryMatchCase is true, queries will only return result...	DataSource
	queryMatchContains : Boolean	DataSource
	Use this to equate cache matching with the type of matching done by your live data source. If caching is on and query...	DataSource
	queryMatchSubset : Boolean	DataSource
	Enables query subset matching. If caching is on and queryMatchSubset is true, substrings of queries will return match...	DataSource
	responseStripAfter : String	DS_XHR
	String after which to strip results. If the results from the XHR are sent back as HTML, the gzip HTML comment appears...	DS_XHR
	responseType : String	DS_XHR
	XHR response data type. Other types that may be defined are YAHOO.widget.DS_XHR.TYPE_XML and YAHOO.widget.DS_XHR.TYPE...	DS_XHR
	scriptQueryAppend : String	DS_XHR
	String of key/value pairs to append to requests made to scriptURI. Define this string when you want to send additiona...	DS_XHR
	scriptQueryParam : String	DS_XHR
	Query string parameter name sent to scriptURI. For instance, queries will be sent to <scriptURI>?<scriptQ...	DS_XHR
	scriptURI : String	DS_XHR
	Absolute or relative URI to script that returns query results. For instance, queries will be sent to <scriptURI&#...	DS_XHR

Public Methods

Method		Defined By
	DS_XHR(`sScriptURI {String}`, `aSchema {String[]}`, [`oConfigs {Object}`])	DS_XHR
		DS_XHR
	doQuery(`oCallbackFn {HTMLFunction}`, `sQuery {String}`, `oParent {Object}`) : void	DS_XHR
	Queries the live data source defined by scriptURI for results. Results are passed back to a callback function.	DS_XHR
	flushCache() : void	DataSource
	Flushes cache.	DataSource
	getResults(`oCallbackFn {HTMLFunction}`, `sQuery {String}`, `oParent {Object}`) : void	DataSource
	Retrieves query results, first checking the local cache, then making the query request to the live data source as def...	DataSource
	parseResponse(`sQuery {String}`, `oResponse {Object}`, `oParent {Object}`) : s	DS_XHR
	Parses raw response data into an array of result objects. The result data key is always stashed in the [0] element of...	DS_XHR
	toString() : String	DataSource
	Public accessor to the unique name of the DataSource instance.	DataSource

Public Events

Event		Defined By
	cacheFlushEvent : (`oSelf {Object}`)	DataSource
	Fired when the local cache is flushed.	DataSource
	cacheQueryEvent : (`oSelf {Object}`, `oParent {Object}`, `sQuery {String}`)	DataSource
	Fired when a query is made to the local cache.	DataSource
	dataErrorEvent : (`oSelf {Object}`, `oParent {Object}`, `sQuery {String}`, `sMsg {String}`)	DataSource
	Fired when an error is encountered with the live data source.	DataSource
	getCachedResultsEvent : (`oSelf {Object}`, `oParent {Object}`, `sQuery {String}`, `aResults {Object[]}`)	DataSource
	Fired when data is retrieved from the local cache.	DataSource
	getResultsEvent : (`oSelf {Object}`, `oParent {Object}`, `sQuery {String}`, `aResults {Object[]}`)	DataSource
	Fired when data is retrieved from the live data source.	DataSource
	queryEvent : (`oSelf {Object}`, `oParent {Object}`, `sQuery {String}`)	DataSource
	Fired when a query is made to the live data source.	DataSource

Property Details

ERROR_DATANULL

public String ERROR_DATANULL

<static> Error message for null data responses.

This property is defined by DataSource.

ERROR_DATAPARSE

public String ERROR_DATAPARSE

<static> Error message for data responses with parsing errors.

This property is defined by DataSource.

ERROR_DATAXHR

public String ERROR_DATAXHR

<static> Error message for XHR failure.

This property is defined by DS_XHR.

TYPE_FLAT

public Number TYPE_FLAT

<static> Flat-file data type.

This property is defined by DS_XHR.

TYPE_JSON

public Number TYPE_JSON

<static> JSON data type.

This property is defined by DS_XHR.

TYPE_XML

public Number TYPE_XML

<static> XML data type.

This property is defined by DS_XHR.

connMgr

public Object connMgr

Alias to YUI Connection Manager. Allows implementers to specify their own subclasses of the YUI Connection Manager utility.

This property is defined by DS_XHR.

connTimeout

public Number connTimeout

Number of milliseconds the XHR connection will wait for a server response. A a value of zero indicates the XHR connection will wait forever. Any value greater than zero will use the Connection utility's Auto-Abort feature.

This property is defined by DS_XHR.

maxCacheEntries

public Number maxCacheEntries

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.

This property is defined by DataSource.

queryMatchCase

public Boolean queryMatchCase

Enables query case-sensitivity matching. If caching is on and queryMatchCase is true, queries will only return results for case-sensitive matches.

This property is defined by DataSource.

queryMatchContains

public Boolean queryMatchContains

Use this to equate cache matching with the type of matching done by your live data source. If caching is on and queryMatchContains is true, the cache returns results that "contain" the query string. By default, queryMatchContains is set to false, meaning the cache only returns results that "start with" the query string.

This property is defined by DataSource.

queryMatchSubset

public Boolean queryMatchSubset

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.

This property is defined by DataSource.

responseStripAfter

public String responseStripAfter

String after which to strip results. If the results from the XHR are sent back as HTML, the gzip HTML comment appears at the end of the data and should be ignored.

This property is defined by DS_XHR.

responseType

public String responseType

XHR response data type. Other types that may be defined are YAHOO.widget.DS_XHR.TYPE_XML and YAHOO.widget.DS_XHR.TYPE_FLAT.

This property is defined by DS_XHR.

scriptQueryAppend

public String scriptQueryAppend

String of key/value pairs to append to requests made to scriptURI. Define this string when you want to send additional query parameters to your script. When defined, queries will be sent to <scriptURI>?<scriptQueryParam>=userinput&<scriptQueryAppend>

This property is defined by DS_XHR.

scriptQueryParam

public String scriptQueryParam

Query string parameter name sent to scriptURI. For instance, queries will be sent to <scriptURI>?<scriptQueryParam>=userinput

This property is defined by DS_XHR.

scriptURI

public String scriptURI

Absolute or relative URI to script that returns query results. For instance, queries will be sent to <scriptURI>?<scriptQueryParam>=userinput

This property is defined by DS_XHR.

Constructor Details

DS_XHR

public function DS_XHR(sScriptURI {String}, aSchema {String[]}, [oConfigs {Object}])

Parameters:

{String} : sScriptURI
Absolute or relative URI to script that returns query results as JSON, XML, or delimited flat-file data.
{String[]} : aSchema
Data schema definition of results.
{Object} : oConfigs
(optional) Object literal of config params.

Method Details

doQuery

public function doQuery(oCallbackFn {HTMLFunction}, sQuery {String}, oParent {Object})

Queries the live data source defined by scriptURI for results. Results are passed back to a callback function.

Parameters:

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

Returns:

void

This method is defined by DS_XHR.

flushCache

public function flushCache()

Flushes cache.

Parameters:

None.

Returns:

void

This method is defined by DataSource.

getResults

public function getResults(oCallbackFn {HTMLFunction}, sQuery {String}, oParent {Object})

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:

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

Returns:

void

This method is defined by DataSource.

parseResponse

public function parseResponse(sQuery {String}, oResponse {Object}, oParent {Object})

Parses raw response data into an array of result objects. The result data key is always stashed in the [0] element of each result object.

Parameters:

{String} : sQuery
Query string.
{Object} : oResponse
The raw response data to parse.
{Object} : oParent
The object instance that has requested data.

Returns:

s
{Object[]} Array of result objects.

This method is defined by DS_XHR.

toString

public function toString()

Public accessor to the unique name of the DataSource instance.

Parameters:

None.

Returns:

String
Unique name of the DataSource instance

This method is defined by DataSource.

Event Details

cacheFlushEvent

public event cacheFlushEvent

Fired when the local cache is flushed.

Subscribers will be called with the following parameters:

{Object} : oSelf
The DataSource instance

This event is defined by DataSource.

cacheQueryEvent

public event cacheQueryEvent

Fired when a query is made to the local cache.

Subscribers will be called with the following parameters:

{Object} : oSelf
The DataSource instance.
{Object} : oParent
The requesting object.
{String} : sQuery
The query string.

This event is defined by DataSource.

dataErrorEvent

public event dataErrorEvent

Fired when an error is encountered with the live data source.

Subscribers will be called with the following parameters:

{Object} : oSelf
The DataSource instance.
{Object} : oParent
The requesting object.
{String} : sQuery
The query string.
{String} : sMsg
Error message string

This event is defined by DataSource.

getCachedResultsEvent

public event getCachedResultsEvent

Fired when data is retrieved from the local cache.

Subscribers will be called with the following parameters:

{Object} : oSelf
The DataSource instance.
{Object} : oParent
The requesting object.
{String} : sQuery
The query string.
{Object[]} : aResults
Array of result objects.

This event is defined by DataSource.

getResultsEvent

public event getResultsEvent

Fired when data is retrieved from the live data source.

Subscribers will be called with the following parameters:

{Object} : oSelf
The DataSource instance.
{Object} : oParent
The requesting object.
{String} : sQuery
The query string.
{Object[]} : aResults
Array of result objects.

This event is defined by DataSource.

queryEvent

public event queryEvent

Fired when a query is made to the live data source.

Subscribers will be called with the following parameters:

{Object} : oSelf
The DataSource instance.
{Object} : oParent
The requesting object.
{String} : sQuery
The query string.

This event is defined by DataSource.