TabbedPane


The TabbedPane component allows you to present related information on separate pages which share the same space and can be viewed by users by clicking a corresponding tab. Each page of the TabbedPane component can contain a number of other JSF components.

Key Features

Specifying Tabs Content

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

  • To create a fixed set of tabs right on a JSF page, use a child <q:tabbedPaneItem> tag for representing one tab and associated page. To specify the object to be displayed on the tab, use the "tab" facet. The components that define the page content should be added as children of the <q:tabbedPaneItem> tag.

The following example shows a two-tab TabbedPane component:

<q:tabbedPane>
  <q:tabbedPaneItem>
    <f:facet name="tab">
      <h:outputText value="First tab"/>
    </f:facet>
    <h:outputText value="Some text on the first tab" />
  </q:tabbedPaneItem>
  <q:tabbedPaneItem>
    <f:facet name="tab">
      <h:outputText value="Second tab"/>
    </f:facet>
    <h:outputText value="Some text on the second tab"/>
  </q:tabbedPaneItem>
</q:tabbedPane>
  • To retrieve dynamically changing data from a backing bean, use a child <q:tabbedPaneItems> tag. The the value attribute of the <q:tabbedPaneItems> tag must be a value-binding expression that references a collection of teamdev.jsf.component.tabset.TabbedPaneItem objects.

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

<q:tabbedPane>
  <q:tabbedPaneItems
          value="#{TabbedPaneBean.tabbedPaneItems}"/>
</q:tabbedPane>

You can combine these two approaches by placing the <q:tabbedPaneItem> and <q:tabbedPaneItems> tags in any order you need.

By using the selectedIndex integer attribute of the <q: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.

<q:tabbedPane selectedIndex="2">
  <q:tabbedPaneItems
          value="#{TabbedPaneBean.tabbedPaneItems}"/>
</q:tabbedPane>

Note, that TabbbedPane tabs are indexed regardless of the rendered attribute. It means that the selectedIndex attribute refers to the tabs specified in the TabbedPane component, not only 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.
  • "server" - Every time a tab is changed, a corresponding tabbed page is reloaded with the tab content.
  • "ajax" (default) - The tab content is retrieved from the server by the AJAX request on the first switch to the tab. Once requested, the content is stored on the client.

The example below uses the "client" loading mode.

<q:tabbedPane loadingMode="client">
  <q:tabbedPaneItems
          value="#{TabbedPaneBean.tabbedPaneItems}"/>
</q: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 the tabs, set the tabPlacement attribute to one of these values: "top" (default), "left", "bottom" and "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.

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

Customizing Styles

With the TabbedPane, 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
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%.

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 teamdev.jsf.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:

<q:tabbedPane selectionChangeListener="#{TPBean.selectionChanged}">
  <q:tabbedPaneItems value="#{TPBean.tabbedPaneItems}"/>
</q:tabbedPane>

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

<q:tabbedPane>
  <q:tabbedPaneItems value="#{TPBean.tabbedPaneItems}"/>
  <q:selectionChangeListener
     type="teamdev.testapp.customEvents.MySelectionChangeListener"/>
</q: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:

TabbedPane methods Public method Description
getSelectedIndex() q_getTabbedPaneSelectedIndex(tabbedPaneId) Gets the index of a selected tab from the TabbedPane component with the id specified in the tabbedPaneId parameter.
setSelectedIndex(index) q_setTabbedPaneSelectedIndex(tabbedPaneId, index) Sets the index of a selected tab for the TabbedPane component with the id specified in the tabbedPaneId parameter. The index parameter is an index of the tab to be selected.
QuipuKit