Browser History Management"

From Documentation
m (remove empty version history (via JWB))
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
 
 
=History Management with Bookmark=
 
=History Management with Bookmark=
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.
+
In traditional multi-page Web applications, users 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 sets 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 requires 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.
+
However, it is more common for ZK applications to represent a lot of features in one desktop, which usually requires 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 on the server.
  
The concept is simple. For each state of a desktop, you could add a so-called bookmark<ref>Each bookmark is an arbitrary string added to the browser's history.</ref> to the browser's history. Then, the user can use the BACK and FORWARD button of the browser to switch around different bookmarks. The change of books will be sent back to the server called <tt>onBookmarkChange</tt>, and you application can switch to the corresponding accordingly.
+
The concept is simple. For each state of a desktop, you could add a so-called bookmark<ref>Each bookmark is an arbitrary string added to the browser's history.</ref> to the browser's history. Then, the user can use the BACK and FORWARD button of the browser to switch around different bookmarks. The change of books will be sent back to the server called <code>onBookmarkChange</code>, and your application can switch to the corresponding accordingly.
  
 
From application's viewpoint, it takes two steps to manage the browser's history:
 
From application's viewpoint, it takes two steps to manage the browser's history:
  
 
# Add a bookmark to the browser's history for each of the visited states of your desktop.
 
# Add a bookmark to the browser's history for each of the visited states of your desktop.
# Listen to the <tt>onBookmarkChange</tt> event for bookmark change, and switch the state accordingly.
+
# Listen to the <code>onBookmarkChange</code> event for bookmark change, and switch the state accordingly.
  
 
<blockquote>
 
<blockquote>
Line 19: Line 18:
  
 
== Add Bookmarks to Browser's History ==
 
== Add Bookmarks 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 step is a good candidate of states for adding to browser's history, such that user can switch around these steps by pressing BACK or FORWARD buttons.
+
Your application has to decide what the appropriate states are to add to the browser's history. For example, in a multi-step operation, each step is a good candidate of states for adding to a browser's history, such that the user can switch around these steps by pressing the BACK or FORWARD buttons.
  
 
Once you decide when to add a state to the browser's history, you can simply invoke <javadoc method="setBookmark(java.lang.String)" type="interface">org.zkoss.zk.ui.Desktop</javadoc>. Notice that it is ''not'' the bookmarks that users add to the browser (aka., My Favorites in Internet Explorer).
 
Once you decide when to add a state to the browser's history, you can simply invoke <javadoc method="setBookmark(java.lang.String)" type="interface">org.zkoss.zk.ui.Desktop</javadoc>. Notice that it is ''not'' the bookmarks that users add to the browser (aka., My Favorites in Internet Explorer).
Line 29: Line 28:
 
</source>
 
</source>
  
If you look carefully at the URL, you will find ZK appends <tt>#Step-2</tt> to the URL.
+
If you look carefully at the URL, you will find ZK appends <code>#Step-2</code> to the URL.
  
 
If you press the BACK button, you will see as follows.
 
If you press the BACK button, you will see as follows.
Line 36: Line 35:
  
 
== Listen to onBookmarkChange and Change the State Accordingly ==
 
== Listen to onBookmarkChange and Change the State Accordingly ==
After adding a bookmark to the browser's history, users can then surf among these bookmarks such as pressing the BACK button to return the previous bookmark. When the bookmark is changed, ZK will notify the application by broadcasting the <tt>onBookmarkChange</tt> event (an instance of the <javadoc>org.zkoss.zk.ui.event.BookmarkEvent</javadoc> class) to all root components in the desktop.
+
After adding a bookmark to the browser's history, users can then surf among these bookmarks such as pressing the BACK button to return to the previous bookmark. When the bookmark is changed, ZK will notify the application by broadcasting the <code>onBookmarkChange</code> event (an instance of the <javadoc>org.zkoss.zk.ui.event.BookmarkEvent</javadoc> class) to all root components in the desktop.
  
Unlike traditional multi-page Web applications, you have to change the desktop's state at the server manually, when <tt>onBookmarkChange</tt> is received. ZK does nothing to allow an application to set a bookmark and notify for the bookmark change. It is application developer's job to manipulate the desktop to reflect the state that a bookmark represented.
+
Unlike traditional multi-page Web applications, you have to change the desktop's state on the server manually, when <code>onBookmarkChange</code> is received. ZK does nothing to allow an application to set a bookmark and notify for the bookmark change. It is the application developer's job to manipulate the desktop to reflect the state that a bookmark has represented.
  
To listen the <tt>onBookmarkChange</tt> event, you can add an event listener to any page of the desktop, or to any of its root component.
+
To listen to the <code>onBookmarkChange</code> event, you can add an event listener to any pages of the desktop, or to any of its root components.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 55: Line 54:
 
</source>
 
</source>
  
Like handling any other events, you can manipulate the UI an way you want, when the <tt>onBookmarkChange</tt> event is received. It is totally up to you.
+
Like handling any other events, you can manipulate the UI any way you want, when the <code>onBookmarkChange</code> event is received. It is totally up to you.
  
A typical approach is to use one of the <tt>createComponents</tt> methods of the <javadoc>org.zkoss.zk.ui.Executions</javadoc> class. In other words, you could represent each state with one ZUML page, and then use <tt>createComponents</tt> to create all components in it when <tt>onBookmarkChange</tt> is received.
+
A typical approach is to use one of the <code>createComponents</code> methods of the <javadoc>org.zkoss.zk.ui.Executions</javadoc> class. In other words, you could represent each state with one ZUML page, and then use <code>createComponents</code> to create all components in it when <code>onBookmarkChange</code> is received.
  
 
<source lang="java" >
 
