TabbedPane

The TabbedPane component is a container that consists of several sub-containers called pages and allows the user to switch between these pages using a set of tabs. It provides flexibility in configuring the tabs and the page content within them and offers several ways for content loading. A variety of style options lets you customize the appearance of the entire TabbedPane component and its individual elements.


API Reference | Tag Reference
Online Demo

Key Features

Specifying Tabs Content

To add the TabbedPane component to a page, use the <o:tabbedPane> tag. There are two ways to define the tabs and the page contents within them:

  • To create a fixed set of tabbed pages right on a JSF page, declare a set of <o:subPanel> tags, where each <o:subPanel> represents one tab and an appropriate content. The content displayed in the tab itself can be specified with the caption attribute of the <o:subPanel> tag to specify a text tab content, or the "caption" facet if you need to specify tab content that is more complex than just text. The components that define the page content should be specified as children of the <o:subPanel> tag.

The following example shows a simple two-page TabbedPane component:

<o:tabbedPane>
  <o:subPanel caption="First tab">
    <h:outputText value="Some text on the first tab" />
  </o:subPanel>
  <o:subPanel caption="Second tab">
    <h:outputText value="Some text on the second tab"/>
  </o:subPanel>
</o:tabbedPane>
  • To specify the list of pages that needs to be calculated at run time according to application logic, use a child <o:subPanels> tag. The the value attribute of this tag must be a value binding expression that references a collection of org.openfaces.component.panel.SubPanel objects.

Here's an example of how you can do it:

<o:tabbedPane>
  <o:subPanels
          value="#{TabbedPaneBean.subPanels}"/>
</o:tabbedPane>

You can combine these two approaches by placing the <o:subPanel> and <o:subPanels> tags in any order you need.

By using the selectedIndex integer attribute of the <o:tabbedPane> tag, you can set a currently selected tab. By default, it is "0", which means that the first tab will be selected on page load. The selectedIndex attribute can be specified as a constant or a value-binding expression.

In the example below, the third tab of the TabbedPane is selected when the page is loaded.

<o:tabbedPane selectedIndex="2">
  <o:subPanels
          value="#{TabbedPaneBean.subPanels}"/>
</o:tabbedPane>

Note that TabbbedPane tabs are indexed regardless of the rendered attribute. It means that the selectedIndex attribute refers to all of the tabs specified in the TabbedPane component, but not just visible tabs.

Loading Modes

The way the data in the TabbedPane component is loaded depends on the loadingMode attribute, which can take one of the following values:

  • "client" - The content of all tabs is loaded to the client side on the first page load. So when the user changes a tab, the corresponding page is not reloaded.
  • "ajaxLazy" (default) - The tab content is retrieved from the server with Ajax request on the first switch to the tab. Once requested, the content is stored on the client.
  • "ajaxAlways" - The tab content is retrieved from the server with Ajax request on each tab switch.
  • "server" - Every time a tab is switched, a corresponding tabbed page is reloaded with the appropriate tab content.

The example below uses the "client" loading mode.

<o:tabbedPane loadingMode="client">
  <o:subPanels
          value="#{TabbedPaneBean.subPanels}"/>
</o:tabbedPane>

Customizing the Appearance

By default, the tabs appear at the top of the TabbedPane, but they can be displayed on any of the four sides of the component. To specify the placement of tabs, set the tabPlacement attribute to one of the following values: "top" (default), "left", "bottom" or "right". Also, by setting the tabAlignment attribute to "topOrLeft" (default) or "bottomOrRight", you specify along which edge the tabs will be aligned. For example, you can place the tabs on the left side of the TabbedPane and align them along the bottom of the component.

The interval between the tabs is defined in pixels by the tabGapWidth attribute. By default, it is set to "2". The size of the tabs depends on what is displayed in them. By default, the TabbedPane component is adjusted to accommodate the content of a currently selected page.

The following example shows a fixed-sized TabbedPane with the tabs located on the left and aligned to the bottom of the component, and spaced at 5 pixels apart.

<o:tabbedPane tabGapWidth="5"
              tabPlacement="left"
              tabAlignment="bottomOrRight">
  <o:subPanels value="#{TabbedPaneBean.subPanels}"/>
