Resetting State of IBM Web Experience Factory portlets

Introduction

IBM® Web Experience Factory (formerly WebSphere® Portlet Factory) is a powerful and flexible development tool that allows developers to rapidly build, customize, and deploy portlets to IBM WebSphere Portal. As a user navigates across various portal pages, WebSphere Portal server maintains the current state of the Web Experience Factory portlets and caches their view state.

Returning users might come to a previously visited page, either using portal page navigation from the theme or through wiring, links from other portlets, or through some other navigation mechanism. When users return to a previously visited page, they are presented with a cached view of the portlet.

Each portlet's state is independently maintained by WebSphere Portal so that, when a user navigates away from a portal page and then later returns, the portlet's state is persisted across page views. This is the default WebSphere Portal and Web Experience Factory behavior, and the cached view for the various portlets is cleared only when the user logs out and logs back in.

In some cases, however, a portlet project may present the developer with a requirement to consistently display a Web Experience Factory portlet, using a page view that reflects a portlet's initial visual state. For these use cases, it is desirable to override the default WebSphere Portal and Web Experience Factory behavior by displaying portlet page views that ignore the portlet's cached state.

This article explains the detailed steps to achieve this scenario in a Web Experience Factory portlet and briefly describes additional strategies to achieve a similar outcome, using a sample solution to guide you through these steps.

To get the most from the article, you should have the experience necessary to deploy portlets in WebSphere Portal, have already reviewed the Web Experience Factory wiki, and have basic knowledge of developing portlets using Web Experience Factory.

Defining terms

Builder. At the core of Web Experience Factory Designer is a set of software automation components called Builders. These Builders capture design intelligence through easy-to-use, wizard-like user interfaces that automate the creation of code.

The use of Builders greatly speeds up the development process of JSR 286-compliant portlets by masking the complexities of the underlying APIs.

Model. A Web Experience Factory Model is an application artifact used to group a set of Builders that are responsible for generating the application code that governs the behavior, structure, and presentation of your portlet application.

Event Handler Builder. An Event Handler Builder specifies an action to perform in response to a specified event. It is used to handle any events that you declare, using either an Event Declaration Builder, or one of the following Automation Engine events: OnWebAppLoad, OnPageLoad, OnRequest, and OnUnHandledError.

Linked JavaTM Object Builder (LJO Builder). This Builder adds the public methods of a Java class to a Web application and can be used to either incorporate existing Java code or to create new Java classes. LJO Builder calls provide a convenient means to consolidate commonly used methods into a single, easily re-used Java class.

Solution description

The sample solution we use here is based on the following key aspects of WebSphere Portal and Web Experience Factory:

Request Types. By identifying the type of incoming portlet request that a portlet receives, we can determine whether or not a portlet needs to reset itself and clear the previously cached visual state. Common portlet request types include “Action Request”, “Render Request”, and “Resource Request”.

When a user performs an action on a portlet, the resulting portlet request will be either an Action Request followed by a Render Request, or a Resource Request, depending on whether Smart Refresh/Ajax is being used.

When a user has previously visited the portlet and then returns to this portlet by using either a Portal Navigation link in the theme, a link provided by another portlet, or by any other mechanism, then the resulting request type will be a Render Request.

Web Experience Factory portlets present the developer with the following two opportunities for handling returning users.

• Case 1: When the Smart Refresh/Ajax is used. Any user action within the portlet results in a Resource Request. In this case, we can reset the model when the request type is Render Request.

• Case 2: When the Smart Refresh/Ajax is not used. Any user action within the portlet results in an Action Request, followed by a Render Request. In this case, we avoid resetting the model when the user action triggers an Action Request followed by a Render Request. We reset portlet state for all other cases when a Render Request is presented.

OnRequest Event. The Event Handler Builder can be used to respond to the OnRequest Event in a Web Experience Factory model. We can determine the request type in the OnRequest Event Handler and, if it is a Render Request, it is appropriate to reset the portlet state by taking the required actions to reset the portlet to initial state.

