TabPane

Overview

Since 2.0

The ace:tabPane component is a child for its ace:tabSet parent, and corresponds to each shown tab, and is responsible for defining the label and content areas. There are scenarios where the whole ace:tabSet can exist within a single form, and which will affect validation for the currently selected ace:tabPane, and possibly the other ace:tabPane's as well. There are also other scenarios that enable having forms within each ace:tabPane content area, to better limit the scope of each submit and validation phase.

The ace:tabSet's clientSide property and the ace:tabPane's cache property interact to control how long the ace:tabPane's content will persist within the browser, which is useful for when multimedia or iframe tags are used within tabs, and it's desirable or necessary for them to not be reloaded as the tabs are changed. There are also performance considerations, as it can be controlled whether the server is contacted at all, and whether the ace:tabPane contents are re-rendered at all, which can affect scalability when large data sets are rendered within the tabs.

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

Getting Started

To use the ace:tabPane 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:tabPane 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.

label property and facet are the two ways for specifying the label, that identifies this ace:tabPane to the user, and is where they click to select this as the current ace:tabPane. In the simple case, where only a text string label is necessary, the label property is best used. Otherwise, when applications require component(s) for the label, for example to include a button for removing the ace:tabPane or to show a thumbnail image, then the label facet is required. This is an example of each being used:

<ace:tabSet>
    <ace:tabPane id="tabWithLabelFacet">
        <f:facet name="label">
            <h:panelGrid columns="3">
                <h:graphicImage url="images/icon.gif"/>
                <h:outputText value="Tab One"/>
                <h:commandButton value="close" actionListener="#{tabBean.closeTab}">
                    <f:ajax execute="closeTab" render="@all" />
                </h:commandButton>
            </h:panelGrid>
        </f:facet>
        <h:outputText value="#{tabBean.tabContents}"/>
    </ace:tabPane>
    <ace:tabPane id="tabWithLabelProperty" label="Tab Two">
        <h:outputText value="Tab Two Contents"/>
    </ace:tabPane>
</ace:tabSet>

cache is a property on ace:tabPane which can be used to manage the lazy browser caching of tab content when the ace:tabSet is in server-side mode (clientSide="false"). When in client-side mode, the tab contents are always dynamically cached, in that they are cached in the browser, but if you do submit to the server and render different content, then that will be updated in the browser. The default for server-side is to only render the active tab's contents, and not have the other tab's contents rendered into the browser. Switching from one tab to another will unrender the old tab's contents, and any state that was not specifically saved or submitted to the server will be lost. Hence having caching for an ace:tabPane will mean that once that ace:tabPane has been rendered into the browser, its contents will remain in the browser, and be preserved when the ace:tabPane becomes the active tab again. Any javascript objects, iframe contents, or other state that exists in the tab content will remain. By default, there is no caching.

When the ace:tabSet renders, it will render the active tab contents, as well as any dynamically cached tab contents, and use the DOM differencing to determine what needs updating in the browser. Everything works automatically, but there is a server performance cost of rendering and DOM differencing non-active but dynamically cached tab content. The term dynamic refers to how the tab content is still updatable. The price is that as dynamically cached tabs become active, they then continue to be rendered in every subsequent lifecycle.

For tab content that might be expensive to render, and does not update frequently or at all, static caching may be more suitable. For example, if the application has large dataTables in the non-active tabs, and have those tabs dynamically cached, then the dataTables will be rendered even when the user can not see them. With static caching, once the tab content has been rendered and sent to the browser, it is no longer rendered nor updated in subsequent lifecycles. It remains in the browser, and that browser copy of the tab contents is solely used. If at some point in the future an update is desired, that tab may be switched to dynamic caching, but because the tab contents had not been rendered for some time, the DOM differencing will not be able to granularly update the tab contents and will instead have to completely update that tab.

In some cases, applications may only want to update a statically cached tab at key moments, and so will only want to temporarily, for one lifecycle, switch to dynamic caching, and then have it revert to static caching. There are several caching settings to facilitate this as well.

disabled tabs have a disabled styling on their non-clickable label area, and so cannot be changed to by the user. Applications may still use ace:tabSet's selectedIndex property to make a disabled tab be the currently selected one.

Known Issues

Disabling is only enforced by not allowing the user to click to change to a tab. Since applications can force a disabled tab to be shown, and there is currently no feature similar to how modal disalogs disable interaction with portions of a page, the contents of the disabled tab can still be interacted with, in that scenario.

Additional Resources

Tutorials

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

None