Portal navigation and Back button behavior

With WebSphere Portal V5.1 users can now use the Back button of the browser to navigate back through the recent history of the views of the pages that they visited.

When a user navigates backwards by using the browser Back button, the portal restores the views of pages that the user visited recently. This behavior of the portal affects the following aspects of the pages:

  • The sequence by which the user navigated through the portal and selected the pages.

  • The expanded or collapsed state of the tree hierarchy that the navigation shows.

  • The lateral scrolling position of the register tabs that users can use to switch between pages.

  • The information of the user's default selection for a label. For example, this can be the information which page is selected for a label by default for that user. If the user selects a different page from that label, the portal displays that page as the default page for that label from then on.

  • The portlet window information that distinguishes between different instances of the same portlet on different pages.

  • Modifications of the view or window state of a portlet, such as the minimized, maximized, or normal or default state. For example, if a user views a portlet in its default view state, and then maximizes the portlet, clicking the Back button returns the portlet to its previous state, that is the portlet is displayed with its default size.

  • The portlet modes, such as view, edit, or configure modes.

  • The information as to whether a portlet is displayed in solo state, and which portlet is displayed in solo state.

  • The information as to whether the Show tools icons are displayed, for example the wrench icon for configuring the portlet.

  • If the portlet complies with the JSR 168 standard, the view state of the portlet is preserved as it is determined by the render parameters of the portlet. For detail about state changes to JSR 168 compliant portlets, refer to Using the Back button with JSR 168 portlets.

This means that using the Back button to return to a previously visited page, and then clicking a link on that page that has not been followed before will correctly preserve any of the settings. For an example, see Example scenario 1.

Terminology: The following terminology conventions are used for this topic:

  1. The terms view state and navigational state are used synonymously here. Render parameters in the sense of the JSR 168 standard also refers to the same.

  2. Everything that is said about the browser Back button here applies to the browser Forward button respectively.

  3. The browser Back button does not have an undo function. It interacts with the view or navigational state only, not with the application state.

 

User experience

Users can click the Back button of the browser as many times as the browser history mechanism allows. In such cases the markup comes from the history cache of the browser and is served without an additional request to the server. Users see exactly the same markup as they saw when they visited the page previously.

When users use the Back button to return to a page, they can use any link on that previously visited page to navigate further as follows:

  • If the link is only a render link and does not result in a portlet action, then no special case applies.

  • If the link is an action link and includes a portlet action, the behavior differs, depending on whether the user had already clicked the same action link during a previous visit to the page in the same session:

    • If the user has not clicked the action link previously, the portal performs the action.

    • If the user has already clicked the action link previously, then the portal displays the markup of the state that resulted from the last invocation of the action link. In other words, the portal does not perform the same action twice.

From an end user point of view the consequences of considering these parameters as view state are as follows:

  • Each different combination of states is part of the address of the page, that is its URL, and can be bookmarked. Users can set separate bookmarks for different states of the same page.

  • Users can use the Back button to navigate through modifications of the view states. For example, if a user maximized a portlet, the user can use the browser Back button to switch back to the previous window state of this portlet.

  • The effect of the Back button on interactions with individual portlets strongly depends on the implementation of the portlet. If the portlet implements its links as render links by changing render parameters on a per-link basis, then the Back button can be used to navigate through the history of the interactions with the portlet. This however is only possible for portlets written against the JSR 168 API. Changes made to portlets that are written to the IBM V4.x API are not influenced by the Back button.

 

Example scenarios

Example scenario 1: Maximizing or minimizing portlets

  1. The user views a page A with two portlets A1 and A2, both in their normal default window state.

  2. The user maximizes portlet A1.

  3. The user clicks the Back button. Portlet A1 is displayed in normal state again.

Example scenario 2: Switching between pages

  1. The user views a page A with two portlets A1 and A2, both in their normal default window state.
  2. The user maximizes portlet A1.
  3. The user selects page B. The portal displays page B.
  4. The user clicks the Back button. The portal returns to page A. Portlet A1 is displayed in maximized state.
  5. The user clicks the Back button once more. Portlet A1 is displayed in normal state again.

