examples/ux/statusbar/StatusBar.js

   1 /**
   2  * @class Ext.ux.StatusBar
   3  * <p>Basic status bar component that can be used as the bottom toolbar of any {@link Ext.Panel}.  In addition to
   4  * supporting the standard {@link Ext.toolbar.Toolbar} interface for adding buttons, menus and other items, the StatusBar
   5  * provides a greedy status element that can be aligned to either side and has convenient methods for setting the
   6  * status text and icon.  You can also indicate that something is processing using the {@link #showBusy} method.</p>
   7  * <pre><code>
   8 Ext.create('Ext.Panel', {
   9     title: 'StatusBar',
  10     // etc.
  11     bbar: Ext.create('Ext.ux.StatusBar', {
  12         id: 'my-status',
  13
  14         // defaults to use when the status is cleared:
  15         defaultText: 'Default status text',
  16         defaultIconCls: 'default-icon',
  17
  18         // values to set initially:
  19         text: 'Ready',
  20         iconCls: 'ready-icon',
  21
  22         // any standard Toolbar items:
  23         items: [{
  24             text: 'A Button'
  25         }, '-', 'Plain Text']
  26     })
  27 });
  28
  29 // Update the status bar later in code:
  30 var sb = Ext.getCmp('my-status');
  31 sb.setStatus({
  32     text: 'OK',
  33     iconCls: 'ok-icon',
  34     clear: true // auto-clear after a set interval
  35 });
  36
  37 // Set the status bar to show that something is processing:
  38 sb.showBusy();
  39
  40 // processing....
  41
  42 sb.clearStatus(); // once completeed
  43 </code></pre>
  44  * @extends Ext.toolbar.Toolbar
  45  * @constructor
  46  * Creates a new StatusBar
  47  * @param {Object/Array} config A config object
  48  */
  49 Ext.define('Ext.ux.statusbar.StatusBar', {
  50     extend: 'Ext.toolbar.Toolbar',
  51     alternateClassName: 'Ext.ux.StatusBar',
  52     alias: 'widget.statusbar',
  53     requires: ['Ext.toolbar.TextItem'],
  54     /**
  55      * @cfg {String} statusAlign
  56      * The alignment of the status element within the overall StatusBar layout.  When the StatusBar is rendered,
  57      * it creates an internal div containing the status text and icon.  Any additional Toolbar items added in the
  58      * StatusBar's {@link #items} config, or added via {@link #add} or any of the supported add* methods, will be
  59      * rendered, in added order, to the opposite side.  The status element is greedy, so it will automatically
  60      * expand to take up all sapce left over by any other items.  Example usage:
  61      * <pre><code>
  62 // Create a left-aligned status bar containing a button,
  63 // separator and text item that will be right-aligned (default):
  64 Ext.create('Ext.Panel', {
  65     title: 'StatusBar',
  66     // etc.
  67     bbar: Ext.create('Ext.ux.StatusBar', {
  68         defaultText: 'Default status text',
  69         id: 'status-id',
  70         items: [{
  71             text: 'A Button'
  72         }, '-', 'Plain Text']
  73     })
  74 });
  75
  76 // By adding the statusAlign config, this will create the
  77 // exact same toolbar, except the status and toolbar item
  78 // layout will be reversed from the previous example:
  79 Ext.create('Ext.Panel', {
  80     title: 'StatusBar',
  81     // etc.
  82     bbar: Ext.create('Ext.ux.StatusBar', {
  83         defaultText: 'Default status text',
  84         id: 'status-id',
  85         statusAlign: 'right',
  86         items: [{
  87             text: 'A Button'
  88         }, '-', 'Plain Text']
  89     })
  90 });
  91 </code></pre>
  92      */
  93     /**
  94      * @cfg {String} defaultText
  95      * The default {@link #text} value.  This will be used anytime the status bar is cleared with the
  96      * <tt>useDefaults:true</tt> option (defaults to '').
  97      */
  98     /**
  99      * @cfg {String} defaultIconCls
 100      * The default {@link #iconCls} value (see the iconCls docs for additional details about customizing the icon).
 101      * This will be used anytime the status bar is cleared with the <tt>useDefaults:true</tt> option (defaults to '').
 102      */
 103     /**
 104      * @cfg {String} text
 105      * A string that will be <b>initially</b> set as the status message.  This string
 106      * will be set as innerHTML (html tags are accepted) for the toolbar item.
 107      * If not specified, the value set for <code>{@link #defaultText}</code>
 108      * will be used.
 109      */
 110     /**
 111      * @cfg {String} iconCls
 112      * A CSS class that will be <b>initially</b> set as the status bar icon and is
 113      * expected to provide a background image (defaults to '').
 114      * Example usage:<pre><code>
 115 // Example CSS rule:
 116 .x-statusbar .x-status-custom {
 117     padding-left: 25px;
 118     background: transparent url(images/custom-icon.gif) no-repeat 3px 2px;
 119 }
 120
 121 // Setting a default icon:
 122 var sb = Ext.create('Ext.ux.StatusBar', {
 123     defaultIconCls: 'x-status-custom'
 124 });
 125
 126 // Changing the icon:
 127 sb.setStatus({
 128     text: 'New status',
 129     iconCls: 'x-status-custom'
 130 });
 131 </code></pre>
 132      */
 133
 134     /**
 135      * @cfg {String} cls
 136      * The base class applied to the containing element for this component on render (defaults to 'x-statusbar')
 137      */
 138     cls : 'x-statusbar',
 139     /**
 140      * @cfg {String} busyIconCls
 141      * The default <code>{@link #iconCls}</code> applied when calling
 142      * <code>{@link #showBusy}</code> (defaults to <tt>'x-status-busy'</tt>).
 143      * It can be overridden at any time by passing the <code>iconCls</code>
 144      * argument into <code>{@link #showBusy}</code>.
 145      */
 146     busyIconCls : 'x-status-busy',
 147     /**
 148      * @cfg {String} busyText
 149      * The default <code>{@link #text}</code> applied when calling
 150      * <code>{@link #showBusy}</code> (defaults to <tt>'Loading...'</tt>).
 151      * It can be overridden at any time by passing the <code>text</code>
 152      * argument into <code>{@link #showBusy}</code>.
 153      */
 154     busyText : 'Loading...',
 155     /**
 156      * @cfg {Number} autoClear
 157      * The number of milliseconds to wait after setting the status via
 158      * <code>{@link #setStatus}</code> before automatically clearing the status
 159      * text and icon (defaults to <tt>5000</tt>).  Note that this only applies
 160      * when passing the <tt>clear</tt> argument to <code>{@link #setStatus}</code>
 161      * since that is the only way to defer clearing the status.  This can
 162      * be overridden by specifying a different <tt>wait</tt> value in
 163      * <code>{@link #setStatus}</code>. Calls to <code>{@link #clearStatus}</code>
 164      * always clear the status bar immediately and ignore this value.
 165      */
 166     autoClear : 5000,
 167
 168     /**
 169      * @cfg {String} emptyText
 170      * The text string to use if no text has been set.  Defaults to
 171      * <tt>'&nbsp;'</tt>).  If there are no other items in the toolbar using
 172      * an empty string (<tt>''</tt>) for this value would end up in the toolbar
 173      * height collapsing since the empty string will not maintain the toolbar
 174      * height.  Use <tt>''</tt> if the toolbar should collapse in height
 175      * vertically when no text is specified and there are no other items in
 176      * the toolbar.
 177      */
 178     emptyText : '&nbsp;',
 179
 180     // private
 181     activeThreadId : 0,
 182
 183     // private
 184     initComponent : function(){
 185         if (this.statusAlign === 'right') {
 186             this.cls += ' x-status-right';
 187         }
 188         this.callParent(arguments);
 189     },
 190
 191     // private
 192     afterRender : function(){
 193         this.callParent(arguments);
 194
 195         var right = this.statusAlign === 'right';
 196         this.currIconCls = this.iconCls || this.defaultIconCls;
 197         this.statusEl = Ext.create('Ext.toolbar.TextItem', {
 198             cls: 'x-status-text ' + (this.currIconCls || ''),
 199             text: this.text || this.defaultText || ''
 200         });
 201
 202         if (right) {
 203             this.add('->');
 204             this.add(this.statusEl);
 205         } else {
 206             this.insert(0, this.statusEl);
 207             this.insert(1, '->');
 208         }
 209         this.height = 27;
 210         this.doLayout();
 211     },
 212
 213     /**
 214      * Sets the status {@link #text} and/or {@link #iconCls}. Also supports automatically clearing the
 215      * status that was set after a specified interval.
 216      * @param {Object/String} config A config object specifying what status to set, or a string assumed
 217      * to be the status text (and all other options are defaulted as explained below). A config
 218      * object containing any or all of the following properties can be passed:<ul>
 219      * <li><tt>text</tt> {String} : (optional) The status text to display.  If not specified, any current
 220      * status text will remain unchanged.</li>
 221      * <li><tt>iconCls</tt> {String} : (optional) The CSS class used to customize the status icon (see
 222      * {@link #iconCls} for details). If not specified, any current iconCls will remain unchanged.</li>
 223      * <li><tt>clear</tt> {Boolean/Number/Object} : (optional) Allows you to set an internal callback that will
 224      * automatically clear the status text and iconCls after a specified amount of time has passed. If clear is not
 225      * specified, the new status will not be auto-cleared and will stay until updated again or cleared using
 226      * {@link #clearStatus}. If <tt>true</tt> is passed, the status will be cleared using {@link #autoClear},
 227      * {@link #defaultText} and {@link #defaultIconCls} via a fade out animation. If a numeric value is passed,
 228      * it will be used as the callback interval (in milliseconds), overriding the {@link #autoClear} value.
 229      * All other options will be defaulted as with the boolean option.  To customize any other options,
 230      * you can pass an object in the format:<ul>
 231      *    <li><tt>wait</tt> {Number} : (optional) The number of milliseconds to wait before clearing
 232      *    (defaults to {@link #autoClear}).</li>
 233      *    <li><tt>anim</tt> {Number} : (optional) False to clear the status immediately once the callback
 234      *    executes (defaults to true which fades the status out).</li>
 235      *    <li><tt>useDefaults</tt> {Number} : (optional) False to completely clear the status text and iconCls
 236      *    (defaults to true which uses {@link #defaultText} and {@link #defaultIconCls}).</li>
 237      * </ul></li></ul>
 238      * Example usage:<pre><code>
 239 // Simple call to update the text
 240 statusBar.setStatus('New status');
 241
 242 // Set the status and icon, auto-clearing with default options:
 243 statusBar.setStatus({
 244     text: 'New status',
 245     iconCls: 'x-status-custom',
 246     clear: true
 247 });
 248
 249 // Auto-clear with custom options:
 250 statusBar.setStatus({
 251     text: 'New status',
 252     iconCls: 'x-status-custom',
 253     clear: {
 254         wait: 8000,
 255         anim: false,
 256         useDefaults: false
 257     }
 258 });
 259 </code></pre>
 260      * @return {Ext.ux.StatusBar} this
 261      */
 262     setStatus : function(o) {
 263         o = o || {};
 264
 265         if (Ext.isString(o)) {
 266             o = {text:o};
 267         }
 268         if (o.text !== undefined) {
 269             this.setText(o.text);
 270         }
 271         if (o.iconCls !== undefined) {
 272             this.setIcon(o.iconCls);
 273         }
 274
 275         if (o.clear) {
 276             var c = o.clear,
 277                 wait = this.autoClear,
 278                 defaults = {useDefaults: true, anim: true};
 279
 280             if (Ext.isObject(c)) {
 281                 c = Ext.applyIf(c, defaults);
 282                 if (c.wait) {
 283                     wait = c.wait;
 284                 }
 285             } else if (Ext.isNumber(c)) {
 286                 wait = c;
 287                 c = defaults;
 288             } else if (Ext.isBoolean(c)) {
 289                 c = defaults;
 290             }
 291
 292             c.threadId = this.activeThreadId;
 293             Ext.defer(this.clearStatus, wait, this, [c]);
 294         }
 295         this.doLayout();
 296         return this;
 297     },
 298
 299     /**
 300      * Clears the status {@link #text} and {@link #iconCls}. Also supports clearing via an optional fade out animation.
 301      * @param {Object} config (optional) A config object containing any or all of the following properties.  If this
 302      * object is not specified the status will be cleared using the defaults below:<ul>
 303      * <li><tt>anim</tt> {Boolean} : (optional) True to clear the status by fading out the status element (defaults
 304      * to false which clears immediately).</li>
 305      * <li><tt>useDefaults</tt> {Boolean} : (optional) True to reset the text and icon using {@link #defaultText} and
 306      * {@link #defaultIconCls} (defaults to false which sets the text to '' and removes any existing icon class).</li>
 307      * </ul>
 308      * @return {Ext.ux.StatusBar} this
 309      */
 310     clearStatus : function(o) {
 311         o = o || {};
 312
 313         if (o.threadId && o.threadId !== this.activeThreadId) {
 314             // this means the current call was made internally, but a newer
 315             // thread has set a message since this call was deferred.  Since
 316             // we don't want to overwrite a newer message just ignore.
 317             return this;
 318         }
 319
 320         var text = o.useDefaults ? this.defaultText : this.emptyText,
 321             iconCls = o.useDefaults ? (this.defaultIconCls ? this.defaultIconCls : '') : '';
 322
 323         if (o.anim) {
 324             // animate the statusEl Ext.core.Element
 325             this.statusEl.el.puff({
 326                 remove: false,
 327                 useDisplay: true,
 328                 scope: this,
 329                 callback: function(){
 330                     this.setStatus({
 331                      text: text,
 332                      iconCls: iconCls
 333                  });
 334
 335                     this.statusEl.el.show();
 336                 }
 337             });
 338         } else {
 339             // hide/show the el to avoid jumpy text or icon
 340              this.statusEl.hide();
 341              this.setStatus({
 342                  text: text,
 343                  iconCls: iconCls
 344              });
 345              this.statusEl.show();
 346         }
 347         this.doLayout();
 348         return this;
 349     },
 350
 351     /**
 352      * Convenience method for setting the status text directly.  For more flexible options see {@link #setStatus}.
 353      * @param {String} text (optional) The text to set (defaults to '')
 354      * @return {Ext.ux.StatusBar} this
 355      */
 356     setText : function(text){
 357         this.activeThreadId++;
 358         this.text = text || '';
 359         if (this.rendered) {
 360             this.statusEl.setText(this.text);
 361         }
 362         return this;
 363     },
 364
 365     /**
 366      * Returns the current status text.
 367      * @return {String} The status text
 368      */
 369     getText : function(){
 370         return this.text;
 371     },
 372
 373     /**
 374      * Convenience method for setting the status icon directly.  For more flexible options see {@link #setStatus}.
 375      * See {@link #iconCls} for complete details about customizing the icon.
 376      * @param {String} iconCls (optional) The icon class to set (defaults to '', and any current icon class is removed)
 377      * @return {Ext.ux.StatusBar} this
 378      */
 379     setIcon : function(cls){
 380         this.activeThreadId++;
 381         cls = cls || '';
 382
 383         if (this.rendered) {
 384          if (this.currIconCls) {
 385              this.statusEl.removeCls(this.currIconCls);
 386              this.currIconCls = null;
 387          }
 388          if (cls.length > 0) {
 389              this.statusEl.addCls(cls);
 390              this.currIconCls = cls;
 391          }
 392         } else {
 393             this.currIconCls = cls;
 394         }
 395         return this;
 396     },
 397
 398     /**
 399      * Convenience method for setting the status text and icon to special values that are pre-configured to indicate
 400      * a "busy" state, usually for loading or processing activities.
 401      * @param {Object/String} config (optional) A config object in the same format supported by {@link #setStatus}, or a
 402      * string to use as the status text (in which case all other options for setStatus will be defaulted).  Use the
 403      * <tt>text</tt> and/or <tt>iconCls</tt> properties on the config to override the default {@link #busyText}
 404      * and {@link #busyIconCls} settings. If the config argument is not specified, {@link #busyText} and
 405      * {@link #busyIconCls} will be used in conjunction with all of the default options for {@link #setStatus}.
 406      * @return {Ext.ux.StatusBar} this
 407      */
 408     showBusy : function(o){
 409         if (Ext.isString(o)) {
 410             o = { text: o };
 411         }
 412         o = Ext.applyIf(o || {}, {
 413             text: this.busyText,
 414             iconCls: this.busyIconCls
 415         });
 416         return this.setStatus(o);
 417     }
 418 });