Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / docs / source / UpdateManager.html
1 <html>\r
2 <head>\r
3   <title>The source code</title>\r
4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
6 </head>\r
7 <body  onload="prettyPrint();">\r
8     <pre class="prettyprint lang-js"><div id="cls-Ext.Updater"></div>/**
9  * @class Ext.Updater
10  * @extends Ext.util.Observable
11  * Provides AJAX-style update capabilities for Element objects.  Updater can be used to {@link #update}
12  * an {@link Ext.Element} once, or you can use {@link #startAutoRefresh} to set up an auto-updating
13  * {@link Ext.Element Element} on a specific interval.<br><br>
14  * Usage:<br>
15  * <pre><code>
16  * var el = Ext.get("foo"); // Get Ext.Element object
17  * var mgr = el.getUpdater();
18  * mgr.update({
19         url: "http://myserver.com/index.php",
20         params: {
21             param1: "foo",
22             param2: "bar"
23         }
24  * });
25  * ...
26  * mgr.formUpdate("myFormId", "http://myserver.com/index.php");
27  * <br>
28  * // or directly (returns the same Updater instance)
29  * var mgr = new Ext.Updater("myElementId");
30  * mgr.startAutoRefresh(60, "http://myserver.com/index.php");
31  * mgr.on("update", myFcnNeedsToKnow);
32  * <br>
33  * // short handed call directly from the element object
34  * Ext.get("foo").load({
35         url: "bar.php",
36         scripts: true,
37         params: "param1=foo&amp;param2=bar",
38         text: "Loading Foo..."
39  * });
40  * </code></pre>
41  * @constructor
42  * Create new Updater directly.
43  * @param {Mixed} el The element to update
44  * @param {Boolean} forceNew (optional) By default the constructor checks to see if the passed element already
45  * has an Updater and if it does it returns the same instance. This will skip that check (useful for extending this class).
46  */
47 Ext.UpdateManager = Ext.Updater = Ext.extend(Ext.util.Observable, 
48 function() {
49         var BEFOREUPDATE = "beforeupdate",
50                 UPDATE = "update",
51                 FAILURE = "failure";
52                 
53         // private
54     function processSuccess(response){      
55             var me = this;
56         me.transaction = null;
57         if (response.argument.form && response.argument.reset) {
58             try { // put in try/catch since some older FF releases had problems with this
59                 response.argument.form.reset();
60             } catch(e){}
61         }
62         if (me.loadScripts) {
63             me.renderer.render(me.el, response, me,
64                updateComplete.createDelegate(me, [response]));
65         } else {
66             me.renderer.render(me.el, response, me);
67             updateComplete.call(me, response);
68         }
69     }
70     
71     // private
72     function updateComplete(response, type, success){
73         this.fireEvent(type || UPDATE, this.el, response);
74         if(Ext.isFunction(response.argument.callback)){
75             response.argument.callback.call(response.argument.scope, this.el, Ext.isEmpty(success) ? true : false, response, response.argument.options);
76         }
77     }
78
79     // private
80     function processFailure(response){              
81         updateComplete.call(this, response, FAILURE, !!(this.transaction = null));
82     }
83             
84         return {
85             constructor: function(el, forceNew){
86                     var me = this;
87                 el = Ext.get(el);
88                 if(!forceNew && el.updateManager){
89                     return el.updateManager;
90                 }
91                 <div id="prop-Ext.Updater-el"></div>/**
92                  * The Element object
93                  * @type Ext.Element
94                  */
95                 me.el = el;
96                 <div id="prop-Ext.Updater-defaultUrl"></div>/**
97                  * Cached url to use for refreshes. Overwritten every time update() is called unless "discardUrl" param is set to true.
98                  * @type String
99                  */
100                 me.defaultUrl = null;
101         
102                 me.addEvents(
103                     <div id="event-Ext.Updater-beforeupdate"></div>/**
104                      * @event beforeupdate
105                      * Fired before an update is made, return false from your handler and the update is cancelled.
106                      * @param {Ext.Element} el
107                      * @param {String/Object/Function} url
108                      * @param {String/Object} params
109                      */
110                     BEFOREUPDATE,
111                     <div id="event-Ext.Updater-update"></div>/**
112                      * @event update
113                      * Fired after successful update is made.
114                      * @param {Ext.Element} el
115                      * @param {Object} oResponseObject The response Object
116                      */
117                     UPDATE,
118                     <div id="event-Ext.Updater-failure"></div>/**
119                      * @event failure
120                      * Fired on update failure.
121                      * @param {Ext.Element} el
122                      * @param {Object} oResponseObject The response Object
123                      */
124                     FAILURE
125                 );
126         
127                 Ext.apply(me, Ext.Updater.defaults);
128                 <div id="prop-Ext.Updater-sslBlankUrl"></div>/**
129                  * Blank page URL to use with SSL file uploads (defaults to {@link Ext.Updater.defaults#sslBlankUrl}).
130                  * @property sslBlankUrl
131                  * @type String
132                  */
133                 <div id="prop-Ext.Updater-disableCaching"></div>/**
134                  * Whether to append unique parameter on get request to disable caching (defaults to {@link Ext.Updater.defaults#disableCaching}).
135                  * @property disableCaching
136                  * @type Boolean
137                  */
138                 <div id="prop-Ext.Updater-indicatorText"></div>/**
139                  * Text for loading indicator (defaults to {@link Ext.Updater.defaults#indicatorText}).
140                  * @property indicatorText
141                  * @type String
142                  */
143                 <div id="prop-Ext.Updater-showLoadIndicator"></div>/**
144                  * Whether to show indicatorText when loading (defaults to {@link Ext.Updater.defaults#showLoadIndicator}).
145                  * @property showLoadIndicator
146                  * @type String
147                  */
148                 <div id="prop-Ext.Updater-timeout"></div>/**
149                  * Timeout for requests or form posts in seconds (defaults to {@link Ext.Updater.defaults#timeout}).
150                  * @property timeout
151                  * @type Number
152                  */
153                 <div id="prop-Ext.Updater-loadScripts"></div>/**
154                  * True to process scripts in the output (defaults to {@link Ext.Updater.defaults#loadScripts}).
155                  * @property loadScripts
156                  * @type Boolean
157                  */
158         
159                 <div id="prop-Ext.Updater-transaction"></div>/**
160                  * Transaction object of the current executing transaction, or null if there is no active transaction.
161                  */
162                 me.transaction = null;
163                 <div id="prop-Ext.Updater-refreshDelegate"></div>/**
164                  * Delegate for refresh() prebound to "this", use myUpdater.refreshDelegate.createCallback(arg1, arg2) to bind arguments
165                  * @type Function
166                  */
167                 me.refreshDelegate = me.refresh.createDelegate(me);
168                 <div id="prop-Ext.Updater-updateDelegate"></div>/**
169                  * Delegate for update() prebound to "this", use myUpdater.updateDelegate.createCallback(arg1, arg2) to bind arguments
170                  * @type Function
171                  */
172                 me.updateDelegate = me.update.createDelegate(me);
173                 <div id="prop-Ext.Updater-formUpdateDelegate"></div>/**
174                  * Delegate for formUpdate() prebound to "this", use myUpdater.formUpdateDelegate.createCallback(arg1, arg2) to bind arguments
175                  * @type Function
176                  */
177                 me.formUpdateDelegate = (me.formUpdate || function(){}).createDelegate(me);     
178                 
179                         <div id="prop-Ext.Updater-renderer"></div>/**
180                          * The renderer for this Updater (defaults to {@link Ext.Updater.BasicRenderer}).
181                          */
182                 me.renderer = me.renderer || me.getDefaultRenderer();
183                 
184                 Ext.Updater.superclass.constructor.call(me);
185             },
186         
187                 <div id="method-Ext.Updater-setRenderer"></div>/**
188              * Sets the content renderer for this Updater. See {@link Ext.Updater.BasicRenderer#render} for more details.
189              * @param {Object} renderer The object implementing the render() method
190              */
191             setRenderer : function(renderer){
192                 this.renderer = renderer;
193             },  
194         
195             <div id="method-Ext.Updater-getRenderer"></div>/**
196              * Returns the current content renderer for this Updater. See {@link Ext.Updater.BasicRenderer#render} for more details.
197              * @return {Object}
198              */
199             getRenderer : function(){
200                return this.renderer;
201             },
202
203             <div id="method-Ext.Updater-getDefaultRenderer"></div>/**
204              * This is an overrideable method which returns a reference to a default
205              * renderer class if none is specified when creating the Ext.Updater.
206              * Defaults to {@link Ext.Updater.BasicRenderer}
207              */
208             getDefaultRenderer: function() {
209                 return new Ext.Updater.BasicRenderer();
210             },
211                 
212             <div id="method-Ext.Updater-setDefaultUrl"></div>/**
213              * Sets the default URL used for updates.
214              * @param {String/Function} defaultUrl The url or a function to call to get the url
215              */
216             setDefaultUrl : function(defaultUrl){
217                 this.defaultUrl = defaultUrl;
218             },
219         
220             <div id="method-Ext.Updater-getEl"></div>/**
221              * Get the Element this Updater is bound to
222              * @return {Ext.Element} The element
223              */
224             getEl : function(){
225                 return this.el;
226             },
227         
228                 <div id="method-Ext.Updater-update"></div>/**
229              * Performs an <b>asynchronous</b> request, updating this element with the response.
230              * If params are specified it uses POST, otherwise it uses GET.<br><br>
231              * <b>Note:</b> Due to the asynchronous nature of remote server requests, the Element
232              * will not have been fully updated when the function returns. To post-process the returned
233              * data, use the callback option, or an <b><tt>update</tt></b> event handler.
234              * @param {Object} options A config object containing any of the following options:<ul>
235              * <li>url : <b>String/Function</b><p class="sub-desc">The URL to request or a function which
236              * <i>returns</i> the URL (defaults to the value of {@link Ext.Ajax#url} if not specified).</p></li>
237              * <li>method : <b>String</b><p class="sub-desc">The HTTP method to
238              * use. Defaults to POST if the <tt>params</tt> argument is present, otherwise GET.</p></li>
239              * <li>params : <b>String/Object/Function</b><p class="sub-desc">The
240              * parameters to pass to the server (defaults to none). These may be specified as a url-encoded
241              * string, or as an object containing properties which represent parameters,
242              * or as a function, which returns such an object.</p></li>
243              * <li>scripts : <b>Boolean</b><p class="sub-desc">If <tt>true</tt>
244              * any &lt;script&gt; tags embedded in the response text will be extracted
245              * and executed (defaults to {@link Ext.Updater.defaults#loadScripts}). If this option is specified,
246              * the callback will be called <i>after</i> the execution of the scripts.</p></li>
247              * <li>callback : <b>Function</b><p class="sub-desc">A function to
248              * be called when the response from the server arrives. The following
249              * parameters are passed:<ul>
250              * <li><b>el</b> : Ext.Element<p class="sub-desc">The Element being updated.</p></li>
251              * <li><b>success</b> : Boolean<p class="sub-desc">True for success, false for failure.</p></li>
252              * <li><b>response</b> : XMLHttpRequest<p class="sub-desc">The XMLHttpRequest which processed the update.</p></li>
253              * <li><b>options</b> : Object<p class="sub-desc">The config object passed to the update call.</p></li></ul>
254              * </p></li>
255              * <li>scope : <b>Object</b><p class="sub-desc">The scope in which
256              * to execute the callback (The callback's <tt>this</tt> reference.) If the
257              * <tt>params</tt> argument is a function, this scope is used for that function also.</p></li>
258              * <li>discardUrl : <b>Boolean</b><p class="sub-desc">By default, the URL of this request becomes
259              * the default URL for this Updater object, and will be subsequently used in {@link #refresh}
260              * calls.  To bypass this behavior, pass <tt>discardUrl:true</tt> (defaults to false).</p></li>
261              * <li>timeout : <b>Number</b><p class="sub-desc">The number of seconds to wait for a response before
262              * timing out (defaults to {@link Ext.Updater.defaults#timeout}).</p></li>
263              * <li>text : <b>String</b><p class="sub-desc">The text to use as the innerHTML of the
264              * {@link Ext.Updater.defaults#indicatorText} div (defaults to 'Loading...').  To replace the entire div, not
265              * just the text, override {@link Ext.Updater.defaults#indicatorText} directly.</p></li>
266              * <li>nocache : <b>Boolean</b><p class="sub-desc">Only needed for GET
267              * requests, this option causes an extra, auto-generated parameter to be appended to the request
268              * to defeat caching (defaults to {@link Ext.Updater.defaults#disableCaching}).</p></li></ul>
269              * <p>
270              * For example:
271         <pre><code>
272         um.update({
273             url: "your-url.php",
274             params: {param1: "foo", param2: "bar"}, // or a URL encoded string
275             callback: yourFunction,
276             scope: yourObject, //(optional scope)
277             discardUrl: true,
278             nocache: true,
279             text: "Loading...",
280             timeout: 60,
281             scripts: false // Save time by avoiding RegExp execution.
282         });
283         </code></pre>
284              */
285             update : function(url, params, callback, discardUrl){
286                     var me = this,
287                         cfg, 
288                         callerScope;
289                         
290                 if(me.fireEvent(BEFOREUPDATE, me.el, url, params) !== false){               
291                     if(Ext.isObject(url)){ // must be config object
292                         cfg = url;
293                         url = cfg.url;
294                         params = params || cfg.params;
295                         callback = callback || cfg.callback;
296                         discardUrl = discardUrl || cfg.discardUrl;
297                         callerScope = cfg.scope;                        
298                         if(!Ext.isEmpty(cfg.nocache)){me.disableCaching = cfg.nocache;};
299                         if(!Ext.isEmpty(cfg.text)){me.indicatorText = '<div class="loading-indicator">'+cfg.text+"</div>";};
300                         if(!Ext.isEmpty(cfg.scripts)){me.loadScripts = cfg.scripts;};
301                         if(!Ext.isEmpty(cfg.timeout)){me.timeout = cfg.timeout;};
302                     }
303                     me.showLoading();
304         
305                     if(!discardUrl){
306                         me.defaultUrl = url;
307                     }
308                     if(Ext.isFunction(url)){
309                         url = url.call(me);
310                     }
311         
312                     var o = Ext.apply({}, {
313                         url : url,
314                         params: (Ext.isFunction(params) && callerScope) ? params.createDelegate(callerScope) : params,
315                         success: processSuccess,
316                         failure: processFailure,
317                         scope: me,
318                         callback: undefined,
319                         timeout: (me.timeout*1000),
320                         disableCaching: me.disableCaching,
321                         argument: {
322                             "options": cfg,
323                             "url": url,
324                             "form": null,
325                             "callback": callback,
326                             "scope": callerScope || window,
327                             "params": params
328                         }
329                     }, cfg);
330         
331                     me.transaction = Ext.Ajax.request(o);
332                 }
333             },          
334
335                 <div id="method-Ext.Updater-formUpdate"></div>/**
336              * <p>Performs an async form post, updating this element with the response. If the form has the attribute
337              * enctype="<a href="http://www.faqs.org/rfcs/rfc2388.html">multipart/form-data</a>", it assumes it's a file upload.
338              * Uses this.sslBlankUrl for SSL file uploads to prevent IE security warning.</p>
339              * <p>File uploads are not performed using normal "Ajax" techniques, that is they are <b>not</b>
340              * performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the
341              * DOM <tt>&lt;form></tt> element temporarily modified to have its
342              * <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
343              * to a dynamically generated, hidden <tt>&lt;iframe></tt> which is inserted into the document
344              * but removed after the return data has been gathered.</p>
345              * <p>Be aware that file upload packets, sent with the content type <a href="http://www.faqs.org/rfcs/rfc2388.html">multipart/form-data</a>
346              * and some server technologies (notably JEE) may require some custom processing in order to
347              * retrieve parameter names and parameter values from the packet content.</p>
348              * @param {String/HTMLElement} form The form Id or form element
349              * @param {String} url (optional) The url to pass the form to. If omitted the action attribute on the form will be used.
350              * @param {Boolean} reset (optional) Whether to try to reset the form after the update
351              * @param {Function} callback (optional) Callback when transaction is complete. The following
352              * parameters are passed:<ul>
353              * <li><b>el</b> : Ext.Element<p class="sub-desc">The Element being updated.</p></li>
354              * <li><b>success</b> : Boolean<p class="sub-desc">True for success, false for failure.</p></li>
355              * <li><b>response</b> : XMLHttpRequest<p class="sub-desc">The XMLHttpRequest which processed the update.</p></li></ul>
356              */
357             formUpdate : function(form, url, reset, callback){
358                     var me = this;
359                 if(me.fireEvent(BEFOREUPDATE, me.el, form, url) !== false){
360                     if(Ext.isFunction(url)){
361                         url = url.call(me);
362                     }
363                     form = Ext.getDom(form)
364                     me.transaction = Ext.Ajax.request({
365                         form: form,
366                         url:url,
367                         success: processSuccess,
368                         failure: processFailure,
369                         scope: me,
370                         timeout: (me.timeout*1000),
371                         argument: {
372                             "url": url,
373                             "form": form,
374                             "callback": callback,
375                             "reset": reset
376                         }
377                     });
378                     me.showLoading.defer(1, me);
379                 }
380             },
381                         
382             <div id="method-Ext.Updater-startAutoRefresh"></div>/**
383              * Set this element to auto refresh.  Can be canceled by calling {@link #stopAutoRefresh}.
384              * @param {Number} interval How often to update (in seconds).
385              * @param {String/Object/Function} url (optional) The url for this request, a config object in the same format
386              * supported by {@link #load}, or a function to call to get the url (defaults to the last used url).  Note that while
387              * the url used in a load call can be reused by this method, other load config options will not be reused and must be
388              * sepcified as part of a config object passed as this paramter if needed.
389              * @param {String/Object} params (optional) The parameters to pass as either a url encoded string
390              * "&param1=1&param2=2" or as an object {param1: 1, param2: 2}
391              * @param {Function} callback (optional) Callback when transaction is complete - called with signature (oElement, bSuccess)
392              * @param {Boolean} refreshNow (optional) Whether to execute the refresh now, or wait the interval
393              */
394             startAutoRefresh : function(interval, url, params, callback, refreshNow){
395                     var me = this;
396                 if(refreshNow){
397                     me.update(url || me.defaultUrl, params, callback, true);
398                 }
399                 if(me.autoRefreshProcId){
400                     clearInterval(me.autoRefreshProcId);
401                 }
402                 me.autoRefreshProcId = setInterval(me.update.createDelegate(me, [url || me.defaultUrl, params, callback, true]), interval * 1000);
403             },
404         
405             <div id="method-Ext.Updater-stopAutoRefresh"></div>/**
406              * Stop auto refresh on this element.
407              */
408             stopAutoRefresh : function(){
409                 if(this.autoRefreshProcId){
410                     clearInterval(this.autoRefreshProcId);
411                     delete this.autoRefreshProcId;
412                 }
413             },
414         
415             <div id="method-Ext.Updater-isAutoRefreshing"></div>/**
416              * Returns true if the Updater is currently set to auto refresh its content (see {@link #startAutoRefresh}), otherwise false.
417              */
418             isAutoRefreshing : function(){
419                return !!this.autoRefreshProcId;
420             },
421         
422             <div id="method-Ext.Updater-showLoading"></div>/**
423              * Display the element's "loading" state. By default, the element is updated with {@link #indicatorText}. This
424              * method may be overridden to perform a custom action while this Updater is actively updating its contents.
425              */
426             showLoading : function(){
427                 if(this.showLoadIndicator){
428                 this.el.dom.innerHTML = this.indicatorText;
429                 }
430             },
431         
432             <div id="method-Ext.Updater-abort"></div>/**
433              * Aborts the currently executing transaction, if any.
434              */
435             abort : function(){
436                 if(this.transaction){
437                     Ext.Ajax.abort(this.transaction);
438                 }
439             },
440         
441             <div id="method-Ext.Updater-isUpdating"></div>/**
442              * Returns true if an update is in progress, otherwise false.
443              * @return {Boolean}
444              */
445             isUpdating : function(){        
446                 return this.transaction ? Ext.Ajax.isLoading(this.transaction) : false;        
447             },
448             
449             <div id="method-Ext.Updater-refresh"></div>/**
450              * Refresh the element with the last used url or defaultUrl. If there is no url, it returns immediately
451              * @param {Function} callback (optional) Callback when transaction is complete - called with signature (oElement, bSuccess)
452              */
453             refresh : function(callback){
454                 if(this.defaultUrl){
455                         this.update(this.defaultUrl, null, callback, true);
456                 }
457             }
458     }
459 }());
460
461 <div id="cls-Ext.Updater.defaults"></div>/**
462  * @class Ext.Updater.defaults
463  * The defaults collection enables customizing the default properties of Updater
464  */
465 Ext.Updater.defaults = {
466    <div id="prop-Ext.Updater.defaults-timeout"></div>/**
467      * Timeout for requests or form posts in seconds (defaults to 30 seconds).
468      * @type Number
469      */
470     timeout : 30,    
471     <div id="prop-Ext.Updater.defaults-disableCaching"></div>/**
472      * True to append a unique parameter to GET requests to disable caching (defaults to false).
473      * @type Boolean
474      */
475     disableCaching : false,
476     <div id="prop-Ext.Updater.defaults-showLoadIndicator"></div>/**
477      * Whether or not to show {@link #indicatorText} during loading (defaults to true).
478      * @type Boolean
479      */
480     showLoadIndicator : true,
481     <div id="prop-Ext.Updater.defaults-indicatorText"></div>/**
482      * Text for loading indicator (defaults to '&lt;div class="loading-indicator"&gt;Loading...&lt;/div&gt;').
483      * @type String
484      */
485     indicatorText : '<div class="loading-indicator">Loading...</div>',
486      <div id="prop-Ext.Updater.defaults-loadScripts"></div>/**
487      * True to process scripts by default (defaults to false).
488      * @type Boolean
489      */
490     loadScripts : false,
491     <div id="prop-Ext.Updater.defaults-sslBlankUrl"></div>/**
492     * Blank page URL to use with SSL file uploads (defaults to {@link Ext#SSL_SECURE_URL} if set, or "javascript:false").
493     * @type String
494     */
495     sslBlankUrl : (Ext.SSL_SECURE_URL || "javascript:false")      
496 };
497
498
499 <div id="method-Ext.Updater-Updater.updateElement"></div>/**
500  * Static convenience method. <b>This method is deprecated in favor of el.load({url:'foo.php', ...})</b>.
501  * Usage:
502  * <pre><code>Ext.Updater.updateElement("my-div", "stuff.php");</code></pre>
503  * @param {Mixed} el The element to update
504  * @param {String} url The url
505  * @param {String/Object} params (optional) Url encoded param string or an object of name/value pairs
506  * @param {Object} options (optional) A config object with any of the Updater properties you want to set - for
507  * example: {disableCaching:true, indicatorText: "Loading data..."}
508  * @static
509  * @deprecated
510  * @member Ext.Updater
511  */
512 Ext.Updater.updateElement = function(el, url, params, options){
513     var um = Ext.get(el).getUpdater();
514     Ext.apply(um, options);
515     um.update(url, params, options ? options.callback : null);
516 };
517
518 <div id="cls-Ext.Updater.BasicRenderer"></div>/**
519  * @class Ext.Updater.BasicRenderer
520  * Default Content renderer. Updates the elements innerHTML with the responseText.
521  */
522 Ext.Updater.BasicRenderer = function(){};
523
524 Ext.Updater.BasicRenderer.prototype = {
525     <div id="method-Ext.Updater.BasicRenderer-render"></div>/**
526      * This is called when the transaction is completed and it's time to update the element - The BasicRenderer
527      * updates the elements innerHTML with the responseText - To perform a custom render (i.e. XML or JSON processing),
528      * create an object with a "render(el, response)" method and pass it to setRenderer on the Updater.
529      * @param {Ext.Element} el The element being rendered
530      * @param {Object} response The XMLHttpRequest object
531      * @param {Updater} updateManager The calling update manager
532      * @param {Function} callback A callback that will need to be called if loadScripts is true on the Updater
533      */
534      render : function(el, response, updateManager, callback){       
535         el.update(response.responseText, updateManager.loadScripts, callback);
536     }
537 };</pre>    \r
538 </body>\r
539 </html>