Portlet Development Guide

Building Portlets

This chapter describes the most common ways to create portlets, including the Portlet Wizard and the use of out-of-the-box portlets. This chapter also contains instructions for building each type of portlet that is supported by WebLogic Portal.

Before you begin, be sure you are familiar with the concepts associated with creating portlets, as described in Understanding Portlet Development.

This chapter contains the following sections:

Supported Portlet Types

The following portlet types are supported by WebLogic Portal:

For a detailed discussion of each portlet type, refer to Portlet Types.

Portlets in J2EE Shared Libraries

You can copy portlets or other resources from a J2EE Shared Library into your portal application and modify them as needed. A portlet existing in your project will supersede a portlet of the same name in a J2EE Shared Library. To see a list of available portlets, you can use the Merged Projects View of the workbench; resources contained in J2EE Shared Libraries are shown in italic print. You can expand the tree to see the resources that are stored in the various modules. For a reference list of all the J2EE Libraries and their locations on your file system, you can select Window > Preferences > WebLogic > J2EE Libraries.

After you locate a portlet that you want to use, you can right-click the portlet in the Merged Projects View and select the Copy to Project option. Figure 5-1 shows an example of a J2EE Shared Library portlet in the Merged Projects view with the Copy to Project option selected.

For more information about J2EE Shared Libraries, refer to the Portal Development Guide.

Portlet Wizard Reference

An important tool that you can use to create portlets from scratch is the WebLogic Portal Portlet Wizard. The following sections describe the Portlet Wizard in detail:

In general, you choose the portlet type on the first dialog of the wizard; when generating a portlet based on an existing resource, the Portlet Wizard automatically detects the portlet type whenever possible.

Order of Creation - Resource or Portlet First

This section provides an overview of the two methods you can use to begin creating a portlet—creating the portlet resource information/file first or creating the portlet itself first.

Creating the Resource First

You might already have a JSP file, for example, that you want to use as the basis for a portlet. (In addition to JSP files, you can drag other resources onto the portal (such as content selectors) to automatically start the portlet wizard.)

If you have an existing resource that you want to use as the basis of a portlet, follow these steps:

Create the Portlet First

If you do not have an existing source file to start with, you can create the portlet using the New Portlet dialog and the Portlet Wizard. To do so, right-click a folder in your portal web project and select New > Portlet. Figure 5-4 shows an example of the New Portlet dialog.

After you confirm or change the parent folder, name the portlet, and click Finish, the Portlet Wizard begins and displays the Select Portlet Type dialog. Figure 5-5 shows an example dialog.

Detailed instructions for creating each type of portlet are contained in How to Build Each Type of Portlet.

Starting the Portlet Wizard

WorkSpace Studio invokes the Portlet Wizard any time you perform one of these operations:

New Portlet Dialog

When you use File > New > Portlet to create a new portlet, a New Portlet dialog displays before the Portlet Wizard begins. Figure 5-4 shows an example of the New Portlet dialog.

The parent folder defaults to the location from which you selected to add the portlet.

This dialog requires that you select a project and directory for the new portlet, and provide a portlet file name. (The file name appears in the Package Explorer view after you create the portlet.) The Finish button is initially disabled; the button enables when you select a valid project/directory and portlet name. If you select an invalid portal project in the folder tree on this dialog, an error message appears in the status area near the top of the dialog explaining that the project is not a valid portal project. You cannot continue until you have selected a valid project (if one is available).

Select Portlet Type Dialog

When the Portlet Wizard starts, it determines the valid portlet types to offer on the Select Portlet Type dialog, based on the type of project that you are working in.

For example, if you are working within a Portal Web Project that has only the WSRP-Producer feature (and its required accompanying features) installed, it does not have the full set of portal libraries. In this case, only the JPF, JSF, Browser, and Struts portlet types are valid selections; the other portlet types are not included in the Select Portlet Type dialog.

If no valid portlet types exist based on the project type, an informational message displays.

Figure 5-8 shows an example of the Select Portlet Type dialog.

The Show All Portlet Types option forces all portlet types to appear in the Select Portlet Type dialog even if their modules were not installed. For example, the Java Server Faces (JSF) Portlet selection only appears by default if you have added the JSF Project facet to your portal web project. In some cases, you may wish to manaully install the modules that are required to create JSF portlets. Although this method is not recommended, if you manually install the appropriate modules, you can force the JSF portlet option to appear in the dialog by selecting Show All Portlet Types. For more information on JSF portlets, see JSF Portlets.

Portlet Details Dialogs

The Portlet Details dialogs that display after you select a portlet type vary according to the type of portlet you are creating. The portlet-building tasks that are described in How to Build Each Type of Portlet contain detailed information about each data entry field of the portlet details dialogs.

How to Build Each Type of Portlet

The following sections describe how to create each type of portlet supported by WebLogic Portal:

JSP and HTML Portlets

JSP portlets are very similar to simple JSP files. In most cases you can use existing JSP files to build portlets from them. JSP portlets are recommended when the portlet is simple and doesn’t require the implementation of complex business logic. Also, JSP portlets are ideally suited for single page portlets.

There are several ways to invoke the Portlet Wizard, as explained in the section Starting the Portlet Wizard. This description assumes that you create a portlet based on an existing JSP file.

To create a JSP portlet, follow these steps:

Java Portlets

Java portlets are based on the JSR 168 specification that establishes rules for portlet portability. Java portlets are intended for software companies and other enterprises that are concerned with portability across multiple portlet containers.

WebLogic Portal provides capabilities for Java portlets beyond those listed in the JSR168 spec. For example, you can set threading options, use a backing file, and so on. To implement these additional features, WebLogic Portal uses a combination of the typical .portlet file—which you create in the same way that you create other portlet types—as well as the standard portlet.xml file and the weblogic-portlet.xml file.

Building a Java Portlet

To create a Java portlet, follow these steps:

The portlet-name attribute in the portlet.xml file matches the definitionLabel property in the .portlet file.

After you create the portlet, you can modify its properties in the Properties view, or double-click the portlet in the editor to view and edit the generated Java class.

Java Portlet Deployment Descriptor

The separate portlet.xml deployment descriptor file for Java portlets is located in the WEB-INF directory. In addition, the weblogic-portlet.xml file is an optional BEA-specific file that you can use to inject some additional features.

Listing 5-1 shows an example of how entries might look in the portlet.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app version="1.0"
   xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <portlet>
      <description>Description goes here</description>
      <portlet-name>helloWorld</portlet-name>
      <portlet-class>aJavaPortlet.HelloWorld</portlet-class>
      <portlet-info><title>Hello World!</title></portlet-info>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>view</portlet-mode>
      </supports>
      <portlet-info><title>new Java Portlet</title></portlet-info>
   </portlet>
</portlet-app>

Importing and Exporting Java Portlets for Use on Other Systems

WebLogic Portal produces Java portlets that conform to the JSR 168 specification and can be used universally across operating systems. WorkSpace Studio lets you export Java portlets to a supported archive file (WAR, JAR, or ZIP) that can be deployed on any supported server. You can also use the Import feature to import archive files containing Java portlets into your WorkSpace Studio workspace. For details, see Importing and Exporting Java Portlets.

Customizing Java Portlets Using weblogic-portlet.xml

WebLogic Portal allows you to add more functionality to java portlets than you can obtain using the standard JSR 168 specification. You can use the optional weblogic-portlet.xml file to inject some additional features. The following sections provide some examples.

Floatable Java Portlets

If you want to create a floatable Java portlet, you can do so by declaring a custom state in weblogic-portlet.xml as shown in the following example code:

    <portlet>

<portlet-name>fooPortlet</portlet-name>

<supports>

<mime-type>text/html</mime-type>

<window-state>

<name>float</name>

</window-state>

</supports>

    </portlet>

Adding an Icon to a Java Portlet

To add an icon to a Java portlet, you need to edit the weblogic-portlet.xml file, as described in this section.

Portlet Init-Params

The init-param element contains a name/value pair as an initialization parameter of the portlet. You can use the getInitParameterNames and getInitParameter methods of the javax.portlet.PortletConfig interface to return these initialization parameter names and values in your portlet code. Init-params are described in the JSR168 specification.

