TabSet

The TabSet component provides a set of tabs enabling the user to switch between different components, one at a time.

Key Features

Specifying the Tabs

To add the TabSet component to a page, use the <q:tabSet> tag. There are two ways of specifying the tabs for the TabSet component:

  • To define a fixed set of tabs, use the <q:tabSetItem> tag for representing one tab. Child components of the <q:tabSetItem> tag are rendered as the tab contents.

The following example shows a four-tab TabSet component:

<q:tabSet>
  <q:tabSetItem>
    <h:outputText value="Client" />
  </q:tabSetItem>
  <q:tabSetItem>
    <h:outputText value="Server" />
  </q:tabSetItem>
  <q:tabSetItem>
    <h:outputText value="Custom" />
  </q:tabSetItem>
  <q:tabSetItem>
    <h:outputText value="Default" />
  </q:tabSetItem>
</q:tabSet>
  • To dynamically change the set of tabs, use the <q:tabSetItems> tag. The value attribute of the <q:tabSetItems> tag should be specified as a value-binding expression that references a list of items of one of the following types:
    • TabSetItem component - Its children will be rendered as the tab content.
    • JSF component - The component will be rendered as the tab content.
    • Object - The tab content will be set to a string retrieved by the toString() method of the object.

The following example shows the tabs specified through binding:

<q:tabSet>
  <q:tabSetItems value="#{TabSetBean.items}"/>
</q:tabSet>

By using the selectedIndex integer attribute, 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 following example, the second tab is selected when the page is loaded.

<q:tabSet selectedIndex="1">

Note, that TabSet tabs are indexed regardless of the rendered attribute. It means that the selectedIndex attribute refers to the tabs specified in the TabSet component, not only visible tabs.

Given the fact the TabSet extends the UIInput class, it has value attribute. This attribute should refer to the value of the selected tab. And the TabSetItem component has itemValue attribute which should refer to the object associated with this item.

Like the JSF UIInput component, the TabSet supports the standard validator, and immediate attributes. For more details about these attributes, see JavaServer Faces version 1.1 specification (section 3.2.5 EditableValueHolder).

Submitting a Page on Tab Change

You can specify whether the page is submitted when the user selects a new tab by using the boolean submitOnChange attribute of the <q:tabSet> tag. The default value is "false", which means that the page is not reloaded when a tab is changed. When set to "true", the page is submitted every time a tab is changed.

In this example, if the user selects a tab, the page is not reloaded:

<q:tabSet submitOnChange="false">

Customizing the Appearance

By default, the tabs appear at the top of the TabSet component. To specify the position of the tabs relative to the components they switch, set the placement attribute to one of these values: "top" (default), "left", "bottom" and "right". Also, by setting the alignment attribute to "topOrLeft" (default) or "bottomOrRight", you can define the alignment of the tabs. The interval between the tabs is defined in pixels by the gapWidth integer attribute. By default, it is set to "2". The size of individual tabs depends on what is displayed in them. If necessary, you can set their size with appropriate styles (see the section Customizing Styles below).
The following example shows a TabSet whose tabs are placed on the left and aligned to the bottom and are spaced 5 pixels apart.

<q:tabSet gapWidth="5"
          placement="left"
          alignment="bottomOrRight">
  <q:tabSetItems value="#{TabSetBean.items}" />
</q:tabSet>

Customizing Styles

The TabSet component provides a number of styles enabling you to customize the appearance of the entire component and its individual parts, both in the normal and rollover states. The following table lists all style-related attributes.

Attributes Description
tabStyle and tabClass A style applied to each tab of the TabSet component.
rolloverTabStyle and rolloverTabClass A style applied to each TabSet 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.
emptySpaceStyle and emptySpaceClass A style applied to the spaces before, after, and between the tabs of the TabSet.
frontBorderStyle A border style for a selected tab and the TabSet component.
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:

Client-Side Events

The TabSet component supports a set of the standard client-side events that allow you to alter the behavior of the component. These are onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onchange events.

Server-Side Event Listeners

To enable you to handle tab selection change on the server side, the TabSet 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 tab selection in the TabSet is changed.

The following example shows the use of the selectionChangeListener attribute:

<q:tabSet selectionChangeListener="#{TSBean.selChanged}" />

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

<q:tabSet>
  <q:selectionChangeListener
     type="teamdev.testapp.customEvents.MySelectionChangeListener"/>
</q:tabSet>

Given the fact that the TabSet is actually a UIInput component, it fires javax.faces.event.ValueChangeEvent just like the HTMLInputText component does. The valueChangeListener attribute should be used to handle a value change event on the server side in the same way as for the HTMLInputText. You can also add a value change listener to the component by using the <f:valueChangeListener> tag.

Client-Side API

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

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