docs/source/ElementLoader.html

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