Print Friendly

# 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.
| ERROR_DATAPARSE : String | DataSource
<static> Error message for data responses with parsing errors.
| ERROR_DATAXHR : String | DS_XHR
<static> Error message for XHR failure.
| TYPE_FLAT : Number | DS_XHR
<static> Flat-file data type.
| TYPE_JSON : Number | DS_XHR
<static> JSON data type.
| TYPE_XML : Number | DS_XHR
<static> XML data type.
| connMgr : Object | DS_XHR
Alias to YUI Connection Manager. Allows implementers to specify their own subclasses of the YUI Connection Manager ut...
| 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...
| 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...
| queryMatchCase : Boolean | DataSource
Enables query case-sensitivity matching. If caching is on and queryMatchCase is true, queries will only return result...
| 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...
| queryMatchSubset : Boolean | DataSource
Enables query subset matching. If caching is on and queryMatchSubset is true, substrings of queries will return match...
| 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...
| 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...
| 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...
| scriptQueryParam : String | DS_XHR
Query string parameter name sent to scriptURI. For instance, queries will be sent to <scriptURI>?<scriptQ...
| scriptURI : String | DS_XHR
Absolute or relative URI to script that returns query results. For instance, queries will be sent to <scriptURI&#...

## Public Methods

Method | Defined By
--- | ---
| DS_XHR(`sScriptURI {String}`, `aSchema {String[]}`, [`oConfigs {Object}`]) | 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.
| flushCache() : void | DataSource
Flushes cache.
| 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...
| 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...
| toString() : String | DataSource
Public accessor to the unique name of the DataSource instance.

## Public Events

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

## 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.

Copyright © 2006 Jack Slocum. All rights reserved.