index.mustache revision ce82477cabe9511f9b4db3793dc39704214058d3
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<div class="intro component">
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj The DataSource Utility provides a consistent API for the retrieval of
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj data from arbitrary sources over a variety of supported protocols.
86c1f4dc9dc6de02690b5c555380d7714ef54ee0Vikram Hegde DataSource plugins and extensions enable additional functionality such
86c1f4dc9dc6de02690b5c555380d7714ef54ee0Vikram Hegde as schema normalization, caching, and polling of data.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj{{>getting-started}}
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h2 id="using">Using DataSources</h2>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h3 id="basics">DataSource basics</h3>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj The DataSource Utility uses a callback mechanism to manage the data
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj retrieval process across a wide variety of potential sources. Define your
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj callback object with custom functions that will execute when the data
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj returns from your source. The <code>sendRequest()</code> method accepts an
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj object literal with properties for the request value, a callback object,
3a634bfc9a31448c742688c603d3e76b83b041a0Vikram Hegde and/or any configuration values for the request.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj request: myRequest,
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj callback: {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj success: function(e){
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj failure: function(e){
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj You must instantiate the appropriate DataSource subclass for your source of
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h4 id="local">Local sources</h4>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj Use DataSource.Local when you are working with data that is held in local
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj memory, such as a JavaScript array or object.
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnsonvar myDataSource = new Y.DataSource.Local({source:["a", "b", "c"]});
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson<h4 id="get">Remote sources with the Get Utility</h4>
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson Use DataSource.Get to access data coming from a server via the Get Utility.
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson The Get Utility supports data retrieval from cross-domain resources without
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson the need for a proxy, but the server must return JSON data and support a
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson script callback parameter in order for the response to return properly.
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson This parameter specifies the name of the internally defined function that
0b7ba6115657ff183e0d3fa2c90c90f7f1cbf6ecMark Johnson the return data will be wrapped in when it returns to the page.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjvar myDataSource = new Y.DataSource.Get({
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj source: "http://query.yahooapis.com/v1/public/yql?format=json&"
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj You should not modify the internally assigned value of this script callback
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj parameter. However, you may need to set the parameter name to a different
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj value so that your server will accept it. By default, the script callback
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj parameter name is <code>"callback"</code>, but this value can be changed
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj via the Attribute <code>scriptCallbackParam</code>.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// By default the request is sent to
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&callback=YUI.Env.DataSource.callbacks[0]"
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj request: "q=foo",
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj callback: myCallback
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// But the parameter name can be customized to match the server requirement
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjmyDataSource.set("scriptCallbackParam", "cbFunc");
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// So now the request is sent to
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// "http://query.yahooapis.com/v1/public/yql?format=json&q=foo&cbFunc=YUI.Env.DataSource.callbacks[0]"
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj request: "q=foo",
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj callback: myCallback
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj Use the DataSourceJSONSchema plugin to normalize the data that is sent to
07c6692fc0943eb709ce6be01afa662c2e03ee90Mark Johnson your callack.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// Normalize the data sent to myCallback
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjmyDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
07c6692fc0943eb709ce6be01afa662c2e03ee90Mark Johnson resultListLocator: "myResults",
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj resultFields: ["myField1", "myField2"]
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h4 id="io">Remote sources with the IO Utility</h4>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj DataSource.IO is used to access data coming from a server via the IO
07c6692fc0943eb709ce6be01afa662c2e03ee90Mark Johnson Utility. Note that accessing a cross-domain server will require a
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj same-domain proxy or enabling IO's XDR feature, in order to bypass standard
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj browser security restrictions.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjvar myDataSource = new Y.DataSource.IO({source:"./myScript.php"});
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj The IO Utility supports retrieval of multiple data formats, including JSON,
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj XML, and plain text. Use the appropriate DataSchema plugin to normalize the
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj data that is sent to your callback.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjmyDataSource.plug({fn: Y.Plugin.DataSourceXMLSchema, cfg: {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj resultListLocator: "resultNodeName",
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj resultFields: [{key:"myField1", locator:"xpath/to/value"}]
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h4 id="function">Sources using custom functions</h4>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj Defining your own JavaScript function that returns data for a given request
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj allows full customization of the data retrieval mechanism.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjvar myDataSource = new Y.DataSource.Function({
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj source: function (request) {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj return data;
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj Since your data can return data of any format, you may consider ways to
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj taking advantage of the built-in infrastructure, including using a
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj DataSchema plugin to normalize the data that is sent to your callback.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjvar myDataSource = new Y.DataSource.Function({
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj source: function (request) {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj return [["ann", 123], ["bill", 456]];
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjmyDataSource.plug({fn: Y.Plugin.DataSourceArraySchema, cfg: {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj resultFields: ["name","id"]
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h3 id="caching">Caching</h3>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj The DataSourceCache plugin provides integrated caching functionality to
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj your DataSource instance. Use the DataSource's <code>plug()</code> method
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj to instantiate a Cache instance. Set the <code>max</code> Attribute value
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj to the maximum number of entries the Cache should hold.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrjmyDataSource.plug({fn:Y.Plugin.DataSourceCache, cfg:{max:3}});
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj Once the plugin is enabled, it will handle caching and retrieval of values
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj seamlessly for you without the need for extra code. However, all the
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj methods and properties of the Cache instance is available on the DataSource
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj instance's <code>cache</code> namepace.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// Flush myDataSource's cache.
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj// Disable myDataSource's cache
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h3 id="polling">Polling</h3>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj Pollable is a DataSource extension that enhances the class with polling
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj functionality. Once the extension is applied, all instances of DataSource
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj will have available on their prototype the methods that enable and disable
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj requests sent at regular intervals. To apply the extension, simply include
3a634bfc9a31448c742688c603d3e76b83b041a0Vikram Hegde the <code>datasource-polling</code> sub-module in your
3a634bfc9a31448c742688c603d3e76b83b041a0Vikram Hegde <code>YUI.use()</code> statement.
3a634bfc9a31448c742688c603d3e76b83b041a0Vikram HegdeYUI().use('datasource-io', 'datasource-polling', 'json-parse', function(Y) {
3a634bfc9a31448c742688c603d3e76b83b041a0Vikram Hegde var onlineFriends = Y.one('#friend-count'),
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj friendData = new Y.DataSource.IO({
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj // Start polling the server every 10 seconds
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj intervalId = friendData.setInterval(10000, {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj request : Y.one('#user-id').get('value'),
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj callback: {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj success: function (e) {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj var friends = Y.JSON.parse(e.response.results[0]).friendCount;
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj if (!friends) {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj friends = 'No friends. You should go outside more.';
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj onlineFriends.set('text', friends);
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj failure: function (e) {
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj '(Bang) Ouch! ' + e.error.message + ' happened!');
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj // Stop polling
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj<h3 id="events">Events</h3>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <th>Event</th>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <th>When</th>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <th>Event properties</th>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td><code>request</code></td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td>Request is made.</td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dt><code>tId</code></dt>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dd>Unique transaction ID.</dd>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dt><code>request</code></dt>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dd>The request value.</dd>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dt><code>callback</code></dt>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dd>The callback object.</dd>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dt><code>cfg</code></dt>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dd>The configuration object.</dd>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td><code>data</code></td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td>Raw data is received from the source.</td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj All properties from `request` plus
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dt><code>data</code></dt>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dd>The raw data.</dd>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td><code>response</code></td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td>Response is returned to a callback function.</td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj All properties from `data` plus
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dt><code>response</code></dt>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <dd>Data normalized into a response object.</dd>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td><code>error</code></td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td>After `response` event, before the configured failure callback is executed.</td>
12f080e7d03a5a6c62c85f0005491e9e4d355cfbmrj <td>Same properties as the `response` event</td>