Browser history

Consider what happens if you access the IBM® web site (https://www.ibm.com/in-en ) and then the IBM® Rational® Cafes (https://developer.ibm.com/). Two different web pages are provided from remote servers, and you can click the Back and Forward buttons in your browser to revisit each of the two sites. In contrast, the main processing in a Rich UI application is solely in your browser. The application may render new content and may even access the server for visual updates, but in most cases, the Back and Forward buttons are either disabled or direct processing to other website.

In Rich UI, you decide what on-screen content to identify as a separate web page. You enforce that decision by accessing functions in History, which is a Rich UI handler part provided with the product. By working with History, you can assign pages to the browser history at run time, and the user can use the Back and Forward buttons to access different pages in the application. Also, you can respond to the user's attempt to close the browser.

The browser-history mechanism does not save the state of a given web page. You need to code the behavior that makes sense for your application.

Setting up a browser history and event response

To set up the browser history and event response, do as follows:

In your Rich UI application, declare a Rich UI handler based on History, as in the following outline:
```
import com.ibm.egl.rui.history.History;
import com.ibm.egl.rui.history.HistoryChanged;
import com.ibm.egl.rui.history.OnBeforeUnloadMessageFunction;

Handler MyApplication Type RUIHandler { onConstructionFunction=start }
   myHistory History {};
end
```
By declaring a variable based on History, you add #empty to the web address displayed in the user's browser. In regard to subsequent processing, empty is the name of the new page. The new page is added to an application-specific browser history, but not to the browser's own history, which retains only the original web address.
In the on-construction function, for example, you can set up access to functions (event handlers) that run in response to specific user events:
- One such event is either adding a new page to the browser history or navigating to a different page. Later, we show how to add or move to a new page. First, we describe how to set up the event handler.
  To enable a custom response to a new-page event, invoke the addListener function and reference an event handler that you code. Here is an example invocation of the addListener function:
```
myHistory.addListener(myHistoryChanged);
```
  The following Delegate part outlines the characteristics of the referenced event handler:
```
Delegate
   HistoryChanged(newPageName String in)
end
```
  As shown, the event handler for the new-page event accepts a string. If you invoke addListener and reference a custom function, the custom function is invoked in the following cases: when the browser adds the initial page named empty, and when you add a subsequent page. In each case, the user's browser displays the web address and includes the page name, which is the address subset that is displayed subsequent to the pound sign (#); also, the EGL Runtime provides that page name to your function.
  Here is an example event handler that is invoked after a new-page event, with myLabel assumed to be a widget in the user display:
```
function myHistoryChanged(newPageName String in)
   myLabel.text = "History was changed. Current page name is "+ newPageName;
end
```
  You can register multiple new-page event handlers by running addListener multiple times. The referenced functions run in the order of registration. Even if you register the same function multiple times, all the registrations are in effect.
- A second event is the user's attempt to close the browser or browser tab.
  In this case, invoke the keepUserOnPage function and reference an event handler that you code. Here is an example invocation of the keepUserOnPage function:
```
history.keepUserOnPage(stayHere);
```
  The following Delegate part outlines the characteristics of the referenced event handler:
```
Delegate
   OnBeforeUnloadMessageFunction() returns(String)
end
```
  As shown, the event handler for the close-browser event returns a string. That string is displayed in a dialog box that lets the user confirm or reverse the browser close.
  Here is an example event handler that is invoked after a close-browser event:
```
function stayHere() returns(String)
		return ("Close the application?");
	end
```

Adding an entry to a browser history

You add an entry to the application-specific browser history by invoking the function addToHistory. The following example adds a page named myNewPage.

myHistory.addToHistory("myNewPage");

The implication is as follows:

The new-page event handler runs; in our example, the handler name is myHistoryChanged
If the user clicks the Back button, the web address in the browser includes the name of the previous page; and then, the Forward button is enabled, too.

Navigating to the previous page

You can navigate to the previous page in your application. Here is the example code:

myHistory.goBack();

The implication is as follows:

The new-page event handler runs; in our example, the handler name is myHistoryChanged
The web address in the browser changes, as appropriate
Subsequent navigation (forward and back) changes to reflect the new web address

Navigating to the next page

You can navigate to the next page in your application. Here is the example code:

myHistory.goForward();

The implication is as follows:

The new-page event handler runs; in our example, the handler name is myHistoryChanged
The web address in the browser changes, as appropriate
Subsequent navigation (forward and back) changes to reflect the new web address