Example scenario 3: Different user action leads to same result.

Initial scenario and user actions:

  1. The user views a page A with a number of portlets on this page.
  2. The user interacts with the portlets.
  3. The user puts portlet A1 into edit mode.
  4. The user clicks A2 into minimized state.
  5. The user makes the document viewer portlet A3, which is a JSR 168 portlet, display page 2 of the document that it shows.
  6. Now the user switches to page B with portlet B1. Portlet B1 is displayed in normal state, view mode and in its default application state.
  7. The user minimizes portlet B1.

Despite different subsequent user actions, the following sub-scenarios have the same final outcome:

Scenario 3a: Using the Back button

  1. The user clicks the Back button. The portal displays portlet B1 in normal state.
  2. The user clicks the Back button once more. The portal changes to page A. It displays portlet A1 in edit mode and portlet A2 in minimized state. Portlet A3 shows page 2 of the document.

Scenario 3b: Making a new selection

  1. The user clicks page A in the navigation to "return" to page A. Conceptually this change is not considered a change back to page A, but forward to page A. As a result, the portal displays page A. It shows portlet A1 in edit mode and portlet A2 in minimized state. Portlet A3 shows page 2 of the document.

 

Set bookmarks

With WebSphere Portal V5.1 the user experience changes with respect to bookmarking a page: All state information except the portlet application state is bookmarked, for example render parameters, session state, window states and modes. The invocation of a bookmark resets the application state to the default state as defined by that bookmark.

Note: The user can set several independent bookmarks for different windows of the same page. Therefore the result of the previous example scenario is independent of other bookmarks that the user might have set on different window states of the same page.

Example scenario: Setting bookmarks

  1. The user selects a page A with portlets A1 and A2.
  2. The user maximizes portlet A1 and minimizes portlet A2.
  3. The user sets a bookmark on the page. The user names the bookmark A1min_A2max.
  4. The user logs out and logs back in.
  5. The user selects the bookmark A1min_A2max. The portal displays page A with portlet A1 maximized and portlet A2 minimized.

The user can set another separate bookmark A1Edit_A2Default on the same page A with portlet A1 in Edit mode and portlet A2 in its default state. Both bookmark will work independently of each other.

 

Considerations for administrators about Back button behavior

The Back button behavior of the portal is internally achieved by coding the combination of all states into the address of the view, that is into its URL. Thus each different combination of navigational states results in a different URL. This has the following additional advantages:

  • Users can set separate bookmarks for different states of the same page.
  • You can have pages cached by configuring specific requirements. For more details about how to do this, refer to Caching.

However, make no assumptions about the syntax or structure of portal URLs. For example, you cannot create valid URLs by simple concatenation. This will automatically be true if only the public API is used to create URLs. The latest version of the IBM Portlet API Javadoc is always available from the WebSphere Portal Product Documentation page.

 

Using the Back button with JSR 168 portlets

If a portlet complies to the JSR 168 standard, users can use the Back button to navigate backwards through the view states of that portlet as determined by the render parameters of the portlet. When the user clicks the Back button after working with that type of portlet, all information defined by the render parameters is reversed. There is no general rule as to which information is stored in cache as render parameters for a portlet. The effect of the Back button on interactions with individual portlets depends on the implementation of the portlet. This is determined by the person who developed the portlet.

For details about the JSR 168 standard and how to implement it, refer to the JSR 168 Portlet Specification.

If the portlet implements its links as render links by changing render parameters on a per-link basis, then users can use the Back button to navigate through the history of the interactions with the portlet. However, this is only possible for portlets written against the JSR 168 API. If a user navigates an IBM V4.x API portlet, clicking the Back button does not influence any changes that the user has made to the navigational state.

As a general rule, all information that influences the view of the portlet rather than its application state should be implemented as render parameters. For more details about how to develop JSR 168 compliant portlets for WebSphere Portal, see Best practices: Developing portlets using JSR 168 and WebSphere Portal.

 