The logic to reset the model could be a combination of the request Type and some other condition, depending on the portlet’s use cases. The basic steps to reset a model involve redirecting the user to the landing page of the model, clearing the data fields, and performing any other dependent tasks necessary for the model to run in a cleared state.

These steps ensure that the portlet behaves as if it is running for the first time for a returning user, without the need to re-log in to the portal.

Creating the HandleUICachePortlet

In this section, we explain the details of the portlet creation steps.

Creating a Web Experience Factory project

Open the Web Experience Factory Designer by starting Eclipse. Make sure that you are in the WebSphere Portlet Factory perspective. If you are not in this perspective, then select Window --- Open Perspective --- Other --- WebSphere Portlet Factory, from the Eclipse menu.

To create the Web Experience Factory project, follow these steps:

1. Select File --- New --- WebSphere Portlet Factory Project (see figure 1).

Figure 1. New Project window



2. Name the project HandleUICache, and click Next.
3. In the Feature Set page window (see figure 2) click Next again.

Figure 2. Feature Set page window



4. In the Server configuration window (see figure 3), select “IBM WebSphere Application Server and Portal Server 7.x” for the Server Type, to deploy the model as WebSphere Portal. If this server type is unavailable, click the Create Server Configuration button to add it. Click Finish.

NOTE: The WebSphere Portal server must running at this time. Also, we choose Portal Server for deployment since the project is using portlet request types, and it cannot run on any non-portal runtime.

Figure 3. Server configuration window



5. Finally, when asked “Would you like to publish your project now?”, answer No.

Creating a new model

To create the model, follow these steps:

1. Right-click the newly created project and select New --- WebSphere Portlet Factory Model.
2. Select HandleUICache in the Choose Project window; click Next.
3. Select Empty from the Select Model window; click Next.
4. In the Save New Model window, name the model as HandleUICache and click Finish.

Adding a landing page, a secondary page, and main ActionList

To do this:

1. In the Outline section, click the plus-sign icon, to add a builder to the model (see figure 4).

Figure 4. Outline section



2. Under Category name, select All; under Builder, select Page; and name the builder LandingPage (see figure 5).

Figure 5. Builder Picker window


3. In the Page Contents section of the LandingPage (figure 6), paste in the code shown in listing 1.

Listing 1. Page Contents code

Figure 6. LandingPage



4. Save the model. The page now contains spans that will be used to place an input text field and a button.
5. Once again in the Outline section, click the plus sign icon, to add a builder to the model.
6. Under Category name, select All; under Builder, select Action List; and name the builder “main” (see figure 7).
7. Keep the Return Type field as void, and leave the ActionList section blank.

Figure 7. main builder



8. Save the model, which now contains a main ActionList and a default page. Add another page as we did above and name it SecondaryPage (see figure 8); in the Page Contents section add the code in listing 2 and save the model.

Listing 2. Page Contents code

Figure 8. SecondaryPage



9. Add a Text Input builder to the model and name it LandingPageInput. In the Page Location section, choose “LandingPage” in the Page field, and “myInputField” in the Tag field, as shown in figure 9.

Figure 9. LandingPageInput builder



10. Now add a Button builder to the model and name it NextPageAction. In the Page Location section choose “LandingPage” in the Page field, and “myNextButton” for Tag. Choose “Submit form and invoke action” as the Action Type, and “SecondaryPage” as the Action (see figure 10).

Figure 10. NextPageAction builder

Adding builders and Java class to handle the UI Cache

Next we add builders and a Java class to enable handling of the UI Cache and to enable resetting the model. Let's add a Boolean variable; specifically, add a Variable builder to the model and name it “ignoreReset”; enter “Boolean” as the Type, and “false” as the Initial Value (see figure 11).

Figure 11. ignoreRest builder



This Boolean variable is used to avoid resetting the model when Smart Refresh/Ajax is not being used and a user action causes an Action Request followed by a Render Request. This handling is not required when Smart Refresh/Ajax is used.

