5462N/A<div class="intro component">
5462N/A The DataSource Utility provides a consistent API for the retrieval of
5462N/A data from arbitrary sources over a variety of supported protocols.
5462N/A DataSource plugins and extensions enable additional functionality such
5462N/A as schema normalization, caching, and polling of data.
5462N/A<h2 id="using">Using DataSources</h2>
5462N/A<h3 id="basics">DataSource basics</h3>
5462N/A The DataSource Utility uses a callback mechanism to manage the data
5462N/A retrieval process across a wide variety of potential sources. Define your
5462N/A callback object with custom functions that will execute when the data
5462N/A returns from your source. The <code>sendRequest()</code> method accepts an
5462N/A object literal with properties for the request value, a callback object,
5462N/A You must instantiate the appropriate DataSource subclass for your source of
5462N/A<h4 id="local">Local sources</h4>
5462N/A memory, such as a JavaScript array or object.
5462N/A<h4 id="get">Remote sources with the Get Utility</h4>
5462N/A The Get Utility supports data retrieval from cross-domain resources without
5462N/A the need for a proxy, but the server must return JSON data and support a
5462N/A script callback parameter in order for the response to return properly.
5462N/A This parameter specifies the name of the internally defined function that
5462N/A the return data will be wrapped in when it returns to the page.
5462N/A You should not modify the internally assigned value of this script callback
5462N/A parameter. However, you may need to set the parameter name to a different
5462N/A value so that your server will accept it. By default, the script callback
5462N/A parameter name is <code>"callback"</code>, but this value can be changed
5462N/A via the Attribute <code>scriptCallbackParam</code>.
5462N/A// By default the request is sent to
5462N/A// But the parameter name can be customized to match the server requirement
5462N/A// So now the request is sent to
5462N/A Use the DataSourceJSONSchema plugin to normalize the data that is sent to
5462N/A// Normalize the data sent to myCallback
5462N/A resultListLocator: "myResults",
5462N/A resultFields: ["myField1", "myField2"]
5462N/A<h4 id="io">Remote sources with the IO Utility</h4>
5462N/A Utility. Note that accessing a cross-domain server will require a
5462N/A same-domain proxy or enabling IO's XDR feature, in order to bypass standard
5462N/A browser security restrictions.
5462N/A The IO Utility supports retrieval of multiple data formats, including JSON,
5462N/A XML, and plain text. Use the appropriate DataSchema plugin to normalize the
5462N/A data that is sent to your callback.
5462N/A resultListLocator: "resultNodeName",
5462N/A<h4 id="function">Sources using custom functions</h4>
5462N/A Defining your own JavaScript function that returns data for a given request
5462N/A allows full customization of the data retrieval mechanism.
5462N/A source: function (request) {
5462N/A Since your data can return data of any format, you may consider ways to
5462N/A taking advantage of the built-in infrastructure, including using a
5462N/A DataSchema plugin to normalize the data that is sent to your callback.
5462N/A source: function (request) {
5462N/A return [["ann", 123], ["bill", 456]];
5462N/A resultFields: ["name","id"]
5462N/A<h3 id="caching">Caching</h3>
5462N/A The DataSourceCache plugin provides integrated caching functionality to
5462N/A your DataSource instance. Use the DataSource's <code>plug()</code> method
5462N/A to instantiate a Cache instance. Set the <code>max</code> Attribute value
5462N/A to the maximum number of entries the Cache should hold.
Once the plugin is enabled, it will handle caching and retrieval of values
seamlessly for you without the need for extra code. However, all the
methods and properties of the Cache instance is available on the DataSource
instance's <code>cache</code> namepace.
// Flush myDataSource's cache.
// Disable myDataSource's cache
<h3 id="polling">Polling</h3>
Pollable is a DataSource extension that enhances the class with polling
functionality. Once the extension is applied, all instances of DataSource
will have available on their prototype the methods that enable and disable
requests sent at regular intervals. To apply the extension, simply include
the <code>datasource-polling</code> sub-module in your
YUI().use("datasource-function", "datasource-polling", function(Y) {
var myFunction = function() {
<h3 id="events">Events</h3>
<th>Event properties</th>
<td><code>request</code></td>
<td>Request is made.</td>
<dt><code>tId</code></dt>
<dd>Unique transaction ID.</dd>
<dt><code>request</code></dt>
<dd>The request value.</dd>
<dt><code>callback</code></dt>
<dd>The callback object.</dd>
<dt><code>cfg</code></dt>
<dd>The configuration object.</dd>
<td><code>data</code></td>
<td>Raw data is received from the source.</td>
All properties from `request` plus
<dt><code>data</code></dt>
<td><code>response</code></td>
<td>Response is returned to a callback function.</td>
All properties from `data` plus
<dt><code>response</code></dt>
<dd>Data normalized into a response object.</dd>
<td><code>error</code></td>
<td>After `response` event, before the configured failure callback is executed.</td>
<td>Same properties as the `response` event</td>