Configure the history expiration limit for portal pages

You can configure the portal so that it discards the render parameters for pages that the user has not visited recently within the same session. The purpose of this setting is to limit the URL length. This might be of benefit for the performance of your portal. The portal discards the navigational state of the portlet application of JSR 168 portlets on pages that are too far back in the history.

You can specify the number of different page visits after which the history mechanism can discard the render parameters of the portlet. Your setting determines how far backwards users can at least navigate in the recent history of portal pages that they visited. The number that you specify defines the minimum number of different pages selected by the user after which the portal can discard the render parameters of a page. (The decision whether the render parameters of the page are actually discarded depends on the expiration policy of the internal cache that stores the render parameters of those pages.) If the user returns to a page after visiting the specified number of other pages and   if the render parameters of that page have expired, the portal displays that page in its default state.

You configure this expiration limit by setting the value for the property com.ibm.portal.state.keymanager.lru.size= (integer). This property is in the file StateManagerService.properties in the directory WP_ROOT/shared/app/config/services of your WebSphere Application Server installation. You can specify by which circumstances the render parameters of a page are stored or discarded:

1

Each time that the user selects a different page, the render parameters of the portlets on the previously selected page can be discarded.

A positive integer

Specify the required number of pages. The render parameters of a given page can be discarded after the user has visited that number of other pages.

0

Render parameters are always stored in the portal session memory and never discarded.

Note: Do not specify a value below zero ( 0 ). Negative values are considered to be not valid.

Example scenario: Configuring a limit to the history of viewed pages

  1. The configuration setting is set to a history value of 2.
  2. The portal pages A, B, and C contain separate instances of the JSR 168 compliant document viewer portlet A1, B1, and C1. Each of the portlets display page 1 of the same document on each page A, B, and C. This is the default for the portlet.
  3. The user selects portal page A and navigates to page 2 of the document in portlet A1.
  4. The user selects portal page B and navigates to page 3 of the document in portlet B1.
  5. The user selects portal page C and navigates to page 4 of the document in portlet C1.
  6. The user selects portal page B. Portlet B1 displays page 3 of the document as before.
  7. The user selects portal page C. Portlet C1 displays page 4 of the document as before.
  8. The user selects portal page A. Portlet A1 displays page 1 of the document because this is the default state for this portlet. The previous state has been discarded because it is back in the view history by 3 pages already, and thereby exceeds the configuration setting of only 2 pages.
  9. The user selects page C. Portlet C1 still displays page 4 as before as it is within the configured history value of two stored pages.

Configure the history setting might result in an inconsistent user experience, depending on the browser cache. If the user uses the Back button to navigate backwards rather than use explicit navigation, the user experience can be inconsistent if the user exceeds the configured view history size on the server. In this case the browser might display the portlets in their previous application state rather than the default state, because the markup is served from the client browser cache without a request to the server. However, if the view history has been exceeded, the server resets the portlet state to its default. Refreshing such a page displays the affected portlet in its default state rather than in the state that was displayed before the refresh operation. If you do not want to accept this behavior, set the size of the view history to the value 0 . This means that the portlet application state never expires.

 

View history limit influences only the navigational state of the application

The configured limit to the view history influences only the navigational state of portlet applications. It does not influence any of the following:

  • The portal view or navigational state.
  • The session state of a portlet application, that is any actions or transactions performed with the portlet.

Example scenario: View history limit influences only the navigational state of the application

  1. The configuration setting is set to a history value of 3.

  2. The user navigates to a shopping site.

  3. The user navigates through several views of pages and looks at various products.

  4. On a page X the user picks an item and puts it in the virtual shopping cart.

  5. The user navigates through four more page views and looks at more products.

  6. The user clicks the browser Back button four times to navigate backward to where the user placed the item in the shopping cart.

    The portal displays page X in its default state and not in the state in which the user has left it. The reason is that the page view is back in the history by 4 navigational steps already and thereby exceeds the configuration setting of 3 views.

    However, the product that the user wants to purchase is not removed from the shopping cart as that information is part of the session state of the application.

 

