Changing a portlet title at run time in WebSphere Portal V6

This tip shows how to leverage the JSR 168 dynamic title programming model with IBM® WebSphere® Portal V6. You learn the pros and cons of using static and dynamic titles, and how to avoid performance impacts that can be incurred when using dynamic titles.

Portlet developers can use dynamic titles to personalize their portlets for their users. For example, you could add the current user name, such as "Birga's bookmarks", or you could show the user's local timezone, such as "Eastern Time (US & Canada)".

You can also download a working sample portlet to see it changes the title during run time.

This article is for portlet programmers and Web administrators who are familiar with the Java Portlet API (JSR 168). See Resources for links to information that can help you gain those skills.

[@more@]

Introduction

Portal users are accustomed to seeing portlet content embedded within a window frame. A bar on top of this frame displays the title for the portlet content and provides control icons that the user can click to change the portlet mode or window state. WebSphere Portal V6.0 defines the layout and controls for this title bar in a portal skin. The WebSphere Portal default skin displays the portlet title that is configured for the portlet in its portlet.xml.

Figure 1 shows the WorldClock portlet example which you can download. The WorldClock portlet defines the portlet title in its portlet deployment descriptor to be "Standard World Clock", as shown in Figure 1.

Figure 1. Title bar displaying the portlet title

WebSphere Portal V6 offers a variety of ways to change the look and feel of the title bar by customizing the portal skin. In this tip, you learn how to update the portal skin to enable dynamic portlet title support so you change the title during run time. This technique uses the WebSphere Portal V6.0 extended programming model and its support for portlet titles.

This article is intended for administrators and developers who want to add dynamic title support for WebSphere Portal V6.0.

About the sample

Attached to this article is a sample JSR 168 portlet that sets a title during run time. You can downloadthis World Clock example, and use it to see how to enable dynamic title support as you read this article. For a detailed description of the sample, see this article “Converting the WorldClock portlet from the IBM Portlet API to the JSR 168 portlet API “ (see Resources) .

Comparing static and dynamic portlet titles

To understand the portlet title support, you need to first understand portal page aggregation. Let’s review how portal pages are rendered.

A portal begins the render process with a theme to display page headings and decorations. Usually, a navigation tree is included to enable the user to easily manage and navigate through the portal’s pages. Page rendering continues by displaying a layout for the currently selected page and its portlets. Each portlet is rendered with the decoration and controls provided by a portlet skin. This skin usually provides a title bar and some control icons to embed the portlet into a window frame. You see a common portal page structure in Figure 2.

Figure 2. A typical portal page structure

For WebSphere Portal, the portlet window frame is defined by the portlet skin, which manages the title bar (for example). The default skin is control.jsp, located in installedAppswps.earwps.warskinshtmlIBM. The control.jsp file defines the layout of the window frame for each portlet embedded in the portal page. WebSphere Portal lets you change the look and feel of your portal by changing or customizing this skin. You can use the WebSphere Portal Administration Portlets to select the skin you want to use. See the Designing topic in the WebSphere Portal InfoCenter (listed in Resources) for more details about designing and using skins.

You can see that the page rendering sequence requires that the portlet title be written to the portal page output stream before writing the portlet content. Because this requirement is essential for portlet title support, it needs special attention when dealing with dynamic titles.

Static portlet title

By default, a portlet-specific static string is used as the portlet heading displayed in the title bar.

You declare a static title for each portlet in the portlet deployment descriptor or using resource bundles. After deployment, these settings are available through the WebSphere Portal Administration Portlets, which you can use to change or add titles for the portlet. See the Managing portlets and portlet applications topic in the WebSphere Portal InfoCenter (listed in Resources).

These title settings are stable for page rendering and can be displayed on top of the portlets content.

com.ibm.wps.portlets.worldclock.nls.worldclock StaticPortletTitle

Portlets have read access to this information. They can retrieve the title during run time by requesting the javax.portlet.title property, defined in the ResourceBundles, through PortletConfig.

String title = portletConfig.getResourceBundle(portletRequest.getLocale()).getString("javax.portlet.title");

For portal page rendering, the portlet skin, which is configured to display the portlet title bar, retrieves the title setting for the portlet using a portletTitle tag. This tag belongs to the portal-skin JSP tag library, provided by WebSphere Portal to enable the JSP to retrieve the portlet title for the current portlet.

Then the portlet skin can display a static title in the title bar prior to rendering the portlet content with the portal tag portletRender. At this point, the portlet content is rendered and has been written to the output stream for the portal page.

The portlet title is configured for the portlet and shows as the portlet heading. As long as a static setting is used, the title cannot change context-sensitively during run time. In the next section, you see how to enable changing the title text during run time.

