Browser's History Management

This documentation is for an older version of ZK. For the latest one, please click here.

This documentation is for an older version of ZK. For the latest one, please click here.

In traditional multi-page Web applications, user usually use the BACK and FORWARD button to surf around multiple pages, and bookmark them for later use. With ZK, you still can use multiple pages to represent different set of features and information, as you did in traditional Web applications.

However, it is common for ZK applications to represent a lot of features in one desktop, which usually take multiple Web pages in a traditional Web application. To make user's surfing easier, ZK supports the browser's history management that enables ZK applications to manage browser's history simply in the server.

The concept is simple. You add items for appropriate states of a desktop to the browser's history, and then users can use the BACK and FORWARD button to surf around different states of the same ZK desktop. When users surf around these states, an event called onBookmarkChange is sent to notify the application.

From application's viewpoint, it takes two steps to manage the browser's history:

1. Add an item to the browser's history for each of the appropriate states of your desktop.
2. Listen to the onBookmarkChange event and manipulate the desktop accordingly.

Add the Appropriate States to Browser's History

Your application has to decide what are the appropriate states to add to the browser's history. For example, in a multi-step operation, each state is a good candidate to add to browser's history, such that users can jump over these states or bookmark them for later use.

Once you decide when to add a state to the browser's history, you can simply invoke the setBookmark method of the Desktop interface when appropriate. Adding a state to the browser's history is called bookmarking. Notice that it is not the bookmarks that users add to the browser (aka., My Favorites in Internet Explorer).

Tip: You might call the adding state in the server as the server's bookmarks in contrast with the browser's bookmarks.

For example, assume you want to bookmark the state when the Next button is clicked, then you do as follows.

<button label="Next" onClick="desktop.setBookmark(&quot;Step-2&quot;)"/>

If you look carefully at the URL, you will find ZK appends #Step-2 to the URL.

If you press the BACK button, you will see as follows.

Listen to the onBookmarkChange Event and Manipulate the Desktop Accordingly

After adding a state to the browser's history, users can then surf among these states such as pressing the BACK button to return the previous state. When the state is changed, ZK will notify the application by broadcasting the onBookmarkChange event (an instance of the BookmarkEvent class) to all root components in the desktop.

Unlike traditional multi-page Web applications, you have to manipulate the ZK desktop manually when the state is changed. It is application developer's job to manipulate the desktop to reflect the state that a bookmark represented.

To listen the onBookmarkChange event, you can add an event listener to any page of the desktop, or to any of its root component.

<window onBookmarkChange="goto(event.bookmark)">
    <zscript>
     void goto(String bookmark) {
         if ("Step-2".equals(bookmark)) {
             ...//create components for Step 2
         } else { //empty bookmark
             ...//create components for Step 1
         }
    </zscript>
</window>

Like handling any other events, you can manipulate the desktop as you want, when the onBookmarkChange event is received. A typical approach is to use the createComponents method of the Executions class. In other words, you can represent each state with one ZUML page, and then use createComponents to create all components in it when onBookmarkChange is received.

 if ("Step-2".equals(bookmark)) {
     //1. Remove components, if any, representing the previous state
     try {
         self.getFellow("replacable").detach();
     } catch (ComponentNotFoundException ex) {
         //not created yet
     }

     //2. Creates components belonging to Step 2
     Executions.createComponents("/bk/step2.zul", self, null);
 }

A Simple Example

In this example, we bookmarks each tab selection.

<window id="wnd" title="Bookmark Demo" width="400px" border="normal">
    <zscript>
     page.addEventListener("onBookmarkChange",
         new EventListener() {
             public void onEvent(Event event) throws UiException {
                 try {
                     wnd.getFellow(wnd.desktop.bookmark).setSelected(true);
                 } catch (ComponentNotFoundException ex) {
                     tab1.setSelected(true);
                 }
             }
         });
    </zscript>

    <tabbox id="tbox" width="100%" onSelect="desktop.bookmark = self.selectedTab.id">
        <tabs>
            <tab id="tab1" label="Tab 1"/>
            <tab id="tab2" label="Tab 2"/>
            <tab id="tab3" label="Tab 3"/>
        </tabs>
        <tabpanels>
            <tabpanel>This is panel 1</tabpanel>
            <tabpanel>This is panel 2</tabpanel>
            <tabpanel>This is panel 3</tabpanel>
        </tabpanels>
    </tabbox>
</window>

Bookmarking with iframe

If a page contains one or more iframe components, it is sometimes better to bookmark the status of the iframe component, too. For example, when the contained iframe was navigated to another URL, you might want to change the bookmark of the page (the container), such that you can restore to the iframe to the right content. To do this, you have to listen to the onURIChange event as follows.

<window onURIChange="desktop.bookmark = storeURI(event.getTarget(), event.getURI())">
    <iframe src="${uri_depends_on_bookmark}" forward="onURIChange"/>
</window>