>> More Visual Web Pack Documentation

Setting Up Page Navigation

This tutorial works with the following technologies and resources:

JavaServer Faces Components/ Java EE Platform	1.2 with Java EE 5* 1.1 with J2EE 1.4
Travel Database	Not required
BluePrints AJAX Component Library	Not required

* As of the date this tutorial was published, only the Sun Java System Application Server supported Java EE 5.

This tutorial has been tailored for use with the Sun Java Application Server PE 9.0 Update Release 1 and with Tomcat 5.5.17. If you are using a different server, consult the Release Notes and FAQs for known problems and workarounds. For detailed information about the supported servers and Java EE platform, see the Release Notes.

Creating the First Page

In the first part of this tutorial, you create a web application with two pages and navigate between two pages using a button. Later, you add a Drop Down List component that enables the user to choose a destination page at run time.

1. Create a new visual web application project and name it NavigationExample.

   Your new project appears with the initial page displayed in the Visual Designer. The following figure shows the page that you create in the steps that follow:

   Figure 1: Page 1 Design

2. From the Basic section of the Palette, drag a Static Text component and drop it on the page. Change the component's text property to Page One by typing directly over the default text on the component.
3. Drag a Button component from the Palette, drop it on the page, and change its text property to Go.

Navigating Between Two Pages

1. Right-click an empty space in the Visual Editor's editing area and choose Page Navigation from the pop-up menu.

   The Page Navigation Editor displays an icon for Page1.jsp, which represents the page you created in the previous section. You can also open the Page Navigation Editor by double-clicking the Page Navigation node in the Projects window.
2. Right-click in the editing area and choose Add Page.

3. Click OK in the Select Page Name dialog box to accept the default name, Page2.

   A Page2.jsp icon appears in the Navigation Editor as shown in Figure 2, and a Page2.jsp node is added in the Projects window under the NavigationExample > Web Pages node.
4. Click the Page1.jsp icon to enlarge it so you can see the button1 icon. Note the blue icon next to the name button1. This is the button's connector port.
5. Click the connector port and drag a line to the Page2.jsp icon. A connector appears that is anchored in the first page and ends in the second page. By default, the newly created connector is named case1.

6. Double-click the connector's name and change it from case1 to Page 2.

   The following figure shows the Page Navigation Editor with the connector between the two pages.

   Figure 2: Page Navigation Editor

7. Click XML in the editing toolbar to see the code that was generated during the last two steps.

   Code Sample 1: Generated Code

   <?xml version="1.0" encoding="UTF-8"?> <faces-config version="1.2" <navigation-rule> <from-view-id>/Page1.jsp</from-view-id> <navigation-case> <from-outcome>Page 2</from-outcome> <to-view-id>/Page2.jsp</to-view-id> </navigation-case> </navigation-rule> </faces-config>

   
   The code that is added inside the faces-config tags specifies the single navigation rule for this web application. Each navigation rule specifies one origin page and one or more destination pages.

Adding Components to the Second Page

1. Click Navigation in the editing toolbar.

2. Double-click the Page2.jsp icon.

   The page opens in the Visual Designer.
3. Place a Static Text component on the page and change the text property to Page Two, as shown in the following figure.
   
   

   Figure 3: Layout of Page 2

4. Deploy the application by pressing F6.

5. After the web application is deployed, Page One opens in your browser as shown in the following figure:

   Figure 4: Simple Navigation Web Application

6. Click the Go button, which navigates you from the first page to the second page.

In this section, you created two pages and established simple navigation from one to the other. In the next section, you establish navigation based on selections from a Drop Down List component.

Adding a Drop Down List for Dynamic Navigation

Now you'll learn about dynamic page navigation. You add a Drop Down List component to the first page of the application. The Drop Down List enables the user to choose a destination page at run time. Later, you add a third page to the application so that the Drop Down list contains two choices of destination.

The following figure shows the modifications you make to Page 1 in the steps that follow:

1. Open Page1.jsp in the Visual Designer.
2. Place a Drop Down List component underneath the Static Text component.
3. Right-click the Drop Down List and choose Configure Default Options.

4. In the dialog box labeled Options Customizer - dropDown1, replace the values of each of the default items with the values shown in the following figure. Click on each table cell to edit the value, and press Enter after editing each field to accept the change.

   Figure 6: The Options Customizer Dialog Box

5. Click OK to save all the changes.

Adding the Third Page

Create the third page to which the first page can navigate. The following figure shows the page you create in the steps that follow:

