Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / JsonP.html
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="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../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 here:
23  * http://en.wikipedia.org/wiki/JSONP
24  */
25 Ext.define('Ext.data.JsonP', {
26     
27     /* Begin Definitions */
28     
29     singleton: true,
30     
31     statics: {
32         requestCount: 0,
33         requests: {}
34     },
35     
36     /* End Definitions */
37     
38 <span id='Ext-data-JsonP-property-timeout'>    /**
39 </span>     * @property timeout
40      * @type Number
41      * A default timeout for any JsonP requests. If the request has not completed in this time the
42      * failure callback will be fired. The timeout is in ms. Defaults to &lt;tt&gt;30000&lt;/tt&gt;.
43      */
44     timeout: 30000,
45     
46 <span id='Ext-data-JsonP-property-disableCaching'>    /**
47 </span>     * @property disableCaching
48      * @type Boolean
49      * True to add a unique cache-buster param to requests. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
50      */
51     disableCaching: true,
52    
53 <span id='Ext-data-JsonP-property-disableCachingParam'>    /**
54 </span>     * @property disableCachingParam 
55      * @type String
56      * Change the parameter which is sent went disabling caching through a cache buster. Defaults to &lt;tt&gt;'_dc'&lt;/tt&gt;.
57      */
58     disableCachingParam: '_dc',
59    
60 <span id='Ext-data-JsonP-property-callbackKey'>    /**
61 </span>     * @property callbackKey
62      * @type String
63      * Specifies the GET parameter that will be sent to the server containing the function name to be executed when
64      * the request completes. Defaults to &lt;tt&gt;callback&lt;/tt&gt;. Thus, a common request will be in the form of
65      * url?callback=Ext.data.JsonP.callback1
66      */
67     callbackKey: 'callback',
68    
69 <span id='Ext-data-JsonP-method-request'>    /**
70 </span>     * Makes a JSONP request.
71      * @param {Object} options An object which may contain the following properties. Note that options will
72      * take priority over any defaults that are specified in the class.
73      * &lt;ul&gt;
74      * &lt;li&gt;&lt;b&gt;url&lt;/b&gt; : String &lt;div class=&quot;sub-desc&quot;&gt;The URL to request.&lt;/div&gt;&lt;/li&gt;
75      * &lt;li&gt;&lt;b&gt;params&lt;/b&gt; : Object (Optional)&lt;div class=&quot;sub-desc&quot;&gt;An object containing a series of
76      * key value pairs that will be sent along with the request.&lt;/div&gt;&lt;/li&gt;
77      * &lt;li&gt;&lt;b&gt;timeout&lt;/b&gt; : Number (Optional) &lt;div class=&quot;sub-desc&quot;&gt;See {@link #timeout}&lt;/div&gt;&lt;/li&gt;
78      * &lt;li&gt;&lt;b&gt;callbackKey&lt;/b&gt; : String (Optional) &lt;div class=&quot;sub-desc&quot;&gt;See {@link #callbackKey}&lt;/div&gt;&lt;/li&gt;
79      * &lt;li&gt;&lt;b&gt;callbackName&lt;/b&gt; : String (Optional) &lt;div class=&quot;sub-desc&quot;&gt;The function name to use for this request.
80      * By default this name will be auto-generated: Ext.data.JsonP.callback1, Ext.data.JsonP.callback2, etc.
81      * Setting this option to &quot;my_name&quot; will force the function name to be Ext.data.JsonP.my_name.
82      * Use this if you want deterministic behavior, but be careful - the callbackName should be different
83      * in each JsonP request that you make.&lt;/div&gt;&lt;/li&gt;
84      * &lt;li&gt;&lt;b&gt;disableCaching&lt;/b&gt; : Boolean (Optional) &lt;div class=&quot;sub-desc&quot;&gt;See {@link #disableCaching}&lt;/div&gt;&lt;/li&gt;
85      * &lt;li&gt;&lt;b&gt;disableCachingParam&lt;/b&gt; : String (Optional) &lt;div class=&quot;sub-desc&quot;&gt;See {@link #disableCachingParam}&lt;/div&gt;&lt;/li&gt;
86      * &lt;li&gt;&lt;b&gt;success&lt;/b&gt; : Function (Optional) &lt;div class=&quot;sub-desc&quot;&gt;A function to execute if the request succeeds.&lt;/div&gt;&lt;/li&gt;
87      * &lt;li&gt;&lt;b&gt;failure&lt;/b&gt; : Function (Optional) &lt;div class=&quot;sub-desc&quot;&gt;A function to execute if the request fails.&lt;/div&gt;&lt;/li&gt;
88      * &lt;li&gt;&lt;b&gt;callback&lt;/b&gt; : Function (Optional) &lt;div class=&quot;sub-desc&quot;&gt;A function to execute when the request 
89      * completes, whether it is a success or failure.&lt;/div&gt;&lt;/li&gt;
90      * &lt;li&gt;&lt;b&gt;scope&lt;/b&gt; : Object (Optional)&lt;div class=&quot;sub-desc&quot;&gt;The scope in
91      * which to execute the callbacks: The &quot;this&quot; object for the callback function. Defaults to the browser window.&lt;/div&gt;&lt;/li&gt;
92      * &lt;/ul&gt;
93      * @return {Object} request An object containing the request details.
94      */
95     request: function(options){
96         options = Ext.apply({}, options);
97        
98         //&lt;debug&gt;
99         if (!options.url) {
100             Ext.Error.raise('A url must be specified for a JSONP request.');
101         }
102         //&lt;/debug&gt;
103         
104         var me = this, 
105             disableCaching = Ext.isDefined(options.disableCaching) ? options.disableCaching : me.disableCaching, 
106             cacheParam = options.disableCachingParam || me.disableCachingParam, 
107             id = ++me.statics().requestCount, 
108             callbackName = options.callbackName || 'callback' + id, 
109             callbackKey = options.callbackKey || me.callbackKey, 
110             timeout = Ext.isDefined(options.timeout) ? options.timeout : me.timeout, 
111             params = Ext.apply({}, options.params), 
112             url = options.url,
113             request, 
114             script;
115             
116         params[callbackKey] = 'Ext.data.JsonP.' + callbackName;
117         if (disableCaching) {
118             params[cacheParam] = new Date().getTime();
119         }
120         
121         script = me.createScript(url, params);
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             callbackName: callbackName
133         };
134         
135         if (timeout &gt; 0) {
136             request.timeout = setTimeout(Ext.bind(me.handleTimeout, me, [request]), timeout);
137         }
138         
139         me.setupErrorHandling(request);
140         me[callbackName] = Ext.bind(me.handleResponse, me, [request], true);
141         Ext.getHead().appendChild(script);
142         return request;
143     },
144     
145 <span id='Ext-data-JsonP-method-abort'>    /**
146 </span>     * Abort a request. If the request parameter is not specified all open requests will
147      * be aborted.
148      * @param {Object/String} request (Optional) The request to abort
149      */
150     abort: function(request){
151         var requests = this.statics().requests,
152             key;
153             
154         if (request) {
155             if (!request.id) {
156                 request = requests[request];
157             }
158             this.abort(request);
159         } else {
160             for (key in requests) {
161                 if (requests.hasOwnProperty(key)) {
162                     this.abort(requests[key]);
163                 }
164             }
165         }
166     },
167     
168 <span id='Ext-data-JsonP-method-setupErrorHandling'>    /**
169 </span>     * Sets up error handling for the script
170      * @private
171      * @param {Object} request The request
172      */
173     setupErrorHandling: function(request){
174         request.script.onerror = Ext.bind(this.handleError, this, [request]);
175     },
176     
177 <span id='Ext-data-JsonP-method-handleAbort'>    /**
178 </span>     * Handles any aborts when loading the script
179      * @private
180      * @param {Object} request The request
181      */
182     handleAbort: function(request){
183         request.errorType = 'abort';
184         this.handleResponse(null, request);
185     },
186     
187 <span id='Ext-data-JsonP-method-handleError'>    /**
188 </span>     * Handles any script errors when loading the script
189      * @private
190      * @param {Object} request The request
191      */
192     handleError: function(request){
193         request.errorType = 'error';
194         this.handleResponse(null, request);
195     },
196  
197 <span id='Ext-data-JsonP-method-cleanupErrorHandling'>    /**
198 </span>     * Cleans up anu script handling errors
199      * @private
200      * @param {Object} request The request
201      */
202     cleanupErrorHandling: function(request){
203         request.script.onerror = null;
204     },
205  
206 <span id='Ext-data-JsonP-method-handleTimeout'>    /**
207 </span>     * Handle any script timeouts
208      * @private
209      * @param {Object} request The request
210      */
211     handleTimeout: function(request){
212         request.errorType = 'timeout';
213         this.handleResponse(null, request);
214     },
215  
216 <span id='Ext-data-JsonP-method-handleResponse'>    /**
217 </span>     * Handle a successful response
218      * @private
219      * @param {Object} result The result from the request
220      * @param {Object} request The request
221      */
222     handleResponse: function(result, request){
223  
224         var success = true;
225  
226         if (request.timeout) {
227             clearTimeout(request.timeout);
228         }
229         delete this[request.callbackName];
230         delete this.statics()[request.id];
231         this.cleanupErrorHandling(request);
232         Ext.fly(request.script).remove();
233  
234         if (request.errorType) {
235             success = false;
236             Ext.callback(request.failure, request.scope, [request.errorType]);
237         } else {
238             Ext.callback(request.success, request.scope, [result]);
239         }
240         Ext.callback(request.callback, request.scope, [success, result, request.errorType]);
241     },
242     
243 <span id='Ext-data-JsonP-method-createScript'>    /**
244 </span>     * Create the script tag
245      * @private
246      * @param {String} url The url of the request
247      * @param {Object} params Any extra params to be sent
248      */
249     createScript: function(url, params) {
250         var script = document.createElement('script');
251         script.setAttribute(&quot;src&quot;, Ext.urlAppend(url, Ext.Object.toQueryString(params)));
252         script.setAttribute(&quot;async&quot;, true);
253         script.setAttribute(&quot;type&quot;, &quot;text/javascript&quot;);
254         return script;
255     }
256 });
257 </pre>
258 </body>
259 </html>