The DataSourceCache plugin enables caching on any DataSource to reduce high-latency calls to remote sources and to reduce server load. In this example, the Cache's `max` value has been set to `3`. + +
Use the plug() method to initialize the
+DataSourceCache plugin and pass in the configuration value
+max to set the maximum size.
DataSource.Function allows the implementer to define a JavaScript function that returns data values, for maximum customizeability. A DataSchema plugin is used to normalize incoming data into a known format for consistency of usage by other components.
+Your custom function can return arbitrary data, so use the appropriate schema plugin to normalize the data into a consistent format. Array data would use a DataSourceArraySchema plugin:
+ +``` +YUI().use("datasource-function", "datasource-arrayschema", function(Y) { + var myFunction = function(request) { + return [ + {name:"abc",id:123}, + {name:"def",id:456}, + {name:"ghi",id:789} + ]; + }, + myDataSource = new Y.DataSource.Function({source:myFunction}), + myCallback = { + success: function(e){ + alert(e.response); + }, + failure: function(e){ + alert("Could not retrieve data: " + e.error.message); + } + }; + + myDataSource.plug(Y.Plugin.DataSourceArraySchema, { + schema: { + resultFields: ["name","id"] + } + }); + + myDataSource.sendRequest({callback:myCallback}); +}); +``` + +Whereas JSON data would use a DataSourceJSONSchema plugin:
+ +``` +YUI().use("datasource-function", "datasource-jsonschema", function(Y) { + var myFunction = function(request) { + return { + "profile":{ + "current":160, + "target":150 + }, + "reference": [ + { + ... + }, + { + "category":"nutrition", + "type":"intake", + "fruit":[ + {"name":"apple", "calories":70}, + {"name":"banana", "calories":70}, + {"name":"orange", "calories":90}, + ], + "vegetables":[ + {"name":"baked potato", "calories":150}, + {"name":"broccoli", "calories":50}, + {"name":"green beans", "calories":30} + ] + } + ], + "program": [ + ... + ] + }; + }, + myDataSource = new Y.DataSource.Function({source:myFunction}), + myCallback = { + success: function(e){ + alert(e.response); + }, + failure: function(e){ + alert("Could not retrieve data: " + e.error.message); + } + }; + + myDataSource.plug(Y.Plugin.DataSourceJSONSchema, { + schema: { + resultListLocator: "reference[1].fruit", + resultFields: ["name","calories"] + } + }); + + myDataSource.sendRequest({callback:myCallback}); +}); +``` + diff --git a/src/datasource/docs/datasource-get.mustache b/src/datasource/docs/datasource-get.mustache new file mode 100644 index 00000000000..1beb582d855 --- /dev/null +++ b/src/datasource/docs/datasource-get.mustache @@ -0,0 +1,39 @@ + + +DataSource.Get uses the Get Utility to retrieve data, even cross-domain resources, via a dynamically created script node. A DataSchema plugin is used to normalize incoming data into a known format for consistency of usage by other components. Please note that your data resource must support a callback mechanism, which is a function wrapper around the returned data. The name of the callback function is passed to the resource via a query string parameter defined by the DataSource.Get attribute `scriptCallbackParam`.
+Use a DataSourceJSONSchema plugin to parse the data against a schema that you provide:
+ +``` +YUI().use("datasource-get", "datasource-jsonschema", function(Y) { + var myDataSource = new Y.DataSource.Get({ + source: "http://query.yahooapis.com/v1/public/yql?format=json&" + }); + + myDataSource.plug(Y.Plugin.DataSourceJSONSchema, { + schema: { + resultListLocator: "query.results.result", + resultFields: ["title"] + } + }); + + myDataSource.sendRequest({ + request: "q=select%20*%20from%20upcoming.events.bestinplace...", + callback: { + success: function (e) { /* output to screen */ }, + failure: function (e) { /* output to screen */ } + } + }); + +}); +``` + diff --git a/src/datasource/docs/datasource-local.mustache b/src/datasource/docs/datasource-local.mustache new file mode 100644 index 00000000000..50667753028 --- /dev/null +++ b/src/datasource/docs/datasource-local.mustache @@ -0,0 +1,118 @@ +Use DataSource.Local to manage retrieval of local data, from JavaScript arrays and objects to DOM elements. A DataSchema plugin is used to normalize incoming data into a known format for consistency of usage by other components.
+If you are working with local array data, use the DataSourceArraySchema plugin to normalize and filter the data into a consistent format:
+ +``` +YUI().use("datasource-local", "datasource-arrayschema", function(Y) { + var myData = [ + {name:"abc",id:123,extra:"foo"}, + {name:"def",id:456,extra:"bar"}, + {name:"ghi",id:789,extra:"baz"} + ], + myDataSource = new Y.DataSource.Local({source:myData}), + myCallback = { + success: function(e){ + alert(e.response); + }, + failure: function(e){ + alert("Could not retrieve data: " + e.error.message); + } + }; + + myDataSource.plug(Y.Plugin.DataSourceArraySchema, { + schema: { + resultFields: ["name","id"] + } + }); + + myDataSource.sendRequest({callback:myCallback}); +}); +``` + +Use the DataSourceJSONSchema plugin to normalize JSON data:
+ +``` +YUI().use("datasource-local", "datasource-jsonschema", function(Y) { + var myData = { + "profile":{ + "current":160, + "target":150 + }, + "reference": [ + { + ... + }, + { + "category":"nutrition", + "type":"intake", + "fruit":[ + {"name":"apple", "calories":70}, + {"name":"banana", "calories":70}, + {"name":"orange", "calories":90}, + ], + "vegetables":[ + {"name":"baked potato", "calories":150}, + {"name":"broccoli", "calories":50}, + {"name":"green beans", "calories":30} + ] + } + ], + "program": [ + ... + ] + }, + myDataSource = new Y.DataSource.Local({source:myData}), + myCallback = { + success: function(e){ + alert(e.response); + }, + failure: function(e){ + alert("Could not retrieve data: " + e.error.message); + } + }; + + myDataSource.plug(Y.Plugin.DataSourceJSONSchema, { + schema: { + resultListLocator: "reference[1].fruit", + resultFields: ["name","calories"] + } + }); + + myDataSource.sendRequest({callback:myCallback}); +}); +``` + +You can use the DataSourceXMLSchema plugin to work with DOM elements:
+ +``` +YUI().use("datasource-local", "datasource-xmlschema", function(Y) { + var myTable = Y.Node.getDOMNode(Y.one("#myTable")), + myDataSource = new Y.DataSource.Local({source:myTable}), + myCallback = { + success: function(e){ + alert(e.response); + }, + failure: function(e){ + alert("Could not retrieve data: " + e.error.message); + } + }; + + myDataSource.plug(Y.Plugin.DataSourceXMLSchema, { + schema: { + resultListLocator: "tr", + resultFields: [ + {key:"beverage", locator:"td[1]"}, + {key:"price", locator:"td[2]"} + ] + } + }); + + myDataSource.sendRequest({callback:myCallback}); +}); +``` diff --git a/src/datasource/docs/datasource-offlinecache.mustache b/src/datasource/docs/datasource-offlinecache.mustache new file mode 100644 index 00000000000..6fe8d110b75 --- /dev/null +++ b/src/datasource/docs/datasource-offlinecache.mustache @@ -0,0 +1,97 @@ + + +The DataSourceCache plugin enables caching on any DataSource to reduce high-latency calls to remote sources and to reduce server load. The plugin can point to `Y.OfflineCache` to allow cached data to persist across browser sessions in browsers that support HTML5 localStorage.
+ +Use the `plug()` method to initialize the DataSourceCache plugin +and point the configuration value `cache` to Y.CacheOffline to enable +offline caching. The configuration value `expires` can be set to +change how soon the data expires.
+ +``` +YUI().use("datasource", "dataschema", "cache", function(Y) { + var callback = { + success: function (e) { /* output to screen */ }, + failure: function (e) { /* output to screen */ } + }, + + myDataSource = new Y.DataSource.Get({ + source: "https://api.github.com/users/", + + // this is only needed because the query appends the url + // rather than the url's query params + generateRequestCallback: function (guid) { + return '/repos?callback=YUI.Env.DataSource.callbacks.' + guid; + } + }), + + myDataSource.plug(Y.Plugin.DataSourceJSONSchema, { + schema: { + resultListLocator: "data", + resultFields: ["name"] + } + }); + + // Enable offline data caching by pointing to Y.CacheOffline. + // For demonstration purposes, data is set to expire after 10 seconds + myDataSource.plug(Y.Plugin.DataSourceCache, { + cache: Y.CacheOffline, + expires: 10000, + max: 5 + }); + + // Retrieves from server. Adds to cache + myDataSource.sendRequest({ + request : "lsmith", + callback: callback + }); + + // Retrieves from server. Adds to cache + myDataSource.sendRequest({ + request : "davglass", + callback: callback + }); + + // Retrieves from cache if requested within 5 seconds + myDataSource.sendRequest({ + request : "lsmith", + callback: callback + }); + + // ... wait 10 seconds ... + + // Cached data has expired. Retrieves from server. Adds to cache. + myDataSource.sendRequest({ + request : "davglass", + callback: callback + }); +}); +``` + +DataSource's Pollable extension enables polling functionality on all your DataSource instances.
+Include the `datasource-pollable` extension in your `Y.use()` statement to add the `setInterval()`, `clearInterval()`, and `clearAllInterval()` methods to all your DataSource instances.
+ +``` +YUI().use("datasource-function", "datasource-polling", function(Y) { + var myFunction = function() { + return new Date(); + }, + myDataSource = new Y.DataSource.Function({source:myFunction}), + request = { + callback: { + success: function(e){ + Y.one("#demo_output_polling") + .setContent("At the tone the time will be: " + + Y.dump(e.response.results[0].toString())); + }, + failure: function(e){ + Y.one("#demo_output_polling") + .setContent("Could not retrieve data: " + e.error.message); + } + } + }, + id = myDataSource.setInterval(1000, request); // Starts polling + + myDataSource.clearInterval(id); // Ends polling +}); +``` \ No newline at end of file diff --git a/src/datasource/docs/datasource_polling_customheader.php b/src/datasource/docs/datasource_polling_customheader.php new file mode 100644 index 00000000000..f07ad9875f7 --- /dev/null +++ b/src/datasource/docs/datasource_polling_customheader.php @@ -0,0 +1,19 @@ + + +DataSource's Pollable extension enables polling functionality on all your DataSource instances.
+Include the `datasource-pollable` extension in your `Y.use()` statement to add the `setInterval()`, `clearInterval()`, and `clearAllInterval()` methods to all your DataSource instances.
+ +``` +YUI().use("datasource-function", "datasource-polling", function(Y) { +}); +``` \ No newline at end of file diff --git a/src/datasource/docs/index.mustache b/src/datasource/docs/index.mustache old mode 100755 new mode 100644 diff --git a/src/datasource/docs/partials/datasource-caching-source.mustache b/src/datasource/docs/partials/datasource-caching-source.mustache new file mode 100644 index 00000000000..8fa02da329a --- /dev/null +++ b/src/datasource/docs/partials/datasource-caching-source.mustache @@ -0,0 +1,85 @@ + + + diff --git a/src/datasource/docs/partials/datasource-function-source.mustache b/src/datasource/docs/partials/datasource-function-source.mustache new file mode 100644 index 00000000000..6aa8395853a --- /dev/null +++ b/src/datasource/docs/partials/datasource-function-source.mustache @@ -0,0 +1,147 @@ + + + diff --git a/src/datasource/docs/partials/datasource-get-source.mustache b/src/datasource/docs/partials/datasource-get-source.mustache new file mode 100644 index 00000000000..8c95845d92a --- /dev/null +++ b/src/datasource/docs/partials/datasource-get-source.mustache @@ -0,0 +1,89 @@ + + + + diff --git a/src/datasource/docs/partials/datasource-local-source.mustache b/src/datasource/docs/partials/datasource-local-source.mustache new file mode 100644 index 00000000000..4c68f64cb61 --- /dev/null +++ b/src/datasource/docs/partials/datasource-local-source.mustache @@ -0,0 +1,204 @@ + + + + + diff --git a/src/datasource/docs/partials/datasource-offlinecache-source.mustache b/src/datasource/docs/partials/datasource-offlinecache-source.mustache new file mode 100644 index 00000000000..a7a2852675e --- /dev/null +++ b/src/datasource/docs/partials/datasource-offlinecache-source.mustache @@ -0,0 +1,91 @@ + + + + + diff --git a/src/datasource/docs/partials/datasource-polling-source.mustache b/src/datasource/docs/partials/datasource-polling-source.mustache new file mode 100644 index 00000000000..8b2c76c568a --- /dev/null +++ b/src/datasource/docs/partials/datasource-polling-source.mustache @@ -0,0 +1,40 @@ + + +