1. In the Projects window, right-click the NavigationExample > Web Pages node and choose New > Page. In the New Page wizard, click Finish. The IDE creates Page3.jsp and displays it.
2. Drag a Static Text component from the Palette window and drop it on the page. Set the text of the component to Page Three.

Implementing Dynamic Page Navigation

1. Open the Page Navigation Editor.
2. Click the Page1.jsp icon to show its contents and drag a connector line from the button's connector port to Page3.jsp icon.
3. Change the name of the connector from case1 to Page 3.
4. Double-click the Page1.jsp icon and click Design in the Editing toolbar to show the layout of Page 1.
5. Double-click the Go button component to display its source code for the action handler method in the Java Editor.

6. Replace the return statement in the method with the following code shown in bold:

   Code Sample 2: Return Statement

   public String button1_action() { return (String) dropDown1.getValue(); }

Deploying the Application

1. Deploy the application by pressing F6.
2. On the first page, select Page 2 from the drop-down list and click Go to take you to the second page.
3. Click your browser's Back button to return to the first page from Page 2.
4. Now select Page 3 from the drop-down list and click Go to take you to the third page.

Implementing Advanced Dynamic Page Navigation

1. Click the Page1 tab and click Design in the editing toolbar to switch to the Visual Designer.
2. Right-click the Go button and select Delete.
3. Double-click the Drop Down List component to view the Page1 class code in the Java Editor.

4. Add the following code in bold to the dropDown1_processValueChange() handler method. The first two lines of the code retrieve an object reference to your application. From the application object, you can get an instance of the Navigation Handler. Calling the handleNavigation() method on this object specifies the value that is retrieved from the Drop Down List component, which specifies the page to which to navigate.

   Code Sample 3: Navigation Handler Method

   public void dropDown1_processValueChange(ValueChangeEvent event) { Application application = getApplication(); NavigationHandler navigator = application.getNavigationHandler(); FacesContext facesContext = getFacesContext(); navigator.handleNavigation(facesContext, null,(String) dropDown1.getValue()); }

   
   Note that red squiggly lines appear to indicate that the Application, NavigationHandler, and FacesContext classes cannot be found. You will import these classes in the next step.

5. Right-click anywhere in the Source Editor and choose Fix Imports to automatically add the following import statements near the top of the source file:

   Code Sample 4: Import Statements for Navigation Handler Method

   import javax.faces.application.Application; import javax.faces.application.NavigationHandler; import javax.faces.context.FacesContext;

6. Click Design in the editing toolbar to view Page1 in the Visual Designer.
7. Right-click the Drop Down List component and select Auto-Submit on Change to indicate that the item selected will be automatically submitted upon selection.
8. Deploy and run the application.
9. Choose the Page 2 item in the drop-down list to navigate from the first page to the second page. Click the Back button to return to the first page.
10. Choose the Page 3 item in the drop-down list to navigate from the first page to the third page.
    

Doing More: Working With a Large Number of Pages

1. In the Page Navigation editor, click the XML button in the editing toolbar.

2. Add a navigation rule like the the first entry in the following XML. Set the <from-view-id> to /*, set the <from-outcome> to some identifying string, and set the <to-view-id> to the destination page.

   Code Sample 5: Page Navigation XML for Applications With a Large Number of Pages

   <?xml version="1.0" encoding="UTF-8"?> <faces-config version="1.2" <navigation-rule> <from-view-id>/*</from-view-id> <navigation-case> <from-outcome>login</from-outcome> <to-view-id>/Page3.jsp</to-view-id> </navigation-case> </navigation-rule> <navigation-rule> <from-view-id>/Page1.jsp</from-view-id> <navigation-case> <from-outcome>case1</from-outcome> <to-view-id>/Page2.jsp</to-view-id> </navigation-case> </navigation-rule> </faces-config>

   
   

   When you return to the Page Navigation editor, the editor will show errors but you can ignore these.

3. In all action handling methods for action components that you want to send to the page, have the methods return the from-outcome (in this case "login"), as shown below:

   public String button1_action() {
           return "login";
       }

Summary

1. Create the pages.
2. Place components that support navigation, such as buttons and drop down lists, on the page.
3. Using the Navigation Editor, draw connectors between components and pages.
4. Implement more advanced navigation using the dropDown1_processValueChange() handler method.
   

See Also:

• Getting Started With NetBeans Visual Web Pack
• Using Databound Components to Access a Database
• Using Page Fragments