Add jsonp examples.

src/jsonp/docs/component.json

@@ -10,7 +10,7 @@
     "examples": [
 
         {
-            "name": "jsonp_github",
+            "name": "jsonp-github",
 	        "displayName": "Getting Cross Domain JSON Data Using Y.jsonp()",
 	        "description": "Get basic <a href='http://github.com'>GitHub</a> user info using a <code>Y.jsonp(url, callback)</code>.",
 	        "modules": ["jsonp"],
@@ -20,22 +20,12 @@
         },
 
         {
-            "name": "jsonp_gallery",
+            "name": "jsonp-gallery",
 	        "displayName": "Reusing a JSONPRequest Instance to Poll a Remote Server",
 	        "description": "Create a reusable JSONPRequest object to poll the YUILibrary.com Gallery web service, fetching info on a random Gallery module.",
 	        "modules": ["jsonp", "transition"],
 	        "useModules": ["jsonp", "transition"],
 
-            "hideTableOfContents": true
-        },
-
-        {
-            "name": "jsonp_fail",
-	        "displayName": "Advanced Configuration of JSONP Requests",
-	        "description": "Handle timeout or connection failures, override the 'this' object of the callback, and provide additional arguments to the callback",
-	        "modules": ["jsonp"],
-	        "useModules": ["jsonp-base", "node"],
-
             "hideTableOfContents": true
         }
     ]

src/jsonp/docs/jsonp-gallery.mustache

@@ -0,0 +1,151 @@
+{{>jsonp-gallery-css}}
+
+<div class="intro">
+    <p>This example shows how to create a reusable JSONPRequest for polling as well as how to configure success and failure callbacks.  See the API docs and user guide for a full listing of available configurations.</p>
+
+    <p>For this example, we will use a JSONP service hosted on <a href="http://yuilibrary.com">YUILibrary</a> to fetch information about a random Gallery module and render some of the information on the page.</p>
+</p>
+
+<div class="example">
+{{>jsonp-gallery-markup}}
+{{>jsonp-gallery-js}}
+</div>
+
+<h3>The data</h3>
+<p>The structure of the JavaScript object returned from YUILibrary's JSONP service will look like this:</p>
+
+```
+{
+    modules: [
+        {
+            url: (the url to the module),
+            title: (the title of the module),
+            summary: (short description of the module),
+            ...,
+            owner: {
+                icon: (url to the author's thumb image),
+                fullname: (the author's full name),
+                rank: (YUI Team member?, Contributor? etc),
+                ...
+            }
+        }
+    ],
+    ...
+}
+
+```
+
+<p>We'll use these objects to populate an HTML template with data <em>{placeholder}</em>s using `Y.Lang.sub( template, object )`.</p>
+
+
+<h3>Start simple</h3>
+<p>To make a single call to the YUILibrary Gallery API, we can just use</p>
+
+```
+Y.jsonp("http://yuilibrary.com/gallery/api/random?callback={callback}", handleJSONP);
+
+```
+
+<p>But since each call to `Y.jsonp()` creates a new instance of `Y.JSONPRequest`, we may as well store the instance and reuse it.</p>
+
+```
+var gallery = new Y.JSONPRequest("http://yuilibrary.com/gallery/api/random?callback={callback}", handleJSONP);
+
+gallery.send();
+
+```
+
+<h3>Add polling</h3>
+<p>JSONPRequest doesn't have any built-in polling mechanism, but `Y.later()` can handle this for us.</p>
+
+```
+var url = "http://yuilibrary.com/gallery/api/random?callback={callback}";
+
+function handleJSONP(response) {
+    // populate template from the response object and add to the output div
+    ...
+
+    Y.one("#out").setContent( Y.Lang.sub(template, module) );
+
+    // After 7 seconds, call the API for a new module
+    Y.later(7000, this, this.send);
+};
+
+var gallery = new Y.JSONPRequest(url, handleJSONP);
+gallery.send();
+
+```
+
+<h3>Add failure protection</h3>
+<p>In case the Gallery API is busy or some other problem arises, we'll also want to handle this case and display an error.  We can do this by passing a configuration object as the second parameter rather than a simple success callback.</p>
+
+```
+var gallery = new Y.JSONPRequest(url, {
+        on: {
+            success: function (response) {
+                // populate output div from the template and response object
+                ...
+
+                Y.one("#out").setContent( Y.Lang.sub(template, module) );
+
+                // After 7 seconds, call the API for a new module
+                Y.later(7000, this, this.send);
+            },
+
+            failure: function () {
+                Y.one("#out").setContent( failureTemplate );
+            }
+        }
+    });
+
+gallery.send();
+
+```
+
+<h3>Add flare</h3>
+<p>Now we'll add a bit of flourish, by adding a visual indicator of how long until the next module is requested.  We'll replace the call to `Y.later()` with a call to `node.transition()` using a shrinking border to show the remaining time.  Then when the transition is complete, we call `send()` again.
+
+```
+var gallery = new Y.JSONPRequest(url, {
+        on: {
+            success: function (response) {
+                // populate output div from the template and response object
+                ...
+
+                Y.one("#out").setContent( Y.Lang.sub(template, module) );
+
+                // Add some flare to the poll interval by showing a "time left"
+                // indicator via the header's border
+                Y.one("#out h4")
+                    .setStyle("borderRightWidth", "100px")
+                    .transition({
+                        borderRightWidth: 0,
+                        duration: 7
+                    }, function () {
+                        gallery.send();
+                    });
+            },
+
+            failure: function () {
+                Y.one("#out").setContent( failureTemplate );
+            }
+        }
+    });
+
+gallery.send();
+
+```
+
+<h3>Stop the poll</h3>
+<p>The final step is to add the ability to start and stop the polling.  We'll manage this by adding a property to the `gallery` JSONPRequest instance named `gallery.polling`.  See the full code listing below for the implementation.
+
+<h3 id="fullcode">Full Code Listing</h3>
+<h4>HTML</h4>
+```
+{{>jsonp-gallery-markup}}
+```
+
+<h4>JavaScript</h4>
+```
+{{>jsonp-gallery-js}}
+```

