Y.jsonp(url, callback).",
"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
}
]
diff --git a/src/jsonp/docs/index.mustache b/src/jsonp/docs/index.mustache
old mode 100755
new mode 100644
diff --git a/src/jsonp/docs/jsonp-gallery.mustache b/src/jsonp/docs/jsonp-gallery.mustache
new file mode 100644
index 00000000000..36db13054f6
--- /dev/null
+++ b/src/jsonp/docs/jsonp-gallery.mustache
@@ -0,0 +1,151 @@
+{{>jsonp-gallery-css}}
+
+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.
+ +For this example, we will use a JSONP service hosted on YUILibrary to fetch information about a random Gallery module and render some of the information on the page.
+ + +The structure of the JavaScript object returned from YUILibrary's JSONP service will look like this:
+ +``` +{ + 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), + ... + } + } + ], + ... +} + +``` + +We'll use these objects to populate an HTML template with data {placeholder}s using `Y.Lang.sub( template, object )`.
+ + +To make a single call to the YUILibrary Gallery API, we can just use
+ +``` +Y.jsonp("http://yuilibrary.com/gallery/api/random?callback={callback}", handleJSONP); + +``` + +But since each call to `Y.jsonp()` creates a new instance of `Y.JSONPRequest`, we may as well store the instance and reuse it.
+ +``` +var gallery = new Y.JSONPRequest("http://yuilibrary.com/gallery/api/random?callback={callback}", handleJSONP); + +gallery.send(); + +``` + +JSONPRequest doesn't have any built-in polling mechanism, but `Y.later()` can handle this for us.
+ +``` +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(); + +``` + +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.
+ +``` +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(); + +``` + +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(); + +``` + +
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. + +
This example illustrates basic use of the `Y.jsonp( url, callback )` method, provided by the `jsonp` module.
+ +For this example, we will use GitHub's webservice API, fetching user information about some members of the YUI team.
+The structure of the JavaScript object returned from GitHub's JSONP API for user info will look like this:
+ +``` +{ + user: { + gravatar_id: "fc2cca...", + login: "username" + name: "User's Name", + ..., + + public_repo_count: 10, + public_gist_count: 20, + following_count: 30, + followers_count: 40 + } +} +``` + +We'll use these objects to populate HTML templates with data {placeholder}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).
+ +Typical JSONP urls are formatted like
+"http://example.com/service?format=json&callback=handleJSONP".
+To use YUI 3's JSONP utility, replace the name of the callback function in the url with placeholder text "{callback}".
+ +``` +// 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}"; +``` + +Then simply pass the url and the function that should handle the JSONP response object to `Y.jsonp(url, handleJSONP)`.
+ +``` +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); +}); +``` + +