daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<div class="intro component">
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The DataSource Utility provides a consistent API for the retrieval of
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith data from arbitrary sources over a variety of supported protocols.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith DataSource plugins and extensions enable additional functionality such
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith as schema normalization, caching, and polling of data.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith{{>getting-started}}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="using">Using DataSources</h2>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="basics">DataSource basics</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The DataSource Utility uses a callback mechanism to manage the data
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith retrieval process across a wide variety of potential sources. Define your
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith callback object with custom functions that will execute when the data
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith returns from your source. The <code>sendRequest()</code> method accepts an
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith object literal with properties for the request value, a callback object,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith and/or any configuration values for the request.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: myRequest,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith success: function(e){
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith failure: function(e){
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith You must instantiate the appropriate DataSource subclass for your source of
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="local">Local sources</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Use DataSource.Local when you are working with data that is held in local
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith memory, such as a JavaScript array or object.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Local({source:["a", "b", "c"]});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="get">Remote sources with the Get Utility</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Use DataSource.Get to access data coming from a server via the Get Utility.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The Get Utility supports data retrieval from cross-domain resources without
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith the need for a proxy, but the server must return JSON data and support a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith script callback parameter in order for the response to return properly.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith This parameter specifies the name of the internally defined function that
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith the return data will be wrapped in when it returns to the page.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Get({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: "http://query.yahooapis.com/v1/public/yql?format=json&"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith You should not modify the internally assigned value of this script callback
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith parameter. However, you may need to set the parameter name to a different
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith value so that your server will accept it. By default, the script callback
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith parameter name is <code>"callback"</code>, but this value can be changed
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith via the Attribute <code>scriptCallbackParam</code>.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// By default the request is sent to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&callback=YUI.Env.DataSource.callbacks[0]"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "q=foo",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith callback: myCallback
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// But the parameter name can be customized to match the server requirement
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.set("scriptCallbackParam", "cbFunc");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// So now the request is sent to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&cbFunc=YUI.Env.DataSource.callbacks[0]"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request: "q=foo",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith callback: myCallback
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Use the DataSourceJSONSchema plugin to normalize the data that is sent to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith your callack.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Normalize the data sent to myCallback
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "myResults",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: ["myField1", "myField2"]
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="io">Remote sources with the IO Utility</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith DataSource.IO is used to access data coming from a server via the IO
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Utility. Note that accessing a cross-domain server will require a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith same-domain proxy or enabling IO's XDR feature, in order to bypass standard
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith browser security restrictions.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.IO({source:"./myScript.php"});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The IO Utility supports retrieval of multiple data formats, including JSON,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith XML, and plain text. Use the appropriate DataSchema plugin to normalize the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith data that is sent to your callback.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.plug({fn: Y.Plugin.DataSourceXMLSchema, cfg: {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultListLocator: "resultNodeName",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: [{key:"myField1", locator:"xpath/to/value"}]
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="function">Sources using custom functions</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Defining your own JavaScript function that returns data for a given request
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith allows full customization of the data retrieval mechanism.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Function({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: function (request) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return data;
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Since your data can return data of any format, you may consider ways to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith taking advantage of the built-in infrastructure, including using a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith DataSchema plugin to normalize the data that is sent to your callback.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar myDataSource = new Y.DataSource.Function({
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith source: function (request) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return [["ann", 123], ["bill", 456]];
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.plug({fn: Y.Plugin.DataSourceArraySchema, cfg: {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith resultFields: ["name","id"]
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="caching">Caching</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The DataSourceCache plugin provides integrated caching functionality to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith your DataSource instance. Use the DataSource's <code>plug()</code> method
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith to instantiate a Cache instance. Set the <code>max</code> Attribute value
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith to the maximum number of entries the Cache should hold.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithmyDataSource.plug({fn:Y.Plugin.DataSourceCache, cfg:{max:3}});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Once the plugin is enabled, it will handle caching and retrieval of values
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith seamlessly for you without the need for extra code. However, all the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith methods and properties of the Cache instance is available on the DataSource
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith instance's <code>cache</code> namepace.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Flush myDataSource's cache.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Disable myDataSource's cache
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="polling">Polling</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Pollable is a DataSource extension that enhances the class with polling
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith functionality. Once the extension is applied, all instances of DataSource
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith will have available on their prototype the methods that enable and disable
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith requests sent at regular intervals. To apply the extension, simply include
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith the <code>datasource-polling</code> sub-module in your
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>YUI.use()</code> statement.
ce82477cabe9511f9b4db3793dc39704214058d3Luke SmithYUI().use('datasource-io', 'datasource-polling', 'json-parse', function(Y) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith var onlineFriends = Y.one('#friend-count'),
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith friendData = new Y.DataSource.IO({
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith // Start polling the server every 10 seconds
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith intervalId = friendData.setInterval(10000, {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith request : Y.one('#user-id').get('value'),
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith success: function (e) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith var friends = Y.JSON.parse(e.response.results[0]).friendCount;
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith if (!friends) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith friends = 'No friends. You should go outside more.';
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith onlineFriends.set('text', friends);
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith failure: function (e) {
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith '(Bang) Ouch! ' + e.error.message + ' happened!');
ce82477cabe9511f9b4db3793dc39704214058d3Luke Smith // Stop polling
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="events">Events</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Event</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>When</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Event properties</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>request</code></td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>Request is made.</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dt><code>tId</code></dt>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dd>Unique transaction ID.</dd>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dt><code>request</code></dt>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dd>The request value.</dd>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dt><code>callback</code></dt>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dd>The callback object.</dd>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dt><code>cfg</code></dt>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dd>The configuration object.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>data</code></td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>Raw data is received from the source.</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith All properties from `request` plus
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dt><code>data</code></dt>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dd>The raw data.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>response</code></td>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>Response is returned to a callback function.</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith All properties from `data` plus
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dt><code>response</code></dt>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <dd>Data normalized into a response object.</dd>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td><code>error</code></td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td>After `response` event, before the configured failure callback is executed.</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <td>Same properties as the `response` event</td>