</o:tabbedPane>

Customizing Styles

With the TabbedPane component, you can define styles for the entire component as well as it individual parts in the normal and rollover states. The style-related attributes are given in the table below.

Attributes Description
style and styleClass A style applied to the entire TabbedPane component.
rolloverStyle and rolloverClass A style applied to the TabbedPane component in the rollover state.
tabStyle and tabClass A style applied to each individual tab.
rolloverTabStyle and rolloverTabClass A style applied to each individual tab in the rollover state.
selectedTabStyle and selectedTabClass A style for a selected tab.
rolloverSelectedTabStyle and rolloverSelectedTabClass A style for a selected tab in the rollover state.
tabEmptySpaceStyle and tabEmptySpaceClass A style applied to the spaces before, after, and between the tabs.
containerStyle and containerClass A style for the TabbedPane pages.
rolloverContainerStyle and rolloverContainerClass A style for the TabbedPane pages in the rollover state.
frontBorderStyle A border style for the TabbedPane component and a selected tab.
backBorderStyle A border style for not selected tabs.


Note
You should specify the frontBorderStyle and backBorderStyle attributes in the same way as the CSS border property but without the "border:" prefix.


For example:

frontBorderStyle="2px solid red"
backBorderStyle="2px solid blue"

And here is the result: |

Note
The TabbedPane container ignores the width and height CSS styles. It always expands to 100%.

Keyboard Support

The user can switch the selected tab with the the Left/Right/Up/Down keys when the TabbedPane has the keyboard focus. The TabbedPane can be made non-focusable and thus not having keyboard control by assigning false to its focusable attribute. Note that disabling focusability affects only the TabbedPane itself, but not its children, which retain their usual keyboard support in any case.

The TabbedPane has the following attributes that allow customizing its look in the focused state:

Attribute Description
focusedStyle/focusedClass A style for the entire TabbedPane in the focused state.
focusedTabStyle/focusedTabClass A style for the TabbedPane's caption in the focused state.
focusAreaStyle/focusAreaClass A style for the focus area inside of the focused tab. A focus area is an area inside a tab that contains tab text.

Client-Side Events

The TabbedPane component supports a set of standard client-side events such as onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onkeydown, onkeyup, onkeypress. In addition, the TabbedPane provides a component-specific onselectionchange event which occurs when the user selects a tab.

Server-Side Event Listeners

To enable you to handle tab selection change on the server side, the TabbedPane component provides the selectionChangeListener attribute. This attribute is MethodBinding that must point to the method that accepts a org.openfaces.event.SelectionChangeEvent. SelectionChangeEvent extends javax.faces.event.FacesEvent and adds the oldIndex and newIndex properties to it. The specified method will be called during the Process Validations phase of the request processing lifecycle, when a selected tab in the TabbedPane is changed.

The following example shows the use of the selectionChangeListener attribute:

<o:tabbedPane selectionChangeListener="#{TPBean.selectionChanged}">
  <o:subPanels value="#{TPBean.subPanels}"/>
</o:tabbedPane>

You can also add a selection change listener (which is the implementation of the org.openfaces.event.SelectionChangeListener interface) to the TabbedPane component by using the <o:selectionChangeListener> tag:

<o:tabbedPane>
  <o:subPanels value="#{TPBean.subPanels}"/>
  <o:selectionChangeListener
     type="my.MySelectionChangeListener"/>
</o:tabbedPane>

There is also immediate attribute that is used to specify whether or not selectionChangeListener should be executed immediately (during the Apply Request Values phase of the request processing lifecycle instead of Process Validations phase).

Client-Side API

All client-side API methods of the TabbedPane component are listed in the following table:

Method Description
getPageCount() Returns the number of pages in the TabbedPane component on which this method is invoked.
getSelectedIndex() Returns a zero-based index of a selected tab from the TabbedPane component on which this method is invoked.
setSelectedIndex(index) Sets the index of a selected tab for the TabbedPane component on which this method is invoked. The index parameter is a zero-based index of a tab to be selected.
OpenFaces