JSR 168: Portlet Modes and Portlet States

bySherwood Zern
09/21/2004
The JSR 168 specification, also known as the Portlet specification, defines portlet modes and portlet states. In accordance with the portlet specification, WebLogic Portal 8.1 adheres to the behavior defined by the specification for these respective items. In an effort to assist with the understanding of these items, the following information will define what is meant by mode, states, and how to get the functionality desired by the business community.
Portlet Modes vs. Portlet States
Portlet Modes
A portlet mode indicates the function a portlet is performing. Normally, portlets perform different tasks and create different content depending on the function they are currently performing. A portlet mode advises the portlet what task it should perform and what content it should generate. There are three defined modes: view, edit, and help. It is only when a portlet is changing a mode that the content being displayed within the portlet is modified.
View: The expected functionality for a portlet in VIEW portlet mode is to generate markup reflecting the current state of the portlet. For example, the VIEW portlet mode of a portlet may include one or more screens that the user can navigate and interact with, or it may consist of static content that does not require any user interaction. Edit: Within the EDIT portlet mode, a portlet should provide content and logic that lets a user customize the behavior of the portlet. The EDIT portlet mode may include one or more screens among which users can navigate to enter their customization data. Help: When in HELP portlet mode, a portlet should provide help information about the portlet. This help information could be a simple help screen explaining the entire portlet in coherent text or it could be context-sensitive help. Custom Portlet Mode: These are modes that provide a specific piece of functionality, in addition to the standard modes. The portlet custom mode is an optional feature when implementing the Portlet specification. The decision to provide this feature is purely a vendor decision. A vendor can still be JSR 168 compliant even if this feature is not made available.
WebLogic Portal 8.1 implements all of the standard modes and also provides a means to create one or more custom modes for portlets. The creation of custom modes will be discussed below.
Portlet States
A window state is an indicator of the amount of portal page space that will be assigned to the content generated by a portlet. When invoking a portlet, the portlet container provides the current window state to the portlet. The portlet may use the window state to decide how much information it should render. There are three portlet states defined: normal, maximized, and minimized. Therefore, when the portlet changes state it is only the view size that will be modified — not the contents of the portlet. The definitions given below are from the portlet specification. Remember: these are specifications, and the implementation is entirely up to the vendor.
Normal: The NORMAL window state indicates that a portlet may be sharing the page with other portlets. It may also indicate that the target device has limited display capabilities. Therefore, a portlet should restrict the size of its rendered output in this window state. Maximized: The MAXIMIZED window state is an indication that a portlet may be the only portlet being rendered in the portal page, or that the portlet has more space compared to other portlets in the portal page. A portlet may generate richer content when its window state is MAXIMIZED. Minimized: When a portlet is in MINIMIZED window state, the portlet should only render minimal output or no output at all. Custom Portlet States: These are states that provide additional functionality in addition to the standard states. For instance, a state could be defined that forces a portlet to take up to 75 percent of the portal page when invoked. The portlet custom state is an optional feature when implementing the Portlet specification. The decision to provide this feature is purely a vendor decision. A vendor can still be JSR 168 compliant even if this feature is not made available.
WebLogic Portal 8.1 implements all of the standard states. At the time of this writing, the Portal product does not allow the creation of portlet custom states.
WebLogic Portal 8.1 SP2
BEA WebLogic Portal implements the portlet specification within the portal framework and adheres to the definition for portlet states and portlet modes. Therefore, the issue regarding only one maximized portlet on a portal page is driven by BEA‘s implementation of the portlet specification. In addition, since the maximization of a portlet is a state change and not a mode change, the content of the portlet will remain as it was in its maximized state.
The WebLogic Portal product does provide a means to implement the desired behavior of modifying the contents of the portlet when modifying the state of the portlet. The means to accomplish this feat is by using the components provided by the portal framework and by taking advantage of the portlet modes and portlet states. The components available to the developer are Java classes known as backing files, the Java Page flow, the XML file - .portlet, and the netuix tag library. The information to follow will outline how to utilize custom modes, which are also part of the Portlet specification, and the previously mentioned components to implement the desired behavior.
1. Define custom modes in the .portlet file. Manually open the XML file within your favorite editor and declare the custom modes with the use of the netuix tag library. The sample shown below identifies two custom modes, RestoreMode and MaximizeMode.

