Navigating Pages in a Web Application

Contributed by the NetBeans Tutorials Team
October, 2007 [Revision number: V6.0]    

This tutorial shows how to set up page navigation in NetBeans IDE 6.0. You first create a web application in the IDE that uses simple navigation between two pages. A button on the first page takes you to the second page. You then modify the application so that the application determines at runtime which page displays based on the value returned by a Drop Down List component. You also learn an alternative and more advanced method of dynamic page navigation, which allows the page navigation to occur as soon as a selection is made from the Drop Down List.

Expected duration: 20 minutes

Contents


This tutorial works with the following technologies and resources:

JavaServer Faces Components/
Java EE Platform
works with1.2 with Java EE 5*
works with1.1 with J2EE 1.4
Travel Database not requiredNot required

* In order to take advantage of NetBeans IDE 6.0's Java EE 5 capabilities, use an application server that is fully compliant with the Java EE 5 specification such as the Sun Java Application Server 9/GlassFish.

This tutorial has been tailored for use with the GlassFish v2 Application Server. 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.

First, create a page that contains a Static Text component and a Button component.
  1. Create a new web application project and named NavigationExample that uses the GlassFish V2 Application Server and the Visual Web JavaServer Faces framework.

    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:

    Page 1 Design 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

Next, add another page to the application and specify the navigation between the first and second pages by creating a link, or page connector.
  1. Right-click an empty space in the Visual Editor's editing area and choose Page Navigation from the pop-up menu.

    The Page Flow Editor displays an icon for Page1.jsp , which represents the page you created in the previous section. Note that this icon has four features:
    1. The badge indicates what kind of page is represented by the icon. The green arrow indicates that the page is the project's main page.
    2. The name of the file represented by the icon distinguishes the pages in the product.
    3. The plus sign expands the icon to display the components on the page.
    4. The connector port is used to draw navigation lines between pages.
  2. Create a new JSP page as follows:

    1. Right-click in the editing area and choose New File.
    2. In the New File dialog, select Java Server Faces under Categories and Visual Web JSF Page under File Types, and click Next.
    3. Accept the default name, Page2 and click Finish.

      A Page2.jsp icon appears in the Page Flow Editor as shown in Figure 2, and a Page2.jsp node is added in the Projects window under the NavigationExample > Web Pages node.
  3. If the Page Flow Editor does not display after Page2.jsp is created, select the faces-config.xml tab to display the Editor.
  4. Click the plus sign on the Page1.jsp icon to enlarge it so you can see the button1 icon.
  5. Click the button1 icon 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 name and change the name from case1 to Page 2.

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

    Page Navigation Editor
    Figure 2: Page Flow Editor
  7. Click XML in the editing toolbar to see the code that was generated during the last two steps. The navigation-rule in bold below is added below the managed bean code, represented by an ellipsis (...).

    Code Sample 1: Generated Code
    <?xml version="1.0" encoding="UTF-8"?>
    <faces-config version="1.2" xmlns="http://java.sun.com/xml/ns/javaee" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"> ... <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

Now add a label to the second page to distinguish the page visually from the first page, then run the application.
  1. Click Page Flow 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.

    Layout of Page 2Figure 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:

    Simple Navigation Web Application 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:

Layout of the Modified First Page Figure 5: Layout of the Modified First Page
  1. Open Page1.jsp in the Visual Designer.
  2. Place a Drop Down List component under 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.

    The Options Customizer Dialog Box Figure 6: The Options Customizer Dialog Box
  5. Click OK to save all the changes.

Adding the Third Page

Next you create a third page to which the first page can navigate.

  1. In the Projects window, right-click the NavigationExample > Web Pages node and choose New > Visual Web JSF Page. In the New Visual Web JSF 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

In this section, you enable dynamic page navigation. With dynamic page navigation, the application determines at runtime which page is displayed when the user clicks the Go button on the first page.
  1. Open the Page Flow 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

Test the navigation between the pages.
  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

In the previous section, dynamic page navigation is handled in a straightforward way. The user selects the page to which to navigate in the drop-down list and clicks the Go button. If you want the page change to occur as soon as the drop-down list value changes, use the following steps to modify the project you created in the previous sections.
  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

The scenario described in this tutorial works for a relatively small number of pages, but many real-world applications require navigation through dozens of pages. To establish this kind of navigation:
  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" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">
    <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

The typical workflow for implementing page navigation is as follows:
  1. Create the pages.
  2. Place components that support navigation, such as buttons and drop down lists, on the page.
  3. Using the Page Flow Editor, draw connectors between components and pages.
  4. Implement more advanced navigation using the dropDown1_processValueChange() handler method.

See Also:




This page was last modified:  October, 2007