You can add init-params to your Java portlet by dragging a New Init-Param icon from the Design Palette onto the Java portlet in the portlet editor. Then, click on the init-param section of the portlet to display the parameter’s properties in the Property view. In the Property view, you can enter the following init-param data:

For example, if you created an init-param called “Color” and set the default value to “green,” the following entry will be made in the portlet.xml file:

<init-param>
    <description>My init param</description>
    <name>Color</name>
    <value>green</value>
</init-param>

Java Page Flow Portlets

You can use the Portlet Wizard to built a portlet that uses Apache Beehive Page Flows to retrieve its content.

To create a page flow portlet, follow these steps:

In order to fully understand the process of creating a page flow portlet, you should be familiar with the concept of Page Flows. For more information on using page flows with WebLogic Portal, refer to the Portal Development Guide.

If you want to create a page flow portlet that calls a web service, refer to Web Service Portlets.

JSF Portlets

You can create JSF portlets for a WSRP producer or a framework web application that has the JSF facet installed (that is, you selected the JSF facet when you created the portal web project).

To create a JSF portlet, follow these steps:

Placing Multiple JSF Portlets on a Portal Page

If you want to have more than one JSF portlet on a portal page, use the namingContainer JSP tag immediately after a JSF view tag, in order to provide component naming in the generated component tree. See Supporting Unique JSF Component Identifiers for an example.

Using JSPs in JSF Portlets

If you are using JSPs in your JSF portlets, be aware that you will only see your JSP edits when you view the portlet in a new session. A simple page refresh is not sufficient. This behavior differs from typical JSP development behavior, where changes are compiled and made available after a page refresh. Normally, JSPs are handled by the servlet container, which checks for updated JSPs. JSF, on the other hand, uses JSPs as a source for the component tree, which typically is loaded only once per session, depending on how the JSF implementation handles or does not handle changed JSP source. To see your JSP changes reflected in a JSF portlet, you must view the portlet in a new session. Typically, you can do this by opening a new browser to view the portal.

Supporting Unique JSF Component Identifiers

JSF applications associate a unique identifier with each JSF component in the component tree. When multiple JSF applications appear on a portal page, it becomes necessary to further scope these unique identifiers.

WLP provides the following features to support scoping JSF component identifiers on a portal page:

These features are discussed in the WLP Javadoc for the com.bea.portlet.adapter.faces package.

Listing 5-2 is an example that demonstrates how to use the <namingContainer> tag. The <namingContainer> tag is described in detail in the JSP Tag Javadoc.

<%@ page language='java' contentType='text/html;charset=UTF-8'%>
<%@ taglib uri='http://java.sun.com/jsf/core' prefix='f' %> 
<%@ taglib uri='http://bea.com/faces/adapter/tags-naming' prefix='jsf-naming' %>
<%@ taglib uri='http://java.sun.com/jsf/html' prefix='h' %>   
<f:view> 
	<jsf-naming:namingContainer id='myPortlet'>
		<h:outputText value='Hello World'/> 	</jsf-naming:namingContainer>
</f:view>

Browser Portlets

Browser portlets, also called Content URI portlets, are basically HTML portlets that use URLs to retrieve their content. Unlike other portlet types that are limited to displaying data contained within the portal project, browser portlets can display URL content that is outside from the portal project.

There are several ways to invoke the Portlet Wizard, as explained in the section Starting the Portlet Wizard. This description assumes that you right-click in the Package Explorer view tree within a portal project and select New > Portlet from the menu.

To create a browser portlet, follow these steps:

Clipper Portlets

A clipper portlet is a portlet that renders content from another web site. A clipper portlet can include all or a subset of another web site’s content using a process called “web clipping.” Clipper portlets are discussed in Creating Clipper Portlets.

Struts Portlets

Use the Portlet Wizard to generate a portlet based on a Struts module, as explained in this section.

Before you can create a Struts portlet, you must first integrate your existing Struts application into your portal web application. For detailed information on integrating Struts applications into WebLogic Portal, refer to the Portal Development Guide.

To create a Struts portlet, follow these steps:

The WorkSpace Studio window updates, adding the Portlet_Name.portlet file to the display tree; by default, WorkSpace Studio places the portlet file in the directory that you specified in the Struts Module Path dialog of the wizard.

Remote Portlets

Because remote portlet development is a fundamental task in a federated portlet environment, the task of creating remote portlets is described in detail within the BEA WebLogic Portal Federated Portals Guide.

The following types of portlets can be exposed with WSRP inside a WebLogic portal:

Web Service Portlets

A web service portlet is a special type of page flow portlet, allowing you to call a web service. You create web service portlets using the features of WorkSpace Studio and WebLogic Portal.

Before you can create a portlet that calls a web service, you must perform the following prerequisite tasks:

Instructions on performing these tasks are contained in the WorkSpace Studio.

After you have performed the setup tasks, you can create a web service portlet by following these steps:

Detached Portlets

WebLogic Portal supports the use of detached portlets, which provide popup-style behavior. Technically, a detached portlet is defined as anything outside of the calling portal context. Any portlet type supported by WebLogic Portal can be rendered as a detached portlet.

Considerations for Using Detached Portlets

Keep the following considerations in mind as you implement detached portlets:

Building Detached Portlets

You use the standalonePortletUrl class or associated JSP tag to create URLs to detached portlets.

To create a detached portlet URL from a JSP page, you use the render:standalonePortletUrl JSP tag or class; the following example shows the syntax of the JSP tag:

<render:standalonePortletUrl portletUri="/absolute_path/detached_portlet_name.portlet" …/>

To create a detached portlet URL from Java code, use the following example as a guide:

StandalonePortletURL detachedURL = StandalonePortletURL.createStandalonePortletURL(request, response);
detachedURL.setPortletUri(“/path/to/detached.portlet”);

Working with Inlined Portlets

A file-based portlet can exist either as a stand-alone .portlet file or as an inlined portlet. Typically, within the WorkSpace Studio portal editing framework, .portlet files are included in portals by reference. For instance, when you drag a .portlet file onto a portal, page or book, a reference is created to the portlet file inside the portal, page, or book. On the other hand, an inlined portlet’s entire XML definition is embedded directly in a page or book.

Inlined portlets are created under the following circumstances:

You can drag and drop, cut, copy, and paste inline portlets from one page or book to another from within the portal editor.

Figure 5-19 shows a remote page that contains an inlined portlet and a referenced portlet. Note that the icon used in an inlined portlet is distinct from a referenced portlet.

Extracting Inlined Portlets

You can export an inlined portlet to a .portlet file. When you do this, the resulting .portlet file is functionally equivalent to any other .portlet file. When you extract an inlined portlet, the inlined portlet XML code is automatically removed from the source file (a page or book) and replaced with a reference to the newly created .portlet file.

To extract an inlined portlet, do the following:

Setting the Theme of an Inlined Portlet

You can set the theme of an inlined portlet exactly as you would for a referenced portlet. To set the theme, right-click the inlined portlet in the book or page editor, and pick a theme from the Theme menu. The theme is retained for that portlet as long as it remains referenced in the page or book.

Extracting Books and Pages

You can extract any book or page in a portal to a .book or .page file. Once a book or page is extracted, you are free to use it in another portal within the same portal web application if you wish.

The procedure for extracting books and pages is similar to the procedure for extracting inlined portlets, described in Extracting Inlined Portlets. To extract a book or page, do the following:

Portlet Properties

Portlet properties are named attributes of the portlet that uniquely identify it and define its characteristics. Some properties—such as title, definition label, and content URI—are required; many optional properties allow you to enable specific functions for the portlet such as scrolling, presentation properties, pre-processing (such as for authorization) and multi-threaded rendering. The specific properties that you use for a portlet vary depending on your expected use for that portlet.

During the development phase of the portal life cycle, you generally edit portlet properties using the WorkSpace Studio interface; this section describes properties that you can edit using WorkSpace Studio.

During staging and production phases, you typically use the WebLogic Portal Administration Console to edit portlet properties; only a subset of properties are editable at that point. For instructions on editing portlet properties from the WebLogic Portal Administration Console, refer to Modifying Library Portlet Properties and Modifying Desktop Portlet Properties.

