index.mustache revision 14ea8dcb06b6d844dd99b7e18cca99172bea0cfd
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley<div class="intro component">
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence The DataSource Utility provides a consistent API for the retrieval of
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley data from arbitrary sources over a variety of supported protocols.
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley DataSource plugins and extensions enable additional functionality such
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley as schema normalization, caching, and polling of data.
15a44745412679c30a6d022733925af70a38b715David Lawrence{{>getting-started}}
15a44745412679c30a6d022733925af70a38b715David Lawrence<h2 id="using">Using DataSources</h2>
15a44745412679c30a6d022733925af70a38b715David Lawrence<h3 id="basics">DataSource basics</h3>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley The DataSource Utility uses a callback mechanism to manage the data
80b782f356f0692c11b4e52e8dd46ec41704e5a2Mark Andrews retrieval process across a wide variety of potential sources. Define your
9c3531d72aeaad6c5f01efe6a1c82023e1379e4dDavid Lawrence callback object with custom functions that will execute when the data
110d1702731f42dd620879c1d765ebe91f3920ceMichael Graff returns from your source. The <code>sendRequest()</code> method accepts an
110d1702731f42dd620879c1d765ebe91f3920ceMichael Graff object literal with properties for the request value, a callback object,
c3b708aaf1bb0a118e0e11befa1b732acfb1d079Bob Halley and/or any configuration values for the request.
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley request: myRequest,
8dfa9caeec8e68db0c937e347a3d6629e7627d54Bob Halley success: function(e){
52637f592f705ca93fadc218e403fd55e8ce4aeaMark Andrews failure: function(e){
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley You must instantiate the appropriate DataSource subclass for your source of
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley<h4 id="local">Local sources</h4>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley Use DataSource.Local when you are working with data that is held in local
ca67883a666bdf314d3da958d5195e7215b1f797Bob Halley memory, such as a JavaScript array or object.
5619558151f1aa4249b3ead979e76876e29278b6Bob Halleyvar myDataSource = new Y.DataSource.Local({source:["a", "b", "c"]});
e496615043400500492fa7b891c515c8e7cb7d08Bob Halley<h4 id="get">Remote sources with the Get Utility</h4>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley Use DataSource.Get to access data coming from a server via the Get Utility.
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley The Get Utility supports data retrieval from cross-domain resources without
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley the need for a proxy, but the server must return JSON data and support a
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley script callback parameter in order for the response to return properly.
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley This parameter specifies the name of the internally defined function that
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley the return data will be wrapped in when it returns to the page.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrencevar myDataSource = new Y.DataSource.Get({
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley source: "http://query.yahooapis.com/v1/public/yql?format=json&"
ca67883a666bdf314d3da958d5195e7215b1f797Bob Halley You should not modify the internally assigned value of this script callback
732e0731dec1922747bb3b3147cf2c3d16b22eaaBob Halley parameter. However, you may need to set the parameter name to a different
b12f0228b32775ee688ed21ddbf3a116c1adfb43Michael Graff value so that your server will accept it. By default, the script callback
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley parameter name is <code>"callback"</code>, but this value can be changed
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley via the Attribute <code>scriptCallbackParam</code>.
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley// By default the request is sent to
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&callback=YUI.Env.DataSource.callbacks[0]"
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley request: "q=foo",
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley callback: myCallback
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley// But the parameter name can be customized to match the server requirement
5619558151f1aa4249b3ead979e76876e29278b6Bob HalleymyDataSource.set("scriptCallbackParam", "cbFunc");
0180ccf72c79b98eb8ee5abbb7331aec6951dd9fBob Halley// So now the request is sent to
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&cbFunc=YUI.Env.DataSource.callbacks[0]"
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley request: "q=foo",
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley callback: myCallback
732e0731dec1922747bb3b3147cf2c3d16b22eaaBob Halley Use the DataSourceJSONSchema plugin to normalize the data that is sent to
b12f0228b32775ee688ed21ddbf3a116c1adfb43Michael Graff your callack.
80b782f356f0692c11b4e52e8dd46ec41704e5a2Mark Andrews// Normalize the data sent to myCallback
e496615043400500492fa7b891c515c8e7cb7d08Bob HalleymyDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley resultListLocator: "myResults",
28640d1da26d561f4137122fe64e9e8cc08bf11eBob Halley resultFields: ["myField1", "myField2"]
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence<h4 id="io">Remote sources with the IO Utility</h4>
28640d1da26d561f4137122fe64e9e8cc08bf11eBob Halley DataSource.IO is used to access data coming from a server via the IO
28640d1da26d561f4137122fe64e9e8cc08bf11eBob Halley Utility. Note that accessing a cross-domain server will require a
28640d1da26d561f4137122fe64e9e8cc08bf11eBob Halley same-domain proxy or enabling IO's XDR feature, in order to bypass standard
28640d1da26d561f4137122fe64e9e8cc08bf11eBob Halley browser security restrictions.
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halleyvar myDataSource = new Y.DataSource.IO({source:"./myScript.php"});
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff The IO Utility supports retrieval of multiple data formats, including JSON,
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley XML, and plain text. Use the appropriate DataSchema plugin to normalize the
e02884167b7c969b56413f76c48c3802c4dca14dAndreas Gustafsson data that is sent to your callback.
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob HalleymyDataSource.plug({fn: Y.Plugin.DataSourceXMLSchema, cfg: {
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley resultListLocator: "resultNodeName",
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley resultFields: [{key:"myField1", locator:"xpath/to/value"}]
e02884167b7c969b56413f76c48c3802c4dca14dAndreas Gustafsson<h4 id="function">Sources using custom functions</h4>
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley Defining your own JavaScript function that returns data for a given request
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley allows full customization of the data retrieval mechanism.
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halleyvar myDataSource = new Y.DataSource.Function({
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley source: function (request) {
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley return data;
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley Since your data can return data of any format, you may consider ways to
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley taking advantage of the built-in infrastructure, including using a
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley DataSchema plugin to normalize the data that is sent to your callback.
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halleyvar myDataSource = new Y.DataSource.Function({
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley source: function (request) {
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley return [["ann", 123], ["bill", 456]];
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob HalleymyDataSource.plug({fn: Y.Plugin.DataSourceArraySchema, cfg: {
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley resultFields: ["name","id"]
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley<h3 id="caching">Caching</h3>
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley The DataSourceCache plugin provides integrated caching functionality to
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley your DataSource instance. Use the DataSource's <code>plug()</code> method
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley to instantiate a Cache instance. Set the <code>max</code> Attribute value
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley to the maximum number of entries the Cache should hold.
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob HalleymyDataSource.plug({fn:Y.Plugin.DataSourceCache, cfg:{max:3}});
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley Once the plugin is enabled, it will handle caching and retrieval of values
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley seamlessly for you without the need for extra code. However, all the
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley methods and properties of the Cache instance is available on the DataSource
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley instance's <code>cache</code> namepace.
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley// Flush myDataSource's cache.
7837d146219db7a85a4b444a9cdf6602254a4f75Bob Halley// Disable myDataSource's cache
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley<h3 id="polling">Polling</h3>
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley Pollable is a DataSource extension that enhances the class with polling
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley functionality. Once the extension is applied, all instances of DataSource
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley will have available on their prototype the methods that enable and disable
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley requests sent at regular intervals. To apply the extension, simply include
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley the <code>datasource-polling</code> sub-module in your
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob Halley <code>YUI.use()</code> statement.
1c724c986de1449e3b2f1eeae4c724dc0d97603cBob HalleyYUI().use("datasource-function", "datasource-polling", function(Y) {
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graff var myFunction = function() {
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley return new Date();
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley myDataSource = new Y.DataSource.Function({source:myFunction}),
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley callback = {
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley success: function(e){
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley alert("At the tone the time will be: " + e.response.results[0]);
0180ccf72c79b98eb8ee5abbb7331aec6951dd9fBob Halley failure: function(e){
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley alert("Could not retrieve data: " + e.error.message);
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley id = myDataSource.setInterval(1000, null,callback); // Starts polling
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley myDataSource.clearInterval(id); // Ends polling
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley<h3 id="events">Events</h3>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <th>Event</th>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <th>When</th>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <th>Event properties</th>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <td><code>request</code></td>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <td>Request is made.</td>
078d49b63324f01d98301ee21671abee0c41fcdeBob Halley <dt><code>tId</code></dt>
0180ccf72c79b98eb8ee5abbb7331aec6951dd9fBob Halley <dd>Unique transaction ID.</dd>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <dt><code>request</code></dt>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <dd>The request value.</dd>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <dt><code>callback</code></dt>
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <dd>The callback object.</dd>
c3b708aaf1bb0a118e0e11befa1b732acfb1d079Bob Halley <dt><code>cfg</code></dt>
c3b708aaf1bb0a118e0e11befa1b732acfb1d079Bob Halley <dd>The configuration object.</dd>
febaa091847ab004f40500cc475a819f2c73fcddAndreas Gustafsson <td><code>data</code></td>
febaa091847ab004f40500cc475a819f2c73fcddAndreas Gustafsson <td>Raw data is received from the source.</td>
febaa091847ab004f40500cc475a819f2c73fcddAndreas Gustafsson All properties from `request` plus
febaa091847ab004f40500cc475a819f2c73fcddAndreas Gustafsson <dt><code>data</code></dt>
febaa091847ab004f40500cc475a819f2c73fcddAndreas Gustafsson <dd>The raw data.</dd>
03f91269f5453bcbd924910ef85a8f8496cf2661Mark Andrews <td><code>response</code></td>
03f91269f5453bcbd924910ef85a8f8496cf2661Mark Andrews <td>Response is returned to a callback function.</td>
84185d19c7a9ef1ac23cc6236c8773697d4efeb1Brian Wellington All properties from `data` plus
5619558151f1aa4249b3ead979e76876e29278b6Bob Halley <dt><code>response</code></dt>
88a6fef4944a00d8350ffd8b64ef58c694b8335eMark Andrews <dd>Data normalized into a response object.</dd>
69be7837c920fac5c71a73e8fad586f9a2711e96Michael Graff <td><code>error</code></td>
bf345589ce0b0b64533d4566e4992a0e63aac6f5Bob Halley <td>After `response` event, before the configured failure callback is executed.</td>
c3b708aaf1bb0a118e0e11befa1b732acfb1d079Bob Halley <td>Same properties as the `response` event</td>