Browser Navigation & History

As a RAP application usually runs in a browser, the user will expect that it behaves and navigates like a traditional website to a certain degree. It is easy to implement the layout of typical websites and web applications using RAP widgets (like TabFolder, List, Menu, etc.). However, some concepts, like history support, require special API.

Links

There are two kind of links supported in RAP.

First, there is the Link widget as implemented by SWT. This widget can display text that looks like it contains a link, but actually behaves like a push button. It's convenient to use this Widget to link between different places within your application. Combined with the URL-Launcher (see below), it can also be used like an actual link to open new websites.

Second, it is possible to integrate real links in the application using the markup feature. Clicking such a link will (by default) not trigger any events, but open the given URL in the same window. The user can also open the URL in a new browser tab or window (e.g. using the links native context menu), or the application can force the URL to be opened in a new tab/window by setting the target attribute to "_blank".

List list = new List( parent, style );
list.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
list.add( "This link opens <a href='http://eclipse.org/rap' target='_blank'>a new tab</a>" );

When embedding a link in List, Tree, or Table widgets, it may also be used to issue selection events instead of navigating to an URL. To do so, the target attribute must be set to "_rwt". If the link is clicked now, a Selection event will be fired. This event is different from ordinary Selection events in that the detail field equals RWT.HYPERLINK and the text field contains the value of the links "href" attribute. If no "href" attribute is set, the value is the text between "<a>" and "</a>". Note that some browser (specifically, Internet Explorer) may re-write the "href" value to an absolute URL if no protocol was given. One possible workaround is to start the "href" value with a "#" and cut of anything before that:

List list = new List( parent, style );
list.setData( RWT.MARKUP_ENABLED, Boolean.TRUE );
list.add( "Click <a href='#myvalue' target='_rwt'>here</a>" );
list.addListener( SWT.Selection, new Listener() {
  public void handleEvent( Event event ) {
    if( event.detail == RWT.HYPERLINK && event.text.contains( "#" ) ) {
      log( "Clicked link \"" + event.text.split( "#" )[ 1 ] + "\"" );
    }
  }
} );

Open URLs in an external browser/application

It is possible in RAP to programmatically open any URL without leaving the current page/session. This is done using the UrlLauncher client service. Any URL starting with http (or https) will open in a new browser tab, window, or pop-up, unless it is blocked by a pop-up blocker. (The browser will usually ask the user if he wants to allow the site to open new windows in general, just in this case, or never.) Other protocols like mailto or tel will not create a browser window, but might trigger another application to open, if one is installed. Examples:

UrlLauncher launcher = RWT.getClient().getService( UrlLauncher.class );
launcher.openURL( "http://www.eclipse.org/" );
launcher.openURL( RWT.getResourceManager().getLocation( "my-doc.pdf" ) );
launcher.openURL(   "mailto:someone@nowhere.org?cc=other@nowhere.org"
                  + "&subject=Hello%3F&body=RAP%20is%20awesome!" );
launcher.openURL( "tel:555-123456" );

Exit Confirmation

The ExitConfirmation service can configure a message that can be shown whenever the user tries to close the browser window/tab, or navigates to another URL. Example:

ExitConfirmation service = RWT.getClient().getService( ExitConfirmation.class );
service.setMessage( "Do you really wanna leave the party?" );

Result:

Exit confirmation dialog

NOTE: Some browser may show additional text in the confirmation dialog, or replace the text completely for security reasons.

Deep Links

Deep links, in traditional websites, are links that point not just to a document, but to a specific position within the document. This is done by adding a fragment id to the URL, separated from the path by a #. For example "http://eclipse.org/#midcolumn".

RAP provides the BrowserNavigation service, which allows the application to access this fragment. After the URL has been entered (or changed - see history support), a BrowserNavigationListener is called, and the fragment is available on the BrowserNavigationEvent via the getState(). The string can then be used to decide where to navigate in your application. If, for example, you are using a TabFolder as your main navigation element, a simple but complete implementation could look like this:

final Map<String, TabItem> navigation = new HashMap<String, TabItem>();
navigation.put( "employees", employeeTab );
navigation.put( "companies", companiesTab ); // etc...
BrowserNavigation service = RWT.getClient().getService( BrowserNavigation.class );
service.addBrowserNavigationListener( new BrowserNavigationListener() {
  @Override
  public void navigated( BrowserNavigationEvent event ) {
    TabItem item = navigation.get( event.getState() );
    if( item != null ) {
      item.getParent().setSelection( item );
    }
  }
} );

The application could then be opened directly at a specific tab using the URL http://myRapApp/#companies.
You could also encode a path within the fragment, pointing to a specific unit of data:

public void navigated( BrowserNavigationEvent event ) {
  String state = event.getState();
  if( state.startsWith( "employees/" ) ) {
    showEmpoyee( state.substring( 10 ) );
  }
}

Opening http://myRapApp/#employees/john.doe could then open the application already displaying the entry or search for John Doe.

Combined with "real" links or the URLLauncher, deep links provide additional ways to navigate within the session, or open new (parallel) UI sessions in additional browser tabs.

Browser History

Support for browser history means that the user is able to go back to a previous state of the application using the browsers back button, without leaving the RAP application itself. He/She can also use the browsers history dialog to jump multiple entries back or forwards.

If a BrowserNavigationListener is already implemented (see above), all that is left to do is to add new entries to the history. To do so, simply call pushState( state, title ) whenever your application enters a new state that should appear in the history. The state string will then be given in the BrowserNavigationEvent when the user presses the back button. The title string is used for the title of the document and will appear in the browsers history tab/dialog.

NOTE: Some browser have issues supporting history and the Browser widget in the same application. The back button may sometimes go back in the history of the browser widget and in the history of the RAP application simultaneously, or not at all. Also, in some browser the current URL will change when navigating, but not in all.