Introduction to portlets

Introduction to portlets

+

Search Tips | Advanced Search

Overview Factory
Develop Portlets with the Portlet Factory
Develop a JSR 168 Compliant Portlet
Develop a WebSphere Portlet
Provide Configure and Edit Functionality
Access Portlet API's from a Model
Rebuild a Portlet WAR
Deploy a Portlet WAR

Overview

Portlet Factory enables you to rapidly deliver dynamic, highly customizable, and adaptive portlets. With Portlet Factory, we can and create, re-purpose, or assimilate web applications and web services into portlets. These portlets can be customized by users, administrators, and developers, all within a protected and controllable framework. In addition, business users can change the various aspects (exposed through Factory profiles) of the portlet functionality, such as presentation or business process, in real time.
Portlet Factory applications can exist as stand alone web applications, portlets, and web services without creating any additional code or requiring the duplication or branching of the current code base. By eliminating the need to code all of these implementations and their variations, there is a significant reduction to the development, deployment and change management process.

Developing portlets with Portlet Factory

During the course of development, you will use the Portlet Factory Designer to create the portlet functionality and portlet WAR files that you can use for testing your portlet. We can then run the Portlet Factory's deployment scripts to create a WAR file that can be deployed to a deployment server.
The Designer generates development WAR files. These files contain items not included (or desirable) in a deployment WAR file. For example, a development WAR might contain some or all of the following:

