Menu

dijit.layout.TabContainer

Authors:Becky Gibson, Peter Higgins, Bill Keese, Nikolai Onken, Marcus Reimann
Developers:?-
Available:since V?
jsDoc:http://api.dojotoolkit.org/jsdoc/HEAD/dijit.layout.TabContainer

A TabContainer is a container that has multiple panes, but shows only one pane at a time. There are a set of tabs corresponding to each pane, where each tab has the title (aka label) of the pane, and optionally a close button.

Usage

You can use tabs in your own application and style them as you want, but they also fit perfectly into the dijit.layout system.

Examples

Programmatic example

First, we’ll demonstrate a programatic TabContainer creation. Note that the tabs all have a fixed height.

<script type="text/javascript">
dojo.require("dijit.layout.TabContainer");
dojo.require("dijit.layout.ContentPane");
dojo.addOnLoad(function(){
    var tc = new dijit.layout.TabContainer({
        style: "height: 100%; width: 100%;"
    },"tc1-prog");

    var cp1 = new dijit.layout.ContentPane({
         title: "Food",
         content: "We offer amazing food"
    });
    tc.addChild(cp1);

    var cp2 = new dijit.layout.ContentPane({
         title: "Drinks",
         content: "We are known for our drinks."
    });
    tc.addChild(cp2);

    tc.startup();
});
</script>

The html is very simple

<div style="width: 350px; height: 290px">
    <div id="tc1-prog"></div>
</div>

Declarative example

Here are some markup examples:

This is a plain TabContainer with three tabs and fixed height. The third tab is closable

<script type="text/javascript">
dojo.require("dijit.layout.TabContainer");
dojo.require("dijit.layout.ContentPane");
</script>

The html is very simple

<div style="width: 350px; height: 300px">
    <div dojoType="dijit.layout.TabContainer" style="width: 100%; height: 100%;">
        <div dojoType="dijit.layout.ContentPane" title="My first tab" selected="true">
            Lorem ipsum and all around...
        </div>
        <div dojoType="dijit.layout.ContentPane" title="My second tab">
            Lorem ipsum and all around - second...
        </div>
        <div dojoType="dijit.layout.ContentPane" title="My last tab" closable="true">
            Lorem ipsum and all around - last...
        </div>
    </div>
</div>

A TabContainer with flexible height

This is a plain TabContainer with three tabs and flexible height using the doLayout=”false” attribute. The second tab is closable.

<script type="text/javascript">
dojo.require("dijit.layout.TabContainer");
dojo.require("dijit.layout.ContentPane");
</script>

The html is very simple

<!-- this div is only for documentation purpose, in real development environments, just take it out -->
<div style="height: 105px;">

  <div dojoType="dijit.layout.TabContainer" style="width: 100%;" doLayout="false">
    <div dojoType="dijit.layout.ContentPane" title="My first tab" selected="true">
      Lorem ipsum and all around...
    </div>
    <div dojoType="dijit.layout.ContentPane" title="My second tab" closable="true">
      Lorem ipsum and all around - second...
      <br />
      Hmmm expanding tabs......
    </div>
    <div dojoType="dijit.layout.ContentPane" title="My last tab">
      Lorem ipsum and all around - last...
      <br />
      <br />
      <br />
      Hmmm even more expanding tabs......
    </div>
  </div>

<!-- end of the div -->
</div>

Selecting another Tab

Normally, TabContainer will show the first Tab. But it’s also possible to automatically open another Tab with giving one of the ContentPanes the argument selected: true (if programmatically created) or the attribute selected=”true” (if declaratively created).

<script type="text/javascript">
dojo.require("dijit.layout.TabContainer");
dojo.require("dijit.layout.ContentPane");
dojo.addOnLoad(function(){
    var tc = new dijit.layout.TabContainer({
        style: "height: 100%; width: 100%;"
    },"tc1-prog");

    var cp1 = new dijit.layout.ContentPane({
         title: "First Tab",
         content: "We offer amazing food"
    });
    tc.addChild(cp1);

    var cp2 = new dijit.layout.ContentPane({
         title: "Second Tab",
         content: "We are known for our drinks."
    });
    tc.addChild(cp2);

    var cp3 = new dijit.layout.ContentPane({
         title: "Third Tab",
         content: "This Tab has the attribute 'selected: true' set.",
         selected: true
    });
    tc.addChild(cp3);


    tc.startup();
});
</script>

The html is very simple

<div style="width: 350px; height: 300px">
    <div id="tc1-prog"></div>
</div>

More examples

There are several more examples of basic use cases available

Like dijit.layout.StackContainer, TabContainer works by using a simple .addChild, .removeChild, and .selectChild API, all accepting a widget to be acted upon.

Manipulating Children

