+ The DataSource Utility provides a consistent API for the retrieval of + data from arbitrary sources over a variety of supported protocols. + DataSource plugins and extensions enable additional functionality such + as schema normalization, caching, and polling of data. +
+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.10.3/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
+| Event | +When | +Event properties | +
|---|---|---|
request |
+ Request is made. | +
+
|
+
data |
+ Raw data is received from the source. | +
+ All properties from request plus
+
|
+
response |
+ Response is returned to a callback function. | +
+ All properties from data plus
+
|
+
error |
+ After response event, before the configured failure callback is executed. |
+ Same properties as the response event |
+