/ext-4.1.0_b3/docs/source/JsonP.html
HTML | 273 lines | 244 code | 29 blank | 0 comment | 0 complexity | 383d227e9cfe61851d6a1f8a4909758d MD5 | raw file
1<!DOCTYPE html>
2<html>
3<head>
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <title>The source code</title>
6 <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7 <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8 <style type="text/css">
9 .highlight { display: block; background-color: #ddd; }
10 </style>
11 <script type="text/javascript">
12 function highlight() {
13 document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14 }
15 </script>
16</head>
17<body onload="prettyPrint(); highlight();">
18 <pre class="prettyprint lang-js"><span id='Ext-data-JsonP'>/**
19</span> * @class Ext.data.JsonP
20 * @singleton
21 * This class is used to create JSONP requests. JSONP is a mechanism that allows for making
22 * requests for data cross domain. More information is available <a href="http://en.wikipedia.org/wiki/JSONP">here</a>.
23 */
24Ext.define('Ext.data.JsonP', {
25
26 /* Begin Definitions */
27
28 singleton: true,
29
30 statics: {
31 requestCount: 0,
32 requests: {}
33 },
34
35 /* End Definitions */
36
37<span id='Ext-data-JsonP-property-timeout'> /**
38</span> * @property timeout
39 * @type Number
40 * A default timeout for any JsonP requests. If the request has not completed in this time the
41 * failure callback will be fired. The timeout is in ms. Defaults to <tt>30000</tt>.
42 */
43 timeout: 30000,
44
45<span id='Ext-data-JsonP-property-disableCaching'> /**
46</span> * @property disableCaching
47 * @type Boolean
48 * True to add a unique cache-buster param to requests. Defaults to <tt>true</tt>.
49 */
50 disableCaching: true,
51
52<span id='Ext-data-JsonP-property-disableCachingParam'> /**
53</span> * @property disableCachingParam
54 * @type String
55 * Change the parameter which is sent went disabling caching through a cache buster. Defaults to <tt>'_dc'</tt>.
56 */
57 disableCachingParam: '_dc',
58
59<span id='Ext-data-JsonP-property-callbackKey'> /**
60</span> * @property callbackKey
61 * @type String
62 * Specifies the GET parameter that will be sent to the server containing the function name to be executed when
63 * the request completes. Defaults to <tt>callback</tt>. Thus, a common request will be in the form of
64 * url?callback=Ext.data.JsonP.callback1
65 */
66 callbackKey: 'callback',
67
68<span id='Ext-data-JsonP-method-request'> /**
69</span> * Makes a JSONP request.
70 * @param {Object} options An object which may contain the following properties. Note that options will
71 * take priority over any defaults that are specified in the class.
72 * <ul>
73 * <li><b>url</b> : String <div class="sub-desc">The URL to request.</div></li>
74 * <li><b>params</b> : Object (Optional)<div class="sub-desc">An object containing a series of
75 * key value pairs that will be sent along with the request.</div></li>
76 * <li><b>timeout</b> : Number (Optional) <div class="sub-desc">See {@link #timeout}</div></li>
77 * <li><b>callbackKey</b> : String (Optional) <div class="sub-desc">See {@link #callbackKey}</div></li>
78 * <li><b>callbackName</b> : String (Optional) <div class="sub-desc">The function name to use for this request.
79 * By default this name will be auto-generated: Ext.data.JsonP.callback1, Ext.data.JsonP.callback2, etc.
80 * Setting this option to "my_name" will force the function name to be Ext.data.JsonP.my_name.
81 * Use this if you want deterministic behavior, but be careful - the callbackName should be different
82 * in each JsonP request that you make.</div></li>
83 * <li><b>disableCaching</b> : Boolean (Optional) <div class="sub-desc">See {@link #disableCaching}</div></li>
84 * <li><b>disableCachingParam</b> : String (Optional) <div class="sub-desc">See {@link #disableCachingParam}</div></li>
85 * <li><b>success</b> : Function (Optional) <div class="sub-desc">A function to execute if the request succeeds.</div></li>
86 * <li><b>failure</b> : Function (Optional) <div class="sub-desc">A function to execute if the request fails.</div></li>
87 * <li><b>callback</b> : Function (Optional) <div class="sub-desc">A function to execute when the request
88 * completes, whether it is a success or failure.</div></li>
89 * <li><b>scope</b> : Object (Optional)<div class="sub-desc">The scope in
90 * which to execute the callbacks: The "this" object for the callback function. Defaults to the browser window.</div></li>
91 * </ul>
92 * @return {Object} request An object containing the request details.
93 */
94 request: function(options){
95 options = Ext.apply({}, options);
96
97 //<debug>
98 if (!options.url) {
99 Ext.Error.raise('A url must be specified for a JSONP request.');
100 }
101 //</debug>
102
103 var me = this,
104 disableCaching = Ext.isDefined(options.disableCaching) ? options.disableCaching : me.disableCaching,
105 cacheParam = options.disableCachingParam || me.disableCachingParam,
106 id = ++me.statics().requestCount,
107 callbackName = options.callbackName || 'callback' + id,
108 callbackKey = options.callbackKey || me.callbackKey,
109 timeout = Ext.isDefined(options.timeout) ? options.timeout : me.timeout,
110 params = Ext.apply({}, options.params),
111 url = options.url,
112 name = Ext.name,
113 request,
114 script;
115
116 params[callbackKey] = name + '.data.JsonP.' + callbackName;
117 if (disableCaching) {
118 params[cacheParam] = new Date().getTime();
119 }
120
121 script = me.createScript(url, params, options);
122
123 me.statics().requests[id] = request = {
124 url: url,
125 params: params,
126 script: script,
127 id: id,
128 scope: options.scope,
129 success: options.success,
130 failure: options.failure,
131 callback: options.callback,
132 callbackKey: callbackKey,
133 callbackName: callbackName
134 };
135
136 if (timeout > 0) {
137 request.timeout = setTimeout(Ext.bind(me.handleTimeout, me, [request]), timeout);
138 }
139
140 me.setupErrorHandling(request);
141 me[callbackName] = Ext.bind(me.handleResponse, me, [request], true);
142 me.loadScript(request);
143 return request;
144 },
145
146<span id='Ext-data-JsonP-method-abort'> /**
147</span> * Abort a request. If the request parameter is not specified all open requests will
148 * be aborted.
149 * @param {Object/String} request (Optional) The request to abort
150 */
151 abort: function(request){
152 var me = this,
153 requests = me.statics().requests,
154 key;
155
156 if (request) {
157 if (!request.id) {
158 request = requests[request];
159 }
160 me.handleAbort(request);
161 } else {
162 for (key in requests) {
163 if (requests.hasOwnProperty(key)) {
164 me.abort(requests[key]);
165 }
166 }
167 }
168 },
169
170<span id='Ext-data-JsonP-method-setupErrorHandling'> /**
171</span> * Sets up error handling for the script
172 * @private
173 * @param {Object} request The request
174 */
175 setupErrorHandling: function(request){
176 request.script.onerror = Ext.bind(this.handleError, this, [request]);
177 },
178
179<span id='Ext-data-JsonP-method-handleAbort'> /**
180</span> * Handles any aborts when loading the script
181 * @private
182 * @param {Object} request The request
183 */
184 handleAbort: function(request){
185 request.errorType = 'abort';
186 this.handleResponse(null, request);
187 },
188
189<span id='Ext-data-JsonP-method-handleError'> /**
190</span> * Handles any script errors when loading the script
191 * @private
192 * @param {Object} request The request
193 */
194 handleError: function(request){
195 request.errorType = 'error';
196 this.handleResponse(null, request);
197 },
198
199<span id='Ext-data-JsonP-method-cleanupErrorHandling'> /**
200</span> * Cleans up anu script handling errors
201 * @private
202 * @param {Object} request The request
203 */
204 cleanupErrorHandling: function(request){
205 request.script.onerror = null;
206 },
207
208<span id='Ext-data-JsonP-method-handleTimeout'> /**
209</span> * Handle any script timeouts
210 * @private
211 * @param {Object} request The request
212 */
213 handleTimeout: function(request){
214 request.errorType = 'timeout';
215 this.handleResponse(null, request);
216 },
217
218<span id='Ext-data-JsonP-method-handleResponse'> /**
219</span> * Handle a successful response
220 * @private
221 * @param {Object} result The result from the request
222 * @param {Object} request The request
223 */
224 handleResponse: function(result, request){
225
226 var success = true;
227
228 if (request.timeout) {
229 clearTimeout(request.timeout);
230 }
231 delete this[request.callbackName];
232 delete this.statics().requests[request.id];
233 this.cleanupErrorHandling(request);
234 Ext.fly(request.script).remove();
235
236 if (request.errorType) {
237 success = false;
238 Ext.callback(request.failure, request.scope, [request.errorType]);
239 } else {
240 Ext.callback(request.success, request.scope, [result]);
241 }
242 Ext.callback(request.callback, request.scope, [success, result, request.errorType]);
243 },
244
245<span id='Ext-data-JsonP-method-createScript'> /**
246</span> * Create the script tag given the specified url, params and options. The options
247 * parameter is passed to allow an override to access it.
248 * @private
249 * @param {String} url The url of the request
250 * @param {Object} params Any extra params to be sent
251 * @param {Object} options The object passed to {@link #request}.
252 */
253 createScript: function(url, params, options) {
254 var script = document.createElement('script');
255 script.setAttribute("src", Ext.urlAppend(url, Ext.Object.toQueryString(params)));
256 script.setAttribute("async", true);
257 script.setAttribute("type", "text/javascript");
258 return script;
259 },
260
261<span id='Ext-data-JsonP-method-loadScript'> /**
262</span> * Loads the script for the given request by appending it to the HEAD element. This is
263 * its own method so that users can override it (as well as {@link #createScript}).
264 * @private
265 * @param request The request object.
266 */
267 loadScript: function (request) {
268 Ext.getHead().appendChild(request.script);
269 }
270});
271</pre>
272</body>
273</html>