--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/cm/media/js/lib/yui/yui_3.10.3/docs/datasource/index.html Tue Jul 16 14:29:46 2013 +0200
@@ -0,0 +1,532 @@
+<!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>