435 lines
No EOL
24 KiB
HTML
435 lines
No EOL
24 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>YAHOO.widget.DataSource</title>
|
|
<link rel="stylesheet" type="text/css" href="../resources/reset.css"/>
|
|
<link rel="stylesheet" type="text/css" href="../resources/style.css" media="screen"/>
|
|
<link rel="stylesheet" type="text/css" href="../resources/print.css" media="print">
|
|
</head>
|
|
<body>
|
|
<div class="body-wrap">
|
|
<div class="top-tools"><img src="../resources/print.gif" width="16" height="16" align="absmiddle"> <a href="YAHOO.widget.DataSource.html" target="_blank">Print Friendly</a></div>
|
|
<h1>Class YAHOO.widget.DataSource</h1>
|
|
<table cellspacing="0">
|
|
<tr><td class="label">Package:</td><td>YAHOO.widget</td></tr>
|
|
<tr><td class="label">Class:</td><td>DataSource</td></tr>
|
|
<tr><td class="label">Extends:</td><td>Object</td></tr>
|
|
<tr><td class="label">Subclasses:</td><td><a href="YAHOO.widget.DS_JSArray.html">DS_JSArray</a>, <a href="YAHOO.widget.DS_JSFunction.html">DS_JSFunction</a>, <a href="YAHOO.widget.DS_XHR.html">DS_XHR</a></td></tr>
|
|
<tr><td class="label">Defined In:</td><td><a href="autocomplete.js.html">autocomplete.js</a></td></tr>
|
|
</table>
|
|
<div class="description">
|
|
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. </div>
|
|
<hr />
|
|
<a name="properties"></a>
|
|
<h2>Public Properties</h2>
|
|
<table cellspacing="0" class="member-table">
|
|
<tr>
|
|
<th class="sig-header" colspan="2">Property</th>
|
|
<th class="msource-header">Defined By</th>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#ERROR_DATANULL">ERROR_DATANULL</a> : String</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc"><static> Error message for null data responses.</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#ERROR_DATAPARSE">ERROR_DATAPARSE</a> : String</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc"><static> Error message for data responses with parsing errors.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#maxCacheEntries">maxCacheEntries</a> : Number</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Max size of the local cache. Set to 0 to turn off caching. Caching is
|
|
useful to reduce the number of server connect...</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#queryMatchCase">queryMatchCase</a> : Boolean</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Enables query case-sensitivity matching. If caching is on and
|
|
queryMatchCase is true, queries will only return result...</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#queryMatchContains">queryMatchContains</a> : Boolean</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Use this to equate cache matching with the type of matching done by your live
|
|
data source. If caching is on and query...</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#queryMatchSubset">queryMatchSubset</a> : Boolean</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Enables query subset matching. If caching is on and queryMatchSubset is
|
|
true, substrings of queries will return match...</td>
|
|
</tr>
|
|
</table>
|
|
<a name="methods"></a>
|
|
<h2>Public Methods</h2>
|
|
<table cellspacing="0" class="member-table">
|
|
<tr>
|
|
<th class="sig-header" colspan="2">Method</th>
|
|
<th class="msource-header">Defined By</th>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#DataSource">DataSource</a>()</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc"></td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#doQuery">doQuery</a>(<code>oCallbackFn {HTMLFunction}</code>, <code>sQuery {String}</code>, <code>oParent {Object}</code>) : void</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Abstract method implemented by subclasses to make a query to the live data
|
|
source. Must call the callback function wi...</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#flushCache">flushCache</a>() : void</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Flushes cache.</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#getResults">getResults</a>(<code>oCallbackFn {HTMLFunction}</code>, <code>sQuery {String}</code>, <code>oParent {Object}</code>) : void</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Retrieves query results, first checking the local cache, then making the
|
|
query request to the live data source as def...</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#toString">toString</a>() : String</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Public accessor to the unique name of the DataSource instance.</td>
|
|
</tr>
|
|
</table>
|
|
<a name="events"></a>
|
|
<h2>Public Events</h2>
|
|
<table cellspacing="0" class="member-table">
|
|
<tr>
|
|
<th class="sig-header" colspan="2">Event</th>
|
|
<th class="msource-header">Defined By</th>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#event-cacheFlushEvent">cacheFlushEvent</a> : (<code>oSelf {Object}</code>)</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Fired when the local cache is flushed.</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#event-cacheQueryEvent">cacheQueryEvent</a> : (<code>oSelf {Object}</code>, <code>oParent {Object}</code>, <code>sQuery {String}</code>)</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Fired when a query is made to the local cache.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#event-dataErrorEvent">dataErrorEvent</a> : (<code>oSelf {Object}</code>, <code>oParent {Object}</code>, <code>sQuery {String}</code>, <code>sMsg {String}</code>)</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Fired when an error is encountered with the live data source.</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#event-getCachedResultsEvent">getCachedResultsEvent</a> : (<code>oSelf {Object}</code>, <code>oParent {Object}</code>, <code>sQuery {String}</code>, <code>aResults {Object[]}</code>)</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Fired when data is retrieved from the local cache.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#event-getResultsEvent">getResultsEvent</a> : (<code>oSelf {Object}</code>, <code>oParent {Object}</code>, <code>sQuery {String}</code>, <code>aResults {Object[]}</code>)</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="mdesc">Fired when data is retrieved from the live data source.</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="micon" rowspan="2"> </td>
|
|
<td class="sig"><a class="mlink" href="#event-queryEvent">queryEvent</a> : (<code>oSelf {Object}</code>, <code>oParent {Object}</code>, <code>sQuery {String}</code>)</td>
|
|
<td class="msource" rowspan="2">DataSource</td>
|
|
</tr>
|
|
<tr class="alt">
|
|
<td class="mdesc">Fired when a query is made to the live data source.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2 class="mdetail-head">Property Details</h2>
|
|
<div class="detail-wrap">
|
|
<a name="ERROR_DATANULL"></a>
|
|
<div class="mdetail">
|
|
<h3>ERROR_DATANULL</i></h3>
|
|
<code>public String ERROR_DATANULL</code>
|
|
<div class="mdetail-desc">
|
|
<static> Error message for null data responses. </div>
|
|
<div class="mdetail-def">This property is defined by DataSource.</div>
|
|
</div>
|
|
<a name="ERROR_DATAPARSE"></a>
|
|
<div class="mdetail alt">
|
|
<h3>ERROR_DATAPARSE</i></h3>
|
|
<code>public String ERROR_DATAPARSE</code>
|
|
<div class="mdetail-desc">
|
|
<static> Error message for data responses with parsing errors. </div>
|
|
<div class="mdetail-def">This property is defined by DataSource.</div>
|
|
</div>
|
|
<a name="maxCacheEntries"></a>
|
|
<div class="mdetail">
|
|
<h3>maxCacheEntries</i></h3>
|
|
<code>public Number maxCacheEntries</code>
|
|
<div class="mdetail-desc">
|
|
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. </div>
|
|
<div class="mdetail-def">This property is defined by DataSource.</div>
|
|
</div>
|
|
<a name="queryMatchCase"></a>
|
|
<div class="mdetail alt">
|
|
<h3>queryMatchCase</i></h3>
|
|
<code>public Boolean queryMatchCase</code>
|
|
<div class="mdetail-desc">
|
|
Enables query case-sensitivity matching. If caching is on and
|
|
queryMatchCase is true, queries will only return results for case-sensitive
|
|
matches. </div>
|
|
<div class="mdetail-def">This property is defined by DataSource.</div>
|
|
</div>
|
|
<a name="queryMatchContains"></a>
|
|
<div class="mdetail">
|
|
<h3>queryMatchContains</i></h3>
|
|
<code>public Boolean queryMatchContains</code>
|
|
<div class="mdetail-desc">
|
|
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. </div>
|
|
<div class="mdetail-def">This property is defined by DataSource.</div>
|
|
</div>
|
|
<a name="queryMatchSubset"></a>
|
|
<div class="mdetail alt">
|
|
<h3>queryMatchSubset</i></h3>
|
|
<code>public Boolean queryMatchSubset</code>
|
|
<div class="mdetail-desc">
|
|
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. </div>
|
|
<div class="mdetail-def">This property is defined by DataSource.</div>
|
|
</div>
|
|
</div>
|
|
|
|
<a name="DataSource"></a>
|
|
<h2 class="mdetail-head">Constructor Details</h2>
|
|
<div class="detail-wrap">
|
|
<div class="mdetail">
|
|
<h3>DataSource</i></h3>
|
|
<code>public function DataSource()</code>
|
|
<div class="mdetail-desc">
|
|
<div class="mdetail-params">
|
|
<strong>Parameters:</strong>
|
|
<ul><li>None.</li> </ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<h2 class="mdetail-head">Method Details</h2>
|
|
<div class="detail-wrap">
|
|
<a name="doQuery"></a>
|
|
<div class="mdetail">
|
|
<h3>doQuery</i></h3>
|
|
<code>public function doQuery(<code>oCallbackFn {HTMLFunction}</code>, <code>sQuery {String}</code>, <code>oParent {Object}</code>)</code>
|
|
<div class="mdetail-desc">
|
|
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).
|
|
<div class="mdetail-params">
|
|
<strong>Parameters:</strong>
|
|
<ul><li><code>{HTMLFunction}</code> : oCallbackFn<div class="sub-desc">Callback function implemented by oParent to which to return results.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">Query string.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The object instance that has requested data.</div></li> </ul>
|
|
<strong>Returns:</strong>
|
|
<ul>
|
|
<li><code>void</code></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This method is defined by DataSource.</div>
|
|
</div>
|
|
<a name="flushCache"></a>
|
|
<div class="mdetail alt">
|
|
<h3>flushCache</i></h3>
|
|
<code>public function flushCache()</code>
|
|
<div class="mdetail-desc">
|
|
Flushes cache.
|
|
<div class="mdetail-params">
|
|
<strong>Parameters:</strong>
|
|
<ul><li>None.</li> </ul>
|
|
<strong>Returns:</strong>
|
|
<ul>
|
|
<li><code>void</code></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This method is defined by DataSource.</div>
|
|
</div>
|
|
<a name="getResults"></a>
|
|
<div class="mdetail">
|
|
<h3>getResults</i></h3>
|
|
<code>public function getResults(<code>oCallbackFn {HTMLFunction}</code>, <code>sQuery {String}</code>, <code>oParent {Object}</code>)</code>
|
|
<div class="mdetail-desc">
|
|
Retrieves query results, first checking the local cache, then making the
|
|
query request to the live data source as defined by the function doQuery.
|
|
<div class="mdetail-params">
|
|
<strong>Parameters:</strong>
|
|
<ul><li><code>{HTMLFunction}</code> : oCallbackFn<div class="sub-desc">Callback function defined by oParent object to which to return results.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">Query string.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The object instance that has requested data.</div></li> </ul>
|
|
<strong>Returns:</strong>
|
|
<ul>
|
|
<li><code>void</code></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This method is defined by DataSource.</div>
|
|
</div>
|
|
<a name="toString"></a>
|
|
<div class="mdetail alt">
|
|
<h3>toString</i></h3>
|
|
<code>public function toString()</code>
|
|
<div class="mdetail-desc">
|
|
Public accessor to the unique name of the DataSource instance.
|
|
<div class="mdetail-params">
|
|
<strong>Parameters:</strong>
|
|
<ul><li>None.</li> </ul>
|
|
<strong>Returns:</strong>
|
|
<ul>
|
|
<li><code>String</code><div class="sub-desc">Unique name of the DataSource instance</div></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This method is defined by DataSource.</div>
|
|
</div>
|
|
</div>
|
|
|
|
<h2 class="mdetail-head">Event Details</h2>
|
|
<div class="detail-wrap">
|
|
<a name="event-cacheFlushEvent"></a>
|
|
<div class="mdetail">
|
|
<h3>cacheFlushEvent</i></h3>
|
|
<code>public event cacheFlushEvent</code>
|
|
<div class="mdetail-desc">
|
|
Fired when the local cache is flushed.
|
|
<div class="mdetail-params">
|
|
<strong style="font-weight:normal;">Subscribers will be called with the following parameters:</strong>
|
|
<ul><li><code>{Object}</code> : oSelf<div class="sub-desc">The DataSource instance</div></li> </ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This event is defined by DataSource.</div>
|
|
</div>
|
|
<a name="event-cacheQueryEvent"></a>
|
|
<div class="mdetail alt">
|
|
<h3>cacheQueryEvent</i></h3>
|
|
<code>public event cacheQueryEvent</code>
|
|
<div class="mdetail-desc">
|
|
Fired when a query is made to the local cache.
|
|
<div class="mdetail-params">
|
|
<strong style="font-weight:normal;">Subscribers will be called with the following parameters:</strong>
|
|
<ul><li><code>{Object}</code> : oSelf<div class="sub-desc">The DataSource instance.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The requesting object.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">The query string.</div></li> </ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This event is defined by DataSource.</div>
|
|
</div>
|
|
<a name="event-dataErrorEvent"></a>
|
|
<div class="mdetail">
|
|
<h3>dataErrorEvent</i></h3>
|
|
<code>public event dataErrorEvent</code>
|
|
<div class="mdetail-desc">
|
|
Fired when an error is encountered with the live data source.
|
|
<div class="mdetail-params">
|
|
<strong style="font-weight:normal;">Subscribers will be called with the following parameters:</strong>
|
|
<ul><li><code>{Object}</code> : oSelf<div class="sub-desc">The DataSource instance.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The requesting object.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">The query string.</div></li><li><code>{String}</code> : sMsg<div class="sub-desc">Error message string</div></li> </ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This event is defined by DataSource.</div>
|
|
</div>
|
|
<a name="event-getCachedResultsEvent"></a>
|
|
<div class="mdetail alt">
|
|
<h3>getCachedResultsEvent</i></h3>
|
|
<code>public event getCachedResultsEvent</code>
|
|
<div class="mdetail-desc">
|
|
Fired when data is retrieved from the local cache.
|
|
<div class="mdetail-params">
|
|
<strong style="font-weight:normal;">Subscribers will be called with the following parameters:</strong>
|
|
<ul><li><code>{Object}</code> : oSelf<div class="sub-desc">The DataSource instance.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The requesting object.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">The query string.</div></li><li><code>{Object[]}</code> : aResults<div class="sub-desc">Array of result objects.</div></li> </ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This event is defined by DataSource.</div>
|
|
</div>
|
|
<a name="event-getResultsEvent"></a>
|
|
<div class="mdetail">
|
|
<h3>getResultsEvent</i></h3>
|
|
<code>public event getResultsEvent</code>
|
|
<div class="mdetail-desc">
|
|
Fired when data is retrieved from the live data source.
|
|
<div class="mdetail-params">
|
|
<strong style="font-weight:normal;">Subscribers will be called with the following parameters:</strong>
|
|
<ul><li><code>{Object}</code> : oSelf<div class="sub-desc">The DataSource instance.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The requesting object.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">The query string.</div></li><li><code>{Object[]}</code> : aResults<div class="sub-desc">Array of result objects.</div></li> </ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This event is defined by DataSource.</div>
|
|
</div>
|
|
<a name="event-queryEvent"></a>
|
|
<div class="mdetail alt">
|
|
<h3>queryEvent</i></h3>
|
|
<code>public event queryEvent</code>
|
|
<div class="mdetail-desc">
|
|
Fired when a query is made to the live data source.
|
|
<div class="mdetail-params">
|
|
<strong style="font-weight:normal;">Subscribers will be called with the following parameters:</strong>
|
|
<ul><li><code>{Object}</code> : oSelf<div class="sub-desc">The DataSource instance.</div></li><li><code>{Object}</code> : oParent<div class="sub-desc">The requesting object.</div></li><li><code>{String}</code> : sQuery<div class="sub-desc">The query string.</div></li> </ul>
|
|
</div>
|
|
</div>
|
|
<div class="mdetail-def">This event is defined by DataSource.</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
Copyright © 2006 Jack Slocum. All rights reserved.
|
|
</body>
|
|
</html>
|
|
|