Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / ElementLoader.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="../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-ElementLoader'>/**
19 </span> * A class used to load remote content to an Element. Sample usage:
20  *
21  *     Ext.get('el').load({
22  *         url: 'myPage.php',
23  *         scripts: true,
24  *         params: {
25  *             id: 1
26  *         }
27  *     });
28  *
29  * In general this class will not be instanced directly, rather the {@link Ext.Element#load} method
30  * will be used.
31  */
32 Ext.define('Ext.ElementLoader', {
33
34     /* Begin Definitions */
35
36     mixins: {
37         observable: 'Ext.util.Observable'
38     },
39
40     uses: [
41         'Ext.data.Connection',
42         'Ext.Ajax'
43     ],
44
45     statics: {
46         Renderer: {
47             Html: function(loader, response, active){
48                 loader.getTarget().update(response.responseText, active.scripts === true);
49                 return true;
50             }
51         }
52     },
53
54     /* End Definitions */
55
56 <span id='Ext-ElementLoader-cfg-url'>    /**
57 </span>     * @cfg {String} url
58      * The url to retrieve the content from.
59      */
60     url: null,
61
62 <span id='Ext-ElementLoader-cfg-params'>    /**
63 </span>     * @cfg {Object} params
64      * Any params to be attached to the Ajax request. These parameters will
65      * be overridden by any params in the load options.
66      */
67     params: null,
68
69 <span id='Ext-ElementLoader-cfg-baseParams'>    /**
70 </span>     * @cfg {Object} baseParams Params that will be attached to every request. These parameters
71      * will not be overridden by any params in the load options.
72      */
73     baseParams: null,
74
75 <span id='Ext-ElementLoader-cfg-autoLoad'>    /**
76 </span>     * @cfg {Boolean/Object} autoLoad
77      * True to have the loader make a request as soon as it is created.
78      * This argument can also be a set of options that will be passed to {@link #load} is called.
79      */
80     autoLoad: false,
81
82 <span id='Ext-ElementLoader-cfg-target'>    /**
83 </span>     * @cfg {HTMLElement/Ext.Element/String} target
84      * The target element for the loader. It can be the DOM element, the id or an {@link Ext.Element}.
85      */
86     target: null,
87
88 <span id='Ext-ElementLoader-cfg-loadMask'>    /**
89 </span>     * @cfg {Boolean/String} loadMask
90      * True or a string to show when the element is loading.
91      */
92     loadMask: false,
93
94 <span id='Ext-ElementLoader-cfg-ajaxOptions'>    /**
95 </span>     * @cfg {Object} ajaxOptions
96      * Any additional options to be passed to the request, for example timeout or headers.
97      */
98     ajaxOptions: null,
99
100 <span id='Ext-ElementLoader-cfg-scripts'>    /**
101 </span>     * @cfg {Boolean} scripts
102      * True to parse any inline script tags in the response.
103      */
104     scripts: false,
105
106 <span id='Ext-ElementLoader-cfg-success'>    /**
107 </span>     * @cfg {Function} success
108      * A function to be called when a load request is successful.
109      * Will be called with the following config parameters:
110      *
111      * - this - The ElementLoader instance.
112      * - response - The response object.
113      * - options - Ajax options.
114      */
115
116 <span id='Ext-ElementLoader-cfg-failure'>    /**
117 </span>     * @cfg {Function} failure A function to be called when a load request fails.
118      * Will be called with the following config parameters:
119      *
120      * - this - The ElementLoader instance.
121      * - response - The response object.
122      * - options - Ajax options.
123      */
124
125 <span id='Ext-ElementLoader-cfg-callback'>    /**
126 </span>     * @cfg {Function} callback A function to be called when a load request finishes.
127      * Will be called with the following config parameters:
128      *
129      * - this - The ElementLoader instance.
130      * - success - True if successful request.
131      * - response - The response object.
132      * - options - Ajax options.
133      */
134
135 <span id='Ext-ElementLoader-cfg-scope'>    /**
136 </span>     * @cfg {Object} scope
137      * The scope to execute the {@link #success} and {@link #failure} functions in.
138      */
139
140 <span id='Ext-ElementLoader-cfg-renderer'>    /**
141 </span>     * @cfg {Function} renderer
142      * A custom function to render the content to the element. The passed parameters are:
143      *
144      * - The loader
145      * - The response
146      * - The active request
147      */
148
149     isLoader: true,
150
151     constructor: function(config) {
152         var me = this,
153             autoLoad;
154
155         config = config || {};
156         Ext.apply(me, config);
157         me.setTarget(me.target);
158         me.addEvents(
159 <span id='Ext-ElementLoader-event-beforeload'>            /**
160 </span>             * @event beforeload
161              * Fires before a load request is made to the server.
162              * Returning false from an event listener can prevent the load
163              * from occurring.
164              * @param {Ext.ElementLoader} this
165              * @param {Object} options The options passed to the request
166              */
167             'beforeload',
168
169 <span id='Ext-ElementLoader-event-exception'>            /**
170 </span>             * @event exception
171              * Fires after an unsuccessful load.
172              * @param {Ext.ElementLoader} this
173              * @param {Object} response The response from the server
174              * @param {Object} options The options passed to the request
175              */
176             'exception',
177
178 <span id='Ext-ElementLoader-event-load'>            /**
179 </span>             * @event load
180              * Fires after a successful load.
181              * @param {Ext.ElementLoader} this
182              * @param {Object} response The response from the server
183              * @param {Object} options The options passed to the request
184              */
185             'load'
186         );
187
188         // don't pass config because we have already applied it.
189         me.mixins.observable.constructor.call(me);
190
191         if (me.autoLoad) {
192             autoLoad = me.autoLoad;
193             if (autoLoad === true) {
194                 autoLoad = {};
195             }
196             me.load(autoLoad);
197         }
198     },
199
200 <span id='Ext-ElementLoader-method-setTarget'>    /**
201 </span>     * Sets an {@link Ext.Element} as the target of this loader.
202      * Note that if the target is changed, any active requests will be aborted.
203      * @param {String/HTMLElement/Ext.Element} target The element or its ID.
204      */
205     setTarget: function(target){
206         var me = this;
207         target = Ext.get(target);
208         if (me.target &amp;&amp; me.target != target) {
209             me.abort();
210         }
211         me.target = target;
212     },
213
214 <span id='Ext-ElementLoader-method-getTarget'>    /**
215 </span>     * Returns the target of this loader.
216      * @return {Ext.Component} The target or null if none exists.
217      */
218     getTarget: function(){
219         return this.target || null;
220     },
221
222 <span id='Ext-ElementLoader-method-abort'>    /**
223 </span>     * Aborts the active load request
224      */
225     abort: function(){
226         var active = this.active;
227         if (active !== undefined) {
228             Ext.Ajax.abort(active.request);
229             if (active.mask) {
230                 this.removeMask();
231             }
232             delete this.active;
233         }
234     },
235
236 <span id='Ext-ElementLoader-method-removeMask'>    /**
237 </span>     * Removes the mask on the target
238      * @private
239      */
240     removeMask: function(){
241         this.target.unmask();
242     },
243
244 <span id='Ext-ElementLoader-method-addMask'>    /**
245 </span>     * Adds the mask on the target
246      * @private
247      * @param {Boolean/Object} mask The mask configuration
248      */
249     addMask: function(mask){
250         this.target.mask(mask === true ? null : mask);
251     },
252
253 <span id='Ext-ElementLoader-method-load'>    /**
254 </span>     * Loads new data from the server.
255      * @param {Object} options The options for the request. They can be any configuration option that can be specified for
256      * the class, with the exception of the target option. Note that any options passed to the method will override any
257      * class defaults.
258      */
259     load: function(options) {
260         //&lt;debug&gt;
261         if (!this.target) {
262             Ext.Error.raise('A valid target is required when loading content');
263         }
264         //&lt;/debug&gt;
265
266         options = Ext.apply({}, options);
267
268         var me = this,
269             target = me.target,
270             mask = Ext.isDefined(options.loadMask) ? options.loadMask : me.loadMask,
271             params = Ext.apply({}, options.params),
272             ajaxOptions = Ext.apply({}, options.ajaxOptions),
273             callback = options.callback || me.callback,
274             scope = options.scope || me.scope || me,
275             request;
276
277         Ext.applyIf(ajaxOptions, me.ajaxOptions);
278         Ext.applyIf(options, ajaxOptions);
279
280         Ext.applyIf(params, me.params);
281         Ext.apply(params, me.baseParams);
282
283         Ext.applyIf(options, {
284             url: me.url
285         });
286
287         //&lt;debug&gt;
288         if (!options.url) {
289             Ext.Error.raise('You must specify the URL from which content should be loaded');
290         }
291         //&lt;/debug&gt;
292
293         Ext.apply(options, {
294             scope: me,
295             params: params,
296             callback: me.onComplete
297         });
298
299         if (me.fireEvent('beforeload', me, options) === false) {
300             return;
301         }
302
303         if (mask) {
304             me.addMask(mask);
305         }
306
307         request = Ext.Ajax.request(options);
308         me.active = {
309             request: request,
310             options: options,
311             mask: mask,
312             scope: scope,
313             callback: callback,
314             success: options.success || me.success,
315             failure: options.failure || me.failure,
316             renderer: options.renderer || me.renderer,
317             scripts: Ext.isDefined(options.scripts) ? options.scripts : me.scripts
318         };
319         me.setOptions(me.active, options);
320     },
321
322 <span id='Ext-ElementLoader-property-setOptions'>    /**
323 </span>     * Sets any additional options on the active request
324      * @private
325      * @param {Object} active The active request
326      * @param {Object} options The initial options
327      */
328     setOptions: Ext.emptyFn,
329
330 <span id='Ext-ElementLoader-method-onComplete'>    /**
331 </span>     * Parses the response after the request completes
332      * @private
333      * @param {Object} options Ajax options
334      * @param {Boolean} success Success status of the request
335      * @param {Object} response The response object
336      */
337     onComplete: function(options, success, response) {
338         var me = this,
339             active = me.active,
340             scope = active.scope,
341             renderer = me.getRenderer(active.renderer);
342
343
344         if (success) {
345             success = renderer.call(me, me, response, active);
346         }
347
348         if (success) {
349             Ext.callback(active.success, scope, [me, response, options]);
350             me.fireEvent('load', me, response, options);
351         } else {
352             Ext.callback(active.failure, scope, [me, response, options]);
353             me.fireEvent('exception', me, response, options);
354         }
355         Ext.callback(active.callback, scope, [me, success, response, options]);
356
357         if (active.mask) {
358             me.removeMask();
359         }
360
361         delete me.active;
362     },
363
364 <span id='Ext-ElementLoader-method-getRenderer'>    /**
365 </span>     * Gets the renderer to use
366      * @private
367      * @param {String/Function} renderer The renderer to use
368      * @return {Function} A rendering function to use.
369      */
370     getRenderer: function(renderer){
371         if (Ext.isFunction(renderer)) {
372             return renderer;
373         }
374         return this.statics().Renderer.Html;
375     },
376
377 <span id='Ext-ElementLoader-method-startAutoRefresh'>    /**
378 </span>     * Automatically refreshes the content over a specified period.
379      * @param {Number} interval The interval to refresh in ms.
380      * @param {Object} options (optional) The options to pass to the load method. See {@link #load}
381      */
382     startAutoRefresh: function(interval, options){
383         var me = this;
384         me.stopAutoRefresh();
385         me.autoRefresh = setInterval(function(){
386             me.load(options);
387         }, interval);
388     },
389
390 <span id='Ext-ElementLoader-method-stopAutoRefresh'>    /**
391 </span>     * Clears any auto refresh. See {@link #startAutoRefresh}.
392      */
393     stopAutoRefresh: function(){
394         clearInterval(this.autoRefresh);
395         delete this.autoRefresh;
396     },
397
398 <span id='Ext-ElementLoader-method-isAutoRefreshing'>    /**
399 </span>     * Checks whether the loader is automatically refreshing. See {@link #startAutoRefresh}.
400      * @return {Boolean} True if the loader is automatically refreshing
401      */
402     isAutoRefreshing: function(){
403         return Ext.isDefined(this.autoRefresh);
404     },
405
406 <span id='Ext-ElementLoader-method-destroy'>    /**
407 </span>     * Destroys the loader. Any active requests will be aborted.
408      */
409     destroy: function(){
410         var me = this;
411         me.stopAutoRefresh();
412         delete me.target;
413         me.abort();
414         me.clearListeners();
415     }
416 });
417 </pre>
418 </body>
419 </html>