<source lang="java" >
Line 68: Line 67:
 
     }
 
     }
  
     //2. Creates components belonging to Step 2
+
     //2. Create components belonging to Step 2
 
     Executions.createComponents("/bk/step2.zul", self, null);
 
     Executions.createComponents("/bk/step2.zul", self, null);
 
  }
 
  }
Line 74: Line 73:
  
 
= Example =
 
= Example =
In this example, we bookmarks each tab selection.
+
In this example, we bookmark each tab selection.
  
 
<source lang="xml" >
 
<source lang="xml" >
 
<window id="wnd" title="Bookmark Demo" width="400px" border="normal">
 
<window id="wnd" title="Bookmark Demo" width="400px" border="normal">
 
     <zscript>
 
     <zscript>
     page.addEventListener("onBookmarkChange",
+
     page.addEventListener(Events.ON_BOOKMARK_CHANGE,
 
         new EventListener() {
 
         new EventListener() {
 
             public void onEvent(Event event) throws UiException {
 
             public void onEvent(Event event) throws UiException {
Line 107: Line 106:
  
 
= Bookmarking with iframe =
 
= Bookmarking with iframe =
If a page contains one or more <tt>iframe</tt> components, it is sometimes better to bookmark the status of the <tt>iframe</tt> component, too. For example, when the contained <tt>iframe</tt> was navigated to another URL, you might want to change the bookmark of the page (the container), such that you can restore to the <tt>iframe</tt> to the right content. To do this, you have to listen to the <tt>onURIChange</tt> event as follows.
+
If a page contains one or more <code>iframe</code> components, it is sometimes better to bookmark the status of the <code>iframe</code> components too. For example, when the contained <code>iframe</code> is navigated to another URL, you might want to change the bookmark of the page (the container), such that you can restore to the <code>iframe</code> to the right content. To do this, you have to listen to the <code>onURIChange</code> event as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 115: Line 114:
 
</source>
 
</source>
  
The <tt>onURIChange</tt> event is sent as an instance of <javadoc>org.zkoss.zk.ui.event.URIEvent</javadoc>.
+
The <code>onURIChange</code> event is sent as an instance of <javadoc>org.zkoss.zk.ui.event.URIEvent</javadoc>.
 +
 
 +
Notice that the <code>onURIChange</code> event is sent only if the iframe contains another ZK page. If it contains a non-ZK page, you have to handle it manually. Please refer to [[ZK_Component_Reference/Essential_Components/Iframe#Integrate_with_Other_Technologies|ZK Component Reference: iframe]] for more information.
  
Notice that the <tt>onURIChange</tt> event is sent only if the iframe contains another ZK page. If it contains non-ZK page, you have to handle it manually. Please refer to [[ZK_Component_Reference/Essential_Components/Iframe#Integrate_with_Other_Technologies|ZK Component Reference: iframe]] for more information.
 
  
=Version History=
 
{{LastUpdated}}
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
|-
 
| &nbsp;
 
| &nbsp;
 
| &nbsp;
 
|}
 
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 05:54, 6 February 2024


Browser History Management


History Management with Bookmark

In traditional multi-page Web applications, users 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 sets of features and information, as you did in traditional Web applications.

However, it is more common for ZK applications to represent a lot of features in one desktop, which usually requires 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 on the server.

The concept is simple. For each state of a desktop, you could add a so-called bookmark[1] to the browser's history. Then, the user can use the BACK and FORWARD button of the browser to switch around different bookmarks. The change of books will be sent back to the server called onBookmarkChange, and your application can switch to the corresponding accordingly.

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

  1. Add a bookmark to the browser's history for each of the visited states of your desktop.
  2. Listen to the onBookmarkChange event for bookmark change, and switch the state accordingly.

  1. Each bookmark is an arbitrary string added to the browser's history.

Add Bookmarks to Browser's History

Your application has to decide what the appropriate states are to add to the browser's history. For example, in a multi-step operation, each step is a good candidate of states for adding to a browser's history, such that the user can switch around these steps by pressing the BACK or FORWARD buttons.

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

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("Step-2")'/>

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.

1000000000000284000000226A7DEE65.png

Listen to onBookmarkChange and Change the State Accordingly

After adding a bookmark to the browser's history, users can then surf among these bookmarks such as pressing the BACK button to return to the previous bookmark. When the bookmark 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 change the desktop's state on the server manually, when onBookmarkChange is received. ZK does nothing to allow an application to set a bookmark and notify for the bookmark change. It is the application developer's job to manipulate the desktop to reflect the state that a bookmark has represented.

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

<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 UI any way you want, when the onBookmarkChange event is received. It is totally up to you.

A typical approach is to use one of the createComponents methods of the Executions class. In other words, you could 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. Create components belonging to Step 2
     Executions.createComponents("/bk/step2.zul", self, null);
 }

Example

In this example, we bookmark each tab selection.

<window id="wnd" title="Bookmark Demo" width="400px" border="normal">
    <zscript>
     page.addEventListener(Events.ON_BOOKMARK_CHANGE,
         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 components too. For example, when the contained iframe is 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>

The onURIChange event is sent as an instance of URIEvent.

Notice that the onURIChange event is sent only if the iframe contains another ZK page. If it contains a non-ZK page, you have to handle it manually. Please refer to ZK Component Reference: iframe for more information.




Last Update : 2024/02/06

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.