Portlet Development - Generating output

Portlet Development - Generating output

View how portlets use JSPs to generate markup, create URLs to portlet resources, support multiple devices, markups, and languages in IBM portlets, and make use of Java Standard Tag Library (JSTL).
In the previous example, the Hello World portlet provided markup using a Java PrintWriter. However, most portlets generate output using JSPs. One exception to this is when the portlet has to transform XML source. In this case, the portlet can use XSLT to generate markup. The following sections describe how JSPs are used by portlets.

Use JSPs to generate markup

Below is the JSP for the view page of the jsrHelloJSP.war sample.
<%@ taglib uri="http://java.sun.com/portlet" prefix="portletAPI" %>
<%@ page session="false"%>
<p class="portlet-font">Hello JSP!</p>

Differences between this standard portlet example and the corresponding IBM JSP....

Set the content type using the method setContentType().

The taglib directive points to the URI for the JSP tag library for the Portlet API Specification.

Style classes from the WSRP specification are used.

Separate JSPs would exist to provide the user interface for supporting any additional portlet modes, such as edit or help. The basic portlet wizard in Rational Application Developer allows us to create a portlet that provides JSPs for some of the other modes in which the portlet can be invoked.
The following shows the doView() method provided in the jsrHelloJSP sample.
package com.ibm.wps.samples.jsr;
 import javax.portlet.*;
import java.io.*;
 public class HelloJSP extends GenericPortlet  {
   public void init(PortletConfig portletConfig) throws UnavailableException, PortletException
  {
    super.init(portletConfig);
  }
   public void doView(RenderRequest request, RenderResponse response)
       throws PortletException, IOException    {
    // set return content type          response.setContentType("text/html");
    PortletContext context = getPortletConfig().getPortletContext();
    context.getRequestDispatcher("/jsp/View.jsp").include( request, response);
  }
 }
If we are familiar with writing to the IBM portlet API, here are some of the key differences between this standard portlet example and the corresponding Figure 8 are as follows:

IBM portlet JSPs are included using PortletContext.include() method. Standard portlet JSPs are included by a request dispatcher's include() method.

The MIME type of the output returned in the response must be set before including the JSP. IBM portlets declare the MIME type in the page directive of the JSP.

There are several points to keep in mind when writing your JSPs:

For consistency in portal look and feel, use the portlet's class specifications in the JSR 168/JSR 286 specification.

Be sure to include the appropriate tag library to obtain the needed functionality in the JSPs.

Become familiar with the guidelines and best practices for portlet markup. For example, all named elements must be namespace-encoded, using the <portletAPI:encodeNamespace> tag, to avoid clashes with other named elements on the portal page.

Portlet JSPs cannot link directly to resources within the portlet's WAR directory structure.

Create URLs to portlet resources

Portlet JSPs cannot link directly to content (for example, images, applets, other JSPs, or other resources) within the portlet's WAR directory structure. Instead, they have to use the services of the portlet container to create portlet URLs from which the content can be accessed. Use the encodeURL() method of the PortletResponse to access content within the portlet WAR structure. The following examples are used in the View World portlet samples.

ibmViewWorld.war

Figure 3. IBM portlet JSP with image file

<img src='<%=portletResponse.encodeURL("images/earth.jpg")%>' />

jsrViewWorld.war

For standard portlets, we also have to add the context path of the portlet from the request:
Figure 4. Standard portlet JSP with image file

<img src='<%=renderResponse.encodeURL(renderRequest.getContextPath() + "/images/earth.jpg")%>' />

The String returned by the encodeURL() method returns the relative URL of the content, without the host name and domain information.
Multimedia example
The following example shows how an audio file can be included in a JSP for a standard portlet.
Figure 5. Standard portlet JSP with multimedia file
<object     classid='<%=renderResponse.encodeURL(renderRequest.getContextPath() +
   "/audio/WakeUpSong.mp3")%>'
        type="audio/wav" width="300" height="18">
   <param name="controls" value="smallconsole" valuetype="data">
   <param name="autostart" value="true" valuetype="data">
   <param name="controller" value="true" valuetype="data">
</object>
Applet example
The following example shows how an applet can be included in an IBM portlet JSP.
Figure 6. Standard portlet JSP with applet
<applet codebase='<%=response.encodeURL("applet")%>'          code="MyColet.class" width="150" height="150">
     <param name="timeout" value="3600">
    <param name="border"  value="5">
    <param name="font"   value="TimesRoman|BOLD|18">
    <param name="bgcolor" value="ffffff">
 </applet>
Support multiple devices, markups, and languages in IBM portlets

