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