<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSONP</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
<link rel="stylesheet" href="../assets/css/main.css">
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
<script src="../../build/yui/yui-min.js"></script>
</head>
<body>
<!--
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
-->
<div id="doc">
<div id="hd">
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
</div>
<a href="#toc" class="jump">Jump to Table of Contents</a>
<h1>JSONP</h1>
<div class="yui3-g">
<div class="yui3-u-3-4">
<div id="main">
<div class="content"><div class="intro component">
<p>
The JSONP Utility is a specialized API for communicating with web
services that provide JSON responses wrapped in a callback
function. A typical JSONP request URL might look like
"http://example.com/service.php?callback=handleData" and
receive a text response in the form of
<code>handleData({"records":[....]});</code>.
</p>
<p>
The nature of YUI 3's sandbox model complicates JSONP transactions
because JSONP relies on a global access point to process the
response, but YUI 3 implementation code is typically wrapped in a
<code>use(...)</code> callback and is therefore not globally
accessible. The JSONP module provides a proxy system for
channeling JSONP responses back into your YUI instance sandbox.
</p>
<p>
<strong>Security Note:</strong> JSONP is an inherently unsecure
communication method, since it involves the transfer of unvalidated
JavaScript. It is by convention alone that the format is
associated with JSON, but in reality, the response can include any
arbitrary JavaScript, potentially opening your page to attack.
<em>Be cautious about which services you communicate with via
JSONP</em>. For safe JSON communication, use the <a
href="../json/index.html">JSON module</a> in
conjunction with the <a
href="../io/index.html">IO module</a> wherever
possible.
</p>
</div>
<h2 id="getting-started">Getting Started</h2>
<p>
To include the source files for JSONP and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>
<pre class="code prettyprint"><script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('jsonp', 'jsonp-url', function (Y) {
// JSONP is available and ready for use. Add implementation
// code here.
});
</script></pre>
<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
</p>
<h2 id="using">Using the JSONP Utility</h2>
<h3 id="basic">Instantiation and the <code>Y.jsonp</code> method</h3>
<p>
The JSONP utility provides the <code>Y.jsonp(url, callback)</code> method
for single transactions as well as a <code>Y.JSONPRequest</code> class to
manage reusable connections.
</p>
<p>
The first argument to either the <code>Y.jsonp</code> method or the
<code>Y.JSONPRequest</code> constructor is the URL of the JSONP service,
and the second is a callback function or <a href="#config">configuration
object</a> that contains a callback function. When the service responds
with the data, the callback will be executed with the response data as the
first parameter.
</p>
<p>
In place of the JSONP callback name in the URL, include the string
"{callback}". This placeholder will be used for a proxy function
that will route the data to your callback.
</p>
<pre class="code prettyprint">// instead of service.php?callback=handleJSONP
var url = "http://example.com/service.php?callback={callback}";
function handleJSONP(response) {
// response is a JavaScript object. No parsing necessary
Y.one("#output").setHTML(response.outputHTML);
}
Y.jsonp(url, handleJSONP);
// or
var service = new Y.JSONPRequest(url, handleJSONP);
service.send();</pre>
<h4 id="timing">Sending JSONP requests</h4>
<p>
<code>Y.jsonp(url, callback)</code> will dispatch the request immediately.
JSONPRequest instances will dispatch the request each time their
<code>send()</code> method is called.
</p>
<pre class="code prettyprint">// request sent immediately
Y.jsonp(url, handleJSONP);
// No request sent
var service = new Y.JSONPRequest(url, handleJSONP);
// ...until now
service.send();
// ...and now again
service.send();</pre>
<p>
<code>Y.jsonp(url, callback)</code> is a convenience wrapper to instantiate
a JSONPRequest instance and call its <code>send()</code> method.
</p>
<p>
This will generate a request to a URL like this one (note that the
<code>{callback}</code> placeholder has been replaced with a dynamically
generated callback name):
</p>
<pre class="code prettyprint">http://example.com/service.php?callback=YUI.Env.JSONP.yui_3_3_0_1_1294184187597423</pre>
<p>
The server will then be expected to respond with a JavaScript value wrapped
in a call to that function, like this:
</p>
<pre class="code prettyprint">YUI.Env.JSONP.yui_3_3_0_1_1294184187597423({"foo":"bar"});</pre>
<h3 id="config">Configuring the connection</h3>
<p>
The second argument to either <code>Y.jsonp</code> or the
<code>Y.JSONPRequest</code> constructor can be a success callback function
or for more control, it can be a configuration object. The supported keys
of this object are:
</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>timeout</td>
<td>
This value, defined as milliseconds, is a time threshold for
the transaction (e.g., <code>{ timeout: 2000 }</code> ). When
this limit is reached, the transaction's
<code>on.timeout</code> callback will be executed if
supplied.
</td>
</tr>
<tr>
<td>context</td>
<td>
Defines what will be "<code>this</code>" in the
callbacks. If undefined, the default will be the JSONPRequest
instance.
</td>
</tr>
<tr>
<td>args</td>
<td>
An array of additional arguments that will be passed to the
callbacks as second, third, and so on arguments.
</td>
</tr>
<tr>
<td>on</td>
<td>
<p>
<strong>Required</strong>. This object defines the
callbacks to be used for the transaction. At least an
<code>on.success</code> handler must be defined.
</p>
<ul>
<li>success (<strong>required</strong>)</li>
<li>failure</li>
<li>timeout</li>
</ul>
</td>
</tr>
<tr>
<td>format</td>
<td>
Preprocessor function to stitch together the supplied URL
(first argument), the proxy function name (internally
generated), and any additional arguments passed to
<code>send()</code>. See <a href="#format">Customizing the
JSONP URL</a> for more detail.
</td>
</tr>
</tbody>
</table>
<p>
This is an example of a configuration object, with a set of properties
defined.
</p>
<pre class="code prettyprint">var url = "http://example.com/service.php?callback={callback}",
service = new Y.JSONPRequest(url, {
on: {
success: MyApp.handleJSONP,
timeout: MyApp.handleTimeout
},
context: MyApp
timeout: 3000, // 3 second timeout
args: [new Date(), 100] // e.g. handleJSONP(data, date, number)
});
service.send();
// or
Y.jsonp(url, {
on: {
success: MyApp.handleJSONP,
timeout: MyApp.handleTimeout
},
context: MyApp
timeout: 3000, // 3 second timeout
args: [new Date(), 100] // e.g. handleJSONP(data, date, number)
});</pre>
<h3 id="url">Parsing the callback from the URL</h3>
<p>
An extension for the <code>jsonp</code> module is the
<code>jsonp-url</code> module which provides a few additional features.
</p>
<ol>
<li>
If you have a global function or a function available from the YUI
instance (e.g. <code>Y.MyApp.handleJSONP</code>), you can include the
name in the URL and omit the second parameter entirely.
</li>
<li>
The URL passed as the first parameter need not include the
"{callback}" string. If it is not found, it will look for
"callback=", then fall back to adding the query parameter
onto the URL.
</li>
</ol>
<pre class="code prettyprint">Y.MyApp.handleJSONP = function (data) {
Y.one("#output").setHTML(data.outputHTML);
};
Y.jsonp("http://example.com/service.php?callback=Y.MyApp.handleJSONP");
// or
Y.jsonp("http://example.com/service.php", {
context: Y.MyApp,
on: {
success: Y.MyApp.handleJSONP,
failure: Y.MyApp.handleFailure
}
});</pre>
<h3 id="format">Customizing the JSONP URL</h3>
<p>
The default URL formatter simply replaces the "{callback}"
placehold with the name of the generated proxy function. If you want to
customize the URL generation process, you can provide a <code>format</code>
function in the configuration. The function will receive the configured
URL (with "{callback}" placeholder), the string name of the proxy
function, and any additional arguments that were passed to
<code>send()</code>.
</p>
<pre class="code prettyprint">// Our custom formatter will expect a URL with an additional placeholder for
// username that must be supplied in send("bill");
// e.g. http://example.com/bill/json?fn=YUI.Env.JSONP._12345
function prepareJSONPUrl(url, proxy, username) {
return Y.Lang.sub(url, {
callback: proxy,
name: username || "user"
});
}
var url = "http://example.com/{name}/json?fn={callback}";
var service = new Y.JSONPRequest(url, {
format: prepareJSONPUrl,
on: {
success: handleJSONP
}
});
service.send("apipkin");
service.send("tivac");
service.send("razass");</pre>
<h2 id="issues">Known Issues</h2>
<ul>
<li>
Unlike the XMLHttpRequest calls generated by the IO utility, JSONP
requests can't be aborted, since they rely on dynamic script insertion
(which provides less low-level control than XHR). Keep this in mind
when deciding which method to use.
</li>
<li>
Since most browsers don't enforce execution order for dynamically
inserted scripts, JSONP callbacks may not be called in the same order
that the requests were sent. On the other hand, some browsers
<em>do</em> enforce execution order, so in these browsers a slow
request may block the execution of subsequent JSONP callbacks.
</li>
<li>
In WinJS (Windows 8 application mode), JSONP is not supported
due to the security measures enforced in that environment. Making
a JSONP request requires a remote script tag which is prohibited.
An alternative is to use the YQL module to query a YQL table that
can return the data that you need. The YQL module is supported in
this environment because it uses native <code>XMLHttpRequest</code> to fetch it's data.
</li>
</ul>
</div>
</div>
</div>
<div class="yui3-u-1-4">
<div class="sidebar">
<div id="toc" class="sidebox">
<div class="hd">
<h2 class="no-toc">Table of Contents</h2>
</div>
<div class="bd">
<ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#using">Using the JSONP Utility</a>
<ul class="toc">
<li>
<a href="#basic">Instantiation and the <code>Y.jsonp</code> method</a>
<ul class="toc">
<li>
<a href="#timing">Sending JSONP requests</a>
</li>
</ul>
</li>
<li>
<a href="#config">Configuring the connection</a>
</li>
<li>
<a href="#url">Parsing the callback from the URL</a>
</li>
<li>
<a href="#format">Customizing the JSONP URL</a>
</li>
</ul>
</li>
<li>
<a href="#issues">Known Issues</a>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="Get basic GitHub user info using a Y.jsonp(url, callback).">
<a href="jsonp-github.html">Getting Cross Domain JSON Data Using Y.jsonp()</a>
</li>
<li data-description="Create a reusable JSONPRequest object to poll the YUILibrary.com Gallery web service, fetching info on a random Gallery module.">
<a href="jsonp-gallery.html">Reusing a JSONPRequest Instance to Poll a Remote Server</a>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples That Use This Component</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="Wrapping async transactions with promises">
<a href="../promise/basic-example.html">Wrapping async transactions with promises</a>
</li>
<li data-description="Extend Y.Promise to create classes that encapsulate standard transaction logic in descriptive method names">
<a href="../promise/subclass-example.html">Subclassing Y.Promise</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script>
YUI.Env.Tests = {
examples: [],
project: '../assets',
assets: '../assets/jsonp',
name: 'jsonp',
title: 'JSONP',
newWindow: '',
auto: false
};
YUI.Env.Tests.examples.push('jsonp-github');
YUI.Env.Tests.examples.push('jsonp-gallery');
YUI.Env.Tests.examples.push('basic-example');
YUI.Env.Tests.examples.push('subclass-example');
</script>
<script src="../assets/yui/test-runner.js"></script>
</body>
</html>