For a detailed description of all portlet properties, refer to Portlet Properties in the Portal Properties View and Portlet Properties in the Portlet Properties View.

This section contains the following topics:

Editing Portlet Properties

To edit portlet properties, follow these steps:

Tips for Using the Properties View

The behavior of the Properties view varies depending on the type of field you are editing. The following tips might help you as you manipulate the content of the data fields in the Properties view.

Portlet Properties in the Portal Properties View

The properties described in this section are contained within the .portal file and are editable using the WorkSpace Studio workbench. The values you enter here override the corresponding value in the .portal file, if a value exists there.

To display the portlet properties that display in the Properties view for a portal, follow these steps:

The Properties view displays the properties of the portlet instance; Figure 5-22 shows an example.

Table 5-6 describes these properties and their values.

Portlet Properties in the Portlet Properties View

The properties described in this section are contained within the .portlet file and are editable using the WorkSpace Studio workbench. The values you enter here override the corresponding value in the .portlet file, if a value exists there.

When you select the outer border of a portlet instance in the editor, a related set of properties appears in the Properties view. The displayed properties vary according to the type of portlet that you are viewing. Figure 5-1 shows a portion of the Properties view for a portlet.

Table 5-7 describes these properties and their values.

Portlet Preferences

Portlet preferences provide the primary means of associating application data with portlets. This feature is key to personalizing portlets based on their usage. This section describes portlet preferences in detail.

After you create a portlet, you can instantiate it several times. Because you can create several instances of a portlet, it is natural to expect each instance to behave differently yet use the same code and user interface. For instance, consider a typical portlet to display a Stock Portfolio. Given a list of stock symbols, this portlet retrieves quotes from a stock quote web service periodically, and displays the quotes in the portlet window. By letting each user change the list of stock symbols and a time interval to reload the quote data, you can let each user customize this portlet.

The portlet needs to be able to store the list of stock symbols and the retrieval interval persistently, and update these values whenever a user customizes these values. In particular, the following data must be persistently managed:

Technically, a portlet preference is a named piece of string data. For example, a Stock Portfolio portlet could have the following portlet preferences:

You can associate several such preferences with a portlet. WebLogic Portal provides the following means to manage portlet preferences:

This section contains the following topics:

Specifying Portlet Preferences

The steps to associate preferences with a portlet depend on the type of portlet you are building. If you are using the Java Portlet API, described in Getting and Setting Preferences for Java Portlets Using the Preferences API, the steps follow those specified in the Java Portlet Specification. For other kinds of portlets, such as those using Java Page Flows, Struts, or JSPs, you can use the WorkSpace Studio workbench to add preferences to a portlet.

You can also allow the administrator to create new preferences using the Administration Console. However, because the portlet developer is more likely to be aware of how portlet preferences are used by the portlet, it is generally better to create portlet preferences during the development phase.

Specifying Preferences for Java Portlets in the Deployment Descriptor

For portlets using Java Portlet API, you can specify preferences in the portlet deployment descriptor according to the specification. For all portlets in a web project, the deployment descriptor is portlet.xml, found in the WEB-INF directory of the web project. Listing 5-3 provides an example.

<portlet>
   <description>This portlet displays a stock portfolio.</description>
   <portlet-name>portfolioPortlet</portlet-name>
   <portlet-class>portlets.stock.PortfolioPortlet </portlet-class>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>edit</portlet-mode>
      </supports>
      <portlet-info>
         <title>My Portfolio</title>
      </portlet-info>
      <portlet-preferences>
         <preference>
            <name>stockSymbols</name>
               <value>BEAS, MSFT</value>
         </preference>
         <preference>
            <name>refreshInterval</name>
            <value>600</value>
         </preference>
   </portlet-preferences>
</portlet>

This snippet deploys the portfolio portlet with two preferences: a preference with name stockSymbols and value BEAS, MSFT, and another preference refreshInterval with value 600.

Instead of specifying a single value for the stockSymbols preference, you can declare each symbol as a separate value as shown in Listing 5-4 below, with the value elements shown in bold.

<portlet>
   <description>
      This portlet displays a stock portfolio. 
   </description>
   <portlet-name>portfolioPortlet</portlet-name>
   <portlet-class>portlets.stock.PortfolioPortlet </portlet-class>
   <supports>
      <mime-type>text/html</mime-type>
      <portlet-mode>edit</portlet-mode>
   </supports>
   <portlet-info>
      <title>My Portfolio</title>
   </portlet-info>
   <portlet-preferences>
      <preference>
         <name>stockSymbols</name>
         <value>BEAS</value>
         <value>MSFT</value>
         </preference>
      <preference>
         <name>refreshInterval</name>
         <value>600</value>
      </preference>
   /portlet-preferences>
</portlet>

If you prefer that portlets should not be allowed to programmatically update any given preference, you can mark the preference as read-only. Listing 5-5 shows an example of preventing a portlet from changing the refreshInterval.

<portlet>
   <description>
      This portlet displays a stock portfolio. 
   </description>
   <portlet-name>portfolioPortlet
   <portlet-class>portlets.stock.PortfolioPortlet 
   <supports>
      <mime-type>text/html</mime-type>
      <portlet-mode>edit</portlet-mode>
   </supports>
   <portlet-info>
      <title>My Portfolio</title>
   </portlet-info>
   <portlet-preferences>
      <preference>
         <name>stockSymbols</name>
         <value>BEAS</value>
         <value>MSFT</value>
      /preference>
      <preference>
         <name>refreshInterval</name>
         <value>600</value>
         <read-only>true</read-only>
      </preference>
   </portlet-preferences>
</portlet>

Note that by marking a preference read-only, you are preventing the portlet from changing the current value only at request time. Portal administrators can always change the value(s) of a preference using the Administration Console.

Specifying Preferences for Other Types of Portlets using WorkSpace Studio

If you are building other kinds of portlets (such as those using Java Page Flows, Struts, or simple JSPs), you can add preferences using WorkSpace Studio.

To add a preference, follow these steps:

Table 5-8 describes the attributes for portlet preferences as shown in the Properties view.

Using the Preferences API to Access or Modify Preferences

At request time, portlet preferences for a given portlet are represented as instances of the javax.portlet.PortletPreferences interface. This interface is part of the Java Portlet API. This interface specifies methods to access and modify portlet preferences.

Getting Preferences Using the Preferences API

Table 5-9 describes methods that allow a portlet to access its preferences.

String getValue(String name, String default)

String[] getValues(String name, String[] defaults) 

boolean isReadOnly(String name)

Enumeration getNames()

Map getMap()

Setting Preferences Using the Preferences API

Table 5-10 describes methods that allow a portlet to change preference values.

void setValue(String name, String value)

void setValues(String name, String[] values)

void store()

void reset(String name)

After modifying preferences by calling setValue(), setValues() and reset() methods, you must call store() explicitly to make the changes permanent; otherwise, changes will not be made permanent.

Getting and Setting Preferences for Java Portlets Using the Preferences API

For portlets written using the Java Portlet API, you can obtain an instance of javax.portlet.PortletPreferences object from the incoming portlet request – javax.portlet.RenderRequest within the processAction() method, or javax.portlet.ActionRequest within the render() method.

In Listing 5-6, the portlet displays a form to edit the current values of portlet preferences in a JSP page included from the doEdit() method of the portfolio portlet.

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
<%@ page import="javax.portlet.PortletPreferences" %>

<portlet:defineObjects/>

<%
   PortletPreferences prefs = renderRequest.getPreferences();
   String refreshInterval = prefs.getValue("refreshInterval", "600");
   String symbols = prefs.getValue("stockSymbols", "BEAS, MSFT");
%>

<form method="POST" action="">
   <table>
      <tr>
         <td>Symbols</td><td><input name="symbols"          value="<%=symbols>"/></td>

      </tr>
      <tr>
         <td>Refresh Interval</td><td><input name="refreshInterval"
         value="<%=refreshInterval>"/></td>
      </tr>
      <tr>
         <td></td>
         <td><input type="submit" value="Submit"/></td>
      </tr>
   </table>
</form>

The portlet updates the preferences in its processAction() method, as shown in Listing 5-7.

