10139N/A The JSONP Utility is a specialized API for communicating with web
10139N/A services that provide JSON responses wrapped in a callback
13600N/A function. A typical JSONP request URL might look like
10139N/A receive a text response in the form of
10139N/A <code>handleData({"records":[....]});</code>.
10139N/A The nature of YUI 3's sandbox model complicates JSONP transactions
16437N/A because JSONP relies on a global access point to process the
16732N/A response, but YUI 3 implementation code is typically wrapped in a
10139N/A <code>use(...)</code> callback and is therefore not globally
10139N/A accessible. The JSONP module provides a proxy system for
10139N/A channeling JSONP responses back into your YUI instance sandbox.
10139N/A <strong>Security Note:</strong> JSONP is an inherently unsecure
10139N/A communication method, since it involves the transfer of unvalidated
15536N/A JavaScript. It is by convention alone that the format is
15536N/A associated with JSON, but in reality, the response can include any
15536N/A arbitrary JavaScript, potentially opening your page to attack.
15536N/A <em>Be cautious about which services you communicate with via
15536N/A JSONP</em>. For safe JSON communication, use the <a
16633N/A<h2 id="using">Using the JSONP Utility</h2>
15536N/A<h3 id="basic">Instantiation and the <code>
Y.jsonp</code> method</h3>
10139N/A The JSONP utility provides the <code>
Y.jsonp(url, callback)</code> method
16437N/A The first argument to either the <code>
Y.jsonp</code> method or the
16437N/A and the second is a callback function or <a href="#config">configuration
10544N/A object</a> that contains a callback function. When the service responds
12830N/A with the data, the callback will be executed with the response data as the
15536N/A In place of the JSONP callback name in the URL, include the string
13914N/A "{callback}". This placeholder will be used for a proxy function
16712N/A that will route the data to your callback.
15536N/Afunction handleJSONP(response) {
15536N/A // response is a JavaScript object. No parsing necessary
16608N/A<h4 id="timing">Sending JSONP requests</h4>
15536N/A <code>
Y.jsonp(url, callback)</code> will dispatch the request immediately.
15516N/A JSONPRequest instances will dispatch the request each time their
16597N/A <code>send()</code> method is called.
16758N/A <code>
Y.jsonp(url, callback)</code> is a convenience wrapper to instantiate
16279N/A a JSONPRequest instance and call its <code>send()</code> method.
16020N/A This will generate a request to a URL like this one (note that the
16020N/A <code>{callback}</code> placeholder has been replaced with a dynamically
16766N/A The server will then be expected to respond with a JavaScript value wrapped
16766N/A in a call to that function, like this:
10139N/A<h3 id="config">Configuring the connection</h3>
10139N/A or for more control, it can be a configuration object. The supported keys
10139N/A This value, defined as milliseconds, is a time threshold for
10139N/A the transaction (
e.g., <code>{ timeout: 2000 }</code> ). When
10139N/A this limit is reached, the transaction's
10139N/A Defines what will be "<code>this</code>" in the
10139N/A callbacks. If undefined, the default will be the JSONPRequest
10139N/A An array of additional arguments that will be passed to the
10139N/A callbacks as second, third, and so on arguments.
10139N/A <strong>Required</strong>. This object defines the
10139N/A callbacks to be used for the transaction. At least an
16061N/A <li>success (<strong>required</strong>)</li>
15536N/A Preprocessor function to stitch together the supplied URL
10139N/A (first argument), the proxy function name (internally
15536N/A generated), and any additional arguments passed to
15536N/A <code>send()</code>. See <a href="#format">Customizing the
10139N/A This is an example of a configuration object, with a set of properties
10139N/A timeout: 3000, // 3 second timeout
16554N/A args: [new Date(), 100] //
e.g. handleJSONP(data, date, number)
10139N/A timeout: 3000, // 3 second timeout
10139N/A args: [new Date(), 100] //
e.g. handleJSONP(data, date, number)
10139N/A<h3 id="url">Parsing the callback from the URL</h3>
10139N/A An extension for the <code>jsonp</code> module is the
10139N/A <code>jsonp-url</code> module which provides a few additional features.
15536N/A If you have a global function or a function available from the YUI
10139N/A name in the URL and omit the second parameter entirely.
10139N/A The URL passed as the first parameter need not include the
10139N/A "{callback}" string. If it is not found, it will look for
13898N/A "callback=", then fall back to adding the query parameter
10139N/A<h3 id="format">Customizing the JSONP URL</h3>
10139N/A The default URL formatter simply replaces the "{callback}"
10139N/A placehold with the name of the generated proxy function. If you want to
10139N/A customize the URL generation process, you can provide a <code>format</code>
10139N/A function in the configuration. The function will receive the configured
13898N/A URL (with "{callback}" placeholder), the string name of the proxy
13898N/A function, and any additional arguments that were passed to
16554N/A// Our custom formatter will expect a URL with an additional placeholder for
16554N/A// username that must be supplied in send("bill");
16554N/Afunction prepareJSONPUrl(url, proxy, username) {
13898N/A<h2 id="issues">Known Issues</h2>
13898N/A Unlike the XMLHttpRequest calls generated by the IO utility, JSONP
13898N/A requests can't be aborted, since they rely on dynamic script insertion
13898N/A (which provides less low-level control than XHR). Keep this in mind
13898N/A when deciding which method to use.
13898N/A Since most browsers don't enforce execution order for dynamically
13898N/A inserted scripts, JSONP callbacks may not be called in the same order
13898N/A that the requests were sent. On the other hand, some browsers
14376N/A <em>do</em> enforce execution order, so in these browsers a slow
13898N/A request may block the execution of subsequent JSONP callbacks.