Add DataSource examples.

src/datasource/docs/component.json

@@ -9,7 +9,7 @@
 
     "examples": [
         {
-            "name": "datasource_local",
+            "name": "datasource-local",
             "displayName": "DataSource.Local",
             "modules": ["datasource", "dataschema"],
             "description": "The Local DataSource manages retrieval of in-page data, from JavaScript arrays and objects to DOM elements.",
@@ -19,7 +19,7 @@
         },
 
         {
-            "name": "datasource_get",
+            "name": "datasource-get",
             "displayName": "DataSource.Get",
             "modules": ["datasource", "dataschema"],
             "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.",
@@ -29,7 +29,7 @@
         },
 
         {
-            "name": "datasource_io",
+            "name": "datasource-io",
             "displayName": "DataSource.IO",
             "modules": ["datasource", "dataschema"],
             "description": "The IO DataSource manages retrieval of data from remote sources, via the IO Utility.",
@@ -39,7 +39,7 @@
         },
 
         {
-            "name": "datasource_function",
+            "name": "datasource-function",
             "displayName": "DataSource.Function",
             "modules": ["datasource", "dataschema"],
             "description": "The Function DataSource, which manages retrieval of data from a JavaScript function, provides a highly customizeable mechanism for implementer-defined data retrieval algorithms",
@@ -49,7 +49,7 @@
         },
 
         {
-            "name": "datasource_caching",
+            "name": "datasource-caching",
             "displayName": "DataSource with Caching",
             "modules": ["datasource", "dataschema", "cache"],
             "description": "Use the DataSourceCache plugin to enable caching and reduce server calls to remote sources.",
@@ -59,7 +59,7 @@
         },
 
         {
-            "name": "datasource_offlinecache",
+            "name": "datasource-offlinecache",
             "displayName": "DataSource with Offline Cache",
             "modules": ["datasource", "dataschema", "cache"],
             "description": "The DataSourceCache plugin supports offline caching so that cached data persists across browser sessions.",
@@ -69,7 +69,7 @@
         },
 
         {
-            "name": "datasource_polling",
+            "name": "datasource-polling",
             "displayName": "DataSource with Polling",
             "modules": ["datasource"],
             "description": "Use the Pollable extension to enable polling in your DataSource.",

src/datasource/docs/datasource-caching.mustache

@@ -0,0 +1,83 @@
+<style scoped>
+/* custom styles for this example */
+#demo .output {
+    margin-bottom:1em;
+    padding:10px;
+    border:1px solid #D9D9D9;
+}
+#demo .output pre {
+    font-size: 11px;
+}
+#demo .output strong {
+    padding: .25em .4em;
+    background: #333;
+    color: #fff;
+    text-shadow: -1px -1px 1px #000;
+    border-radius: 5px;
+}
+</style>
+
+<div class="intro">
+    <p>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`.
+
+</div>
+
+<div class="example">
+    {{>datasource-caching-source}}
+</div>
+
+<p>Use the <code>plug()</code> method to initialize the
+<code>DataSourceCache</code> plugin and pass in the configuration value
+<code>max</code> to set the maximum size.</p>
+
+```
+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"]
+        }
+    });
+
+    myDataSource.plug(Y.Plugin.DataSourceCache, { max: 3 });
+
+    // Adds to cache
+    myDataSource.sendRequest({
+        request : "lsmith",
+        callback: callback
+    });
+
+    // Adds to cache
+    myDataSource.sendRequest({
+        request : "davglass",
+        callback: callback
+    });
+
+    // Retrieves from cache
+    myDataSource.sendRequest({
+        request : "lsmith",
+        callback: callback
+    });
+});
+```
+
+<h3 id="fullsource">Full Example Source Listing</h3>
+
+```
+    {{>datasource-caching-source}}
+```

src/datasource/docs/datasource-function.mustache

@@ -0,0 +1,99 @@
+<style scoped>
+/* custom styles for this example */
+#demo .output {margin-bottom:1em; padding:10px; border:1px solid #D9D9D9;}
+</style>
+
+<div class="intro">
+    <p>DataSource.Function allows the implementer to define a JavaScript function that returns data values, for maximum customizeability. A <a href="../dataschema/">DataSchema</a> plugin is used to normalize incoming data into a known format for consistency of usage by other components.</p>
+</div>
+
+<div class="example">
+    {{>datasource-function-source}}
+</div>
+
+<p>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:</p>
+
+```
+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});
+});
+```
+
+<p>Whereas JSON data would use a DataSourceJSONSchema plugin:</p>
+
+```
+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});
+});
+```
+

src/datasource/docs/datasource-get.mustache

@@ -0,0 +1,39 @@
+<style scoped>
+/* custom styles for this example */
+#demo .output {margin-bottom:1em; padding:10px; border:1px solid #D9D9D9;}
+</style>
+
+<div class="intro">
+    <p>DataSource.Get uses the Get Utility to retrieve data, even cross-domain resources, via a dynamically created script node. A <a href="../dataschema/">DataSchema</a> 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`.</p>
+</div>
+
+<div class="example">
+    {{>datasource-get-source}}
+</div>
+
+<p>Use a DataSourceJSONSchema plugin to parse the data against a schema that you provide:</p>
+
+```
+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 */ }
+        }
+    });
+
+});
+```
+