TabSet

Added by Ken Fyten, last edited by Ken Fyten on Feb 29, 2016  (view change)
Table of Contents

Overview

Since 2.0

The ace:tabSet component is a container for its ace:tabPane children, where the contents of only one ace:tabPane may be visible at a given time. The ace:tabSet may operate in a server-side mode where only the current ace:tabPane's contents exist in the browser; or in client-side mode, where every ace:tabPane's contents exist in the browser, and no server round-trip is necessary to change the current ace:tabPane. The ace:tabSet may be configured so that it need not itself be within a form, so that each ace:tabPane may contain its own form. This entails using an ace:tabSetProxy, which would go into a form outside of the ace:tabSet.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

To use the ace:tabSet component, first the ACE Components tag-lib name-space has to be added in your page. 

<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
Now you ready to use ace:tabSet component, here is the basic example:

<ace:tabSet>
   <ace:tabPane label="Tab One">
       <h:outputText value="Contents of tab one"/>
   </ace:tabPane>
   <ace:tabPane label="Tab Two">
       <h:outputText value="Contents of tab one"/>
   </ace:tabPane>
</ace:tabSet>

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.
clientSide The ace:tabSet can be all client side, by just setting clientSide attribute to true. Then, every ace:tabPane's contents exist in the browser, and no server round-trip is necessary to change the current ace:tabPane. When clientSide is false, then a server round-trip is done for every change of the current ace:tabPane.

With the ace:tabPane's cache property, applications can control whether each individual ace:tabPane's content will continue to exist in the browser when it is not the current ace:tabPane. This creates a middle ground between client side and server side features.

<ace:tabSet clientSide="true">
   <ace:tabPane label="Tab One">
       <h:outputText value="Contents of tab one"/>
   </ace:tabPane>
   <ace:tabPane label="Tab Two">
       <h:outputText value="Contents of tab one"/>
   </ace:tabPane>
</ace:tabSet>

selectedIndex and tabChangeListener can control the selection of the current ace:tabPane, and provide notification of changes to that selection by the user, respectively. They're only used in server side mode, although in client side mode, selectedIndex may be initialised to a specific value for when the ace:tabSet is initially rendered.

<ace:tabSet clientSide="false" selectedIndex="#{bean.selectedIndex}" tabChangeListener="#{bean.tabChangeListener}">
   ...
</ace:tabSet>

public class Bean {
    private int selectedIndex = 0;

    public int getSelectedIndex() {
        return selectedIndex;
    }
    public void setSelectedIndex(int selectedIndex) {
        this.selectedIndex = selectedIndex;
    }

    public void tabChangeListener(javax.faces.event.ValueChangeEvent event) {
        ...
    }
}

immediate and cancelOnInvalid work together to control in what phase the changing of the current ace:tabPane takes place, and whether the change will be stopped by, or continue regardless of, validation errors from input components in the submitted form. They are an alternative to using ace:ajax to specify fine grained execution and rendering, to avoid validation of input components altogether.

When cancelOnInvalid is false, then irrespective of immediate, selectedIndex will be set and tabChangeListener will be invoked in APPLY_REQUEST_VALUES phase. PROCESS_VALIDATIONS phase will still execute and create any FacesMessage(s), but won't interfere with the changing TabPane selection.

Otherwise, when cancelOnInvalid is true, then it depends on immediate. When immediate is true, selectedIndex will be set and tabChangeListener will be invoked in APPLY_REQUEST_VALUES phase, but PROCESS_VALIDATIONS phase will not execute, so no FacesMessage(s) can be created. When immediate is false, then selectedIndex will be set in UPDATE_MODEL and tabChangeListener will be invoked in INVOKE_APPLICATION, and so any validation error in PROCESS_VALIDATIONS will stop the changing of the selected TabPane.

<h:messages/>
<h:form>
    <!-- Only change tabs when the current tab's inputText have been filled in -->
    <ace:tabSet clientSide="false" cancelOnInvalid="true" immediate="false">
        <ace:tabPane label="Tab One">
            <h:inputText required="true"/>
        </ace:tabPane>
        <ace:tabPane label="Tab Two">
            <h:inputText required="true"/>
        </ace:tabPane>
    </ace:tabSet>
</h:form>

showEffect and showEffectLength can be used to apply an animation effect to the tab contents when transitioning to a new tab. It works by specifying a name of a predefined effect as the value of the showEffect attribute. The showEffectLength attribute is optional and can take a numerical value to specify the duration of the effect in milliseconds. The default duration depends on the type of effect. The following are the supported effects.

Blind - Blinds the element away or shows it by blinding it in.
Clip - Clips the element on or off, vertically or horizontally.
Drop - Drops the element away or shows it by dropping it in.
Explode - Explodes the element into multiple pieces.
Fade - Fades the element, by gradually changing its opacity.
Fold - Folds the element like a piece of paper.
Puff - Scale and fade out animations create the puff effect.
Slide - Slides the element out of the viewport.
Scale - Shrink or grow an element by a percentage factor.
Bounce - Bounces the element vertically or horizontally n-times.
Highlight - Highlights the background with a defined color.
Pulsate - Pulsates the opacity of the element multiple times.
Shake - Shakes the element vertically or horizontally n-times.

Event Listeners

tabChangeListener Used to define a server-side tabChangeListener which will be notified each time the tabSet's active tabPane is changed. The tabChangeEvent is fired whenever the "serverSideTabChange" client event fires. 
<ace:tabSet clientSide="false" tabChangeListener="#{bean.tabChanged}">
    ...
</ace:tabSet>

Client Behavior Events

clientSideTabChange Fired when the tabSet has clientSide=true, and a tab change occurs.
serverSideTabChange Fired when the tabSet has clientSide=false, and a tab change occurs. 
<ace:tabSet clientSide="false">
    <ace:ajax event="serverSideTabChange" execute="@this" render="messages" />
    ...
</ace:tabSet>

Keyboard and ARIA Support

The following ARIA roles are supported: tablist, tab, tabpanel, presentation.

Javascriipt API

ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the widgetVar attribute.

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

var widget = ice.ace.instance('frm:componentId);
The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).
This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.
The ice.ace.tabset.clearSelectedIndexState(tabSetClientId) utility function is provided for developers who wish to change the selected tab pane programmatically and need a way to reset it to the original state. This can be accomplished by simply calling this function passing the client id of the tab set.

CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<!-- Root container -->
<div class="yui-navset yui-navset-top ui-tabset ui-widget ui-widget-content ui-corner-all asdf" style="color:#000;">
	<ul class="yui-nav ui-tabs-nav ui-helper-reset ui-helper-clearfix ui-widget-header ui-corner-all">
		<!-- First tab -->
		<li class="ui-state-default ui-corner-top ui-state-active">
			<div class="yui-navdiv">
				<em>Tab label</em>
			</div>
		</li>
		<!-- Other tabs go here... -->
	</ul>
	<!-- Tab content -->
	<div class="yui-content ui-tabs-panel ui-widget-content ui-corner-bottom">
		<div>
			<div class="ui-tabs-panel ui-widget-content ui-corner-bottom">
				<span>Tab content</span>
			</div>
		</div>
	</div>
</div>

Known Issues

Additional Resources

Tutorials

The ace:tabSet component appears in the following ICEfaces tutorials:

None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2021 ICEsoft Technologies Canada Corp.