<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DataSource</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
<link rel="stylesheet" href="../assets/css/main.css">
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
<script src="../../build/yui/yui-min.js"></script>
</head>
<body>
<!--
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
-->
<div id="doc">
<div id="hd">
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
</div>
<a href="#toc" class="jump">Jump to Table of Contents</a>
<h1>DataSource</h1>
<div class="yui3-g">
<div class="yui3-u-3-4">
<div id="main">
<div class="content"><div class="intro component">
<p>
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.
</p>
</div>
<h2 id="getting-started">Getting Started</h2>
<p>
To include the source files for DataSource and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>
<pre class="code prettyprint"><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></pre>
<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
</p>
<h2 id="using">Using DataSources</h2>
<h3 id="basics">DataSource basics</h3>
<p>
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 <code>sendRequest()</code> method accepts an
object literal with properties for the request value, a callback object,
and/or any configuration values for the request.
</p>
<pre class="code prettyprint">myDataSource.sendRequest({
request: myRequest,
on: {
success: function(e){
alert(e.response);
},
failure: function(e){
alert(e.error.message);
}
}
});</pre>
<p>
You must instantiate the appropriate DataSource subclass for your source of
data.
</p>
<h4 id="local">Local sources</h4>
<p>
Use DataSource.Local when you are working with data that is held in local
memory, such as a JavaScript array or object.
</p>
<pre class="code prettyprint">var myDataSource = new Y.DataSource.Local({source:["a", "b", "c"]});</pre>
<h4 id="get">Remote sources with the Get Utility</h4>
<p>
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.
</p>
<pre class="code prettyprint">var myDataSource = new Y.DataSource.Get({
source: "http://query.yahooapis.com/v1/public/yql?format=json&"
});</pre>
<p>
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 <code>"callback"</code>, but this value can be changed
via the Attribute <code>scriptCallbackParam</code>.
</p>
<pre class="code prettyprint">// 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
});</pre>
<p>
Use the DataSourceJSONSchema plugin to normalize the data that is sent to
your callack.
</p>
<pre class="code prettyprint">// Normalize the data sent to myCallback
myDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
schema: {
resultListLocator: "myResults",
resultFields: ["myField1", "myField2"]
}
}});</pre>
<h4 id="io">Remote sources with the IO Utility</h4>
<p>
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.
</p>
<pre class="code prettyprint">var myDataSource = new Y.DataSource.IO({source:"./myScript.php"});</pre>
<p>
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.
</p>
<pre class="code prettyprint">myDataSource.plug({fn: Y.Plugin.DataSourceXMLSchema, cfg: {
schema: {
resultListLocator: "resultNodeName",
resultFields: [{key:"myField1", locator:"xpath/to/value"}]
}
}});</pre>
<h4 id="function">Sources using custom functions</h4>
<p>
Defining your own JavaScript function that returns data for a given request
allows full customization of the data retrieval mechanism.
</p>
<pre class="code prettyprint">var myDataSource = new Y.DataSource.Function({
source: function (request) {
return data;
}
});</pre>
<p>
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.
</p>
<pre class="code prettyprint">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"]
}
}});</pre>
<h3 id="caching">Caching</h3>
<p>
The DataSourceCache plugin provides integrated caching functionality to
your DataSource instance. Use the DataSource's <code>plug()</code> method
to instantiate a Cache instance. Set the <code>max</code> Attribute value
to the maximum number of entries the Cache should hold.
</p>
<pre class="code prettyprint">myDataSource.plug({fn:Y.Plugin.DataSourceCache, cfg:{max:3}});</pre>
<p>
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 <code>cache</code> namepace.
</p>
<pre class="code prettyprint">// Flush myDataSource's cache.
myDataSource.cache.flush();
// Disable myDataSource's cache
myDataSource.cache.set("max", 0);</pre>
<h3 id="polling">Polling</h3>
<p>
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 <code>datasource-polling</code> sub-module in your
<code>YUI.use()</code> statement.
</p>
<pre class="code prettyprint">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);
}
}
});
});</pre>
<h3 id="events">Events</h3>
<table>
<thead>
<tr>
<th>Event</th>
<th>When</th>
<th>Event properties</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>request</code></td>
<td>Request is made.</td>
<td>
<dl>
<dt><code>tId</code></dt>
<dd>Unique transaction ID.</dd>
<dt><code>request</code></dt>
<dd>The request value.</dd>
<dt><code>callback</code></dt>
<dd>The callback object.</dd>
<dt><code>cfg</code></dt>
<dd>The configuration object.</dd>
</dl>
</td>
</tr>
<tr>
<td><code>data</code></td>
<td>Raw data is received from the source.</td>
<td>
All properties from <code>request</code> plus
<dl>
<dt><code>data</code></dt>
<dd>The raw data.</dd>
</dl>
</td>
</tr>
<tr>
<td><code>response</code></td>
<td>Response is returned to a callback function.</td>
<td>
All properties from <code>data</code> plus
<dl>
<dt><code>response</code></dt>
<dd>Data normalized into a response object.</dd>
</dl>
</td>
</tr>
<tr>
<td><code>error</code></td>
<td>After <code>response</code> event, before the configured failure callback is executed.</td>
<td>Same properties as the <code>response</code> event</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="yui3-u-1-4">
<div class="sidebar">
<div id="toc" class="sidebox">
<div class="hd">
<h2 class="no-toc">Table of Contents</h2>
</div>
<div class="bd">
<ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#using">Using DataSources</a>
<ul class="toc">
<li>
<a href="#basics">DataSource basics</a>
<ul class="toc">
<li>
<a href="#local">Local sources</a>
</li>
<li>
<a href="#get">Remote sources with the Get Utility</a>
</li>
<li>
<a href="#io">Remote sources with the IO Utility</a>
</li>
<li>
<a href="#function">Sources using custom functions</a>
</li>
</ul>
</li>
<li>
<a href="#caching">Caching</a>
</li>
<li>
<a href="#polling">Polling</a>
</li>
<li>
<a href="#events">Events</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="The Local DataSource manages retrieval of in-page data, from JavaScript arrays and objects to DOM elements.">
<a href="datasource-local.html">DataSource.Local</a>
</li>
<li data-description="The Get DataSource, which manages retrieval of data from remote sources via the Get Utility, can be useful for accessing data from cross-domain servers without the need for a proxy.">
<a href="datasource-get.html">DataSource.Get</a>
</li>
<li data-description="The IO DataSource manages retrieval of data from remote sources, via the IO Utility.">
<a href="datasource-io.html">DataSource.IO</a>
</li>
<li data-description="The Function DataSource, which manages retrieval of data from a JavaScript function, provides a highly customizeable mechanism for implementer-defined data retrieval algorithms">
<a href="datasource-function.html">DataSource.Function</a>
</li>
<li data-description="Use the DataSourceCache plugin to enable caching and reduce server calls to remote sources.">
<a href="datasource-caching.html">DataSource with Caching</a>
</li>
<li data-description="The DataSourceCache plugin supports offline caching so that cached data persists across browser sessions.">
<a href="datasource-offlinecache.html">DataSource with Offline Cache</a>
</li>
<li data-description="Use the Pollable extension to enable polling in your DataSource.">
<a href="datasource-polling.html">DataSource with Polling</a>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples That Use This Component</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="How to provide autocomplete suggestions using a DataSource instance.">
<a href="../autocomplete/ac-datasource.html">Remote Data via DataSource</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script>
YUI.Env.Tests = {
examples: [],
project: '../assets',
assets: '../assets/datasource',
name: 'datasource',
title: 'DataSource',
newWindow: '',
auto: false
};
YUI.Env.Tests.examples.push('datasource-local');
YUI.Env.Tests.examples.push('datasource-get');
YUI.Env.Tests.examples.push('datasource-io');
YUI.Env.Tests.examples.push('datasource-function');
YUI.Env.Tests.examples.push('datasource-caching');
YUI.Env.Tests.examples.push('datasource-offlinecache');
YUI.Env.Tests.examples.push('datasource-polling');
YUI.Env.Tests.examples.push('ac-datasource');
</script>
<script src="../assets/yui/test-runner.js"></script>
</body>
</html>