Getting Started

To include the source files for DataSource and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('datasource', function (Y) {
    // DataSource is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using DataSources

DataSource basics

The DataSource Utility uses a callback mechanism to manage the data retrieval process across a wide variety of potential sources. Define your callback object with custom functions that will execute when the data returns from your source. The sendRequest() method accepts an object literal with properties for the request value, a callback object, and/or any configuration values for the request.

myDataSource.sendRequest({
    request: myRequest,
    on: {
        success: function(e){
            alert(e.response);
        },
        failure: function(e){
            alert(e.error.message);
        }
    }
});

You must instantiate the appropriate DataSource subclass for your source of data.

Local sources

Use DataSource.Local when you are working with data that is held in local memory, such as a JavaScript array or object.

var myDataSource = new Y.DataSource.Local({source:["a", "b", "c"]});

Remote sources with the Get Utility

Use DataSource.Get to access data coming from a server via the Get Utility. The Get Utility supports data retrieval from cross-domain resources without the need for a proxy, but the server must return JSON data and support a script callback parameter in order for the response to return properly. This parameter specifies the name of the internally defined function that the return data will be wrapped in when it returns to the page.

var myDataSource = new Y.DataSource.Get({
    source: "http://query.yahooapis.com/v1/public/yql?format=json&"
});

You should not modify the internally assigned value of this script callback parameter. However, you may need to set the parameter name to a different value so that your server will accept it. By default, the script callback parameter name is "callback", but this value can be changed via the Attribute scriptCallbackParam.

// By default the request is sent to
// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&callback=YUI.Env.DataSource.callbacks[0]"
myDataSource.sendRequest({
    request: "q=foo",
    callback: myCallback
});

// But the parameter name can be customized to match the server requirement
myDataSource.set("scriptCallbackParam", "cbFunc");

// So now the request is sent to
// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&cbFunc=YUI.Env.DataSource.callbacks[0]"
myDataSource.sendRequest({
    request: "q=foo",
    callback: myCallback
});

Use the DataSourceJSONSchema plugin to normalize the data that is sent to your callack.

// Normalize the data sent to myCallback
myDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
    schema: {
        resultListLocator: "myResults",
        resultFields: ["myField1", "myField2"]
    }
}});

Remote sources with the IO Utility

DataSource.IO is used to access data coming from a server via the IO Utility. Note that accessing a cross-domain server will require a same-domain proxy or enabling IO's XDR feature, in order to bypass standard browser security restrictions.

var myDataSource = new Y.DataSource.IO({source:"./myScript.php"});

The IO Utility supports retrieval of multiple data formats, including JSON, XML, and plain text. Use the appropriate DataSchema plugin to normalize the data that is sent to your callback.

myDataSource.plug({fn: Y.Plugin.DataSourceXMLSchema, cfg: {
    schema: {
        resultListLocator: "resultNodeName",
        resultFields: [{key:"myField1", locator:"xpath/to/value"}]
    }
}});

Sources using custom functions

Defining your own JavaScript function that returns data for a given request allows full customization of the data retrieval mechanism.

var myDataSource = new Y.DataSource.Function({
    source: function (request) {
        return data;
    }
});

Since your data can return data of any format, you may consider ways to taking advantage of the built-in infrastructure, including using a DataSchema plugin to normalize the data that is sent to your callback.

var myDataSource = new Y.DataSource.Function({
    source: function (request) {
        return [["ann", 123], ["bill", 456]];
    }
});

myDataSource.plug({fn: Y.Plugin.DataSourceArraySchema, cfg: {
    schema: {
        resultFields: ["name","id"]
    }
}});

Caching

The DataSourceCache plugin provides integrated caching functionality to your DataSource instance. Use the DataSource's plug() method to instantiate a Cache instance. Set the max Attribute value to the maximum number of entries the Cache should hold.

myDataSource.plug({fn:Y.Plugin.DataSourceCache, cfg:{max:3}});

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 cache namepace.

// Flush myDataSource's cache.
myDataSource.cache.flush();

// Disable myDataSource's cache
myDataSource.cache.set("max", 0);

Polling

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 datasource-polling sub-module in your YUI.use() statement.

YUI().use('datasource-io', 'datasource-polling', 'json-parse', function(Y) {
    var onlineFriends = Y.one('#friend-count'),
        friendData,
        intervalId;

    friendData = new Y.DataSource.IO({
        source: '/services/friends/'
    });

    // Start polling the server every 10 seconds
    intervalId = friendData.setInterval(10000, {
        request : Y.one('#user-id').get('value'),
        callback: {
            success: function (e) {
                var friends = Y.JSON.parse(e.response.results[0]).friendCount;

                if (!friends) {
                    friends = 'No friends.  You should go outside more.';
                }

                onlineFriends.set('text', friends);
            },
            failure: function (e) {
                onlineFriends.set('text',
                    '(Bang) Ouch! ' + e.error.message + ' happened!');

                // Stop polling
                friendData.clearInterval(intervalId);
            }
        }
    });
});

Events