Known limitations

The following restrictions apply to backward navigability of portal pages.

 

The Back and Forward buttons have no undo or redo function

The browser Back and Forward buttons do not have an undo or redo function for actions or transactions performed by users. The portal marks completed actions by an internal identifier. If a user performs an action in a portlet and then navigates back to the same portlet panel by the Back or Forward buttons of the browser, the action is not performed once more.

For example, if a user initiates a money transfer or payment of a bill and then navigates further, clicking the Back and Forward buttons of the browser does not repeat the money transfer once again. An action is only performed once.

If a user wants to perform the same action again, the user can do so after refreshing the page. That portal marks that action with a different internal identifier. The protection against repeating the same action applies only to actions within the same markup fragment.

 

URL length limitation

In a browser, the possible length of a URL is limited to 2048 characters. This depends on the browser and its implementation. Reverse proxies usually have a length limit of 1024 characters for URLs. To circumvent this limit, you can keep the URLs shorter by configuring an expiration limit for pages that are too far back in the navigation history. For more details about how to do this, refer to Configure the history expiration limit for portal pages.

 

URL length limit on small devices

Small devices have a more severe length limit for URLs than browsers and proxies. For such small devices the complete view state is kept in the session on the server and is referenced by an ID in the URL. Therefore users cannot bookmark pages with their view state. However, they can use the Back button the same way as described above to navigate back to the same state of a page.

 

Structure of portal URLs

Do not make any assumptions about the syntax or structure of portal URLs. For example, you cannot create valid URLs by simple concatenation. This will automatically be true if only the public API is used to create URLs. The latest version of the IBM Portlet API Javadoc is always available from the WebSphere Portal Product Documentation page.

 

Troubleshoot and problem determination

Standard logging and tracing can be used to locate failure conditions related to Back button behavior within the server.

 

Problems with URLs that exceed the allowed length limit

If URLs exceed the allowed limit, the following problems can occur:

  • Depending on the browser, URL lengths exceeding 2048 characters might be ignored or rejected.

  • Depending on the reverse proxy infrastructure, URL lengths exceeding 1024 characters might break the reverse caches. This can lead to unpredictable results.

  • On small devices, such as portable phones, the following differences to browsers apply:

    • The portal reduces the long URLs that contain the navigational state. It caches the state on the server and sends only a state reference to the device. For example, this applies to WML devices, which only support URL up to a length of 100 characters. As the cache has only a limited size, the Back button works only work to a depth that depends on the cache size.

    • Users cannot use bookmarks on small client devices.

 

System load and usage

Depending on your configuration, system load on your portal can be influenced by the following ways:

  • The encoding of the portlet states in the URL of a page results in longer URLs. This might impact performance, especially in low-bandwidth networks.

  • Render parameters for JSR 168 portlets are encoded in the URL as a key only, but kept in full on the server. Depending on the number of portlet states stored on the server, session size and thereby memory consumption can grow significantly.

To alleviate this situation, set the history expiration limit for portal pages to a lower figure. For details about how to do this, refer to Configure the history expiration limit for portal pages.

 

Page history expiration limit can seem faulty

Depending on the limit configured for the view history of recently visited pages the portal behavior might be experienced by users as erroneous. However, this works as configured.

For example, if a user uses the browser Back button to navigate backwards through the history of recent views, the portal might restore only a limited number of view states that the user selected, and then return to the default settings for the preceding pages. This depends on the value specified for the com.ibm.portal.state.keymanager.lru.size property.

 

Bookmarks from previous versions of WebSphere Portal do not work

Browser bookmarks to pages from WebSphere Portal V5.0 do not work for V5.1. Users need to create their bookmarks new.

Server side bookmarks of the WebSphere Portal Favorites portlet are migrated automatically as you migrate to WebSphere Portal V5.1.

 

See also

Also, look for this resource on WebSphere Portal Zone:

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.