jsonp-gallery.mustache revision 819e90d415ed17d59af3a247b2ad9d6feb0c21b5
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein{{>jsonp-gallery-css}}
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews<div class="intro">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This example shows how to create a reusable JSONPRequest for polling as
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein well as how to configure success and failure callbacks. See the API
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein docs and user guide for a full listing of available configurations.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein For this example, we will use a JSONP service hosted on <a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein href="http://yuilibrary.com">YUILibrary</a> to fetch information about
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein a random Gallery module and render some of the information on the page.
9ef82979c49da3dd3647273b1cd6ed7d3352c003Automatic Updater<div class="example yui3-skin-sam">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein{{>jsonp-gallery-markup}}
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein{{>jsonp-gallery-js}}
e21a2904f02a03fa06b6db04d348f65fe9c67b2bMark Andrews<h3>The data</h3>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p>The structure of the JavaScript object returned from YUILibrary's JSONP service will look like this:</p>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein url: (the url to the module),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein title: (the title of the module),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein summary: (short description of the module),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein icon: (url to the author's thumb image),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein fullname: (the author's full name),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein rank: (YUI Team member?, Contributor? etc),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p>We'll use these objects to populate an HTML template with data <em>{placeholder}</em>s using `Y.Lang.sub( template, object )`.</p>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<h3>Start simple</h3>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<p>To make a single call to the YUILibrary Gallery API, we can just use</p>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinY.jsonp("http://yuilibrary.com/gallery/api/random?callback={callback}", handleJSONP);
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updater<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>
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updatervar gallery = new Y.JSONPRequest("http://yuilibrary.com/gallery/api/random?callback={callback}", handleJSONP);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<h3>Add polling</h3>
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews<p>JSONPRequest doesn't have any built-in polling mechanism, but `Y.later()` can handle this for us.</p>
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updatervar url = "http://yuilibrary.com/gallery/api/random?callback={callback}";
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updaterfunction handleJSONP(response) {
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updater // populate template from the response object and add to the output div
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Y.one("#out").setContent( Y.Lang.sub(template, module) );
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein // After 7 seconds, call the API for a new module
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updatervar gallery = new Y.JSONPRequest(url, handleJSONP);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<h3>Add failure protection</h3>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<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>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvar gallery = new Y.JSONPRequest(url, {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein success: function (response) {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein // populate output div from the template and response object
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Y.one("#out").setContent( Y.Lang.sub(template, module) );
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updater // After 7 seconds, call the API for a new module
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updater failure: function () {
ab8729140b1ad688ab03e1e9ce438fb1cbb49222Automatic Updater Y.one("#out").setContent( failureTemplate );
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<h3>Add flare</h3>
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater<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.
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updatervar gallery = new Y.JSONPRequest(url, {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein success: function (response) {
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews // populate output div from the template and response object
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Y.one("#out").setContent( Y.Lang.sub(template, module) );
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews // Add some flare to the poll interval by showing a "time left"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein // indicator via the header's border
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein .setStyle("borderRightWidth", "100px")
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein .transition({
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater borderRightWidth: 0,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein }, function () {
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater failure: function () {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Y.one("#out").setContent( failureTemplate );
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<h3>Stop the poll</h3>
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater<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.
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater<h3 id="fullcode">Full Code Listing</h3>
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater{{>jsonp-gallery-markup}}
98b5a9d1099f72169c90de39712fc4f63e9d990eAutomatic Updater<h4>JavaScript</h4>
c6d486af36165da7eb970354981d145249e342e4Mark Andrews{{>jsonp-gallery-js}}