ALI Portlet Development

IDK Quickstart: Hello World Portlet - Java

This simplified Hello World portlet example allows a user to set the message that is displayed within a portlet. The portlet code sends a Portlet setting to a Set Preferences page, which stores it in the ALI database and redirects to the portal, refreshing the portlet display. This page provides instructions and sample code for Java developers.

Note: This example assumes you have installed the AquaLogic Interaction Development Kit (IDK). For details on installing the IDK, see the IDK Product Documentation. To download the IDK or ALI Logging Utilities, go to the ALUI Developer Center on dev2dev.

Step 1: Set Up a Custom IDK Project - Eclipse

The instructions for setting up a new project are different depending on whether or not you have WTP installed.

Eclipse with WTP

  1. Open Eclipse and click File | New | Other... | Web | Dynamic Web Project.

  2. Enter a Project Name (e.g., "idkWeb").

  3. Choose a Target Runtime from the drop-down list. If you have not previously configured a server runtime, click New... to configure your Tomcat setup.  

  4. Click Finish to complete the Dynamic Web Project wizard.

  5. Import the IDK Web project template:

    1. Right-click the project in the Project Explorer and click Import | General | File System.

    2. To define the From directory field, navigate to the IDK root directory and select the \devkit\WEB-INF folder.

    3. Change the Into folder field to <project name>/WebContent/WEB-INF (e.g., idkWeb/WebContent/WEB-INF).

    4. Click Finish.

Note: The Eclipse Web project view hides the imported JARs stored in WEB-INF/lib and puts those files under ./Java Resources/src/Libraries/Web App Libraries.

Eclipse Stand-Alone (without WTP)

  1. Open Eclipse and click File | New| Project. Click Next.

  2. Enter a Project Name (e.g., "idkWeb"). Click Next and Finish.

  3. In the Package Explorer in Eclipse, right-click on the new project and click Properties | Java Build Path | Libraries | Add External Jars.

  4. Select the *.jar files from the IDK installation directory under the ptedk\5.x\devkit\java\WEB-INF\lib directory. Click OK.

Step 2: Create Portlet Pages (.jsp)

As noted above, this example uses two pages: a portlet that displays the current setting value and a form for changing the value, and a page that sets the value in the ALI database and redirects to the portal page.

In your idkWeb project, create a new JSP page for the portlet (portlet.jsp).

The portlet code shown below instantiates the IDK and uses the IDK Portlet API IPortletRequest object to check for a Portlet setting called "PortletEntry." If the setting has an associated value, the portlet displays it. The portlet also displays a form that allows the user to enter a value. When the user clicks Submit, the portlet code sends the value from the form in a request to the setPrefs.jsp page, shown next.

Note: There is no need to include html, head and body tags; the portlet is displayed as part of the HTML table that makes up the portal page.

<%@ page language="java" import="com.plumtree.remote.portlet.*,java.util.Date" %>
You refreshed at <%= new Date().toString()%><br/>

<%
//get the idk
IPortletContext portletContext = PortletContextFactory.createPortletContext(request, response);
IPortletRequest portletRequest = portletContext.getRequest();
String settingKey = "PortletEntry";

String settingValue = portletRequest.getSettingValue(SettingType.Portlet, settingKey);

//if the entry has already been set, display it here
if (null != settingValue)
{
%>
<br/><b> Preference value is <%=settingValue%></b>!<br/>
<%
}  

//form to enter the preference
%>
<P>Enter your preference:
<form METHOD="post" ACTION="setPrefs.jsp" name="form1">
<input type="text" name="<%=settingKey%>">
<br/>
<input type="submit" name="Submit" value="Submit">
</form>

Next, create the Set Preferences page (setPrefs.jsp). The code shown below gets the value for the PortletEntry Portlet setting from the request, then uses the IDK Portlet API IPortletResponse object to add the setting to the database and redirect to the portal. The redirect causes the portal page to refresh and display the updated setting in the portlet.

<%@ page language="java" import="com.plumtree.remote.portlet.*" %>

<%
//set the cache control so we don't get a cached page
response.setHeader("Cache-control", "max-age=0");

//get the idk
IPortletContext portletContext = PortletContextFactory.createPortletContext(request, response);  

