webgui/www/extras/yui/docs/YAHOO.widget.DataSource.html
2008-03-25 16:13:25 +00:00

1159 lines
57 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>API: autocomplete YAHOO.widget.DataSource (YUI Library)</title>
<link rel="stylesheet" type="text/css" href="assets/api.css">
<script type="text/javascript" src="assets/api-js"></script>
<script type="text/javascript" src="assets/ac-js"></script>
</head>
<body id="yahoo-com">
<div id="doc3" class="yui-t2">
<div id="hd">
<a href="http://developer.yahoo.com/yui/"><h1>Yahoo! UI Library</h1></a>
<h3>AutoComplete Widget&nbsp; <span class="subtitle">2.5.1</span></h3>
<p>
<a href="./index.html">Yahoo! UI Library</a>
&gt; <a href="./module_autocomplete.html">autocomplete</a>
&gt; YAHOO.widget.DataSource
</p>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<form name="yui-classopts-form">
<span id="classopts"><input type="checkbox" name="showprivate" id="showprivate" /> Show Private</span>
<span id="classopts"><input type="checkbox" name="showprotected" id="showprotected" /> Show Protected</span>
</form>
<h2>
Class <b>YAHOO.widget.DataSource</b>
<span class="extends">
</span>
<span class="extends">
</span>
</code>
</h2>
<!-- class tree goes here -->
<dl class="subclasses">
<dt>Known Subclasses:</dd>
<dd>
<a href="YAHOO.widget.DS_XHR.html">YAHOO.widget.DS_XHR</a>
<a href="YAHOO.widget.DS_JSFunction.html">YAHOO.widget.DS_JSFunction</a>
<a href="YAHOO.widget.DS_JSArray.html">YAHOO.widget.DS_JSArray</a>
<a href="YAHOO.widget.DS_ScriptNode.html">YAHOO.widget.DS_ScriptNode</a>
</dd>
</dl>
<div class="summary 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>
<div class="section constructor details">
<h3 id="constructor">Constructor</h3>
<div class="content">
<div class="detail">
<strong>YAHOO.widget.DataSource</strong>
<code>
(
)
</code>
<div class="description">
</div>
</div>
</div>
</div>
<div class="section field details">
<h3 id="properties">Properties</h3>
<div class="content">
<div class="private">
<h4><a name="property__aCache">_aCache</a>
<code>- private Object[]</code>
</h4>
<div class="detail">
<div class="description">
Local cache of data result objects indexed chronologically.
</div>
</div>
<hr />
</div>
<div class="private">
<h4><a name="property__nIndex">_nIndex</a>
<code>- private static Number</code>
</h4>
<div class="detail">
<div class="description">
Internal class variable to index multiple DataSource instances.
</div>
</div>
<hr />
</div>
<div class="private">
<h4><a name="property__sName">_sName</a>
<code>- private String</code>
</h4>
<div class="detail">
<div class="description">
Name of DataSource instance.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_ERROR_DATANULL">ERROR_DATANULL</a>
<code>- static final String</code>
</h4>
<div class="detail">
<div class="description">
Error message for null data responses.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_ERROR_DATAPARSE">ERROR_DATAPARSE</a>
<code>- static final String</code>
</h4>
<div class="detail">
<div class="description">
Error message for data responses with parsing errors.
</div>
</div>
<hr />
</div>
<div class="">
<h4><a name="property_maxCacheEntries">maxCacheEntries</a>
<code>- Number</code>
</h4>
<div class="detail">
<div class="description">
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>
<div class="default">
Default Value: 15
</div>
<hr />
</div>
<div class="">
<h4><a name="property_queryMatchCase">queryMatchCase</a>
<code>- Boolean</code>
</h4>
<div class="detail">
<div class="description">
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.
</div>
</div>
<div class="default">
Default Value: false
</div>
<hr />
</div>
<div class="">
<h4><a name="property_queryMatchContains">queryMatchContains</a>
<code>- Boolean</code>
</h4>
<div class="detail">
<div class="description">
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.
</div>
</div>
<div class="default">
Default Value: false
</div>
<hr />
</div>
<div class="">
<h4><a name="property_queryMatchSubset">queryMatchSubset</a>
<code>- Boolean</code>
</h4>
<div class="detail">
<div class="description">
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>
<div class="default">
Default Value: false
</div>
<hr />
</div>
</div>
</div>
<div class="section method details">
<h3 id="methods">Methods</h3>
<div class="content">
<div class="private">
<h4>
<a name="method__addCacheElem">_addCacheElem</a></h4>
<div class="detail">
<code>
private
void
<strong>_addCacheElem</strong>
(
oResult
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oResult &lt;Object&gt;</code>
Data result object, including array of results.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__doQueryCache">_doQueryCache</a></h4>
<div class="detail">
<code>
private
Object[]
<strong>_doQueryCache</strong>
(
oCallbackFn
,
sQuery
,
oParent
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oCallbackFn &lt;HTMLFunction&gt;</code>
Callback function defined by oParent object to which to return results.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
Query string.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The object instance that has requested data.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
Object[]
</code></dt>
<dd>aResults Array of results from local cache if found, otherwise null.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__init">_init</a></h4>
<div class="detail">
<code>
private
void
<strong>_init</strong>
(
)
</code>
<div class="description">
Initializes DataSource instance.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_doQuery">doQuery</a></h4>
<div class="detail">
<code>
void
<strong>doQuery</strong>
(
oCallbackFn
,
sQuery
,
oParent
)
</code>
<div class="description">
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>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oCallbackFn &lt;HTMLFunction&gt;</code>
Callback function implemented by oParent to which to return results.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
Query string.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The object instance that has requested data.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_flushCache">flushCache</a></h4>
<div class="detail">
<code>
void
<strong>flushCache</strong>
(
)
</code>
<div class="description">
Flushes cache.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_getResults">getResults</a></h4>
<div class="detail">
<code>
void
<strong>getResults</strong>
(
oCallbackFn
,
sQuery
,
oParent
)
</code>
<div class="description">
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>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oCallbackFn &lt;HTMLFunction&gt;</code>
Callback function defined by oParent object to which to return results.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
Query string.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The object instance that has requested data.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_toString">toString</a></h4>
<div class="detail">
<code>
String
<strong>toString</strong>
(
)
</code>
<div class="description">
Public accessor to the unique name of the DataSource instance.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
String
</code></dt>
<dd>Unique name of the DataSource instance</dd>
</dl>
</div>
</div>
<hr />
</div>
</div>
</div>
<div class="section method details">
<h3 id="events">Events</h3>
<div class="content">
<div class="">
<h4>
<a name="event_cacheFlushEvent">cacheFlushEvent</a></h4>
<div class="detail">
<code>
<strong>cacheFlushEvent</strong>
(
oSelf
)
</code>
<div class="description">
Fired when the local cache is flushed.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oSelf &lt;Object&gt;</code>
The DataSource instance
</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="event_cacheQueryEvent">cacheQueryEvent</a></h4>
<div class="detail">
<code>
<strong>cacheQueryEvent</strong>
(
oSelf
,
oParent
,
sQuery
)
</code>
<div class="description">
Fired when a query is made to the local cache.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oSelf &lt;Object&gt;</code>
The DataSource instance.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The requesting object.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
The query string.
</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="event_dataErrorEvent">dataErrorEvent</a></h4>
<div class="detail">
<code>
<strong>dataErrorEvent</strong>
(
oSelf
,
oParent
,
sQuery
,
sMsg
)
</code>
<div class="description">
Fired when an error is encountered with the live data source.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oSelf &lt;Object&gt;</code>
The DataSource instance.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The requesting object.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
The query string.
</dd>
<dd>
<code>sMsg &lt;String&gt;</code>
Error message string
</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="event_getCachedResultsEvent">getCachedResultsEvent</a></h4>
<div class="detail">
<code>
<strong>getCachedResultsEvent</strong>
(
oSelf
,
oParent
,
sQuery
,
aResults
)
</code>
<div class="description">
Fired when data is retrieved from the local cache.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oSelf &lt;Object&gt;</code>
The DataSource instance.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The requesting object.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
The query string.
</dd>
<dd>
<code>aResults &lt;Object[]&gt;</code>
Array of result objects.
</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="event_getResultsEvent">getResultsEvent</a></h4>
<div class="detail">
<code>
<strong>getResultsEvent</strong>
(
oSelf
,
oParent
,
sQuery
,
aResults
)
</code>
<div class="description">
Fired when data is retrieved from the live data source.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oSelf &lt;Object&gt;</code>
The DataSource instance.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The requesting object.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
The query string.
</dd>
<dd>
<code>aResults &lt;Object[]&gt;</code>
Array of result objects.
</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="event_queryEvent">queryEvent</a></h4>
<div class="detail">
<code>
<strong>queryEvent</strong>
(
oSelf
,
oParent
,
sQuery
)
</code>
<div class="description">
Fired when a query is made to the live data source.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>oSelf &lt;Object&gt;</code>
The DataSource instance.
</dd>
<dd>
<code>oParent &lt;Object&gt;</code>
The requesting object.
</dd>
<dd>
<code>sQuery &lt;String&gt;</code>
The query string.
</dd>
</dl>
</div>
</div>
<hr />
</div>
</div>
</div>
</div>
</div>
<div class="yui-b">
<div class="nav">
<div class="module">
<h4>Modules</h4>
<ul class="content">
<li class=""><a href="module_animation.html">animation</a></li>
<li class="selected"><a href="module_autocomplete.html">autocomplete</a></li>
<li class=""><a href="module_button.html">button</a></li>
<li class=""><a href="module_calendar.html">calendar</a></li>
<li class=""><a href="module_charts.html">charts</a></li>
<li class=""><a href="module_colorpicker.html">colorpicker</a></li>
<li class=""><a href="module_connection.html">connection</a></li>
<li class=""><a href="module_container.html">container</a></li>
<li class=""><a href="module_cookie.html">cookie</a></li>
<li class=""><a href="module_datasource.html">datasource</a></li>
<li class=""><a href="module_datatable.html">datatable</a></li>
<li class=""><a href="module_dom.html">dom</a></li>
<li class=""><a href="module_dragdrop.html">dragdrop</a></li>
<li class=""><a href="module_editor.html">editor</a></li>
<li class=""><a href="module_element.html">element</a></li>
<li class=""><a href="module_event.html">event</a></li>
<li class=""><a href="module_get.html">get</a></li>
<li class=""><a href="module_history.html">history</a></li>
<li class=""><a href="module_imagecropper.html">imagecropper</a></li>
<li class=""><a href="module_imageloader.html">imageloader</a></li>
<li class=""><a href="module_json.html">json</a></li>
<li class=""><a href="module_layout.html">layout</a></li>
<li class=""><a href="module_logger.html">logger</a></li>
<li class=""><a href="module_menu.html">menu</a></li>
<li class=""><a href="module_profiler.html">profiler</a></li>
<li class=""><a href="module_profilerviewer.html">profilerviewer</a></li>
<li class=""><a href="module_resize.html">resize</a></li>
<li class=""><a href="module_selector.html">selector</a></li>
<li class=""><a href="module_slider.html">slider</a></li>
<li class=""><a href="module_tabview.html">tabview</a></li>
<li class=""><a href="module_treeview.html">treeview</a></li>
<li class=""><a href="module_uploader.html">uploader</a></li>
<li class=""><a href="module_yahoo.html">yahoo</a></li>
<li class=""><a href="module_yuiloader.html">yuiloader</a></li>
<li class=""><a href="module_yuitest.html">yuitest</a></li>
</ul>
</div>
<div class="module">
<h4>Classes</h4>
<ul class="content">
<li class=""><a href="YAHOO.widget.AutoComplete.html">YAHOO.widget.AutoComplete</a></li>
<li class="selected"><a href="YAHOO.widget.DataSource.html">YAHOO.widget.DataSource</a></li>
<li class=""><a href="YAHOO.widget.DS_JSArray.html">YAHOO.widget.DS_JSArray</a></li>
<li class=""><a href="YAHOO.widget.DS_JSFunction.html">YAHOO.widget.DS_JSFunction</a></li>
<li class=""><a href="YAHOO.widget.DS_ScriptNode.html">YAHOO.widget.DS_ScriptNode</a></li>
<li class=""><a href="YAHOO.widget.DS_XHR.html">YAHOO.widget.DS_XHR</a></li>
</ul>
</div>
<div class="module">
<h4>Files</h4>
<ul class="content">
<li class=""><a href="AutoComplete.js.html">AutoComplete.js</a></li>
<li class=""><a href="DataSource.js.html">DataSource.js</a></li>
</ul>
</div>
<div class="module">
<h4>Properties</h4>
<ul class="content">
<li class="private"><a href="#property__aCache">_aCache</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class="private"><a href="#property__nIndex">_nIndex</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class="private"><a href="#property__sName">_sName</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class=""><a href="#property_ERROR_DATANULL">ERROR_DATANULL</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class=""><a href="#property_ERROR_DATAPARSE">ERROR_DATAPARSE</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class=""><a href="#property_maxCacheEntries">maxCacheEntries</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class=""><a href="#property_queryMatchCase">queryMatchCase</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class=""><a href="#property_queryMatchContains">queryMatchContains</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
<li class=""><a href="#property_queryMatchSubset">queryMatchSubset</a>
<!--<code>&lt;Boolean&gt;</code>-->
</li>
</ul>
</div>
<div class="module">
<h4>Methods</h4>
<ul class="content">
<li class="private"><!--<code>void</code>-->
<a href="#method__addCacheElem">_addCacheElem</a>
</li>
<li class="private"><!--<code>Object[]</code>-->
<a href="#method__doQueryCache">_doQueryCache</a>
</li>
<li class="private"><!--<code>void</code>-->
<a href="#method__init">_init</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_doQuery">doQuery</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_flushCache">flushCache</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_getResults">getResults</a>
</li>
<li class=""><!--<code>String</code>-->
<a href="#method_toString">toString</a>
</li>
</ul>
</div>
<div class="module">
<h4>Events</h4>
<ul class="content">
<li class="">
<a href="#event_cacheFlushEvent">cacheFlushEvent</a>
</li>
<li class="">
<a href="#event_cacheQueryEvent">cacheQueryEvent</a>
</li>
<li class="">
<a href="#event_dataErrorEvent">dataErrorEvent</a>
</li>
<li class="">
<a href="#event_getCachedResultsEvent">getCachedResultsEvent</a>
</li>
<li class="">
<a href="#event_getResultsEvent">getResultsEvent</a>
</li>
<li class="">
<a href="#event_queryEvent">queryEvent</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="ft">
<hr />
Copyright &copy; 2007 Yahoo! Inc. All rights reserved.
</div>
</div>
</body>
</html>