Now let's add a Java class with two utility methods to the project:

1. Right-click on the project and select New --- Class.
2. Enter com.ibm.util in the Package field, and HandlePortletCacheUtil in the Name field (see figure 12); click Finish.

Figure 12. New Java Class window


3. Replace the contents of the Java class with the code in listing 3.

Listing 3. Code to replace Java class
4. Add an LJO builder to the model, naming it HandlePortletCacheUtilLJO and entering com.ibm.util.HandlePortletCacheUtil for the Class Name; save the model (see figure 13).

Figure 13. HandlePortletCacheUtilLJO builder


5. Add the EventHandler builder that will contain the logic to reset the model, naming it HandlePortletRequestEvent and selecting System:OnRequest for the Event Name. In the Return Type field, choose void, and for the ActionList provide the inputs shown in listing 4 in sequence; save (see figure 14).

Listing 4. ActionList inputs

The Event Handler builder will look like figure 14.

Figure 14. Event Handler builder



The Event Handler builder will listen to the OnRequest event and will do a model reset, only if the ignoreReset variable is false and the Portlet Request type is Render Request.

The LJO methods are used in the Event Handler ActionList to determine the type of Portlet Request and then to change the Model Page to Landing page.

Depending on the use case, any logic to clear the datapage variables, other variables, and any other logic required to successfully run the LandingPage, should be present here.

Now let's add a Portlet Adapter builder and publish the project to the server:

1. For both the Name and the Portlet Title fields, enter HandleUICache (see figure 15).

Figure 15. HandleUICache builder
.


2. Save the model and publish the project on the server. The Outline view of the model will look like figure 16.

Figure 16. Outline view

Testing the Upload Documents portlet

To do this:

1. Go to Portal Administration --- Manage Pages, and create a test page to place in this portlet.
2. Search for HandleUICache as the Portlet Name and place the portlet on a Portal page.
3. Go to the Portal page where the portlet was deployed; it should look similar to figure 17.

Figure 17. HandleUICache portlet


4. Click the NextPage button and you should get the secondary page (see figure 18).

Figure 18. Secondary page

5. Now go to another Portal page and then return to the same page that has the HandleUICache portlet, using Portal Navigation in the theme; you should now see the landing page (recall figure 17) instead of the secondary page that was visited earlier.

Other possible solutions

(1) For a page that needs to have the functionality we've just created, the URL should use the parameter keepNavigationalState set to false, and the same should be used to come to this page. For more information, refer to the WebSphere Portal info center topic, “<portal-navigation/> tags.”

(2) By finding out when a user transitions between portal pages, we can determine whether or not the portlet needs to reset itself. We can do this by keeping the IDs of the previous portal page and the current portal page, and then each portlet for which we want to reset the state would need to use something like an OnRequest Event Handler to be notified of every request made to that portlet.

The Portlet could then examine the current portal page and the previous portal page and determine whether a page transition has occurred; if it has, the portlet could then handle resetting itself back to the initial page.

Conclusion

In this article, you learned how to build a portlet with Web Experience Factory that can override the default WebSphere Portal behavior, is able to reset itself for a returning user, and not maintain its state.

Resources

developerWorks® IBM Web Experience Factory product page:
http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/

IBM Web Experience discussion forum:
http://www-01.ibm.com/support/docview.wss?rs=3044&uid=swg27011853

IBM WebSphere Portal infocenter:
http://www.ibm.com/developerworks/websphere/zones/portal/proddoc/index.html#v70proddocwiki

About the author

Animesh Sharma is a WebSphere Portal Specialist with IBM India Software Labs, currently working for the Lab Services division. He specializes in WebSphere Portal, IBM Mobile Portal Accelerator, IBM Web Experience Factory, and IBM Web Content Manager, and participates in various customer-facing engagements. You can reach Animesh at animshar@in.ibm.com.