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".

When embedding a link in List, Tree, Table or Grid 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:

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
UrlLauncherclient 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:

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:

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.