src/tab/Panel.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This 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
  12 If 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  * @author Ed Spencer, Tommy Maintz, Brian Moeskau
  17  *
  18  * A basic tab container. TabPanels can be used exactly like a standard {@link Ext.panel.Panel} for
  19  * layout purposes, but also have special support for containing child Components
  20  * (`{@link Ext.container.Container#items items}`) that are managed using a
  21  * {@link Ext.layout.container.Card CardLayout layout manager}, and displayed as separate tabs.
  22  *
  23  * **Note:** By default, a tab's close tool _destroys_ the child tab Component and all its descendants.
  24  * This makes the child tab Component, and all its descendants **unusable**.  To enable re-use of a tab,
  25  * configure the TabPanel with `{@link #autoDestroy autoDestroy: false}`.
  26  *
  27  * ## TabPanel's layout
  28  *
  29  * TabPanels use a Dock layout to position the {@link Ext.tab.Bar TabBar} at the top of the widget.
  30  * Panels added to the TabPanel will have their header hidden by default because the Tab will
  31  * automatically take the Panel's configured title and icon.
  32  *
  33  * TabPanels use their {@link Ext.panel.Header header} or {@link Ext.panel.Panel#fbar footer}
  34  * element (depending on the {@link #tabPosition} configuration) to accommodate the tab selector buttons.
  35  * This means that a TabPanel will not display any configured title, and will not display any configured
  36  * header {@link Ext.panel.Panel#tools tools}.
  37  *
  38  * To display a header, embed the TabPanel in a {@link Ext.panel.Panel Panel} which uses
  39  * `{@link Ext.container.Container#layout layout: 'fit'}`.
  40  *
  41  * ## Controlling tabs
  42  *
  43  * Configuration options for the {@link Ext.tab.Tab} that represents the component can be passed in
  44  * by specifying the tabConfig option:
  45  *
  46  *     @example
  47  *     Ext.create('Ext.tab.Panel', {
  48  *         width: 400,
  49  *         height: 400,
  50  *         renderTo: document.body,
  51  *         items: [{
  52  *             title: 'Foo'
  53  *         }, {
  54  *             title: 'Bar',
  55  *             tabConfig: {
  56  *                 title: 'Custom Title',
  57  *                 tooltip: 'A button tooltip'
  58  *             }
  59  *         }]
  60  *     });
  61  *
  62  * # Examples
  63  *
  64  * Here is a basic TabPanel rendered to the body. This also shows the useful configuration {@link #activeTab},
  65  * which allows you to set the active tab on render. If you do not set an {@link #activeTab}, no tabs will be
  66  * active by default.
  67  *
  68  *     @example
  69  *     Ext.create('Ext.tab.Panel', {
  70  *         width: 300,
  71  *         height: 200,
  72  *         activeTab: 0,
  73  *         items: [
  74  *             {
  75  *                 title: 'Tab 1',
  76  *                 bodyPadding: 10,
  77  *                 html : 'A simple tab'
  78  *             },
  79  *             {
  80  *                 title: 'Tab 2',
  81  *                 html : 'Another one'
  82  *             }
  83  *         ],
  84  *         renderTo : Ext.getBody()
  85  *     });
  86  *
  87  * It is easy to control the visibility of items in the tab bar. Specify hidden: true to have the
  88  * tab button hidden initially. Items can be subsequently hidden and show by accessing the
  89  * tab property on the child item.
  90  *
  91  *     @example
  92  *     var tabs = Ext.create('Ext.tab.Panel', {
  93  *         width: 400,
  94  *         height: 400,
  95  *         renderTo: document.body,
  96  *         items: [{
  97  *             title: 'Home',
  98  *             html: 'Home',
  99  *             itemId: 'home'
 100  *         }, {
 101  *             title: 'Users',
 102  *             html: 'Users',
 103  *             itemId: 'users',
 104  *             hidden: true
 105  *         }, {
 106  *             title: 'Tickets',
 107  *             html: 'Tickets',
 108  *             itemId: 'tickets'
 109  *         }]
 110  *     });
 111  *
 112  *     setTimeout(function(){
 113  *         tabs.child('#home').tab.hide();
 114  *         var users = tabs.child('#users');
 115  *         users.tab.show();
 116  *         tabs.setActiveTab(users);
 117  *     }, 1000);
 118  *
 119  * You can remove the background of the TabBar by setting the {@link #plain} property to `true`.
 120  *
 121  *     @example
 122  *     Ext.create('Ext.tab.Panel', {
 123  *         width: 300,
 124  *         height: 200,
 125  *         activeTab: 0,
 126  *         plain: true,
 127  *         items: [
 128  *             {
 129  *                 title: 'Tab 1',
 130  *                 bodyPadding: 10,
 131  *                 html : 'A simple tab'
 132  *             },
 133  *             {
 134  *                 title: 'Tab 2',
 135  *                 html : 'Another one'
 136  *             }
 137  *         ],
 138  *         renderTo : Ext.getBody()
 139  *     });
 140  *
 141  * Another useful configuration of TabPanel is {@link #tabPosition}. This allows you to change the
 142  * position where the tabs are displayed. The available options for this are `'top'` (default) and
 143  * `'bottom'`.
 144  *
 145  *     @example
 146  *     Ext.create('Ext.tab.Panel', {
 147  *         width: 300,
 148  *         height: 200,
 149  *         activeTab: 0,
 150  *         bodyPadding: 10,
 151  *         tabPosition: 'bottom',
 152  *         items: [
 153  *             {
 154  *                 title: 'Tab 1',
 155  *                 html : 'A simple tab'
 156  *             },
 157  *             {
 158  *                 title: 'Tab 2',
 159  *                 html : 'Another one'
 160  *             }
 161  *         ],
 162  *         renderTo : Ext.getBody()
 163  *     });
 164  *
 165  * The {@link #setActiveTab} is a very useful method in TabPanel which will allow you to change the
 166  * current active tab. You can either give it an index or an instance of a tab. For example:
 167  *
 168  *     @example
 169  *     var tabs = Ext.create('Ext.tab.Panel', {
 170  *         items: [
 171  *             {
 172  *                 id   : 'my-tab',
 173  *                 title: 'Tab 1',
 174  *                 html : 'A simple tab'
 175  *             },
 176  *             {
 177  *                 title: 'Tab 2',
 178  *                 html : 'Another one'
 179  *             }
 180  *         ],
 181  *         renderTo : Ext.getBody()
 182  *     });
 183  *
 184  *     var tab = Ext.getCmp('my-tab');
 185  *
 186  *     Ext.create('Ext.button.Button', {
 187  *         renderTo: Ext.getBody(),
 188  *         text    : 'Select the first tab',
 189  *         scope   : this,
 190  *         handler : function() {
 191  *             tabs.setActiveTab(tab);
 192  *         }
 193  *     });
 194  *
 195  *     Ext.create('Ext.button.Button', {
 196  *         text    : 'Select the second tab',
 197  *         scope   : this,
 198  *         handler : function() {
 199  *             tabs.setActiveTab(1);
 200  *         },
 201  *         renderTo : Ext.getBody()
 202  *     });
 203  *
 204  * The {@link #getActiveTab} is a another useful method in TabPanel which will return the current active tab.
 205  *
 206  *     @example
 207  *     var tabs = Ext.create('Ext.tab.Panel', {
 208  *         items: [
 209  *             {
 210  *                 title: 'Tab 1',
 211  *                 html : 'A simple tab'
 212  *             },
 213  *             {
 214  *                 title: 'Tab 2',
 215  *                 html : 'Another one'
 216  *             }
 217  *         ],
 218  *         renderTo : Ext.getBody()
 219  *     });
 220  *
 221  *     Ext.create('Ext.button.Button', {
 222  *         text    : 'Get active tab',
 223  *         scope   : this,
 224  *         handler : function() {
 225  *             var tab = tabs.getActiveTab();
 226  *             alert('Current tab: ' + tab.title);
 227  *         },
 228  *         renderTo : Ext.getBody()
 229  *     });
 230  *
 231  * Adding a new tab is very simple with a TabPanel. You simple call the {@link #add} method with an config
 232  * object for a panel.
 233  *
 234  *     @example
 235  *     var tabs = Ext.create('Ext.tab.Panel', {
 236  *         items: [
 237  *             {
 238  *                 title: 'Tab 1',
 239  *                 html : 'A simple tab'
 240  *             },
 241  *             {
 242  *                 title: 'Tab 2',
 243  *                 html : 'Another one'
 244  *             }
 245  *         ],
 246  *         renderTo : Ext.getBody()
 247  *     });
 248  *
 249  *     Ext.create('Ext.button.Button', {
 250  *         text    : 'New tab',
 251  *         scope   : this,
 252  *         handler : function() {
 253  *             var tab = tabs.add({
 254  *                 // we use the tabs.items property to get the length of current items/tabs
 255  *                 title: 'Tab ' + (tabs.items.length + 1),
 256  *                 html : 'Another one'
 257  *             });
 258  *
 259  *             tabs.setActiveTab(tab);
 260  *         },
 261  *         renderTo : Ext.getBody()
 262  *     });
 263  *
 264  * Additionally, removing a tab is very also simple with a TabPanel. You simple call the {@link #remove} method
 265  * with an config object for a panel.
 266  *
 267  *     @example
 268  *     var tabs = Ext.create('Ext.tab.Panel', {
 269  *         items: [
 270  *             {
 271  *                 title: 'Tab 1',
 272  *                 html : 'A simple tab'
 273  *             },
 274  *             {
 275  *                 id   : 'remove-this-tab',
 276  *                 title: 'Tab 2',
 277  *                 html : 'Another one'
 278  *             }
 279  *         ],
 280  *         renderTo : Ext.getBody()
 281  *     });
 282  *
 283  *     Ext.create('Ext.button.Button', {
 284  *         text    : 'Remove tab',
 285  *         scope   : this,
 286  *         handler : function() {
 287  *             var tab = Ext.getCmp('remove-this-tab');
 288  *             tabs.remove(tab);
 289  *         },
 290  *         renderTo : Ext.getBody()
 291  *     });
 292  */
 293 Ext.define('Ext.tab.Panel', {
 294     extend: 'Ext.panel.Panel',
 295     alias: 'widget.tabpanel',
 296     alternateClassName: ['Ext.TabPanel'],
 297
 298     requires: ['Ext.layout.container.Card', 'Ext.tab.Bar'],
 299
 300     /**
 301      * @cfg {String} tabPosition
 302      * The position where the tab strip should be rendered. Can be `top` or `bottom`.
 303      */
 304     tabPosition : 'top',
 305
 306     /**
 307      * @cfg {String/Number} activeItem
 308      * Doesn't apply for {@link Ext.tab.Panel TabPanel}, use {@link #activeTab} instead.
 309      */
 310
 311     /**
 312      * @cfg {String/Number/Ext.Component} activeTab
 313      * The tab to activate initially. Either an ID, index or the tab component itself.
 314      */
 315
 316     /**
 317      * @cfg {Object} tabBar
 318      * Optional configuration object for the internal {@link Ext.tab.Bar}.
 319      * If present, this is passed straight through to the TabBar's constructor
 320      */
 321
 322     /**
 323      * @cfg {Object} layout
 324      * Optional configuration object for the internal {@link Ext.layout.container.Card card layout}.
 325      * If present, this is passed straight through to the layout's constructor
 326      */
 327
 328     /**
 329      * @cfg {Boolean} removePanelHeader
 330      * True to instruct each Panel added to the TabContainer to not render its header element.
 331      * This is to ensure that the title of the panel does not appear twice.
 332      */
 333     removePanelHeader: true,
 334
 335     /**
 336      * @cfg {Boolean} plain
 337      * True to not show the full background on the TabBar.
 338      */
 339     plain: false,
 340
 341     /**
 342      * @cfg {String} itemCls
 343      * The class added to each child item of this TabPanel.
 344      */
 345     itemCls: 'x-tabpanel-child',
 346
 347     /**
 348      * @cfg {Number} minTabWidth
 349      * The minimum width for a tab in the {@link #tabBar}.
 350      */
 351     minTabWidth: undefined,
 352
 353     /**
 354      * @cfg {Number} maxTabWidth The maximum width for each tab.
 355      */
 356     maxTabWidth: undefined,
 357
 358     /**
 359      * @cfg {Boolean} deferredRender
 360      *
 361      * True by default to defer the rendering of child {@link Ext.container.Container#items items} to the browsers DOM
 362      * until a tab is activated. False will render all contained {@link Ext.container.Container#items items} as soon as
 363      * the {@link Ext.layout.container.Card layout} is rendered. If there is a significant amount of content or a lot of
 364      * heavy controls being rendered into panels that are not displayed by default, setting this to true might improve
 365      * performance.
 366      *
 367      * The deferredRender property is internally passed to the layout manager for TabPanels ({@link
 368      * Ext.layout.container.Card}) as its {@link Ext.layout.container.Card#deferredRender} configuration value.
 369      *
 370      * **Note**: leaving deferredRender as true means that the content within an unactivated tab will not be available
 371      */
 372     deferredRender : true,
 373
 374     //inherit docs
 375     initComponent: function() {
 376         var me = this,
 377             dockedItems = me.dockedItems || [],
 378             activeTab = me.activeTab || 0;
 379
 380         me.layout = Ext.create('Ext.layout.container.Card', Ext.apply({
 381             owner: me,
 382             deferredRender: me.deferredRender,
 383             itemCls: me.itemCls
 384         }, me.layout));
 385
 386         /**
 387          * @property {Ext.tab.Bar} tabBar Internal reference to the docked TabBar
 388          */
 389         me.tabBar = Ext.create('Ext.tab.Bar', Ext.apply({}, me.tabBar, {
 390             dock: me.tabPosition,
 391             plain: me.plain,
 392             border: me.border,
 393             cardLayout: me.layout,
 394             tabPanel: me
 395         }));
 396
 397         if (dockedItems && !Ext.isArray(dockedItems)) {
 398             dockedItems = [dockedItems];
 399         }
 400
 401         dockedItems.push(me.tabBar);
 402         me.dockedItems = dockedItems;
 403
 404         me.addEvents(
 405             /**
 406              * @event
 407              * Fires before a tab change (activated by {@link #setActiveTab}). Return false in any listener to cancel
 408              * the tabchange
 409              * @param {Ext.tab.Panel} tabPanel The TabPanel
 410              * @param {Ext.Component} newCard The card that is about to be activated
 411              * @param {Ext.Component} oldCard The card that is currently active
 412              */
 413             'beforetabchange',
 414
 415             /**
 416              * @event
 417              * Fires when a new tab has been activated (activated by {@link #setActiveTab}).
 418              * @param {Ext.tab.Panel} tabPanel The TabPanel
 419              * @param {Ext.Component} newCard The newly activated item
 420              * @param {Ext.Component} oldCard The previously active item
 421              */
 422             'tabchange'
 423         );
 424         me.callParent(arguments);
 425
 426         //set the active tab
 427         me.setActiveTab(activeTab);
 428         //set the active tab after initial layout
 429         me.on('afterlayout', me.afterInitialLayout, me, {single: true});
 430     },
 431
 432     /**
 433      * @private
 434      * We have to wait until after the initial layout to visually activate the activeTab (if set).
 435      * The active tab has different margins than normal tabs, so if the initial layout happens with
 436      * a tab active, its layout will be offset improperly due to the active margin style. Waiting
 437      * until after the initial layout avoids this issue.
 438      */
 439     afterInitialLayout: function() {
 440         var me = this,
 441             card = me.getComponent(me.activeTab);
 442
 443         if (card) {
 444             me.layout.setActiveItem(card);
 445         }
 446     },
 447
 448     /**
 449      * Makes the given card active. Makes it the visible card in the TabPanel's CardLayout and highlights the Tab.
 450      * @param {String/Number/Ext.Component} card The card to make active. Either an ID, index or the component itself.
 451      */
 452     setActiveTab: function(card) {
 453         var me = this,
 454             previous;
 455
 456         card = me.getComponent(card);
 457         if (card) {
 458             previous = me.getActiveTab();
 459
 460             if (previous && previous !== card && me.fireEvent('beforetabchange', me, card, previous) === false) {
 461                 return false;
 462             }
 463
 464             me.tabBar.setActiveTab(card.tab);
 465             me.activeTab = card;
 466             if (me.rendered) {
 467                 me.layout.setActiveItem(card);
 468             }
 469
 470             if (previous && previous !== card) {
 471                 me.fireEvent('tabchange', me, card, previous);
 472             }
 473         }
 474     },
 475
 476     /**
 477      * Returns the item that is currently active inside this TabPanel. Note that before the TabPanel first activates a
 478      * child component this will return whatever was configured in the {@link #activeTab} config option
 479      * @return {String/Number/Ext.Component} The currently active item
 480      */
 481     getActiveTab: function() {
 482         return this.activeTab;
 483     },
 484
 485     /**
 486      * Returns the {@link Ext.tab.Bar} currently used in this TabPanel
 487      * @return {Ext.tab.Bar} The TabBar
 488      */
 489     getTabBar: function() {
 490         return this.tabBar;
 491     },
 492
 493     /**
 494      * @ignore
 495      * Makes sure we have a Tab for each item added to the TabPanel
 496      */
 497     onAdd: function(item, index) {
 498         var me = this,
 499             cfg = item.tabConfig || {},
 500             defaultConfig = {
 501                 xtype: 'tab',
 502                 card: item,
 503                 disabled: item.disabled,
 504                 closable: item.closable,
 505                 hidden: item.hidden,
 506                 tabBar: me.tabBar
 507             };
 508
 509         if (item.closeText) {
 510             defaultConfig.closeText = item.closeText;
 511         }
 512         cfg = Ext.applyIf(cfg, defaultConfig);
 513         item.tab = me.tabBar.insert(index, cfg);
 514
 515         item.on({
 516             scope : me,
 517             enable: me.onItemEnable,
 518             disable: me.onItemDisable,
 519             beforeshow: me.onItemBeforeShow,
 520             iconchange: me.onItemIconChange,
 521             titlechange: me.onItemTitleChange
 522         });
 523
 524         if (item.isPanel) {
 525             if (me.removePanelHeader) {
 526                 item.preventHeader = true;
 527                 if (item.rendered) {
 528                     item.updateHeader();
 529                 }
 530             }
 531             if (item.isPanel && me.border) {
 532                 item.setBorder(false);
 533             }
 534         }
 535
 536         // ensure that there is at least one active tab
 537         if (this.rendered && me.items.getCount() === 1) {
 538             me.setActiveTab(0);
 539         }
 540     },
 541
 542     /**
 543      * @private
 544      * Enable corresponding tab when item is enabled.
 545      */
 546     onItemEnable: function(item){
 547         item.tab.enable();
 548     },
 549
 550     /**
 551      * @private
 552      * Disable corresponding tab when item is enabled.
 553      */
 554     onItemDisable: function(item){
 555         item.tab.disable();
 556     },
 557
 558     /**
 559      * @private
 560      * Sets activeTab before item is shown.
 561      */
 562     onItemBeforeShow: function(item) {
 563         if (item !== this.activeTab) {
 564             this.setActiveTab(item);
 565             return false;
 566         }
 567     },
 568
 569     /**
 570      * @private
 571      * Update the tab iconCls when panel iconCls has been set or changed.
 572      */
 573     onItemIconChange: function(item, newIconCls) {
 574         item.tab.setIconCls(newIconCls);
 575         this.getTabBar().doLayout();
 576     },
 577
 578     /**
 579      * @private
 580      * Update the tab title when panel title has been set or changed.
 581      */
 582     onItemTitleChange: function(item, newTitle) {
 583         item.tab.setText(newTitle);
 584         this.getTabBar().doLayout();
 585     },
 586
 587
 588     /**
 589      * @ignore
 590      * If we're removing the currently active tab, activate the nearest one. The item is removed when we call super,
 591      * so we can do preprocessing before then to find the card's index
 592      */
 593     doRemove: function(item, autoDestroy) {
 594         var me = this,
 595             items = me.items,
 596             // At this point the item hasn't been removed from the items collection.
 597             // As such, if we want to check if there are no more tabs left, we have to
 598             // check for one, as opposed to 0.
 599             hasItemsLeft = items.getCount() > 1;
 600
 601         if (me.destroying || !hasItemsLeft) {
 602             me.activeTab = null;
 603         } else if (item === me.activeTab) {
 604              me.setActiveTab(item.next() || items.getAt(0));
 605         }
 606         me.callParent(arguments);
 607
 608         // Remove the two references
 609         delete item.tab.card;
 610         delete item.tab;
 611     },
 612
 613     /**
 614      * @ignore
 615      * Makes sure we remove the corresponding Tab when an item is removed
 616      */
 617     onRemove: function(item, autoDestroy) {
 618         var me = this;
 619
 620         item.un({
 621             scope : me,
 622             enable: me.onItemEnable,
 623             disable: me.onItemDisable,
 624             beforeshow: me.onItemBeforeShow
 625         });
 626         if (!me.destroying && item.tab.ownerCt == me.tabBar) {
 627             me.tabBar.remove(item.tab);
 628         }
 629     }
 630 });
 631