Adding navigation with page events

Introduction tutorial - Adding navigation with page events - Edit the navigation page

SUMMARY Navigation can be achieved in many ways within a XUI application and the method of achieving navigation in this step should by no means be seen as definitive.

FURTHER READING This step introduces the concept of binding events to page functions. This can be automated for you with the kalideoscope editor and is illustrated in the kalideoscope editor tutorial. Advanced navigation can be done though library functions and by declaraing the navigation pages in a separate XML navigation file. This process is illustrated in the 'Advanced Navigation using Library Functions' step of the Advanced Tutorial.

Any useful application will consist of several pages so now we'll add a page and handle the navigation to it. Begin by creating a new file in the pages directory called personal.xml and declare some basic components for data entry. In this example we have created inputs for Title, Firstname, Surname and Date of birth.

Listing 1 - personal.xml

<XPage>
  <Components>
    <Label x="123" y="51" w="100" h="20" style="prompt" content="Title:" 
	opaque="true"/>
    <ComboBox x="238" y="51" w="100" h="20"/>
    <Label x="123" y="80" w="100" h="20" style="prompt" content="Firstname:" 
	opaque="true"/>
    <Label x="123" y="110" w="99" h="20" style="prompt" content="Surname:" 
	opaque="true"/>
    <Label x="124" y="138" w="99" h="20" style="prompt" content="Date of birth:" 
	opaque="true"/>
    <Edit x="238" y="78" w="178" h="20" alignment="Leading"/>
    <Edit x="238" y="106" w="178" h="20" alignment="Leading"/>
    <Edit x="238" y="133" w="100" h="20" alignment="Leading"/>
  </Components>
</XPage>

Now we need to be able to navigate to this new page. In order to do this the navpanel page needs to be amended as shown in listing 2.

Listing 2 - navpanel.xml

<XPage class="net.xoetrope.mortgage.NavPanel" style="Heading">
  <Components>
    <Image name="nextButton" x="564" y="51" w="19" h="18" content="right.gif"/>
    <Image name="prevButton" x="60" y="54" w="19" h="18" content="left.gif"/>
  </Components>
  <Events>
    <Event method="nextPage" target="nextButton" type="MouseHandler"/>
    <Event method="prevPage" target="prevButton" type="MouseHandler"/>
  </Events>
</XPage>

The first thing to note is the class attribute of the page. The XPage subclass which will handle events and other more complex functionality of the page is specified here. The name attribute has been added to the image components. This is necessary because the events defined at the bottom of the page need to refer to them.

The Event nodes have three basic attributes. The target attribute specifies the component to which the event will be bound. The type attribute specifies the event type and in this case the images will trigger mouse events. The method attribute is of most interest here as it specifies the method within the net.xoetrope.mortgage.NavPanel class which will be called when the event is invoked.

So now create the net.xoetrope.mortgage.NavPanel.java file under the src directory.

Listing 3 - NavPanel.java

package net.xoetrope.mortgage;

import net.xoetrope.xui.*;

public class NavPanel extends XPage
{

  public void nextPage()
  {
    if ( wasMouseClicked())
      navigateToPage( "next" );
  }

  protected void navigateToPage( String key )
  {
    XPage target = ( XPage )( ( XTarget ) 
	pageMgr.getTarget( "content" ) ).getComponent( 0 );
    String dest = ( String )target.getAttribute( key, null );
    if ( dest != null )
      pageMgr.showPage( dest, "content" );
  }

  public void prevPage() {
    if ( wasMouseClicked() )
      pageMgr.showPrevious();
  }
}

The NavPanel class extends the XPage class. In this case the welcome page is modified to contain the next attribute as in listing 4.

Listing 4 - welcome.xml

<XPage next="personal">
    ...

In both the nextPage and prevPage methods a check is first made with the wasMouseClicked function call to see if a mouse click event triggered the event. This function call is with the XPage class for convenience.

In the nextPage method the navigateToPage method is called with the name of the parameter which is to be checked.

The first line of the navigateToPage function locates the XPage which is contained in the content frame. This frame is named in the frames.xml file. Now get the attribute of the page as specified by the key parameter. Now use the XPageManager to navigate to the page.

The prevPage method simply calls the showPrevious function of the page manager. This has the effect of displaying the last page in the history stack. This can be called for however many pages have been navigated up to this point.

After compiling NavPanel.java, execute the run.bat file and the application will appear as in the screenshot.