16 Navigation and page management
Carousel provides all the infrastructure necessary to manage pages within an application whether the pages are created with XML or via Java. The page manager at the heart of Carousel also provides support for framesets and page history management.
The page management function is separated from the application and from the individual pages to provide independence of the underlying widget set.
Navigation
In Carousel each page can be regarded as a discrete entity displayed by the application or applet. All pages must be derived from the basic XPage class and this class interacts with the XPageManager class to provide several methods of changing the displayed page. The page manager acts to maintain references to pages so that they do not need to be recreated whenever they are displayed, hidden or redisplayed.
In order to get a reference to the XPageManager for the current project the call below can be used.
Code Sample 16-1 - Retrieving the XPageManager for the current project
XProjectManager.getPageManager();
|
The main methods are showPage and showPrevious , which unsurprisingly show a new page and redisplay the previously selected page.
To invoke these methods it is necessary to add a way of initiating the navigation action. Normally this is accomplished by having a button or hostpot on the page with a text or graphic to indicate that a click will cause, say the next page to be displayed.
In the example below the user can initiate the navigation action by clicking on a button.
Code Sample 16-2 - Setting up the navigation button and response event
< XPage class= "myPackage.MyCustomPageClass" >
< Components >
...
< Button name= "btnProceed" x= "40" y= "10" w= "60" h= "20" content= "Proceed" />
< /Components >
< Events >
...
< Event method= "proceed" target= "btnProceed" type= "ActionHandler" />
< /Events >
|
The page must then implement the proceed response method. The XPage class contains a reference to the XPageManager for the current XProject and can be used directly from subclassed XPages as shown below:
Code Sample 16-3 - Implementing the response method
package myPackage;
import net.xoetrope.xui.*;
import net.xoetrope.swing.*;
import net.xoetrope.xui.data.*;
import net.xoetrope.xui.helper.*;
public class MyCustomPageClass extends XPage
{
public MyCustomPageClass()
{
}
...
public void proceed()
{
pageMgr.showPage( "Page2");
}
}
|
The page manager
The Carousel page manager provides a mechanism for loading and displaying pages. It takes care of managing the page's lifecycle so that you need not be concerned with when and how a page is loaded or destroyed.
When an application requests a page by calling the showPage method the actual loading of the page is delegated to the page manager. The page manager will then attempt to load an XML file corresponding by name to the requested page. If an XML file is not found then the page manager will attempt to load a Java class of that name (and failing that, a dummy page can be created).
The page manager also takes care of the page lifecycle, calling the pageCreated , pageActivated and pageDeactivated methods as appropriate.
As the pages are separated from one another and from the applet class through this page manager mechanism the pages can be loaded independently of each other (unless explicit links or references are inserted). Furthermore, as the page manager is also separate from the applet and the widget set it is possible to code a large variety of utility functions so that they can work with different widget sets such as Swing and AWT.
Showing a page
A few simple methods are provided to allow loading and display of pages. It is generally assumed that all page handling will be delegated to the page manager and this is the case whenever the XPage 's methods are used to display pages and this is the case for the normal response methods used in Carousel applications.
The showPage method simply takes the name of a page. An alternative form of the showPage method can also take a second parameter indicating the target area (but more on this later). The showPage method loads the page as described above and requests that the applet displays the page. Implicitly in this process any currently visible page is deactivated and hidden.
Once a page has been shown it is regarded as the current page and at any point the current page can be referenced by calling the page manager's getCurrentPage method.
Targets
Carousel supports the notion of framesets similar to those used in HTML. Like HTML the framesets in Carousel are defined in a separate frames file (pointed to by the startup properties file).
Each of the areas referenced by the frames file is known as a target area. Most of the page management methods include versions that take a target area name as a parameter and these functions affect the named area. Thus if you use the showPage method with a target area name, the area named in the method call is updated instead of the application's entire content area.
In cases where a frameset is used it is still possible to call the single argument versions of the page management functions. It is then assumed that the target area name defaults to 'content'.
Generally this default name works well where the frameset is being used to provide navigation facilities and other long lived facilities such as banners and footer. (see also "Framesets" on page 129 )
Page history
In addition to the showPage method Carousel also provides the showPrevious method. As a page is shown, the history/order of the displayed pages is saved and the showPrevious method allows you to reverse through this order of pages. The showPrevious method works in much the same way as showPage and in fact relies on the same mechanisms to update the application.
Page history should be used with caution as it does not necessarily correspond to the end user's notion of what the previous page was. Furthermore if the user has navigated through a loop of pages then over use of the showPrevious method could lead to confusion.
Frequently there may be a need for multiple navigation mechanisms to help avoid such situations. It may be that it is just the user's perception of the order of pages that is out of sync with the way things are implemented and therefore we recommend adding visual feedback to your application to help support navigation.
Visual feedback should let the user know where they are within the application, how far they have progressed and how far they have to go to completion. The type of feedback used will of course vary from application to application and will also depend on the visual styles employed but whatever the detail, such hints greatly aid usability.
Resetting the page cache
On rare occasions it may be necessary to reset the page cache and page history. Some instances of this occur whenever the bound data is changed or reloaded from a different source, when a language changes or when it is necessary to reset all pages, removing user inputs.
To reset the page cache in this way use the following code:
Code Sample 16-4 - Reset the page cache
// Use the XPage's member variable pageMgr!
pageMgr.reset();
|
Page loaders
Carousel employs an extensible method of loading pages. The page manager normally loads pages from XML or from Java classes if it cannot find a suitable XML page. This process can be altered by setting up a secondary page loader. The page loader is described by the XPageLoader interface and can be configured through the startup property value for BuilderClass.
Dataset defined navigation
When applications which use pages in a particular sequence are being written such as application forms consisting of multiple pages or wizard applications it is possible to define those pages in a static XML dataset file. For example in the code sample below, pages are defined within in a dataset file for a wizard type application.
This dataset file needs to be referenced from the datasources file which is in turn loaded from the ModelData startup property. For more on loading datasets see "Data management" on page 205. Once loaded, the application will have access to these definitions via the XModel for the project. There are three possible paths declared in this wizard dataset, 'wizardpages', 'generationpages' and 'buildpages'. The relevant path can be set upon clicking a button, a menu or seleting a radio button.
A singleton class can then be written which takes care of the navigation and of course the pages referenced by the value attribute of the model nodes need to exist on the classpath.
Code Sample 16-6 - NavigationManager Singleton class
public class NavigationManager {
XBaseModel navMdl;
protected int currentNode = 0;
BasePage currentPage;
private static NavigationManager navMgr;
|
private NavigationManager( String navPath ) {
navMdl = ( XBaseModel ) XProjectManager.getModel().get( "navigation/wizardpages" );
}
|
public static NavigationManager getInstance()
{
if ( navMgr == null )
navMgr = new NavigationManager()
return navMgr;
}
public static void next()
{
getInstance.showNextPage();
}
public static void prev()
{
getInstance.showPrevPage();
}
public void showPrevPage()
{
currentNode--;
showpage();
}
public void showNextPage()
{
if ( currentPage == null ) {
XBaseModel mdl = (XBaseModel) navMdl.get( currentNode );
String pagename = (String) mdl.get();
currentPage = (BasePage) XProjectManager.getPageManager().getPage( pagename );
}
if ( currentPage.checkValidations() == 0 ) {
currentNode++;
showpage();
}
}
public void showHomePage()
{
currentPage = null;
currentNode = 0;
XBaseModel mdl = (XBaseModel) navMdl.get( currentNode );
String pagename = (String) mdl.get();
currentPage = (BasePage) XProjectManager.getPageManager().showPage( pagename );
}
private void showpage()
{
XBaseModel mdl = ( XBaseModel ) navMdl.get( currentNode );
String pagename = ( String ) mdl.get();
currentPage = ( BasePage ) XProjectManager.getPageManager().showPage( pagename );
}
}
|
This mechanism can be used in conjunction with Library Functions to manage the page navigation in a simple and easy to maintain way. Take the following XML page declaration for example.
Code Sample 16-7 - A navigation page XML declaration
|
|
This code will call the static methods of the NavigationManager class and the NavigationManager will take care of presenting the correct page. Of course this can be extended to take care of multiple routes through an application or to repeat certain pages which will bind to different parts of the model and it should be obvious that pages can be added or rearranged without any difficulty.
If you were logged in you could rate this article or add a comment.
