|
1 <!DOCTYPE html> |
|
2 <html lang="en"> |
|
3 <head> |
|
4 <meta charset="utf-8"> |
|
5 <title>JSONP</title> |
|
6 <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic"> |
|
7 <link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css"> |
|
8 <link rel="stylesheet" href="../assets/css/main.css"> |
|
9 <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css"> |
|
10 <link rel="shortcut icon" type="image/png" href="../assets/favicon.png"> |
|
11 <script src="../../build/yui/yui-min.js"></script> |
|
12 |
|
13 </head> |
|
14 <body> |
|
15 <!-- |
|
16 <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> |
|
17 --> |
|
18 <div id="doc"> |
|
19 <div id="hd"> |
|
20 <h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1> |
|
21 </div> |
|
22 |
|
23 <a href="#toc" class="jump">Jump to Table of Contents</a> |
|
24 |
|
25 |
|
26 <h1>JSONP</h1> |
|
27 <div class="yui3-g"> |
|
28 <div class="yui3-u-3-4"> |
|
29 <div id="main"> |
|
30 <div class="content"><div class="intro component"> |
|
31 <p> |
|
32 The JSONP Utility is a specialized API for communicating with web |
|
33 services that provide JSON responses wrapped in a callback |
|
34 function. A typical JSONP request URL might look like |
|
35 "http://example.com/service.php?callback=handleData" and |
|
36 receive a text response in the form of |
|
37 <code>handleData({"records":[....]});</code>. |
|
38 </p> |
|
39 |
|
40 <p> |
|
41 The nature of YUI 3's sandbox model complicates JSONP transactions |
|
42 because JSONP relies on a global access point to process the |
|
43 response, but YUI 3 implementation code is typically wrapped in a |
|
44 <code>use(...)</code> callback and is therefore not globally |
|
45 accessible. The JSONP module provides a proxy system for |
|
46 channeling JSONP responses back into your YUI instance sandbox. |
|
47 </p> |
|
48 |
|
49 <p> |
|
50 <strong>Security Note:</strong> JSONP is an inherently unsecure |
|
51 communication method, since it involves the transfer of unvalidated |
|
52 JavaScript. It is by convention alone that the format is |
|
53 associated with JSON, but in reality, the response can include any |
|
54 arbitrary JavaScript, potentially opening your page to attack. |
|
55 <em>Be cautious about which services you communicate with via |
|
56 JSONP</em>. For safe JSON communication, use the <a |
|
57 href="../json/index.html">JSON module</a> in |
|
58 conjunction with the <a |
|
59 href="../io/index.html">IO module</a> wherever |
|
60 possible. |
|
61 </p> |
|
62 </div> |
|
63 |
|
64 <h2 id="getting-started">Getting Started</h2> |
|
65 |
|
66 <p> |
|
67 To include the source files for JSONP and its dependencies, first load |
|
68 the YUI seed file if you haven't already loaded it. |
|
69 </p> |
|
70 |
|
71 <pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre> |
|
72 |
|
73 |
|
74 <p> |
|
75 Next, create a new YUI instance for your application and populate it with the |
|
76 modules you need by specifying them as arguments to the <code>YUI().use()</code> method. |
|
77 YUI will automatically load any dependencies required by the modules you |
|
78 specify. |
|
79 </p> |
|
80 |
|
81 <pre class="code prettyprint"><script> |
|
82 // Create a new YUI instance and populate it with the required modules. |
|
83 YUI().use('jsonp', 'jsonp-url', function (Y) { |
|
84 // JSONP is available and ready for use. Add implementation |
|
85 // code here. |
|
86 }); |
|
87 </script></pre> |
|
88 |
|
89 |
|
90 <p> |
|
91 For more information on creating YUI instances and on the |
|
92 <a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the |
|
93 documentation for the <a href="../yui/index.html">YUI Global Object</a>. |
|
94 </p> |
|
95 |
|
96 |
|
97 <h2 id="using">Using the JSONP Utility</h2> |
|
98 |
|
99 <h3 id="basic">Instantiation and the <code>Y.jsonp</code> method</h3> |
|
100 |
|
101 <p> |
|
102 The JSONP utility provides the <code>Y.jsonp(url, callback)</code> method |
|
103 for single transactions as well as a <code>Y.JSONPRequest</code> class to |
|
104 manage reusable connections. |
|
105 </p> |
|
106 |
|
107 |
|
108 <p> |
|
109 The first argument to either the <code>Y.jsonp</code> method or the |
|
110 <code>Y.JSONPRequest</code> constructor is the URL of the JSONP service, |
|
111 and the second is a callback function or <a href="#config">configuration |
|
112 object</a> that contains a callback function. When the service responds |
|
113 with the data, the callback will be executed with the response data as the |
|
114 first parameter. |
|
115 </p> |
|
116 |
|
117 |
|
118 <p> |
|
119 In place of the JSONP callback name in the URL, include the string |
|
120 "{callback}". This placeholder will be used for a proxy function |
|
121 that will route the data to your callback. |
|
122 </p> |
|
123 |
|
124 |
|
125 <pre class="code prettyprint">// instead of service.php?callback=handleJSONP |
|
126 var url = "http://example.com/service.php?callback={callback}"; |
|
127 |
|
128 function handleJSONP(response) { |
|
129 // response is a JavaScript object. No parsing necessary |
|
130 Y.one("#output").setHTML(response.outputHTML); |
|
131 } |
|
132 |
|
133 Y.jsonp(url, handleJSONP); |
|
134 |
|
135 // or |
|
136 var service = new Y.JSONPRequest(url, handleJSONP); |
|
137 service.send();</pre> |
|
138 |
|
139 |
|
140 <h4 id="timing">Sending JSONP requests</h4> |
|
141 |
|
142 <p> |
|
143 <code>Y.jsonp(url, callback)</code> will dispatch the request immediately. |
|
144 JSONPRequest instances will dispatch the request each time their |
|
145 <code>send()</code> method is called. |
|
146 </p> |
|
147 |
|
148 |
|
149 <pre class="code prettyprint">// request sent immediately |
|
150 Y.jsonp(url, handleJSONP); |
|
151 |
|
152 // No request sent |
|
153 var service = new Y.JSONPRequest(url, handleJSONP); |
|
154 |
|
155 // ...until now |
|
156 service.send(); |
|
157 |
|
158 // ...and now again |
|
159 service.send();</pre> |
|
160 |
|
161 |
|
162 <p> |
|
163 <code>Y.jsonp(url, callback)</code> is a convenience wrapper to instantiate |
|
164 a JSONPRequest instance and call its <code>send()</code> method. |
|
165 </p> |
|
166 |
|
167 |
|
168 <p> |
|
169 This will generate a request to a URL like this one (note that the |
|
170 <code>{callback}</code> placeholder has been replaced with a dynamically |
|
171 generated callback name): |
|
172 </p> |
|
173 |
|
174 |
|
175 <pre class="code prettyprint">http://example.com/service.php?callback=YUI.Env.JSONP.yui_3_3_0_1_1294184187597423</pre> |
|
176 |
|
177 |
|
178 <p> |
|
179 The server will then be expected to respond with a JavaScript value wrapped |
|
180 in a call to that function, like this: |
|
181 </p> |
|
182 |
|
183 <pre class="code prettyprint">YUI.Env.JSONP.yui_3_3_0_1_1294184187597423({"foo":"bar"});</pre> |
|
184 |
|
185 |
|
186 <h3 id="config">Configuring the connection</h3> |
|
187 |
|
188 <p> |
|
189 The second argument to either <code>Y.jsonp</code> or the |
|
190 <code>Y.JSONPRequest</code> constructor can be a success callback function |
|
191 or for more control, it can be a configuration object. The supported keys |
|
192 of this object are: |
|
193 </p> |
|
194 |
|
195 |
|
196 <table> |
|
197 <thead> |
|
198 <tr> |
|
199 <th>Property</th> |
|
200 <th>Description</th> |
|
201 </tr> |
|
202 </thead> |
|
203 <tbody> |
|
204 <tr> |
|
205 <td>timeout</td> |
|
206 <td> |
|
207 This value, defined as milliseconds, is a time threshold for |
|
208 the transaction (e.g., <code>{ timeout: 2000 }</code> ). When |
|
209 this limit is reached, the transaction's |
|
210 <code>on.timeout</code> callback will be executed if |
|
211 supplied. |
|
212 </td> |
|
213 </tr> |
|
214 <tr> |
|
215 <td>context</td> |
|
216 <td> |
|
217 Defines what will be "<code>this</code>" in the |
|
218 callbacks. If undefined, the default will be the JSONPRequest |
|
219 instance. |
|
220 </td> |
|
221 </tr> |
|
222 <tr> |
|
223 <td>args</td> |
|
224 <td> |
|
225 An array of additional arguments that will be passed to the |
|
226 callbacks as second, third, and so on arguments. |
|
227 </td> |
|
228 </tr> |
|
229 <tr> |
|
230 <td>on</td> |
|
231 <td> |
|
232 <p> |
|
233 <strong>Required</strong>. This object defines the |
|
234 callbacks to be used for the transaction. At least an |
|
235 <code>on.success</code> handler must be defined. |
|
236 </p> |
|
237 <ul> |
|
238 <li>success (<strong>required</strong>)</li> |
|
239 <li>failure</li> |
|
240 <li>timeout</li> |
|
241 </ul> |
|
242 </td> |
|
243 </tr> |
|
244 <tr> |
|
245 <td>format</td> |
|
246 <td> |
|
247 Preprocessor function to stitch together the supplied URL |
|
248 (first argument), the proxy function name (internally |
|
249 generated), and any additional arguments passed to |
|
250 <code>send()</code>. See <a href="#format">Customizing the |
|
251 JSONP URL</a> for more detail. |
|
252 </td> |
|
253 </tr> |
|
254 </tbody> |
|
255 </table> |
|
256 |
|
257 <p> |
|
258 This is an example of a configuration object, with a set of properties |
|
259 defined. |
|
260 </p> |
|
261 |
|
262 <pre class="code prettyprint">var url = "http://example.com/service.php?callback={callback}", |
|
263 service = new Y.JSONPRequest(url, { |
|
264 on: { |
|
265 success: MyApp.handleJSONP, |
|
266 timeout: MyApp.handleTimeout |
|
267 }, |
|
268 context: MyApp |
|
269 timeout: 3000, // 3 second timeout |
|
270 args: [new Date(), 100] // e.g. handleJSONP(data, date, number) |
|
271 }); |
|
272 |
|
273 service.send(); |
|
274 |
|
275 // or |
|
276 Y.jsonp(url, { |
|
277 on: { |
|
278 success: MyApp.handleJSONP, |
|
279 timeout: MyApp.handleTimeout |
|
280 }, |
|
281 context: MyApp |
|
282 timeout: 3000, // 3 second timeout |
|
283 args: [new Date(), 100] // e.g. handleJSONP(data, date, number) |
|
284 });</pre> |
|
285 |
|
286 |
|
287 <h3 id="url">Parsing the callback from the URL</h3> |
|
288 |
|
289 <p> |
|
290 An extension for the <code>jsonp</code> module is the |
|
291 <code>jsonp-url</code> module which provides a few additional features. |
|
292 </p> |
|
293 |
|
294 |
|
295 <ol> |
|
296 <li> |
|
297 If you have a global function or a function available from the YUI |
|
298 instance (e.g. <code>Y.MyApp.handleJSONP</code>), you can include the |
|
299 name in the URL and omit the second parameter entirely. |
|
300 </li> |
|
301 <li> |
|
302 The URL passed as the first parameter need not include the |
|
303 "{callback}" string. If it is not found, it will look for |
|
304 "callback=", then fall back to adding the query parameter |
|
305 onto the URL. |
|
306 </li> |
|
307 </ol> |
|
308 |
|
309 <pre class="code prettyprint">Y.MyApp.handleJSONP = function (data) { |
|
310 Y.one("#output").setHTML(data.outputHTML); |
|
311 }; |
|
312 |
|
313 Y.jsonp("http://example.com/service.php?callback=Y.MyApp.handleJSONP"); |
|
314 |
|
315 // or |
|
316 Y.jsonp("http://example.com/service.php", { |
|
317 context: Y.MyApp, |
|
318 on: { |
|
319 success: Y.MyApp.handleJSONP, |
|
320 failure: Y.MyApp.handleFailure |
|
321 } |
|
322 });</pre> |
|
323 |
|
324 |
|
325 <h3 id="format">Customizing the JSONP URL</h3> |
|
326 |
|
327 <p> |
|
328 The default URL formatter simply replaces the "{callback}" |
|
329 placehold with the name of the generated proxy function. If you want to |
|
330 customize the URL generation process, you can provide a <code>format</code> |
|
331 function in the configuration. The function will receive the configured |
|
332 URL (with "{callback}" placeholder), the string name of the proxy |
|
333 function, and any additional arguments that were passed to |
|
334 <code>send()</code>. |
|
335 </p> |
|
336 |
|
337 <pre class="code prettyprint">// Our custom formatter will expect a URL with an additional placeholder for |
|
338 // username that must be supplied in send("bill"); |
|
339 // e.g. http://example.com/bill/json?fn=YUI.Env.JSONP._12345 |
|
340 function prepareJSONPUrl(url, proxy, username) { |
|
341 return Y.Lang.sub(url, { |
|
342 callback: proxy, |
|
343 name: username || "user" |
|
344 }); |
|
345 } |
|
346 |
|
347 var url = "http://example.com/{name}/json?fn={callback}"; |
|
348 |
|
349 var service = new Y.JSONPRequest(url, { |
|
350 format: prepareJSONPUrl, |
|
351 on: { |
|
352 success: handleJSONP |
|
353 } |
|
354 }); |
|
355 |
|
356 service.send("apipkin"); |
|
357 service.send("tivac"); |
|
358 service.send("razass");</pre> |
|
359 |
|
360 |
|
361 <h2 id="issues">Known Issues</h2> |
|
362 |
|
363 <ul> |
|
364 <li> |
|
365 Unlike the XMLHttpRequest calls generated by the IO utility, JSONP |
|
366 requests can't be aborted, since they rely on dynamic script insertion |
|
367 (which provides less low-level control than XHR). Keep this in mind |
|
368 when deciding which method to use. |
|
369 </li> |
|
370 |
|
371 <li> |
|
372 Since most browsers don't enforce execution order for dynamically |
|
373 inserted scripts, JSONP callbacks may not be called in the same order |
|
374 that the requests were sent. On the other hand, some browsers |
|
375 <em>do</em> enforce execution order, so in these browsers a slow |
|
376 request may block the execution of subsequent JSONP callbacks. |
|
377 </li> |
|
378 <li> |
|
379 In WinJS (Windows 8 application mode), JSONP is not supported |
|
380 due to the security measures enforced in that environment. Making |
|
381 a JSONP request requires a remote script tag which is prohibited. |
|
382 An alternative is to use the YQL module to query a YQL table that |
|
383 can return the data that you need. The YQL module is supported in |
|
384 this environment because it uses native <code>XMLHttpRequest</code> to fetch it's data. |
|
385 </li> |
|
386 </ul> |
|
387 </div> |
|
388 </div> |
|
389 </div> |
|
390 |
|
391 <div class="yui3-u-1-4"> |
|
392 <div class="sidebar"> |
|
393 |
|
394 <div id="toc" class="sidebox"> |
|
395 <div class="hd"> |
|
396 <h2 class="no-toc">Table of Contents</h2> |
|
397 </div> |
|
398 |
|
399 <div class="bd"> |
|
400 <ul class="toc"> |
|
401 <li> |
|
402 <a href="#getting-started">Getting Started</a> |
|
403 </li> |
|
404 <li> |
|
405 <a href="#using">Using the JSONP Utility</a> |
|
406 <ul class="toc"> |
|
407 <li> |
|
408 <a href="#basic">Instantiation and the <code>Y.jsonp</code> method</a> |
|
409 <ul class="toc"> |
|
410 <li> |
|
411 <a href="#timing">Sending JSONP requests</a> |
|
412 </li> |
|
413 </ul> |
|
414 </li> |
|
415 <li> |
|
416 <a href="#config">Configuring the connection</a> |
|
417 </li> |
|
418 <li> |
|
419 <a href="#url">Parsing the callback from the URL</a> |
|
420 </li> |
|
421 <li> |
|
422 <a href="#format">Customizing the JSONP URL</a> |
|
423 </li> |
|
424 </ul> |
|
425 </li> |
|
426 <li> |
|
427 <a href="#issues">Known Issues</a> |
|
428 </li> |
|
429 </ul> |
|
430 </div> |
|
431 </div> |
|
432 |
|
433 |
|
434 |
|
435 <div class="sidebox"> |
|
436 <div class="hd"> |
|
437 <h2 class="no-toc">Examples</h2> |
|
438 </div> |
|
439 |
|
440 <div class="bd"> |
|
441 <ul class="examples"> |
|
442 |
|
443 |
|
444 <li data-description="Get basic GitHub user info using a Y.jsonp(url, callback)."> |
|
445 <a href="jsonp-github.html">Getting Cross Domain JSON Data Using Y.jsonp()</a> |
|
446 </li> |
|
447 |
|
448 |
|
449 |
|
450 <li data-description="Create a reusable JSONPRequest object to poll the YUILibrary.com Gallery web service, fetching info on a random Gallery module."> |
|
451 <a href="jsonp-gallery.html">Reusing a JSONPRequest Instance to Poll a Remote Server</a> |
|
452 </li> |
|
453 |
|
454 |
|
455 |
|
456 |
|
457 |
|
458 |
|
459 </ul> |
|
460 </div> |
|
461 </div> |
|
462 |
|
463 |
|
464 |
|
465 <div class="sidebox"> |
|
466 <div class="hd"> |
|
467 <h2 class="no-toc">Examples That Use This Component</h2> |
|
468 </div> |
|
469 |
|
470 <div class="bd"> |
|
471 <ul class="examples"> |
|
472 |
|
473 |
|
474 |
|
475 |
|
476 |
|
477 |
|
478 <li data-description="Wrapping async transactions with promises"> |
|
479 <a href="../promise/basic-example.html">Wrapping async transactions with promises</a> |
|
480 </li> |
|
481 |
|
482 |
|
483 |
|
484 <li data-description="Extend Y.Promise to create classes that encapsulate standard transaction logic in descriptive method names"> |
|
485 <a href="../promise/subclass-example.html">Subclassing Y.Promise</a> |
|
486 </li> |
|
487 |
|
488 |
|
489 </ul> |
|
490 </div> |
|
491 </div> |
|
492 |
|
493 </div> |
|
494 </div> |
|
495 </div> |
|
496 </div> |
|
497 |
|
498 <script src="../assets/vendor/prettify/prettify-min.js"></script> |
|
499 <script>prettyPrint();</script> |
|
500 |
|
501 <script> |
|
502 YUI.Env.Tests = { |
|
503 examples: [], |
|
504 project: '../assets', |
|
505 assets: '../assets/jsonp', |
|
506 name: 'jsonp', |
|
507 title: 'JSONP', |
|
508 newWindow: '', |
|
509 auto: false |
|
510 }; |
|
511 YUI.Env.Tests.examples.push('jsonp-github'); |
|
512 YUI.Env.Tests.examples.push('jsonp-gallery'); |
|
513 YUI.Env.Tests.examples.push('basic-example'); |
|
514 YUI.Env.Tests.examples.push('subclass-example'); |
|
515 |
|
516 </script> |
|
517 <script src="../assets/yui/test-runner.js"></script> |
|
518 |
|
519 |
|
520 |
|
521 </body> |
|
522 </html> |