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