src/jsonp/docs/jsonp-github.mustache

@@ -0,0 +1,72 @@
+{{>jsonp-github-css}}
+
+<div class="intro">
+    <p>This example illustrates basic use of the `Y.jsonp( url, callback )` method, provided by the `jsonp` module.</p>
+
+    <p>For this example, we will use <a href="http://develop.github.com/">GitHub's webservice API</a>, fetching user information about some members of the YUI team.</p>
+</div>
+
+<div class="example">
+{{>jsonp-github-markup}}
+{{>jsonp-github-js}}
+</div>
+
+<h3>The data</h3>
+<p>The structure of the JavaScript object returned from GitHub's JSONP API for user info will look like this:</p>
+
+```
+{
+    user: {
+        gravatar_id: "fc2cca...",
+        login: "username"
+        name: "User's Name",
+        ...,
+
+        public_repo_count: 10,
+        public_gist_count: 20,
+        following_count: 30,
+        followers_count: 40
+    }
+}
+```
+
+<p>We'll use these objects to populate HTML templates with data <em>{placeholder}</em>s using `Y.Lang.sub( template, object )`.  The resulting HTML can then simply be passed to any of YUI 3's DOM creation methods, such as `node.setContent( html )` or `node.append( html )`.  We'll do this in the function that will receive the JSONP response (seen below).</p>
+
+<h3>Format the JSONP url</h3>
+<p>Typical JSONP urls are formatted like</p>
+<p>&quot;http://example.com/service?format=json&<em>callback=handleJSONP</em>&quot;.</p>
+<p>To use YUI 3's JSONP utility, replace the name of the callback function in the url with placeholder text &quot;{callback}&quot;.</p>
+
+```
+// BEFORE
+var url = "http://github.com/api/v2/json/user/show/yui?callback=handleJSONP";
+
+//AFTER
+var url = "http://github.com/api/v2/json/user/show/yui?callback={callback}";
+```
+
+<p>Then simply pass the url and the function that should handle the JSONP response object to `Y.jsonp(<em>url</em>, <em>handleJSONP</em>)`.</p>
+
+```
+function handleJSONP(response) {
+    Y.one("#out").setContent(Y.Lang.sub(template, response.user));
+}
+
+Y.one("#demo_btn").on("click", function (e) {
+    // e.g. http://github.com/api/v2/json/user/show/yui?callback={callback}
+    var url = githubAPI + user.get("value") + "?callback={callback}";
+
+    Y.jsonp(url, handleJSONP);
+});
+```
+
+<h3 id="fullcode">Full Code Listing</h3>
+<h4>HTML</h4>
+```
+{{>jsonp-github-markup}}
+```
+
+<h4>JavaScript</h4>
+```
+{{>jsonp-github-js}}
+```

