We have received quite a few requests for a tab tutorial. We are working with the engineers to come up with a good sample application. It will be awhile before we publish that tutorial, so here is a quick bare-bones mini-tutorial of how to use a TabSet component to set up page navigation.

1. In the Projects window, right-click Web Pages and choose New > Page Fragement. Name the page fragment BannerPF.
   
   
2. Drag a TabSet from the Layout section of the Palette and drop it on the upper-left corner of the page fragment. Resize as desired.
   
   
3. In the Outline window, right-click the TabSet and choose Add Tab.
   
   
4. Set the text for the tabs to A and B.
   
   
5. In the Layout section, expand the TabSet node to see the Tab node.
   
   
6. Drag a Tab component from the Palette and drop it on tab1 in the Outline window. Drag another and drop it on tab1 too. Set the text for these tabs to Page 1 and Page 2.
   
   
7. Drag 2 tabs and drop them on tab2. Set the text for these tabs to Page 3 and Page 4.
   
   You should now have tab3 and tab4 under tab1 and tab5 and tab6 under tab2.
   
   
   
   
8. For each of these tabs set the immediate property to true (check the checkbox). Whether you do this or not depends on whether you want people to be able to tab to another page without validating the page that they are on. Setting the immediate property to true means that the pages won't go through validation when the user clicks a tab. The pages will still go through validation when the user submits the page by clicking a button or changing a value in an Auto-Submit on Change component.
   
   
9. In the Outline window, right-click tab1 and choose Edit Action Event Handler. The IDE switches to the Java source and adds the tab1_action method.
   
   
10. Make the code look like this:

      
        public String tab1_action() {
            tabSet1.setSelected("tab3");
            return "case1";
        }
    

11. Paste the code below into the Java source under the tab1_action() method. Then, in the Outline window, select tab3. In the Properties window, click the ellipsis button (...) for the action property, choose tab3_action from the drop-down list, and click ok. Repeat for every tab and subtab. When you are done, the action property for each tab must name its action handler.

        public String tab2_action() {
            tabSet1.setSelected("tab5");
            return "case3";
        }
          
        public String tab3_action() {
            return "case1";
        }
        
        public String tab4_action() {
            return "case2";
        }
        
        public String tab5_action() {
            return "case3";
        }
        
        public String tab6_action() {
            return "case4";
        }    
    

12. Open Page1. In the Layout section of the Palette, double-click the Page Fragment Box. Click Close. The page fragment appears at the top of the page.
    
    
13. Create Page2, Page3, and Page4. Add the BannerPF to each of them using the same method.
    
    You might want to add a Static Text component to each page to label that page, such as "Page 1". Doing so makes it easier to test.
    
    
14. Right-click on a blank spot on one of the pages and choose Page Navigation. In the Page Navigation editor, click Source. Add the following after <faces-config>:

        <navigation-rule>
            <from-view-id>/*</from-view-id>
            <navigation-case>
                <from-outcome>case1</from-outcome>
                <to-view-id>/Page1.jsp</to-view-id>
            </navigation-case>
        </navigation-rule>
        <navigation-rule>
            <from-view-id>/*</from-view-id>
            <navigation-case>
                <from-outcome>case2</from-outcome>
                <to-view-id>/Page2.jsp</to-view-id>
            </navigation-case>
        </navigation-rule>
        <navigation-rule>
            <from-view-id>/*</from-view-id>
            <navigation-case>
                <from-outcome>case3</from-outcome>
                <to-view-id>/Page3.jsp</to-view-id>
            </navigation-case>
        </navigation-rule>
        <navigation-rule>
            <from-view-id>/*</from-view-id>
            <navigation-case>
                <from-outcome>case4</from-outcome>
                <to-view-id>/Page4.jsp</to-view-id>
            </navigation-case>
        </navigation-rule> 
    

15. Close the Page Navigation editor and click Save.
    
    
16. Open BannerPF in the Visual Designer. Click JSP to view the JSP source.
    
    
17. Look for this line:

    <ui:tabSet binding="#{BannerPF.tabSet1}" id="tabSet1" selected="tab6" style="position: absolute; left: 0px; top: 0px">
    

    Delete the selected="tabn" parameter. This is important. If you don't do that, then the current tab doesn't always highlight correctly because this JSP code is resetting the current selected value.
    
    Important: Every time you edit the page fragment, you have to remember to remove the selected parameter from the JSP code. The IDE will keep sticking it in whenever you click on one of the tabs in the Visual Designer. So, if your tabs look like they aren't working, this is the first place to look (the selected parameter in the JSP).
    
    
18. Run and test.
    
    Notice that the URL doesn't match page displayed. This is because of the forward dispatching mechanism which Winston explains in this blog entry.
    
    

As with any quick and dirty write-up, I am sure I left something out, wasn't detailed enough when I needed to be, or didn't take into consideration a common scenario that most people want to do. Post questions and frustrations to the comments.

Sept 2006 Update: SDN member MWH@Keystroke pointed out in the Sun Java Studio Creator forum a common scenario that this doesn't cover. I updated the tab1 and tab2 actions to better handle switching back to the major tabs. MWH replied as follows with some good points to remember:

"Of course there is still the issue that if you select tab 'B', then 'Page 4' within tab B; then select tab 'A'; then return to tab 'B' by selecting 'B' you return to 'Page 3' not 'Page 4'. The developer must maintain the state of each level 1 tab, say via a session bean and restore the proper state when the level 1 tab is selected. When tab 'B' 'Page 4' is selected, set the value in the session. When tab 'B' is selected, retrieve the last level 2 sub tab selected and set it via the tabset1.setSelected('xxx') method. That way the system returns the user to the proper state relative to tab 'B'. Of course the same holds for tab 'A'.

The key is that developers need to understand they are explicitly responsible for keeping the tab state and navigation state in synch if they are using tabsets for navigation from within a page fragment. Which is quite different from using the tabset object from within a single page."