We just declared two custom modes, RestoreMode and MaximizeMode. The Java page flow to be executed for both of the modes is portlets.helloWorld.HelloWorldController. However, the declaration defines two different actions, restore and maximize. The declaration utilizes the visible parameter to prevent a toggle button from displaying on the portlet title bar. The only means of invoking these modes is programmatically.
2. Next the Java page flow needs to be developed so when the mode is requested, the Java page flow is executed. The code sample given below is very basic; however, there is enough there to deliver the message.
/** * @jpf:action * @jpf:forward name="success" path="normalview.jsp" */ protected Forward restore() { System.out.println("Executing the restore"); System.out.println("Say " + helloCtrl.sayHello()); return new Forward("success"); } /** * @jpf:action * @jpf:forward name="success" path="index.jsp" */ protected Forward maximize() { return new Forward("success"); }
3. Now a backing file needs to be developed and assigned to the portlet. The backing file is important to determine the current mode and the current portlet state. By identifying these very important aspects of the portlet then a determination can be made on whether or not to change modes. The entire implementation of the backing file is given below.
public class MaxBacking extends AbstractJspBacking { public boolean handlePostbackData(HttpServletRequest request, HttpServletResponse response) { PortletBackingContext pbc = PortletBackingContext.getPortletBackingContext(request); // Remember this is the current state, not the state I want to switch too if (isMaximizeView(pbc)) { pbc.setupModeChangeEvent("RestoreMode"); } else { if (isNormalView(pbc)) { if (isSwitchToMaximizeView(request)) { pbc.setupModeChangeEvent("MaximizeMode"); } } } return true; } public boolean preRender(HttpServletRequest request, HttpServletResponse response) { return true; } protected boolean isNormalView(PortletBackingContext portlet) { WindowState state = portlet.getWindowState(); return (WindowCapabilities.NORMAL.getName().equals(state.getName())); } protected boolean isMaximizeView(PortletBackingContext portlet) { WindowState state = portlet.getWindowState(); return (WindowCapabilities.MAXIMIZED.getName().equals(state.getName())); } protected boolean isSwitchToNormalView(HttpServletRequest request) { if (isRequestTargeted(request)) { HttpServletRequest outerRequest = ScopedServletUtils.getOuterRequest(request); String state = outerRequest.getParameter("_state"); return (WindowCapabilities.NORMAL.getName().equals(state)); } return false; } protected boolean isSwitchToMaximizeView(HttpServletRequest request) { if (isRequestTargeted(request)) { HttpServletRequest outerRequest = ScopedServletUtils.getOuterRequest(request); String state = outerRequest.getParameter("_state"); return (WindowCapabilities.MAXIMIZED.getName().equals(state)); } return false; } private String getCurrentModeAndState(PortletBackingContext portlet) { String state = portlet.getWindowState().getName(); String mode = portlet.getWindowMode().getName(); return "Mode: " + mode + " State: " + state; } }
4. The last item is to associate the backing file with the portlet.
So, what is going to happen when all of this is implemented as written? When the visitor selects the maximize button on the portlet, the portlet is targeted and would therefore need to respond with itself in maximized state. However, with the custom mode defined and the backing file associated a couple of other actions are also invoked.
The backing file‘s handlePostbackData is eventually called and it verifies its current state. It determines that is in view mode and a normal state; however, it is being requested to modify its state. Therefore, the implementation of the backing file forces a mode change to MaximizeMode, which forces the execution of the Java page flow maximize method. This will in turn modify the contents of the portlet.
When the restore button is selected from the portlet title bar the same scenarios is invoked; however, this time the mode change to RestoreMode is requested. This invokes the Java page flow‘s restore method to be executed.
Conclusion
With the many components provided by WebLogic Portal, it is very easy to get the behavior one desires. The custom modes may be implemented with a Java page flow or just a standard JSP defined as the content URI. The implementation of a backing file is necessary to implement the portlet custom mode features discussed above. In addition, when dealing with non-JPF portlets, it is necessary to handle pre-rendering functionality. The backing file is a perfect place to do this.