src/jsonp/docs/partials/jsonp-gallery-css.mustache

@@ -0,0 +1,8 @@
+<style scoped>
+    #out {
+        margin-top: 2em;
+    }
+    #out h4 {
+        border-right: 100px solid #ccc;
+    }
+</style>

src/jsonp/docs/partials/jsonp-gallery-js.mustache

@@ -0,0 +1,83 @@
+<script>
+YUI().use("jsonp", "transition",function (Y) {
+
+    var url = "http://yuilibrary.com/gallery/api/random?callback={callback}",
+        outputDiv = Y.one("#out"),
+        gallery;
+        
+    // Using the configuration object syntax
+    gallery = new Y.JSONPRequest(url, {
+        on: {
+            success: function (response) {
+                var module = response.modules[0],
+                    author = module.owner;
+
+                // Some users don't have a rank
+                if (!author.rank) {
+                    author.rank = "user";
+                }
+
+                // Format the author info and store as a property of the
+                // module object for use by Y.Lang.sub
+                // ('this' refers to the JSONPRequest object by default)
+                module.authorHTML = Y.Lang.sub(this.authorTemplate, author);
+
+                outputDiv.setContent(Y.Lang.sub(this.moduleTemplate, module));
+
+                // Add some flare to the poll interval by showing a "time left"
+                // indicator via the header's border
+                Y.one("#out h4")
+                    .setStyle("borderRightWidth", "100px")
+                    .transition({
+                        borderRightWidth: 0,
+                        duration: 7
+                    }, function () {
+                        if (gallery.polling) {
+                            gallery.send();
+                        }
+                    });
+            },
+
+            failure: function () {
+                gallery.polling = false;
+                outputDiv.setContent(this.failureTemplate);
+
+                // Wire up the Try again button
+                outputDiv.one("button").on("click", function () {
+                    gallery.send();
+                });
+            }
+        }
+    });
+
+
+    gallery.moduleTemplate =
+        '<h4><a href="{url}">{title}</a></h4>' +
+        '<p class="author">{authorHTML}</p>' +
+        '<div>{summary}</div>';
+
+    gallery.authorTemplate =
+        '<img src="{icon}" height="30" width="30">' +
+        ' {fullname} <span class="rank">({rank})</span>';
+
+    gallery.failureTemplate =
+        '<p class="error">Ack, I couldn\'t reach the Gallery web service!</p>' +
+        '<button>Try again</button>';
+
+    gallery.polling = false;
+
+
+    // Click the button to send the JSONP request
+    Y.one("#start").on("click", function (e) {
+        if (!gallery.polling) {
+            gallery.polling = true;
+            gallery.send();
+        }
+    });
+
+    Y.one("#stop").on("click", function (e) {
+        gallery.polling = false;
+    });
+
+});
+</script>

src/jsonp/docs/partials/jsonp-gallery-markup.mustache

@@ -0,0 +1,6 @@
+<div id="demo">
+    <input type="button" id="start" value="Start polling">
+    <input type="button" id="stop" value="Stop polling">
+    <div id="out">
+    </div>
+</div>

src/jsonp/docs/partials/jsonp-github-css.mustache

@@ -0,0 +1,11 @@
+<style scoped>
+#out {
+    margin-top: 1em;
+}
+#out caption  {
+    color: #f80;
+    font-size: 123%;
+    display: table-caption;
+    *display: block;
+}
+</style>