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