1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<div class="intro component">
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The JSONP Utility is a specialized API for communicating with web
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith services that provide JSON responses wrapped in a callback
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith function. A typical JSONP request URL might look like
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith "http://example.com/service.php?callback=handleData" and
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith receive a text response in the form of
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>handleData({"records":[....]});</code>.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The nature of YUI 3's sandbox model complicates JSONP transactions
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith because JSONP relies on a global access point to process the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith response, but YUI 3 implementation code is typically wrapped in a
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>use(...)</code> callback and is therefore not globally
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith accessible. The JSONP module provides a proxy system for
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith channeling JSONP responses back into your YUI instance sandbox.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <strong>Security Note:</strong> JSONP is an inherently unsecure
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith communication method, since it involves the transfer of unvalidated
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith JavaScript. It is by convention alone that the format is
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith associated with JSON, but in reality, the response can include any
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith arbitrary JavaScript, potentially opening your page to attack.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <em>Be cautious about which services you communicate with via
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith JSONP</em>. For safe JSON communication, use the <a
949cffcab80cdd0b820d11da7f7514cfd070d9faEric Ferraiuolo href="../json/index.html">JSON module</a> in
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith conjunction with the <a
949cffcab80cdd0b820d11da7f7514cfd070d9faEric Ferraiuolo href="../io/index.html">IO module</a> wherever
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith{{>getting-started}}
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="using">Using the JSONP Utility</h2>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="basic">Instantiation and the <code>Y.jsonp</code> method</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The JSONP utility provides the <code>Y.jsonp(url, callback)</code> method
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith for single transactions as well as a <code>Y.JSONPRequest</code> class to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith manage reusable connections.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The first argument to either the <code>Y.jsonp</code> method or the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>Y.JSONPRequest</code> constructor is the URL of the JSONP service,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith and the second is a callback function or <a href="#config">configuration
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith object</a> that contains a callback function. When the service responds
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith with the data, the callback will be executed with the response data as the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith first parameter.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith In place of the JSONP callback name in the URL, include the string
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith "{callback}". This placeholder will be used for a proxy function
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith that will route the data to your callback.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// instead of service.php?callback=handleJSONP
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar url = "http://example.com/service.php?callback={callback}";
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithfunction handleJSONP(response) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith // response is a JavaScript object. No parsing necessary
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Y.one("#output").setContent(response.outputHTML);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithY.jsonp(url, handleJSONP);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar service = new Y.JSONPRequest(url, handleJSONP);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h4 id="timing">Sending JSONP requests</h4>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>Y.jsonp(url, callback)</code> will dispatch the request immediately.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith JSONPRequest instances will dispatch the request each time their
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>send()</code> method is called.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// request sent immediately
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithY.jsonp(url, handleJSONP);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// No request sent
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar service = new Y.JSONPRequest(url, handleJSONP);
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>Y.jsonp(url, callback)</code> is a convenience wrapper to instantiate
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith a JSONPRequest instance and call its <code>send()</code> method.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith This will generate a request to a URL like this one (note that the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>{callback}</code> placeholder has been replaced with a dynamically
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith generated callback name):
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithhttp://example.com/service.php?callback=YUI.Env.JSONP.yui_3_3_0_1_1294184187597423
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The server will then be expected to respond with a JavaScript value wrapped
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith in a call to that function, like this:
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithYUI.Env.JSONP.yui_3_3_0_1_1294184187597423({"foo":"bar"});
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="config">Configuring the connection</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The second argument to either <code>Y.jsonp</code> or the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>Y.JSONPRequest</code> constructor can be a success callback function
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith or for more control, it can be a configuration object. The supported keys
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith of this object are:
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Property</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <th>Description</th>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>timeout</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith This value, defined as milliseconds, is a time threshold for
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith the transaction (e.g., <code>{ timeout: 2000 }</code> ). When
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith this limit is reached, the transaction's
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <code>on.timeout</code> callback will be executed if
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>context</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Defines what will be "<code>this</code>" in the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith callbacks. If undefined, the default will be the JSONPRequest
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>args</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith An array of additional arguments that will be passed to the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith callbacks as second, third, and so on arguments.
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <strong>Required</strong>. This object defines the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith callbacks to be used for the transaction. At least an
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <code>on.success</code> handler must be defined.
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <li>success (<strong>required</strong>)</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>failure</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <li>timeout</li>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <td>format</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Preprocessor function to stitch together the supplied URL
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith (first argument), the proxy function name (internally
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith generated), and any additional arguments passed to
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <code>send()</code>. See <a href="#format">Customizing the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith JSONP URL</a> for more detail.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith This is an example of a configuration object, with a set of properties
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar url = "http://example.com/service.php?callback={callback}",
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith service = new Y.JSONPRequest(url, {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith context: MyApp
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith timeout: 3000, // 3 second timeout
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith args: [new Date(), 100] // e.g. handleJSONP(data, date, number)
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith context: MyApp
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith timeout: 3000, // 3 second timeout
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith args: [new Date(), 100] // e.g. handleJSONP(data, date, number)
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="url">Parsing the callback from the URL</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith An extension for the <code>jsonp</code> module is the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>jsonp-url</code> module which provides a few additional features.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith If you have a global function or a function available from the YUI
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith instance (e.g. <code>Y.MyApp.handleJSONP</code>), you can include the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith name in the URL and omit the second parameter entirely.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The URL passed as the first parameter need not include the
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith "{callback}" string. If it is not found, it will look for
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith "callback=", then fall back to adding the query parameter
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith onto the URL.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithY.MyApp.handleJSONP = function (data) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke SmithY.jsonp("http://example.com/service.php?callback=Y.MyApp.handleJSONP");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h3 id="format">Customizing the JSONP URL</h3>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith The default URL formatter simply replaces the "{callback}"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith placehold with the name of the generated proxy function. If you want to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith customize the URL generation process, you can provide a <code>format</code>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith function in the configuration. The function will receive the configured
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith URL (with "{callback}" placeholder), the string name of the proxy
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith function, and any additional arguments that were passed to
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <code>send()</code>.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// Our custom formatter will expect a URL with an additional placeholder for
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// username that must be supplied in send("bill");
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith// e.g. http://example.com/bill/json?fn=YUI.Env.JSONP._12345
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithfunction prepareJSONPUrl(url, proxy, username) {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith return Y.Lang.sub(url, {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith callback: proxy,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith name: username || "user"
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar url = "http://example.com/{name}/json?fn={callback}";
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smithvar service = new Y.JSONPRequest(url, {
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith format: prepareJSONPUrl,
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith success: handleJSONP
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith<h2 id="issues">Known Issues</h2>
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Unlike the XMLHttpRequest calls generated by the IO utility, JSONP
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith requests can't be aborted, since they rely on dynamic script insertion
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith (which provides less low-level control than XHR). Keep this in mind
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith when deciding which method to use.
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith Since most browsers don't enforce execution order for dynamically
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith inserted scripts, JSONP callbacks may not be called in the same order
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith that the requests were sent. On the other hand, some browsers
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith <em>do</em> enforce execution order, so in these browsers a slow
daa301d2a0f17b5c1b04d777de3acf969b9b63d2Luke Smith request may block the execution of subsequent JSONP callbacks.