Skip to content

TabSet 2.x

Jump to bottom
AlexanderLitus edited this page Aug 12, 2014 · 3 revisions

TOCSTART

TOCEND

The TabSet is a component that displays a set of tabs that look like the ones used in the TabbedPane component. As opposed to TabbedPane, the TabSet component is not a container and doesn't display any data when the user switches the tab. Instead it just serves as a selector that can be used to introduce a content switching on pages where TabbedPane can't be used because of special layout or some other reason. The TabSet component provides means for configuring tabs, their content, placement and appearance.


Online Demo

Key Features

Specifying the Tabs

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

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

The following example shows a four-tab TabSet component:

<o:tabSet>
  <o:tabSetItem>
    <h:outputText value="Client" />
  </o:tabSetItem>
  <o:tabSetItem>
    <h:outputText value="Server" />
  </o:tabSetItem>
  <o:tabSetItem>
    <h:outputText value="Custom" />
  </o:tabSetItem>
  <o:tabSetItem>
    <h:outputText value="Default" />
  </o:tabSetItem>
</o:tabSet>
  • To dynamically change the set of tabs, use the <o:tabSetItems> tag. The value attribute of the <o: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:

<o:tabSet>
  <o:tabSetItems value="#{TabSetBean.items}"/>
</o: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.

<o: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 that 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 specification (section "EditableValueHolder").

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.

<o:tabSet gapWidth="5"
          placement="left"
          alignment="bottomOrRight">
  <o:tabSetItems value="#{TabSetBean.items}" />
</o: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.


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:

Keyboard Support

The user can switch the selected tab with the the Left/Right/Up/Down keys when the TabSet has the keyboard focus. The TabSet can be made non-focusable and thus not having keyboard control by assigning false to its focusable attribute.

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

          Attribute
Description
focusedStyle/focusedClass A style for the entire TabSet in the focused state.
focusedTabStyle/focusedTabClass A style for the TabSet'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 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 org.openfaces.event.SelectionChangeEvent. SelectionChangeEvent extending 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:

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

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

<o:tabSet>
  <o:selectionChangeListener
     type="my.MySelectionChangeListener"/>
</o: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:

       Method
Description
getTabCount() Returns the number of tabs in the TabSet component on which this method is invoked.
getSelectedIndex() Returns a zero-based index of a selected tab from the TabSet component on which this method is invoked.
setSelectedIndex(index) Sets a selected tab for the TabSet component on which this method is invoked. The index parameter is a zero-based index of a tab to be selected.
focus() Gives the keyboard focus to the component on which this method is invoked.
blur() Removes the keyboard focus from the component on which this method is invoked.
Clone this wiki locally