History API
The History
API allows you to access the browser navigation history from the server side.
It also allows you to modify the navigation history by adding a new entry to it or changing the current entry.
For example, you can change the current URL shown in the browser address bar without invoking any navigation.
The history is always bound to the current browser window / frame, so you can access it through the Page
object (available through the UI
).
History history = UI.getCurrent().getPage().getHistory();
Traversing the History
With the methods forward()
, back()
and go(int)
, you can programmatically traverse the browser’s history entries.
The methods correspond to the user actions on the browser’s back and forward buttons.
history.back(); // navigates back to the previous entry
history.forward(); // navigates forward to the next entry
history.go(-2); // navigates back two entries
history.go(1); // equal to history.forward();
history.go(0); // reloads the current page
Note
|
Triggering the forward() , back() and go() methods asynchronously trigger a HistoryStateChangeEvent if the history entries are for the same document; for example, if the entries share the
same origin.
|
Handling User Navigation
If you want to manually handle navigation events, you can replace it by setting a handler for navigation events using history.setHistoryStateChangeHandler(HistoryStateChangeHandler)
.
It is notified when:
-
the user navigates back or forward using the browser buttons;
-
the navigation was done programmatically from server-side Java code or client-side JavaScript;
-
the user clicks a link marked with the
router-link
attribute.
history.setHistoryStateChangeHandler(this::onHistoryStateChange);
private void onHistoryStateChange(HistoryStateChangeEvent event) {
// site base url is www.abc.com/
// user navigates back from abc.com/dashboard to abc.com/home
event.getLocation().getPath(); // returns "home"
}
Note
| The server-side history state change event isn’t fired if only the hash has changed. Hash is always stripped from the location sent to server. Hash is a browser feature not intended for use on the server side. |
Changing History
You can update the history by either pushing new entries to the history, or by
replacing the current entry.
You may optionally provide a JSON value as the state parameter.
This state value is available via LocationChangeEvent:getState()
when the entry next visited.
// adds a new history entry for location "home", no state
history.pushState(null, "home");
// replaces the current entry with location "about" and a state object
JsonValue state = Json.create("preview-mode");
history.replaceState(state, "about");
Note
|
The URL used with pushState() and replaceState() must be for the same origin as the current URL.
Otherwise, browser throws an exception and the history isn’t updated.
|
Note
|
If you use either pushState() or replaceState() , the framework internal scroll position restoration on navigation doesn’t work, since it stores data in the history.state to keep track of the scroll position.
|
CDD7DD56-9749-4F4C-9126-9C984B65B066