1
2
3
var tabs = dijit.byId("myTabContainer");
var pane = new dijit.layout.ContentPane({ title:"Remote Content", href:"remote.html" });
tabs.addChild(pane);

A Tab doesn't get displayed unless you call .selectChild

1
2
3
4
var tabs = dijit.byId("myTabContainer");
var pane = new dijit.layout.ContentPane({ title:"Remote Content", href:"remote.html" });
tabs.addChild(pane);
tabs.selectChild(pane);

the addChild method accepts a position index, telling where in the order to add the new pane:

1
2
3
var tabs = dijit.byId("myTabContainer");
var pane = new dijit.layout.ContentPane({ title:"Remote Content", href:"remote.html" });
tabs.addChild(pane,1);

This will add the new remote pane after the first pane (0).

Closing A Tab

A common action for closable tabs is to register an onClose function on the child, returning true or false to indicate whether or not the closing should take place:

<script type="text/javascript">
dojo.require("dijit.layout.TabContainer");
dojo.require("dijit.layout.ContentPane");
dojo.addOnLoad(function(){
    var tabs = dijit.byId("onClose-ex");
    var closablePane = new dijit.layout.ContentPane({
        title:"Close Me",
        closable: true,
        onClose: function(){
           // confirm() returns true or false, so return that.
           return confirm("Do you really want to Close this?");
        }
    });
    tabs.addChild(closablePane);
});
</script>

You can, of course, attach the onClose function directly on a pane as well:

<div style="height: 100px;">

  <div id="onClose-ex" dojoType="dijit.layout.TabContainer" style="width: 100%;" doLayout="false">
    <div dojoType="dijit.layout.ContentPane" title="My first tab" selected="true">
      Lorem ipsum and all around...
    </div>
    <div dojoType="dijit.layout.ContentPane" title="Other Closable" closable="true" onClose="return confirm('really?');">
        ... I have an in-line onClose
    </div>
  </div>

</div>

TabContainer Events

There are two methods of observing TabContainer shenanigans. The first, by using dojo.subscribe. Each TabContainer publishes notices based on the id of the Container. Several different actions are tracked this way:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// assuming our tabContainer has id="bar"
dojo.subscribe("bar-selectChild", function(child){
    console.log("A new child was selected:", child);
});

dojo.subscribe("bar-addChild", function(child){
    console.log("A child was added:", child);
});

dojo.subscribe("bar-removeChild", function(child){
    console.log("Child is gone: ", child); // but not destroyed!
});

the -selectChild subscription will not execute if the selected child is already the visible Pane. It will only publish when a different child is selected. Notice how this differs from our other method of wiring up TabContainer events, via dojo.connect:

1
2
3
4
5
6
7
8
9
// assuming the same id="bar" TabContainer
var tabs = dijit.byId("bar");

dojo.connect(tabs,"selectChild",function(child){
    console.log("called anytime selectChild is");
});
dojo.connect(tabs,"addChild",function(child){
    console.log("just added: ", child);
});

This simply uses dojo.connect to listen to the native function calls.

A common request for selectChild functionality is to know both the new and old widgets being transitioned. The easiest way to accomplish this is connect to the "private" :ref:transition method of a TabContainer:

1
2
3
4
5
var tabs = dijit.byId("tabs");
dojo.connect(tabs,"_transition", function(newPage, oldPage){
    console.log("I was showing: ", oldPage || "nothing");
    console.log("I am now showing: ", newPage);
});

It is worth noting: If you need a function to be called absolutely every time a child is added to a TabContainer (or StackContainer), you need to listen to the :ref:setupChild function to ensure you are notified of the children already existing in markup. This is only relevant if you are subclassing for reason:

1
2
3
4
5
6
dojo.declare("my.TabContainer", dijit.layout.TabContainer, {
    _setupChild: function(child){
         this.inherited(arguments);
         console.log("I've seen: ", child);
    }
});

This is because addChild will not be called for existing panes (in markup).

Accessibility

Keyboard

Action Key
Navigate to next tab button Right arrow
Navigate to previous tab button Left arrow
Navigate to first tab button Home
Navigate to last tab button End
Navigate into page Tab
Navigate to next page Ctrl + page down, ctrl + tab (FF and IE6 only)
Navigate to previous page Ctrl + page up, ctrl + shift + tab (FF and IE6 only)
Delete a tab With focus on the tab title of the tab to delete, press Delete or ctrl + w. Note that the tab must have been created with deletion enabled via the closable attribute. For 1.1 and later releases, pressing shift-F10 with focus on the tab title or right mouse clicking on the tab title will bring up a context menu with the option to Close the tab. This provides a mechanism to determine if the tab is closable.
Error in the documentation? Can’t find what you are looking for? Let us know!