h2. 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_.
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=tabSet] of this component, complete with source code.{tip}
h2. Getting Started
To use the _ace:tabSet_ component, first the ACE Components tag-lib name-space has to be added in your page.
{panel}
{code:xml|borderStyle=dashed}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
{code}
{panel}Now you ready to use _ace:tabSet_ component, here is the basic example:
{panel}
{code:xml|borderStyle=dashed}<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>
{code}
{panel}
h2. Attributes
{tip:title=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|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/tabSet.html].{tip}{*}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.
{code:xml}<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>
{code}
*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.
{code:xml}<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) {
...
}
}
{code}
*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.
{code:xml}<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>
{code}
*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.
{panel}
*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.
{panel}
h2. 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. |
{code:xml|borderStyle=dashed}<ace:tabSet clientSide="false" tabChangeListener="#{bean.tabChanged}">
...
</ace:tabSet>
{code}
h2. 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. |
{code:xml|borderStyle=dashed}<ace:tabSet clientSide="false">
<ace:ajax event="serverSideTabChange" execute="@this" render="messages" />
...
</ace:tabSet>
{code}
h2. Keyboard and ARIA Support
The following ARIA roles are supported: tablist, tab, tabpanel, presentation.
h2. Javascriipt API
h4. ICEfaces 3.x
The client side component object is exposed through the global variable name specified in the *widgetVar* attribute.
h4. 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.
{code}var widget = ice.ace.instance('frm:componentId);{code}
{tip}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">_).{tip}
{info}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.
{info}
{info}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.
{info}
h2. CSS Classes
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
{code:xml}
<!-- 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>
{code}
h2. Known Issues
* As of ICEfaces 4.1 the ace:clientValidate* components are not supported when embedded inside an ace:tabSet component. See http://jira.icesoft.org/browse/ICE-10894 for details.
h2. Additional Resources
h4. Tutorials
The _ace:tabSet_ component appears in the following ICEfaces tutorials:
*None*
_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_.
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=tabSet] of this component, complete with source code.{tip}
h2. Getting Started
To use the _ace:tabSet_ component, first the ACE Components tag-lib name-space has to be added in your page.
{panel}
{code:xml|borderStyle=dashed}<html ... xmlns:ace="http://www.icefaces.org/icefaces/components">
{code}
{panel}Now you ready to use _ace:tabSet_ component, here is the basic example:
{panel}
{code:xml|borderStyle=dashed}<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>
{code}
{panel}
h2. Attributes
{tip:title=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|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/tabSet.html].{tip}{*}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.
{code:xml}<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>
{code}
*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.
{code:xml}<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) {
...
}
}
{code}
*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.
{code:xml}<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>
{code}
*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.
{panel}
*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.
{panel}
h2. 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. |
{code:xml|borderStyle=dashed}<ace:tabSet clientSide="false" tabChangeListener="#{bean.tabChanged}">
...
</ace:tabSet>
{code}
h2. 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. |
{code:xml|borderStyle=dashed}<ace:tabSet clientSide="false">
<ace:ajax event="serverSideTabChange" execute="@this" render="messages" />
...
</ace:tabSet>
{code}
h2. Keyboard and ARIA Support
The following ARIA roles are supported: tablist, tab, tabpanel, presentation.
h2. Javascriipt API
h4. ICEfaces 3.x
The client side component object is exposed through the global variable name specified in the *widgetVar* attribute.
h4. 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.
{code}var widget = ice.ace.instance('frm:componentId);{code}
{tip}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">_).{tip}
{info}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.
{info}
{info}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.
{info}
h2. CSS Classes
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
{code:xml}
<!-- 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>
{code}
h2. Known Issues
* As of ICEfaces 4.1 the ace:clientValidate* components are not supported when embedded inside an ace:tabSet component. See http://jira.icesoft.org/browse/ICE-10894 for details.
h2. Additional Resources
h4. Tutorials
The _ace:tabSet_ component appears in the following ICEfaces tutorials:
*None*