/ext-4.0.7/src/ElementLoader.js

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