HCL WebSphere Portal supports PC browsers, i-mode and WAP phones, plus the ability to create and add support for other devices and clients, markup types, and languages. The challenge with supporting multiple devices, markups, and languages is to render content differently depending on the characteristics of the client, which is provided in the portlet request. For example, one browser may accept HTML 4.0 while another supports XHMTL 1.0. One WAP device might support four lines with 25 characters while another phone has its own PDA-style interface.
For IBM portlets, the aggregation component of HCL WebSphere Portal allows us to package JSPs and resources in directories that match the client with the request, reducing the amount of programming we have to do to support multiple client types. JSPs containing mostly text, such as help JSPs, can be translated directly rather than storing strings in a resource bundle. JSPs that do not use resource bundles need to be stored in the appropriate location. When a portlet uses a JSP for rendering of the portlet's content, the portal searches for and selects the proper JSP based on the client type (including browser), markup language, and locale indicated in the request.
To include a JSP in a portlet, use the appropriate method:
// JSR 168 include     context.getRequestDispatcher("/jsp/View.jsp").include( request, response);
 // IBM API include      context.include("/jsp/View.jsp", request, response);
To support multiple markup types and locales, the portlet's JSP's must be packaged in the WAR file using the following directory structure:
jsp_path/markup_type /language _region/client/jspname.jsp

Where

jsp_path a path defined by the developer. For example, JSPs can be located in the root of the WAR file or in a jsp directory. However, this path must not include...
mime-type/language_region_variant

The include() method already locates the correct JSP also in those directories.
markup_type Either html, wml, or chtml .
language Language for this JSP, for example, en, ja, or de .
region Country, region, or territory of the JSP, for example, US, UK, or CA.
client Type of device. For example, it could indicate a JSP with browser-specific markup, such as ie or ns4. Manage Clients help describes how clients are identified by the portal server.

For example, if the client is using Internet Explorer 5 with language properties are set to English (United States), the method include(/mypath/mytemplate.jsp, portletRequest, portletResponse) would cause the portal server to look for the JSP in the following order.

/mypath/html/ie5/en_US/mytemplate.jsp
/mypath/html/ie5/en/mytemplate.jsp
/mypath/html/ie5/mytemplate.jsp
/mypath/html/en_US/mytemplate.jsp
/mypath/html/en/mytemplate.jsp
/mypath/html/mytemplate.jsp
/mypath/mytemplate.jsp

Standard portlets must provide their own logic for handling requests from multiple locales and markup types.
Content accessed by a portlet JSP (for example, images or HTML pages) using ServletResponse.encodeURL() are not found by portal aggregation. To provide different versions of these resources based on client type, markup, and locale, the portlet must use PortletContext.include().

Use JSTL in portlet JSPs

The following example shows how to use JSTL to retrieve translated Strings from a resource bundle in the JSPs.

The JSTL tag library is included at the beginning of the JSP.
The <fmt:setBundle/> tag indicates the resource bundle to use.
The <fmt:message/> tag indicates the key to look for in the resource bundle.
For the image source, the encodeURL() method is used in a Java scriptlet.
<%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %>
...
<fmt:setBundle basename="nls.reminder"/>
...
<img border='0'
     src='<%=response.encodeURL("task_add.gif")%>'
     title='<fmt:message key="add_reminder"/>'
     alt='<fmt:message key="add_reminder"/>'/>
The JARs required to implement JSTL tags are included with the portal server. We should not package these JARs in your portlet's WAR file.

IBM portlet API examples for Hello JSP

The following examples are from the ibmHelloJSP.war sample.
Figure 7. Example: JSP for Hello JSP portlet (IBM)
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" session="false" %>
 <p class="portlet-font">Hello JSP!</p>
Figure 8. Example: JSP for Hello JSP portlet (IBM)
The PortletContext.include() method is used to invoke the JSP for the view mode.
package com.ibm.wps.samples.v4;
 import org.apache.jetspeed.portlet.*;
import java.io.*;
 public class HelloJSP extends PortletAdapter  {
   public void init(PortletConfig portletConfig) throws UnavailableException
  {
    super.init(portletConfig);
  }     public void doView(PortletRequest request, PortletResponse response)          throws PortletException, IOException    {
     PortletContext context = getPortletConfig().getContext();
    context.include("/jsp/View.jsp", request, response);
  }
 }
Parent Portlet creation basics
Related reference:

JSP tags for standard portlets

jsp_path	a path defined by the developer. For example, JSPs can be located in the root of the WAR file or in a jsp directory. However, this path must not include... mime-type/language_region_variant The include() method already locates the correct JSP also in those directories.
markup_type	Either html, wml, or chtml .
language	Language for this JSP, for example, en, ja, or de .
region	Country, region, or territory of the JSP, for example, US, UK, or CA.
client	Type of device. For example, it could indicate a JSP with browser-specific markup, such as ie or ns4. Manage Clients help describes how clients are identified by the portal server.