public class PortfolioPortlet extends GenericPortlet 
{
   {
      public void doEdit(RenderRequest renderRequest, RenderResponse
      renderResponse) 
      throws IOException, PortletException 
      {
         ...
      }
      public void processAction(ActionRequest actionRequest, ActionResponse
      actionResponse) 
      throws PortletException
      {
         String refreshInterval =
         actionRequest.getParameter(“refreshInterval”);
         String symbols = actionRequest.getParameter(“stockSymbols”);

         PortletPreferences prefs = actionRequest.getPreferences();
         prefs.setValue(“refreshInterval”, refreshInterval);
         prefs.setValue(“stockSymbols”, symbols);
         try 
         {
            prefs.store();
         } 
         catch(SecurityException se) {
         // Thrown when the user does not have enough privileges to store
         // preferences. Make sure that the user logged into the portal.
         ...
         }
      catch(catch(IOException ioe) {
      // There is an error storing preferences
      ...          
      }
   }
}

During processAction(), this portlet uses the javax.portlet.ActionRequest object to obtain preferences.

Getting and Setting Portlet Preferences Using the API for Other Portlet Types

Portlet preferences can be accessed and updated from other kinds of portlets too. The main difference is in the way your portlets obtain an instance of the javax.portlet.PortletPreferences object.

Both these classes provide a method getPortletPreferences(HttpServletRequest req) that takes javax.servlet.HttpServletRequest as an argument and return an object of type javax.portlet.PortletPreferences.

JSP Tags for Getting Portlet Preferences

WebLogic Portal provides a JSP tag library for setting up portlet preferences. Table 5-11 describes the applicable JSP tags.

getPreference

getPreferences

forEachPreference

ifModifible

else

For more information on the Java classes associated with these tags, refer to the Javadoc.

Portlet Preferences SPI

In WebLogic Portal, the framework includes a default implementation that manages portlet preferences in the built-in PF_PORTLET_PREFERENCE and PF_PORTLET_PREFERENCE_VALUE database tables. If desired, you can replace this implementation with your own.

You can use the Portlet Preferences SPI to allow portal applications to manage portlet preferences outside framework-managed database tables. For example, you can store preferences along with other application data in another back-end system or a different set of database tables.

When propagating a portal, the preferences SPI participates in the propagation process. When you exporting data for the propagation, the SPI is called to obtain the preferences, and when you are importing data, the SPI is called to store the preferences.

The following sections describe how to use the Portlet Preferences SPI.

Implement the SPI

You specify the SPI using the interface com.bea.portlet.prefs.IPreferenceAppStore. An implementation of this class must be deployed as a EJB jar file.

Listing 5-8 provides an example.

public interface IPreferenceAppStore extends EJBObject
{
   /**
   * Returns preferences for a portlet entity with the given uniqueId.
   *
   * The returned java.util.Map contains
   * com.bea.netuix.application.prefs.Preference
   * objects keyed against their names.</p>
   *
   * @param uniqueId unique ID
   * @return preferences
   */
   public Map getPreferences(PortletPreferencesId uniqueId) throws
   RemoteException, PreferenceAppStoreException;

   /**
   * Writes the preferences to the underlying persistence.
   *
   * This method should be implemented to be atomic. That is, the
   * implemenation should guarantee that either all preference
   * values are persisted or none at all.
   *
   * The java.util.Map argument should contain
   * com.bea.netuix.application.prefs.Preference
   * objects keyed against their names.
   *
   * @param uniqueId unique ID
   * @param preferences preferences
   */
   public void storePreferences(PortletPreferencesId uniqueId,
   Map preferences) throws RemoteException, PreferenceAppStoreException;

   /**
   * Clear all preferences for the given unique ID from the
   * underlying persistence store.
   *
   * @param uniqueIds unique IDs
   */
   public void removePreferences(PortletPreferencesId[] uniqueIds) throws
   RemoteException, PreferenceAppStoreException;
}

Using the SPI

To cause the framework to use a new SPI in place of the default SPI, you must update the EJB named PreferencePersistenceManager in the ejb-jar.xml file within netuix.jar. The value BEA_netuix.DefaultStore must be changed to the name of the SPI EJB as specified in its deployment descriptor (ejb-jar.xml). The value com.bea.portlet.prefs.provider.DefaultStoreHome must be changed to the home interface of the SPI implementation.

The code segment in Listing 5-9 shows the default entries, which you must change to use the SPI.

<session>
   <ejb-name>PreferencePersistenceManager</ejb-name>
   <home>com.bea.portlet.prefs.PreferencePersistenceManagerHome</home>
   <remote>com.bea.portlet.prefs.PreferencePersistenceManager</remote>
   <ejb-class>com.bea.portlet.prefs.PreferencePersistenceManagerImpl
   </ejb-class>
   <session-type>Stateless</session-type>
   <transaction-type>Container</transaction-type>
   <env-entry>
      <env-entry-name>prefs-spi-jndi-name</env-entry-name>
      <env-entry-type>java.lang.String</env-entry-type>
      <env-entry-value>BEA_netuix.DefaultStore</env-entry-value>
   </env-entry>
   <env-entry>
      <env-entry-name>prefs-spi-home-class-name</env-entry-name>
      <env-entry-type>java.lang.String</env-entry-type>
      <env-entry-value>com.bea.portlet.prefs.provider.DefaultStoreHome
      </env-entry-value>
   </env-entry>
<!-- Snip -->
</session>

Best Practices in Using Portlet Preferences

Desktop Testing of Portlet Preferences

In order to view and test the preferences that you have created, you must use a desktop view from the WebLogic Portal Administration Console rather than WorkSpace Studio’s Open on Server view.

Portlets accessed from .portal files cannot store preferences. If you update a preference using a .portal file, your portlet encounters a java.lang.UnsupportedOperationException error.

Users Must be Authenticated

You must provide a means for users to log in before they can update preferences; users who are updating portlet preferences must first be authenticated. If an anonymous user attempts to update a portlet, a java.lang.SecurityException error occurs.

Note that portlets can always get portlet preferences whether or not the user is anonymous or whether the portlet is accessed via a .portal file.

Do Not Store Arbitrary Data as Preferences

It is tempting to store arbitrary application data as portlet preferences. For example, if you have a portlet that allows users to upload and store documents on the server, it might seem appropriate to store those documents as portlet preferences. This is not a good practice. The purpose of portlet preferences is to associate some properties for a portlet instance without having to be aware of any implementation-specific portlet instance IDs. These properties allow customization of the portlet’s behavior. The underlying implementation of portlet preferences is not designed for storing arbitrary application data.

The following steps outline an alternative implementation that can meet the needs of the portlet:

Perform setup steps:

Set up preferences in your portlet:

This procedure ensures that your application data is always scoped to portlet instances.

Do Not Use Instance IDs Instead of Preferences

The portal framework maintains instance identity using internally generated instance IDs. Portlets can access their instance IDs using getInstanceId() methods on com.bea.netuix.servlets.controls.portlet.PortletPresentationContext and com.bea.netuix.servlets.controls.portlet.PortletBackingContext.

Storing data directly in the database using portlet instance IDs does not work, for the following reasons:

Backing Files

The most common means of influencing portlet behavior within the control life cycle is to use a portlet backing file. A portlet backing file is a Java class that can contain methods corresponding to portal control life cycle stages, such as init() and preRender(). A portlet’s backing context, an abstraction of the portlet control itself, can be used to query and alter the portlet’s characteristics. For example, in the init() life cycle method, a request parameter might be evaluated, and depending on the parameter’s value, the portlet backing context can be used to specify whether the portlet is visible or hidden. For more information about backing contexts, refer to the Portal Development Guide.

Backing files can be attached to portals either by using WorkSpace Studio or coding them directly into a .portlet file.

Backing files are simple Java classes that implement the com.bea.netuix.servlets.controls.content.backing.JspBacking interface or extend the com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking interface abstract class. The methods on the interface mimic the controls life cycle methods (refer to How Backing Files are Executed) and are invoked at the same time the controls life cycle methods are invoked.

The following portal controls support backing files:

The interportlet communication example in Local Interportlet Communication uses backing files.

This section contains the following topics:

How Backing Files are Executed

All backing files are executed before and after the JSP is called. In its life cycle, each backing file calls these methods:

Figure 5-25 illustrates the life cycle of a backing file.

On every request, the following sequence occurs:

Thread Safety and Backing Files

A new instance of a backing file is created per request, so you do not have to worry about thread safety issues. New Java VMs are specially tuned for short-lived objects, so this is not the performance issue it was in the past. Also, JspContent controls support a special type of backing file that allows you to specify whether or not the backing file is thread safe. If this value is set to true, only one instance of the backing file is created and shared across all requests.

Scoping and Backing Files

The difference between having a backing file as part of <netuix: portlet backingfile =some_value> or part of <netuix: jspContent backingfile=some_value> is related to scoping.

For example, if you have the backing file on the portlet itself, you can actually stop the portlet from rendering. If the backing file is at the jspContent level, the portlet portion of the control tree has already run; you use this implementation to run processes that are specifically for the JSP in the portlet.

Backing File Guidelines

Follow these guidelines when creating a backing file:

Listing 5-10 shows an example backing file.In this example, the AbstractJspBacking class is extended to provide the backing functionality required by the portlet. The example uses a session attribute because of the volatility of the HTTPRequest object; BEA recommends that you pass data between life cycle methods using the session rather than the request object.

package backing;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import com.bea.netuix.events.Event;
import com.bea.netuix.events.CustomEvent;
import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;

public class ListenCustomerName extends AbstractJspBacking
{
   public void listenCustomerName(HttpServletRequest request,
   HttpServletResponse response, Event event)
   {
      CustomEvent customEvent = (CustomEvent) event;
      String message = (String) customEvent.getPayload();
      HttpSession mySession = request.getSession();
      mySession.setAttribute("customerName", message);
   }
} 

Adding a Backing File Using WorkSpace Studio

You can add a backing file to a portlet either from within WorkSpace Studio or by coding it directly into the file to which you are attaching it. Simply specify the backing file in the Backing File field of the Properties view, as shown in Figure 5-26. You need to specify the backing directory and, following a dot-separator, only the backing file name. Do not include the backing file extension; for example enter this:

backing.ListenCustomerName

Not this:

backing.ListenCustomerName.java

For the preceding example, if you include the file extension, the application interprets it as the file name—because the file path is specified by a dot-separator—and looks for a non-existent file called java in a non-existent directory called ListenCustomerName.

Adding the Backing File Directly to the .portlet File

To add the backing file by coding it into a .portlet file, use the backingFile parameter within the <netuix:jspContent> element, as shown in Listing 5-11.

<netuix:content>
   <netuix:jspContent
   backingFile="portletToPortlet.pageFlowSelectionDisplayOnly.menu.
      backing.MenuBacking"
   contentUri="/portletToPortlet/pageFlowSelectionDisplayOnly/menu/
      menu.jsp"/>
</netuix:content>

Portlet Appearance and Features

Some aspects of portlet appearance are controlled by default at the portal level, such as colors, layouts, and themes. Appearance/rendering characteristics and portlet-specific features include the use of title bars and associated states (minimize, maximize, float, and delete) and modes that affect portlet content (edit mode, help mode, and custom modes).

The following sections describe how to work with portlet-specific appearance/content features and modes:

Portlet Dependencies

In a rendered HTML page, the proper place to include most types of resources, such as script files or style sheet references, is in the header of the document. Portlets sometimes need to specify resources that are required for rendering the portlet in the page. In the past, methods for making required elements available on the page included placing elements into the skeleton, which is not recommended because this creates a coupling between the skeleton and the portlet; or putting references directly in the portlet content, leading to the possibility of creating invalid HTML.

The problem was exacerbated in a federated (WSRP) environment because remote portlets are potentially included in several places and there was no way for one of these portlets to indicate that it relies on, for example, a piece of a CSS that resides in an external file.

WebLogic Portal now provides an explicit way to handle this requirement, using the portlet dependencies feature.

The concepts related to skin and skeleton resource dependencies are more formally known as render dependencies and script dependencies. Typical examples of such dependencies are CSS files and JavaScript files.

Both skins and skeletons can now specify such dependencies as well as associated search paths to be used for resolving these dependencies. Additionally, mechanisms exist to eliminate redundancy and to provide a reliable ordering for dependencies related to skins, skeletons, and theme skin and skeletons. These same capabilities are now available for portlets as well as portals, so that a portlet can specify necessary dependencies in a standards-compliant way; you identify these dependencies using appropriate elements located in the head section of the rendered page. The other advantages of the Look & Feel dependencies framework are also realized at a portlet level, such as reliable ordering and redundancy elimination.

This section contains the following topics:

Identifying Portlet Dependencies

The configuration of portlet dependencies shares the same mechanisms as the standard Look & Feel—you use an XML configuration document conforming to a standard Look & Feel schema. This XML document is referenced from a .portlet file using an attribute on the portlet element.

As with a Look & Feel’s render dependencies, you can resolve a portlet’s render dependencies utilizing a set of application search paths. Additionally, the search paths of the Look & Feel skin, or any appropriate Theme skin, are used before the portlet’s own search paths to resolve a portlet’s render dependencies.

You can specify a portlet’s dependencies configuration file in the WorkSpace Studio Properties view by entering the value in LAF Dependencies Path field. Alternatively, you can add the attribute lafDependenciesUri to the portlet element in a .portlet file, as shown in the following example:

<netuix:portlet definitionLabel="myPortlet" title="My Portlet" lafDependenciesUri="/portlets/example/myPortlet.dependencies">

By convention, you should adhere to the following guidelines when setting up a portlet’s dependencies configuration file:

Although the guidelines listed here are not required, deviating from them can lead to unexpected behavior. For more information, refer to Considerations and Limitations.

The portlet dependencies configuration file uses standard types from the standard Look & Feel schemas and looks similar to the example shown in Listing 5-12.

<?xml version="1.0" encoding="UTF-8"?>
<p:window 
xmlns:p="http://www.bea.com/servers/portal/framework/laf/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/servers/portal/framework/laf/1.0.0 
laf-window-1_0_0.xsd ">
   <p:render-dependencies>
     <p:html>
       <p:links>
         <p:search-path>
           <p:path-element>.</p:path-element>
         </p:search-path>
         <p:link rel="stylesheet" type="text/css" href="my.css"/>
       </p:links>
     </p:html>
   </p:render-dependencies>
</p:window>

The configuration file shown in Listing 5-12 causes a CSS file to be included in the rendered page output (as a link element in the HTML head section). First, the search occurs for the CSS file relative to the Look & Feel or Theme skin search paths for the links element. If the CSS file is not found, then the search path in the configuration file is used. Relative search paths use the directory of the configuration file as a base.

The default behavior is to look first in the Look & Feel or Theme– specified search paths. This behavior allows a Look & Feel/Theme the ability to properly skin portlet resources. However, portlet-level resources should not be placed in the Look & Feel/Theme directories. If a situation arises when you do not want to use this behavior, you can disable it by specifying a value of false for the use-skin-paths attribute on the render-dependencies element.

Creating and Editing a Dependency File

You can use WorkSpace Studio to create a valid dependency file that you can then complete using Workshop’s XML editor.

The simplest way to create a dependency file is to select File > New > Other > Markup Files > Render Dependencies. The .dependencies file must reside in a WebLogic Portal framework project, within the web content folder (typically named WebContent).

You can also create a dependency file as follows:

You can use the WorkSpace Studio XML editor to add elements and attributes to the dependency file. Right-click on an element and use the menu to select child elements and add attributes. As shown in Figure 5-27, valid choices based on the schema file are automatically populated in the menu.

Example Dependency Files

This section includes the following examples:

Including JavaScript in a Render Dependencies File

Listing 5-13 illustrates how to include both an external JavaScript file as well as an embedded script. 

<p:window
    xmlns:p='http://www.bea.com/servers/portal/framework/laf/1.0.0'
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xsi:schemaLocation='http://www.bea.com/servers/portal/framework/laf/1.0.0
    laf-window-1_0_0.xsd '>
   <p:render-dependencies>
     <p:html>
       <p:scripts>
         <p:search-path>
           <p:path-element>.</p:path-element>
         </p:search-path>
         <p:script type='text/javascript' src='my.js'/>
         <p:script type='text/javascript'>
             alert('hello world');
         </p:script>
       </p:scripts>
     </p:html>
   </p:render-dependencies>
</p:window>

Including Meta and Style Elements in a Render Dependencies File

Listing 5-14 shows the use of both the metas and styles elements. The metas element lets you specify HTML meta tags, and the styles element lets you embed HTML style tags.

<p:window
    xmlns:p='http://www.bea.com/servers/portal/framework/laf/1.0.0'
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xsi:schemaLocation='http://www.bea.com/servers/portal/framework/laf/1.0.0
    laf-window-1_0_0.xsd '>
   <p:render-dependencies>
     <p:html>
       <p:metas>
         <p:meta name='keywords' content='pirate, ninja'/>
       </p:metas>
       <p:styles>
         <p:style type='text/css'>
           div.myClass {
             background-color: red;
           }
         </p:style>
       </p:styles>
     </p:html>
   </p:render-dependencies>
</p:window>

Considerations and Limitations

At this time, WorkSpace Studio does not provide editing capabilities for portlet render dependencies configuration files; you can use the included Eclipse-based XML file editor for this purpose.

BEA recommends that you not share a single .dependencies file across several portlets. Although WebLogic Portal does not prevent this usage, sharing a single file might lead to confusion when coordinating updates to the file later.

Scoping JavaScript Variables and CSS Styles

Whenever you place multiple instances of a portlet on a page, you can encounter scoping problems with JavaScript variables and CSS styles. For example, if a portlet includes inlined JavaScript and you place two instances of that portlet on a page, it is possible that changing a JavaScript variable in one portlet will affect the other portlet.

To ensure that JavaScript and CSS styles are scoped to a specific portlet instance, add the token wlp_rewrite_ to the front of the variable or style class name. When the portlet is rendered, this token is replaced by the portlet instance label, which is unique for each portlet instance.

For example, to ensure portlet instance-level scoping of a JavaScript variable called stockQuote that is defined in a .js file that is referenced from a .dependencies file, you need to append wlp_rewrite_ to the front of the variable name:

var wlp_rewrite_stockQuote 

To ensure portlet instance-level scoping of a CSS class name called portlet_bg that is defined in a .css file that is referenced from a .dependencies file, you need to append wlp_rewrite_ to the front of the class name. For example:

.wlp_rewrite_portlet_bg { background_color:white; }

In both of these cases, the wlp_rewrite_ token is replaced by the portlet’s instance label, which is a unique identifier.

Rewriting Resource URLs

WebLogic Portal also has the ability to rewrite URLs contained in the content of files referenced in a <script> or <style> section of a .dependencies file. The URLs are rewritten based on the standard Look and Feel URL Templating mechanism using the window-resource url-template-ref, as described in the section Optional Look And Feel URL Templates in the WebLogic Portal Development Guide.

For example, if your .dependencies file specifies:

 ...

      <p:styles>

        <p:search-path>

          <p:path-element>styles</p:path-element>

        </p:search-path>

        <p:style content-uri='my-style.css' type='text/css'/>

      </p:styles>

 ...

and the contents of my-style.css look like this:

.my_portlet_bg

{

    background-image: url('wlp_rewrite?/images/picture.gif/wlp_rewrite');

}

then when the portlet is rendered, the value of /images/picture.gif will be templatized based on the standard Look and Feel URL Templating mechanism.

In a non-WSRP case, this value can take one of two forms:

When the portlet that specifies the .dependencies file is being accessed remotely through a WLP remote (WSRP) portlet, then this rewritten URL also takes one of two forms:

Portlet Modes

All portlets created with WebLogic Portal support the use of modes. Modes allow you to affect the end user’s ability to edit the portlet or display Help for the portlet. You add icon buttons to a portlet’s title bar to indicate the availability of a mode.

The following pre-defined modes exist for WebLogic Portal:

You can also create your own custom portlet modes using WebLogic Portal.

Buttons for the selected modes appear in the portlet’s title bar. Figure 5-28 shows an example of the default buttons for the portlet modes when displayed in the editor; Figure 5-29 shows the appearance of the mode icons in a running portlet.

When you use the Portlet Wizard to create a portlet, mode and state settings are available on the Portlet Details dialog. These settings can also be edited in the portlet’s Properties view: The following sections describe possible methods of performing these tasks.

Adding or Removing a Mode for an Existing Portlet

To add or remove the Help or Edit mode from the title bar, follow these steps:

Properties Related to Portlet Modes

You can view and edit the mode's property details in the Properties view. For example, you can edit the Portlet Backing File property if you want to perform preprocessing before rendering the portlet's mode page (such as the edit page).

To display the mode properties for the portlet, click the expand/contract toggle button in the Portlet Mode area of the portlet. Edit mode properties and Help mode properties display in the Properties view.

For descriptions of the mode properties, refer to Table 5-7.

Creating Custom Modes

A custom mode is a portlet mode that you implement. Like with the help and edit modes, a custom mode is activated with a button that appears in the portlet’s title bar. To implement a custom mode, you need to supply a display part, typically a JSP, and a backing file. This section includes an example that explains how to create a simple custom mode that lets a user add or remove the Maximize button from a portlet. Once you understand the basic principles involved in writing a custom mode, you can create a custom mode to perform the specific tasks you want.

Figure 5-32 shows the example portlet and the portlet’s custom mode view. When the user clicks the custom mode button in the example portlet on the left, the portlet display changes to the custom mode view on the right. In this example, the custom mode offers a way for the user to add or remove the portlet’s Maximize button.

Table 5-12 briefly describes each of the custom mode properties:

Portlet States

States determine the end user’s ability to affect the rendering of a portlet. WebLogic Portal supports these portlet states:

Normal – the typical rendered appearance of the portlet.

When you use the Portlet Wizard to create a portlet, state and mode settings are available on the Portlet Details dialog. These settings can also be edited in the portlet’s Properties view: The following sections describe possible methods of performing these tasks.

Modifying Portlet States in WorkSpace Studio

You can select which of the states you want to include with the portlet by following these steps:

Minimizing or Maximizing a Portlet Programmatically

You can minimize or maximize a portlet either in the portlet file or in a portlet’s backing file. The actual code is the same for both. Here is an example of maximizing a (Java page flow) portlet:

PortletBackingContext context = PortletBackingContext.getPortletBackingContext(request);
context.setupStateChangeEvent(WindowCapabilities.MAXIMIZED.getName());

You can put this code in an action method of the Java page flow or in the handlePostbackData method of the backing file. When using the backing file, in order to get the handlePostbackData method to be called, you must have '_nfpb=true' in the URL.

These mechanisms do not work if asynchronous content rendering is enabled for the portlet.

Portlet Title Bar Icons

The default state and mode icons used in portlet title bars are stored in the wlp-lookandfeel-web-lib J2EE Shared Library; you can view them in Merged Projects view in the various subdirectories of framework/skins.

Portlet Height and Scrolling

All portlets created with WebLogic Portal support height and scrolling.

You can control the height of portlets and determine whether or not their contents scroll.

Portlet height and scrolling is controlled by the following CSS style attributes:

You can set these attributes on a portlet that is open in the workbench editor.

To set these properties, follow these steps:

Making All Portlets Scroll

To provide portlet height and scrolling automatically, you can specify an additional rule for the standard portlet content CSS class. For example, you can do one of the following:

For more information on portal skins, themes, and skeletons, refer to the Portal Development Guide.

Getting Request Data in Page Flow Portlets

A page flow stores information in the requests. If you have a portal page with multiple page flow portlets, you need a way for each page flow to individually store and retrieve that information. For example, the request object for a page might have a variable car_type, with a value of x. When the page flow runs, it obtains this value and uses it in some way. If you have another page flow portlet with a car_type value of z, and if only one request exists for the whole page, the two page flow portlets might interfere with each other. To prevent this problem, WebLogic Portal essentially makes a copy of the outer (portal) request to make separate scoped requests, one for each portlet. This gives each page flow portlet its own unique request to use to store its information.

In some cases, you might want to use information that is stored at the outer request rather than within the scoped request.

For example, if you use regular HTML tags within Netui form tags, you might have something similar to this:

<netui:form action="myAction">
   <input type="check box" name="test"/>
   <netui:button value="myAction"></netui:button>
</netui:form>

Based on the tags used above, you might typically use a regular getParameter request like this:

<%request.getParameter("test")%>

However, to get that HTML input value from the outer request, use the following:

<%@page import="org.apache.beehive.netui.pageflow.scoping.ScopedServletUtils"%>
   <%
   HttpServletRequest outerRequest = ScopedServletUtils.getOuterRequest
   ( request );
   %>
   test: <%=outerReq.getParameter("test")%>

JSP Tags and Controls in Portlets

WebLogic Portal provides JSP tags that you can use within JSPs. You can view available JSP tags in the Design Palette and then drag them into the Source View of your JSP, and use the Properties view to edit elements of the code.

WebLogic Portal also provides custom Java controls that make it easy for you to quickly add pre-built modules to your portal; custom Java controls exist for event management, Visitor Tools, Community management, and so on. For example, most user management functionality can be easily exposed with a User Manager Control on a page flow.

Viewing Available JSP Tags

When you open a JSP in WorkSpace Studio, you can use the Design Palette to display all the JSP tags currently loaded and available; Figure 5-40 shows a portion of the display.

To use a tag, drag it into the editor, use the Source View to edit the code directly, and use the Properties view to set properties, as shown in Figure 5-41:

For information about the Java class associated with each JSP tag, refer to the Javadoc.

Viewing Available Controls

To view the available custom controls provided by WebLogic Portal when viewing a page flow:

After you add a custom WebLogic Portal control, all the methods in the control become available to your Page Flow.

For more information about the custom controls provided by WebLogic Portal, refer to the Portal Development Guide. For details about each control, refer to the Javadoc. (Links to the Javadoc for each of the controls packages are conveniently listed in the Javadoc Overview frame.)

Portlet State Persistence

You can control portlet state persistence using the persistence-enabled attribute in the netuix-config.xml file, which is located by default in the WEB-INF directory. Using this attribute causes the state to be saved in the WebLogic Portal database. The attribute is set to false by default.

The following code segment shows an example of the attribute syntax:

<control-state-location>
<session persistence-enabled="true"/>
</control-state-location>

WebLogic Portal places an entry for the control tree state in the PROPERTY_KEY table, with the following PROPERTY_SET_NAME value:

Adding a Portlet to a Portal

In the development phase of the portal life cycle, you add portlets to a portal using the WorkSpace Studio workbench.

Follow these steps:

With the portlet selected, you can use the Properties view to customize desired portlet properties.

For detailed information about portlet properties, refer to Portlet Properties.

When you add a portlet to a page in the workbench editor, a reference to that portlet is added to the .portal file. You can use the .portal file as a template for creating desktops in the WebLogic Portal Administration Console. When a portal administrator creates a desktop based on that template, the portlet is added to the portal resource library where it can be added to pages in streaming desktops. For an overview of file-based portals compared with streaming portals, refer to the Portal Development Guide.

In the Staging phase of the portal life cycle, you use the WebLogic Portal Administration Console to configure portlets on desktops. A single portlet definition can be associated with one or more portals (desktops) by creating instances of the portlet. Each of these portlet instances can have its own “personality” and behavior as specified by a variety of different configuration options.

For details in adding a portlet to a portal desktop in the WebLogic Portal Administration Console, refer to Managing Portlets on Pages.

Deleting Portlets

To remove a portlet from a portal without deleting the portlet from your portal web project, right-click the portlet in the WorkSpace Studio workbench editor and click Delete.

To delete a portlet from your portal web project, right-click the portlet in the Package Explorer view and choose Delete.

To remove a portlet after you have assembled portlet instances into portal desktops using the Administration Console, refer to Deleting a Portlet.

Advanced Portlet Development with Tag Libraries

During the Development phase, you can use tag libraries to add features to a GroupSpace Community, a custom Community, or a portal web application. This section discusses the following tag libraries:

See the Communities Guide for additional information.

Adding ActiveMenus

You can add the ActiveMenus JSP tag library to a GroupSpace Community, a custom Community, or a portal web application.

The ActiveMenus JSP tag library lets you set up a popup menu that displays when the mouse hovers over specific text. An activemenus-config.xml file controls the contents of each menu. The activemenus_taglib.jar file contains the ActiveMenus tag library.

By default, a GroupSpace Community has ActiveMenus enabled, so you only need to configure the ActiveMenus tag (see Configuring the ActiveMenus Tag). See Figure 5-4 for an example of the ActiveMenus tag in a GroupSpace Community.

You can tie a user’s capability to the ActiveMenu that you see when you hover your mouse over an item (an Issue, for example) and hover over the arrow that appears. In this example, if your assigned capabilities include the ability to delete items, you will see the Delete choice, as shown in Figure 5-4.

Perform the following steps to enable ActiveMenus in a custom Community:

After you enable the ActiveMenus, you must configure the ActiveMenus tag.

Configuring the ActiveMenus Tag

To use the ActiveMenus tag, you must set up the activemenus-config.xml file (the XSD that defines this config file is located in the activemenus_taglib.jar file as activemenus-config.xsd). This activemenus-config.xml file file must exist in your web application's /WEB-INF directory. Multiple menus can be set up that consist of completely different items, styles, and icons.

Use the following sections to configure the activemenus-config.xml file file:

Using The TypeInclude tag

Use the typeInclude tag to keep your configuration file clean. Rather than adding the type tag (see Using The Type Tag) you can add this tag and point its href attribute to an XML file (relative to the web application) that contains all of the type information. An example of the typeInclude tag is:

<typeInclude xhref="/WEB-INF/activemenuTypes/username.xml"/>.

You can also use the type tag with the typeInclude tag in the configuration file. See the code sample in Listing 5-2.

<typeInclude xhref="/WEB-INF/activemenuTypes/username.xml"/>
<type>
     <menuItem>
          <param name="linkId"/>
          <action action="editLink">
               <i18nNamebundleName="com.bea.apps.groupspace.links.
                    LinksPopupMenu" key="edit.link"/>
          </action>
          <img xsrc="wlpAppsCollaborationCore/images/wlp-edit-16.gif"/>
     </menuItem>
</type>

When you point to another XML file, ensure that you namespace it correctly, as shown in Listing 5-3.

<type name="username"
     xmlns="http://www.bea.com/servers/apps/groupspace/ui/
          activemenus-config/9.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.bea.com/servers/apps/groupspace/ui/
          activemenus-config/9.0">
...
</type>

Using The Type Tag

The type tag defines the individual menus to use within the web application. The name attribute must be unique for each menu, because the name is how the menu is referenced when you use the ActiveMenus tag. Following is an example of the type tag:

<type name="foo">
</type>

Using The TypeDefault Tag

The typeDefault tag defines what displays in the browser where the ActiveMenus tag is used. You can control the text that displays, the style of the text, and the image that appears on the mouseover of that text (which denotes the menu itself).

The following items display within the browser where you used the ActiveMenus tag:

Using The menuItem Tag

The menuItem tag defines the individual items within the popup menu. Listing 5-4 shows a code sample using the menuItem tag.

<menuItem>
     <param name="userId"/>
     <xmlHttp url="GetFirstNameServlet"/>
     <row class="menuRow" style="backround-color:red"/>
     <text class="menuText" style="color:#000000"/>
     <rowRollover class="menuRowRollover" style="background-color:green"/>
     <textRollover class="menuTextRollover" style="color:#FFFFFF"/>
</menuItem>
<menuItem>
     <javascript>
     <name>Testing</name>
     <script>testing(this);</script>
     </javascript>
</menuItem>
<menuItem default="true" showMenuItem="false">
     <param name="q" value="foo"/>
     <link url="http://www.google.com">
          <name>Google</name>
     </link>
</menuItem>
<menuItem>
     <showMenuItem className="com.foo.CheckUserRights" methodName=
          "doesUserHaveRights">
          <rights name="can_view"/>
          <rights name="can_edit"/>
     </showMenuItem>
     <allParams/>
     <action action="addEditLink" disableAsync="true">
          <i18nName bundleName="com.foo.LinksPopupMenu" key="edit.link"/>
     </action>
</menuItem>
<menuItem>
     <allParams/>
     <dcAction action="showFeedData" dcContainerId="feedDataContainer">
          <i18nName bundleName="com.foo.LinksPopupMenu" key="show.
               feedData"/>
     </dcAction>
</menuItem>

The menuItem tag defines the individual items within the popup menu with the following four types:

Using the ActiveMenus Tag

The taglib.tld file is located in the activemenus_taglib.jar file.

You can use the following attributes and elements with the ActiveMenus tag:

Enabling Drag and Drop

You can use the DragDrop JSP tag library to enable drag and drop functionality in a GroupSpace Community, a custom Community, or a portal web application. You must identify draggable objects that are displayed on a JSP, and identify drop zones that are configured to react to a dropped draggable object. The drop zones react by triggering Page Flow actions, calling JavaScript functions, or posting data to a servlet.

Perform the following actions before you use the DragDrop tag library:

Using the DragDrop Tags

Three tags are defined in the DragDrop tag library. Following are descriptions of how each tag is used, along with sample JSP code:

Using the dragDropScript Tag

You must include the dragDropScript tag before you use any other DragDrop tags on the page. This tag ensures that the appropriate JavaScript libraries are included. The dragDropScript tag does not take any attributes.

The following example shows how to use the dragDropScript tag: <dragdrop:dragDropScript/>.

Using the draggableResource Tag

The draggableResource tag specifies a draggable resource on the page. The tag takes the following attributes:

The draggableResource tag performs a search for a child img tag that has a dragdrop:image attribute. This image becomes the image that is displayed while performing the drag operation. The image must have an absolute height and width attribute.

The resourceId value is accessible through the JavaScript function getSourceId(), when the value is dropped onto a resourceDropZone. The resourceId value is also available as a parameter in the request named sourceId, when it is dropped onto a resourceDropZone that triggers a POST action. See Listing 5-7.

<dragdrop:draggableResource imageId="0" resourceId="${id}"resourceName=
    "${name}">
     <img src="/image.gif" width="16px" height="16px"dragdrop:image="true"/>
         ${name}
</dragdrop:draggableResource>

Using the resourceDropZone Tag

The resourceDropZone tag identifies an area where draggable resources can be dropped.

The tag takes the following attributes:

Only one of the following attributes is required: jsFunctionCall, pageFlowAction, or formAction. The jsFunctionCall takes precedence, then pageFlowAction, and finally formAction.

The targetId value is accessible through the JavaScript function getTargetId() when a draggable resource is dropped. It is also available as a parameter in the targetId request when a draggable resource is dropped that triggers a POST action. The following code shows how this works:

<dragdrop:resourceDropZone targetId="${id}" pageFlowAction="moveIssue">
     <img src="/folder.gif"/>Issues Folder
</dragdrop:resourceDropZone>

Listing 5-8 demonstrates how the moveIssue action can be coded in a file called IssuesPageFlowController.java.

@Jpf.Action(forwards={ @Jpf.Forward(name = "success", path =
     "displayIssuesTree.do")})
     protected Forward moveIssue() {
          Forward forward = new Forward("success");
          String sourceId = getRequest().getParameter("sourceId");
          String targetId = getRequest().getParameter("targetId");
          move(sourceId, targetId);
          return forward;
     }

Enabling Dynamic Content

You can use the DynamicContent tag library to quickly update parts of a JSP page in a GroupSpace Community, a custom Community, or a portal web application.

The DynamicContent tags let you use an AJAX request to update part of a JSP page within a Page Flow-based portlet. The tags allow parts of the page to be updated without performing a full portal request. These AJAX requests are smaller and faster than full portal requests, and therefore provide a more responsive user experience when interacting with a portal application.

These tags are easy to incorporate into standard Page Flow-based portlet development and can help create advanced user interface features that improve a user’s portal experience.

Understanding the DynamicContent Tags

This section describes the main tags in the DynamicContent tag library.

The Container Tag

The Container tag designates a place on the JSP page that contains the HTML output from the execution of a Page Flow action. The only required attribute for this tag is a container id. This id is referenced by other DynamicContent tags to identify the container. The following code shows how this tag is used: <dc:container dcContainerId="outputContainer"/>.

The Container Action Script Tag

This tag is a child of the Container tag and identifies a Page Flow action that can be executed and whose HTML output is placed inside the parent container. The containerActionScript tag takes the following attributes:

Only the action attribute is required. The following code sample shows how this tag is used in the parent Container tag:

<dc:container dcContainerId="outputContainer">
     <dc:containerActionScript action="resetDynamicContentContainer"
          initial="true"/>
     <dc:containerActionScript action="showServerTime"/>
<dc:container/>

The Execute Container Action Tag

The Execute Container Action tag is used to create a call to a specific action inside a container. This tag takes the following attributes:

The dcContainerId and action attributes are required. Following is a sample of how this tag is used:

<dc:executeContainerAction action="showServerTime" dcContainerId=
"outputContainer"
var="showServerTimeVar"/>

In the previous example, the call to the specified action is stored in the variable showServerTimeVar. This variable can then be referenced, as shown in the following HTML code:

<form>
     <input type="button" onclick="${showServerTimeVar}" value="Show Server
          Time"/>
</form>

When the user clicks a button, an AJAX request is created that executes the showServerTime action and places the HTML output generated by that action into the container with the id of outputContainer.

The Parameter Tags

The DynamicContent tags also include tags for parameters that are passed into the action through the request. You can define parameters within the executeContainerAction tag or the containerActionScript tag. These parameters are then accessible in the Page Flow action by calling the request.getParameter() method.

Using the DynamicContent Tags

Some critical limitations are associated with the DynamicContent tags. The AJAX requests used to trigger the Page Flow actions are not processed through the main portal servlet. These requests go through a special servlet that performs some processing to ensure that the proper Page Flow instance is used. Many key elements that are normally available in the request are not accessible from these AJAX requests. For example, in Community-based portal applications, the CommunityContext object is not accessible from the AJAX request. The lack of access to some of these framework elements could have an impact on things like entitlements and security.

Because of these limitations, the DynamicContent tags are best suited for specific uses that involve small amounts of processing, with few dependencies on larger framework services. The following use cases could benefit from the DynamicContent tags:

See dev2dev for sample code and utilities contained in the sample.zip file.

Using the User Picker

During the Development phase, you can use the UserPicker tag library to add a form button to a JSP page in a GroupSpace Community, a custom Community, or a portal web application.

The UserPicker:popupButton tag provides the developer with the ability to add a form button to a JSP page which opens a popup window that displays a list of current users. You can select a user from this list. The name of the selected user is populated into a specified form field on the parent window.

Using the UserPicker Tags

This section describes the UserPicker:popupButton tag in a custom Community and how to use the following attributes:

Importing and Exporting Java Portlets

WorkSpace Studio lets you import and export Java (JSR168) portlets. You can import Java portlets from a Web Archive (WAR), Java Archive (JAR), or ZIP file directly into your workspace. WorkSpace Studio automatically creates .portlet files for all imported Java portlets, making them available for immediate use in your portal. You can also export Java portlets from your workspace to a supported archive file.

By default, WorkSpace Studio imports and exports the portlet.xml, any Java class files required by the portlet, and any Java source files. Also, if any class or source Java files are found within a JAR or ZIP archive, that archive is also imported or exported. You can optionally specify additional files to be imported or exported. Once exported, a Java portlet contained in a supported archive file can be used with any compatible web server.

Importing Java Portlets

To import Java portlets packaged in a supported archive file into your WorkSpace Studio workspace:

Exporting Java Portlets

You can export Java portlets to a new or existing supported archive file (WAR, JAR, or ZIP). To export Java portlets to a supported archive file:

Using the JSR168 Import Utility

WebLogic Portal provides a utility for automatically deploying JSR-168 portlets that are packaged in JSR-168 WAR files. This utility lets you import JSR-168 WAR files containing JSR-168 portlets, and expose the portlets in WSRP producers. For detailed information on this utility, see the chapter “Deploying Portal Applications” in the Production Operations Guide.