Generating output

In the previous example, the Hello World portlet provided markup by 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

One of the easiest ways to separate the portlet markup from the main functionality of the portlet is to use a JSP. Below is the JSP for the view page of the HelloJSP.war sample in the wp_root/dev/samples directory. 


<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" %>

<p class="wpsPortletText">Hello JSP!</p>

A separate edit, help, or configure JSP would exist to provide the user interface for supporting any additional portlet modes. The basic portlet wizard in Portal Toolkit allows you 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 HelloJSP sample. The PortletContext.include() method is used to invoke the JSP for the view mode. 

package com.ibm.wps.samples;

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 
   {
      getPortletConfig().getContext().include("/jsp/View.jsp", request, response);
   }

}

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

  1. For consistency in portal look and feel, use the portlet's class specifications in the Portal style sheet .

  2. Be sure to include the Portlet API JSP tag library to obtain the needed functionality in your JSPs.

  3. Become familiar with the guidelines for portlet markup described in Portlet Development Best Practices and Coding Guidelines. 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.

  4. Portlet JSPs cannot link directly to content (for example, images) within the portlet's WAR directory structure. Instead, they have to use the services of the portlet container to create portlet URIs from which the content can be accessed. Use the encodeURL() method of the ServletResponse to access content within the portlet WAR structure. For example: 
        <%=response.encodeURL("/images/results.gif")%>

    The String returned by the encodeURL() method returns the relative URL of the content, without the host name and domain information.

 

Generating markup for multiple devices, markups, and languages

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 PortletRequest. 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.

WebSphere Portal provides several ways to support the diverse characteristics of the client. For example, you can use the getMarkupName() method to check the markup supported by the client. However, the portal aggregation component allows you to package JSPs and resources in directories that match the client with the request, reducing the amount of programming you have to do to support multiple client types. JSPs that contain 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 function PortletContext.include(): 


   getPortletConfig().getContext().include(jsp_path/jspname.jsp, portletRequest, portletResponse);

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

is either html, wml, or chtml .

language

is the language for this JSP, for example, en, ja, or de .

region

is the country, region, or territory of the JSP, for example, US, UK, or CA.

client

is the 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.

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

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

  3. /mypath/html/ie5/mytemplate.jsp

  4. /mypath/html/en_US/mytemplate.jsp

  5. /mypath/html/en/mytemplate.jsp

  6. /mypath/html/mytemplate.jsp

  7. /mypath/mytemplate.jsp

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().

 

Portlet API tag quick reference

This section describes the tags that are recognized by the portlet container. The portlet container provides tags for use in portlet JSPs. To make these tags available in a JSP, the following directive is required at the beginning of the JSP: 

   <%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>

Note: Portlet API JSP tags are not available if you use the getRequestDispatcher() method of the servlet API to invoke the JSP. Instead, use the PortletContext.include() method of the IBM Portlet API.

The following is a brief description of each tag. See Detailed descriptions of the Portlet API tags for more information.

Tag Description
<portletAPI:if /> Through the attributes of this tag, several conditions can be checked. If the condition is true, the content of the tag is written to the page.
<portletAPI:log /> Writes a string in the portlet log.
<portletAPI:bidi /> This tag is used to support text for bidirectional languages.
<portletAPI:dataLoop /> Loops through all attributes in PortletData of the current concrete portlet instance.
<portletAPI:dataAttribute /> Returns the value of one or more PortletData attributes.
<portletAPI:settingsLoop /> Loops through all attributes in PortletSettings of the current concrete portlet.
<portletAPI:settingsAttribute /> Returns the value of one or more PortletSettings attributes.
<portletAPI:CreateReturnURI /> Creates a URI that points to the caller of the portlet.
<portletAPI:createURI /> Creates an URI that points to the current portlet with the given parameters.
<portletAPI:URIParameter /> Adds a parameter to the URI of the createURI and CreateReturnURI tags.
<portletAPI:URIAction /> Adds a default action to the URI of the createURI and createReturnURI tags.
<portletAPI:encodeNamespace /> Maps the given string value into this portlet's namespace.
<portletAPI:init /> Provides access to the portletRequest, portletResponse, and portletConfig objects.

 

Deprecated portlet JSP tags

The following tags have been deprecated.

Deprecated tag Replacement
<portletAPI:encodeURI/> encodeURL() method of the ServletResponse
<portletAPI:text/> <fmt:message/> and <fmt:bundle/> tags of the Java Standard Tag Library (JSTL)

Example:

The following example shows how to create an image tag using the replacements for both of the deprecated tags. 


<%@ taglib prefix="fmt" uri="WEB-INF/tld/fmt.tld" %>  
...
<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 JSTL tags require the following JARs from the Jakarta open-source implementation of the JSP Standard Tag Library.

There are two ways to make these JARs available to your portlet.

 

Packaging the JARS in your portlet WAR file

  1. Download the standard taglib package from http://mirrors.midco.net/pub/apache.org/jakarta/taglibs/standard-1.0/.

  2. Extract the jstl.jar and standard.jar from the package.

  3. Place the JARs in the /WEB-INF/lib directory of the portlet WAR file.

  4. Extract the tag library file, fmt.tld, from standard.jar and copy it to the /WEB-INF/tld directory of the portlet WAR file.

 

Copying the JARs to the application server's classpath

  1. Download the standard taglib package from http://mirrors.midco.net/pub/apache.org/jakarta/taglibs/standard-1.0/.
  2. Extract the jstl.jar and standard.jar from the package.
  3. Place the JARs in the WPSLib shared library, wp_root/shared/app, of the portal server.
  4. From the WebSphere Application Server Administrative Console, update the application server's classpath with the name and location of these two new JARs. Click Environment then click Shared Libraries then click WPSlib.
  5. Extract the tag library file, fmt.tld, from standard.jar and copy it to WPSLib/WEB-INF/tld on the portal server.

For more information about JSTL tags, see JavaServer Pages Standard Tag Library.

For more information about JSTL tags, see http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html.

See also