//get IPortletResponse to set preferences and redirect back to the portal
IPortletResponse portletResponse = portletContext.getResponse();

//get the setting value from the servlet request
String settingKey = "PortletEntry";
String settingValue = request.getParameter(settingKey);

//set the setting value
portletResponse.setSettingValue(SettingType.Portlet, settingKey, settingValue);

//redirect back to the portal
portletResponse.returnToPortal();

%>

Step 3: Deploy and Debug Your Custom Project

The instructions for debugging are also different depending on whether or not you have WTP installed.

Eclipse with WTP

These instructions use Tomcat as an example.

  1. Define the server in Eclipse:

    1. Click File | New | Other | Server | Server and click Next.

    2. Select the server type as Tomcat v5.0 and click Next.

    3. Select the Tomcat v5.0 installation directory and click Next.

    4. Add your project (e.g., idkWeb) to the list of configured Tomcat projects and click Finish.

  2. Run and debug the application:

    1. In Project Explorer, right-click your project (e.g., idkWeb) and click Debug As | Debug On Server.

    2. Select the existing server and click Finish.

  3. When Tomcat starts in a new Servers tab, hit http://localhost:8080/idkWeb/servlet/AxisServlet to ensure that Axis has deployed correctly and the Web service APIs are correctly configured.

For instructions on deploying your project in the portal, see Next Steps at the bottom of this page.

Eclipse Stand-Alone (without WTP)

  1. Deploy the IDK in your application server. For BEA WebLogic or Apache Tomcat, follow the instructions below. For IBM WebSphere, you must create a .war or .ear file that is compatible with WebSphere. You must first create an appropriate server-config.wsdd using the IDK DeployServlet or the supplied service wsdd files. See the WebSphere documentation for detailed instructions. 

    1. Create a folder called \idkWeb in the application server's \webapps directory. (For example, if Tomcat is installed in C:\tomcat, the path might be C:\tomcat\webapps\idkWeb.)

    2. Navigate to the IDK installation directory and copy the WEB-INF and its \LIB subfolder from \ptedk\5.x\devkit\ folder to the new \webapps\idkWeb directory in the application server. This loads Apache AXIS into the application server.

    3. Confirm that Apache AXIS is available by opening the following page in a Web browser: http://<hostname:port>/idkWeb/servlet/AxisServlet (change <hostname:port> to fit your application server, e.g., localhost:8080 for Tomcat). The browser should display the message "And now... Some Services" and a list of installed services.

  2. Compile the class that implements the IDK interface and copy the entire package structure to the appropriate location in your Web application (usually the \WEB-INF\classes directory).

  3. Start your application server. (In most cases, you must restart your application server after copying a file.)

Next Steps

To view a portlet in the portal, you must configure portal objects as described in Configuring Portlets in the Portal.  Note: The Set Preferences page must be included in the gateway space.

For more information on the IPortletRequest and IPortletResponse objects, see IDK Proxy and Portlet APIs.

Forms and functions must be uniquely named. Always use the Portlet ID in form and function names to avoid name collisions with other portlets on the portal page. You can append the Portlet ID using the pt:namespace and pt:token tags, as shown in the code below. (Adaptive Tags can be used on any gatewayed page. For details, see Developing Adaptive Portlets: Using Adaptive Tags.)

<pt:namespace pt:token="$$TOKEN$$" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>
<a onclick="doStuff$$TOKEN$$();" href="#">do stuff</a>
<script>
   function doStuff$$TOKEN$$() {
     alert("hello");
   }
</script>

Valid values for the token must be in the ASCII range 0x21 to 0x7E, excluding "<". The scope of the token runs from the tag defining it to the end of the file; you cannot use a token prior to defining it. A second pt:namespace tag with a different token redefines it; two tokens cannot be defined at the same time.

The Adaptive Portlet Toolkit provides tools for building cohesive applications within a portal page. Adaptive portlets work dynamically to react to user actions and refresh content within the page. For details on adaptive portlets, including Adaptive Tags and the ALI Scripting Framework, see Adaptive Pagelets.

The Programmable Remote Client (PRC) allows you to embed components and functions into any Web application delivered through the ALI framework. The PRC provides APIs for a wide range of functionality, including portal object management, search, and content processing, as well as ALI Collaboration and ALI Publisher operations. For details, see Remote APIs.