The ability to use context-sensitive titles provides benefits, but also has some disadvantages to consider. For example, using dynamic titles can cause performance impacts or require special conditions; using a static title lacks flexibility, but does not require these considerations.

Dynamic portlet title

The JSR168 Portlet Specification states that a portlet can indicate its preferred title during run time, using the RenderResponse.setTitle(String title) method (Portlet API 1.0).

Because portlets can dynamically set the title during rendering, the title is only available after its content has been rendered. Therefore, the portlet must be rendered first, if you want to have access to the title. However, this requirement conflicts with the requirement that the title be displayed on the portal page before the portlet content.

Therefore, adding dynamic title support means you need to find a way to overcome these discrepancies. Let’s look at the two known alternatives to support dynamic titles.

First, the portlet content can be buffered into a stored response; then you can first transfer the title to the portal page output stream before the portlet response. This buffering solution has a big performance impact because all portlet content needs to be kept in memory for later access and once again transferred to the response from the buffer. Because of this performance impact, WebSphere Portal does not use this design for dynamic titles.

The second alternative is to use JavaScript, along with streaming (instead of buffering). JavaScript is browser-specific and is often seen as security risk; for this reason (and others) JavaScript is sometimes not accepted by some enterprises. However, if you can use JavaScript you can write the title to the output stream and replace it later in the browser. There is no noticeable performance impact. This solution is the recommended way to add dynamic title support with WebSphere Portal V6.

Back to top

Using dynamic title support for WebSphere Portal

In the previous section, you learned the limits and differences of static and dynamic portlet titles. The core problem is that the title is only available after the portlet has rendered. In this section, you see how to overcome this challenge to enable dynamic title support using WebSphere Portal V6.

Beginning with Version 6 of WebSphere Portal, when a title is set by RenderResponse.setTitle(String title), it is transferred to the request attribute, com.ibm.portal.portlet.Constants.DYNAMIC_TITLE. Therefore, the dynamic title is available after the portlet content has been rendered using the portal tag portletRender. The skin JSP can access the portlet title (set by the portlet during run time), as soon as the portlet has finished rendering, using the DYNAMIC_TITLE request attribute.
Important: This attribute is not scoped by portlet; therefore, the title is lost as soon as the next portlet is rendered.

You can use this new capability to display the dynamic title. And, you can also use this dynamic title support when parallel portlet rendering is enabled.

Enable dynamic portlet titles using JavaScript

In WebSphere Portal, the title bar is defined by the control.jsp located at wps.earwps.warskinshtml. To add dynamic title support, you need to update this JSP. The static portlet title and portlet content are rendered as usual. Then, the static portlet title can be replaced by the dynamic title, if available.

To enable the static title to be replaced later, the title needs to be marked within the portlet skin using the HTML elements or

. The element must be uniquely identifiable by using the id attribute because it might appear multiple times on a portal page. Search for the portletTitle tag in your portlet skin that retrieves the static portlet title, and surround it with a span element as shown here.

At the end of the portlet skin, you can retrieve the title that was dynamically set during portlet rendering to replace this spanned static title fragment. You can use the DYNAMIC_TITLE request attribute to acces the dynamic title. You only replace the static title when a title has been set during run time.

This JavaScript snippet analyzes the HTML document to search for the element ID title.< portal-skin:portletID/> to replace the static title with the dynamic title retrieved from the request attribute. Because the elementID must differ for each portlet on the portal page, the elementID needs to be scoped for each portlet skin. The easiest and recommended way to do this is to use the unique portlet window identifier returned by the portletID tag.

Figure 3 shows the a portlet title that has been dynamically set during run time. Configuring the local time of the WorldClock example results in a change to the title.

Figure 3. Title bar displaying a dynamic portlet title


In this way, you can enable dynamic title support with the portlet skin in WebSphere Portal V6 using JavaScript.

Conclusion

This tip reviewed the portlet title support provided by WebSphere Portal V6 and described a way to support dynamic titles without performance issues.

You learned the requirements and limits of dynamic portlet titles. You can use the explanation of the static portlet title within the portlet skin to easily analyze your custom skin. With this analysis, and the explanation of using JavaScript to dynamically replace the title, you can now use WebSphere Portal V6 to dynamically render portlet titles. A good understanding of the portlet title concepts discussed in this article can help you to decide when to use this title support.

来自 “ ITPUB博客 ” ，链接：http://blog.itpub.net/7199667/viewspace-1006638/，如需转载，请注明出处，否则将追究法律责任。

转载于:http://blog.itpub.net/7199667/viewspace-1006638/