/factory/designer/preview_webapp.jsp Should not be on a deployment server
/factory/portletadapter/* Not needed in Factory deployment WARs
/WEB-INF/bin/deployment/*/* Not needed in deployment WARs
/WEB-INF/clientlibs/* Not needed in deployment WARs
/WEB-INF/models/factory/adapters/* Not needed in deployment Factory WARs

Most models will run fine both as standalone web applications and as portlets. There are a couple restrictions on models that you intend to use as portlets, however, that we need to be observe:

Use the POST Method -- Use method="POST" in your input <form> tags in your HTML pages rather than method="GET" or unspecified which defaults to GET.

Accessing Input Data -- The JSR168 Portlet request life cycle processes Action requests separately from Render requests in order to allow portlets on a page to be rendered multiple times per explicit portlet action. Due to behavior we cannot rely on request parameters being available in the page rendering stage. For example, do not use ${Inputs/inputname} as an indirect reference for Page Control builders (Text builder, etc.). Instead, save necessary inputs to Variables or application state data and reference them in page controls from that saved state instead.

For example, the sample code below grabs the RequestInput data from a webApp instance, and saves the results into the XML variable named formdata.
{
 Iterator itr = webAppAccess.getRequestInputs().getInputNames(); 
 IXml formData = webAppAccess.getVariables().getXml("formdata"); 

 // Clear old form data out of variable.
 formData.removeChildren(); 

 String inputName = new String(); 

  while (itr.hasNext())
  {
   inputname = (String)itr.next(); 
   formData.addChildWithText(inputname, webAppAccess.getRequestInputs().getInputValue(inputname));       

  } 
}
In summary, developing a portlet with the Portlet Factory consists of these general steps:

Create a project that implements the portlet functionality using Portlet Factory Designer to model and profile the application. For Websphere portlets, we can also create customized Configure and Edit functionality with Designer.

Install the generated portlet WAR file using the portal's administration tools. On Websphere Portal 5.x, we can configure your project to auto-deploy the portlet WAR file to the portal. On a JSR 168 portal, use the portal's native deployment procedure to deploy the portlet WAR file.

The following sections describe each of these steps in more detail. Each of the other sections describe the specific steps in the portlet development process.

Developing a WebSphere Portlet

You use Portlet Factory's Designer to develop the portlet's functionality. Designer includes several builders useful in developing portlets for WebSphere in addition to the more general builders used for J2EE application development. These builders include:

Portlet Adapter - Adding this builder call to a model allows you to define portlet information such as a name and description as well as specifying the HTML pages or Portlet Factory models to be used when the user configures or edits the portlet.

Portal Event Declaration - Adding this builder call to a model allows you to declare an event that can be handled through the WebSphere Portal's event processes. Other portlets, whether they are created with the Portlet Factory or not, may handle these events.

Portlet Customizer - Adding this builder call to a model allows you to create custom Configure and Edit models for a particular portlet, providing the portal you are using supports these features.

See Developing WebSphere Portlets for more information.

Providing Configure and Edit Functionality

When the user views WebSphere portlets, they may have the option to configure or edit the portlet, which entails setting values for any configurable or editable properties of the portlet. For portlets created with Portlet Factory, these properties are the profile names and entries declared to be configurable or editable in the Portlet Adapter builder call.
Some, but not all, JSR 168 portals support configure and edit functionality. If you plan to provide this functionality, be sure the JSR 168 portal container you use supports these options.
The WebSphere Portal provides default Configure and Edit functionality, but we can alter the appearance of the Configure and Edit pages for the portlet by specifying an HTML page that you create to be used instead of the default. Also, we can implement your own Configure and Edit functionality by creating Portlet Factory models that include a Portlet Customizer builder call.

Create HTML pages for configure and edit pages if you want to customize the appearance of the configure and edit pages.

Specify the filenames of the HTML pages in the Portlet Adapter builder call.

Specify edit or configure model in Portlet Adapter builder call.

Create specified model, using Portlet Customizer builder call for the basic functionality.

See Implementing Configure and Edit Functionality for more information.

Developing a WebSphere JSR 168 Portlet

To limit yourself to the functionality defined in JSR 168, you cannot use WebSphere Portal-specific features, such as Click-to-Action (C2A) or People Awareness. These features will still work on WebSphere Portal that uses JSR 168, but will not work on other JSR 168 portals.
The JSR 168 portlet specification does not support J2EE 1.2 portlet applications. If you build JSR 168 portlets, the portlets must be based on the J2EE 1.3 or later specification.
Do not rely on HTTP headers for the functionality of your models/portlets. The JSR168 Portlet Specification states the following :
"Depending on the underlying web-server/ servlet-container and the portal/ portletcontainer implementation, client request HTTP headers may not be always available. Portlets should not rely on the presence of headers to function properly."

Portlets may run remote to the portal server, (via WSRP). As such, do not rely on HttpServletRequest API methods that in a traditional Web application return information about the caller/browser's request (for example, getRemoteAddr, getRemoteHost, getRequestURL, getProtocol). In other words, the http request to the portlet may not be the same as the http request from the browser to the portal.
Existing portlets configured using the WebSphere Portal portlet adapter are not immediately and automatically configured once the JSR 168 Portlet Adapter is installed. To make an existing deployed portlet available as a JSR 168 portlet, simply perform a copy of the base portlet and set the model name. Your portlets will now run as JSR 168 portlets and will not require any code changes.

WAR Deployment Locations

When you configure a project to produce a JSR 168 portlet WAR, we can specify two WAR locations. These settings are made in the Modify Project Wizard's JSR 168 Portlet Settings page. The locations are:

Portlet WAR Location - Location in which the portlet WAR will be created. Once this WAR is created, use the portal's admin tools to deploy this WAR file to the proper location.
JSR 168 Portlet WAR Deployment Location - This location is specified when auto-refresh is enabled. It represents the location in the portal file system where deployed portlet WAR file is located. This location is unique to the portal server, and the WAR file is initially placed here using the portal server admin tools.

Note: The Portlet War Deployment location values can be found (and changed) in the "IBM" section of the project properties screen as well.

Accessing Portlet APIs from a Model

We can access the Portlet API directly from a model by retrieving the PortletRequest, PortletResponse, or PortletConfig from request attributes. Both the JSR-168 and WPS portlet adapters place these objects in the HttpServletRequest on each request using predefined keys from the com.bowstreet.adapters.Constants class.
Here are examples of retrieving each of the Portlet objects:

PortletRequest portletRequest = (PortletRequest) webAppAccess.getHttpServletRequest().getAttribute(Constants.PORTLET_REQUEST);
PortletResponse portletResponse = (PortletResponse) webAppAccess.getHttpServletRequest().getAttribute(Constants.PORTLET_RESPONSE);
PortletConfig portletConfig = (PortletConfig) webAppAccess.getHttpServletRequest().getAttribute(Constants.PORTLET_CONFIG);

When running your model outside of a portal these object will be null.
You will need to import the proper object types based on your JSR-168 or WebSphere environment.

Imports for WebSphere Portlets:
com.bowstreet.adapters.Constants
org.apache.jetspeed.portlet.PortletRequest
org.apache.jetspeed.portlet.PortletResponse
org.apache.jetspeed.portlet.PortletConfig

Imports for JSR-168 Portlets:

com.bowstreet.adapters.Constants
javax.portlet.PortletRequest;
javax.portlet.PortletResponse;
javax.portlet.PortletConfig;

Designing the appearance of portlet pages

Portlets developed using WebSphere Portlet Factory should adhere to the design standards of other portlets provided by the portal server. To ensure consistency in the appearance of the user interface, applications should use common style classes instead of inline style definitions. The style classes provided by WebSphere Portal are maintained in the file, styles_portlets.jspf. The class names are the same as those suggested by the WSRP 1.0 specification to ensure consistency as portlets are ported across different portal implementations. See the following references for further information.

Portal style classes
WSRP 1.0 specification
Best practices: Developing portlets using JSR 168 and WebSphere Portal

Rebuilding a Portlet WAR File

Use the Rebuild WAR menu choice available in the project's right-click menu to rebuild a deployed WAR file. This command will rebuild the WAR on the server, using the current content of the WAR's project. Normally you will not need to redeploy a deployed WAR unless you make some changes to web.xml file. However, we can use this feature to keep files in sync by removing from the deployed WAR files that have been removed from the workspace.
Rebuild WAR accomplishes its work by initially deleting the WAR from the server. Rebuild WAR then rebuilds the WAR from the project contents and places the rebuilt WAR back on the server in the location specified for the project's WAR Location.
Since files are being deleted from and written to the application server, the server must be halted for the Rebuild WAR operation to succeed. If the server is not stopped, errors might occur as the operation attempts to delete files from the server.
To rebuild a portlet WAR file:

Halt the server on which the WAR file you want to rebuild is installed.

In the WAR file's project right-click menu select Factory WebApp Project | Rebuild WAR.

Select the WAR(s) you want to rebuild. A progress meter is displayed indicating rebuild status.

Restart the application server.

Deploying a Portlet WAR File

Depending on how you have configured your project, deployment of the portal WAR can be automatic or manual. For information on deploying a portlet WAR see, Deploying WAR Files for Production Use.
If you use your Portal tools to remove a deployed portlet WAR file, and you then attempt to redeploy the WAR again using the Factory, problems will result because some portals (such as WebSphere) leave remnants of the removed WAR on the server. As a result, you might need to modify your portlet root directory properties in the Designer Project Wizard to correctly point to the newly deployed portlet.
For more information about WAR files in general see, Working with WAR Files.

Related Topics...
Working with Projects
Working with WAR Files

/factory/designer/preview_webapp.jsp	Should not be on a deployment server
/factory/portletadapter/*	Not needed in Factory deployment WARs
/WEB-INF/bin/deployment//	Not needed in deployment WARs
/WEB-INF/clientlibs/*	Not needed in deployment WARs
/WEB-INF/models/factory/adapters/*	Not needed in deployment Factory WARs