Java Portlet Tools: Converting Java Web Applications into Adaptive Portlets
Pages: 1, 2, 3, 4, 5

The PortletBean

Java Portlet Tools provides a specialized JavaBean for use in JSP scriptlets and in the JSP expression language. The PortletBean is a JavaBean wrapper around EDK and client-side portlet API functionality. It provides property getter and setter methods for:

  • Portlet, community, and page IDs, imageserver URLs, stylesheet URLs, and more
  • Portlet preference settings (for example Admin, Community, and User)
  • Generating adaptive portlets JavaScript for actions such as raising PCC events or setting session prefs

This bean is automatically attached to each ServletRequest that passes through the PTPortletFilter using the attribute name "portlet." Rather than constructing IPortletContext and IPortletRequest objects in scriptlets in the JSP, developers can instead reference EDK method values through the PortletBean. While this seems to be simply a matter of wrapping functionality that already existed in JavaBean syntax, the PortletBean can be used in very powerful ways in Java Web applications. For example, a JSF Web application developer wants to create a personal profile portlet that can set user preferences and fire off a PCC event to notify other portlets that the preferences have been set. In the JSP page, the markup would look like the following:

<f:view>
<h:form>
    <b>Personal Profile Information:</b><br>

    <h:panelGrid columns="2">

    <h:outputText value="Name:"/>
    <h:inputText value="#{portlet.userSettings.name}"/>

    <h:outputText value="Age:"/>
    <h:inputText value="#{portlet.userSettings.age}"/>

    <h:outputText value="Height:"/>
    <h:inputText value="#{portlet.userSettings.height}"/>

    <h:outputText value="Weight:"/>
    <h:inputText value="#{portlet.userSettings.weight}"/>

    <h:outputText value="Nationality:"/>
    <h:inputText value="#{portlet.userSettings.nationality}"/>

    </h:panelGrid>

    <h:commandButton action="success" value="Submit"
                     onclick="#{portlet.raiseEventJS['submitinfo']}"/>

</h:form>
</f:view>

This simple JSP will allow user preference values to be displayed as the value of an <input type="text"> tag and set whenever the form is submitted. This is referred to as a value binding and allows JSF applications to automatically set bean property values from the servlet request without the developer having to write any request processing code. Without the PortletBean, the JSF application would have to create the IPortletContext, IPortletRequest, and IPortletResponse objects, retrieve a setting value for each setting and insert it into the input tags using JSP scriptlets, and finally process the request in a server-side handler class that would have to get each setting value from the request and manually set it to the IPortletResponse. This request handling code would have to be hard-coded and would be difficult to modify if more preference settings were required.

Note also the <h:commandButton> tag. This tag has an onclick attribute value that raises a JavaScript PCC event that can be caught by registered PCC event handlers in other portlets in the portal page. In this case, the PortletBean property value resolves to:

onclick="document.PCC.RaiseEvent
      ('urn:/plumtree.com/adaptiveportlets', 'submitinfo');"

For more information on using the PortletBean EDK properties or using the PortletBean to generate client-side JavaScript, see: Appendix B: PortletBean API.

Java Portlet Tools Tags

The JSP specification allows developers to define custom tag libraries that, when evaluated by a JSP, can generate custom UI components to be displayed in the Web application. The Java Portlet Tools library provides a set of custom tags that allows developers to exploit client-side adaptive portlets technology. The custom tag library is included in a JSP page by adding a taglib directive to the JSP page, for example:

<html>
<head>
   <title>Car Store</title>
</head>

<%@ taglib uri="http://plumtree.com/javaportlettools" prefix="portlet" %>
<body>
    ...
</body>
</html>

The http://plumtree.com/javaportlettools URI is used to uniquely identify the Plumtree Java Portlet Tools tag library. In this library you will find the following tags. (Note: After clicking the links in the left column below, you may need to refresh your browser to access the login page.)

<portlet:group> A tag for grouping multiple portlets in a shared namespace. This namespace will allow the portlets to fire and respond to PCC events from other portlets in the portlet group as well as allow portlets to get and set session prefs that are accessible to the portlet group.
<portlet:raiseEvent> A tag that raises a PCC event that can be caught by other portlets.
<portlet:onEvent> A tag that defines a PCC event handler. It will listen for a specific PCC event and invoke a handler function or custom JavaScript contained in the tag.
<portlet:clickOnEvent> A PCC event handler tag that clicks any elements between its tags when it catches an event.
<portlet:refreshOnEvent> A PCC event handler tag that performs an in-place refresh on the portlet content when it catches an event. The refresh URL is set as the "url" attribute of the tag. This event handler tag can refresh the portlet content or send the in-place refresh response object to a handler function.
<portlet:formRefreshOnEvent> A PCC event handler tag that submits a form using an in-place refresh post when it catches an event. This event handler tag can refresh the portlet content or send the in-place refresh response object to a handler function.
<portlet:adaptivePortlet> A special tag used to include adaptive portlets JavaScript into a JSP page. It duplicates the script includes and PortletBean attachment (but not the HTML filtering) of the PTPortletFilter and is intended for use in JSPs that are not handled by the PTPortletFilter, or in Web applications that should not be processed by the filter.
<portlet:unfiltered> Any response content enclosed by these tags will be ignored by the ResponseFilter.
<portlet:getSessionPref> Generates the JavaScript for retrieving a session pref value from the PCC.
<portlet:setSessionPref> Generates the JavaScript for setting a session pref value on the PCC.

Some of these tags duplicate functionality that is provided by the PortletBean. For example, a developer could raise a PCC event in three different ways in a JSF application:

<h:outputLink onclick="#{portlet.raiseEventJS['myevent']}">
<h:outputLink onclick="<%= ((PortletBean) request.getAttribute("name")).raiseEventJS("myevent") %>">
<a onclick="<portlet:raiseEvent eventname="myevent"/>">

The reason for this duplication of functionality is that the JSP expression language only works in custom tag attributes of JSP 2.0 tags, and scriptlets can be too cumbersome to write and read. Many Web application frameworks specifically discourage users from relying on scriptlets in their JSPs. The custom tags provided by Java Portlet Tools allow developers to avoid scriptlets in situations where the expression language is unavailable or cannot be used. Other tags, such as the <portlet:onEvent> tag, are not suited for use as PortletBean property, either because they generate a great deal of complex JavaScript and HTML or because they are not intended to be used within other tags as attribute values. Developers should consult Appendix C: Frequently Asked Questions to see when they should use custom tags and the PortletBean.

Summary

The Java Portlet Toolkit allows Web applications to be easily converted into portlets. With the simple addition of a filter to the Web application's web.xml configuration files, the Java Portlet Toolkit will rewrite Web application HTML so it will work effectively in a portal environment. This filter can be configured easily to the needs of a particular Web application. In addition, the Java Portlet Toolkit offers a set of JavaBeans and JSP tags that make application development and access to portal resources easier for Java Web applications.

Pages: 1, 2, 3, 4, 5

Next Page »