YUI 3: DataSource [beta]

Getting Started

Include Dependencies

The easiest way to include the source files for DataSource and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:

<!-- YUI Seed --> <script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

The YUI instance will automatically pull down DataSource's source files and any missing dependencies when the datasource module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.

If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use DataSource.

The YUI Instance

Once you have the YUI seed file on your page (yui-min.js), you can create a new YUI instance for your application to use and populate it with the modules you need, specified as the first set of arguments to the use method:

// Create new YUI instance, and populate it with the required modules YUI().use("datasource", function(Y) { // DataSource available, and ready for use. });

The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the datasource module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.

For more information on creating instances of YUI and the use method, see the YUI Global object documentation.

Using the DataSource Utility

This section describes how to use the DataSource Utility in further detail. It contains these subsections:

• DataSource basics
• Local sources
• Remote sources with the Get Utility
• Remote sources with the IO Utility
• Sources using custom functions
• Caching
• Polling
• Events

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 the request as the first argument and a callback object as the second argument.

myDataSource.sendRequest(myRequest, { 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("q=foo", 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("q=foo", 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-function", "datasource-polling", function(Y) { var myFunction = function() { return new Date(); }, myDataSource = new Y.DataSource.Function({source:myFunction}), callback = { success: function(e){ alert("At the tone the time will be: " + e.response.results[0]); }, failure: function(e){ alert("Could not retrieve data: " + e.error.message); } }, id = myDataSource.setInterval(1000, null,callback); // Starts polling myDataSource.clearInterval(id); // Ends polling });

Events

Event	When	Properties available on the Event Facade passed to handler
request	Request is made.	tId Unique transaction ID. request The request object. callback The callback object. cfg The configuration object.
data	Raw data is received from the source.	tId Unique transaction ID. request The request object. callback The callback object. cfg The configuration object. data The raw data.
response	Response is returned to a callback function.	tId Unique transaction ID. request The request object. callback The callback object. cfg The configuration object. data The raw data. response Data normalized into a response object.
error	An error is encountered	tId Unique transaction ID. request The request object. callback The callback object. cfg The configuration object. data The raw data. response Data normalized into a response object.

Support & Community