Web 2.0 portlet and portal programming support for IBM WebSphere Portal Version 6.1

This article shows you how to exploit the benefits of the Web 2.0 tooling support in IBM® Rational® Application Developer V7.5 for portlet and portal applications running on IBM® WebSphere® Portal V6.1. In a typical portlet application, each request to the server causes a complete refresh of the browser page, which leads to page flickering and performance gaps. Web 2.0 technology enables you to create more dynamic and responsive applications with a superior user experience. The technology aims to turn Web browsers into semi-rich clients by projecting user interface logic for page rendering, navigation, aggregation, and cross-portlet interaction into user's browsers.

The Web 2.0 tooling support provided with Rational Application Developer aids and expedites the process of creating such dynamic and responsive portlet and portal applications. Tooling support has been provided so that you can:

• Design portlets that interact using Client-Side Click-to-Action, which is a new event paradigm introduced in WebSphere Portal V6.1 for cooperation between portlets.
  
• Insert Person Menu and the capability to extend the Person Menu.
  
• Use an Ajax proxy for portlet applications.
  
• Use a client-side programming model to retrieve portlet preferences efficiently, performing portlet state changes on the client side.

This article discusses the above four topics in order. For each, it begins by describing a particular Web 2.0-based technology, followed with simple examples that illustrate the tooling support for the same.

Who should read this: Developers of portlet and portal-based applications.

Goals of this article: Describe how to develop rich, interactive, and responsive portlet and portal-based applications, exploiting the benefits of the tooling support for semantic tagging, Ajax proxy, and the Client-side programming model.

Designing portlets that interact and co-operate using Client-Side Click-to-Action

A click-to-action (C2A) event is one of the ways in which portlets can interact with each other and share information.

Click-to-action (C2A)

Using the C2A delivery method, you can transfer data from a source portlet to one or more target portlets with a simple click. When you click the source element, a pop-up menu displays a list of target actions that match the selected source. When you select a menu item, the corresponding target is invoked, and the source data is transferred to it. After the source data is processed, the target portlet triggers an action and displays the results.

Client-side click-to-action

Client-Side Click-to-Action is the new implementation of the C2A framework introduced in WebSphere Portal V6.1. It is based on Web 2.0 technology, and uses semantic tagging to define sources and targets.

The main purpose of semantic tags is to re-use the normal content of an HTML document, and to annotate it with meta-information that is evaluated during Document Object Model (DOM) parsing.

Semantic tagging and the Live Object Framework

Client-Side Click-to-Action is built on the Live Object Framework (LOF), which defines C2A sources as live objects in the system. The root element of a semantic tag is marked by adding a specific class to the element, which is specified by the live object framework.

The LOF also provides the basic DOM parsing and menu management services.

Advantages over the earlier C2A technique

The new Client-Side Click-to-Action technique introduced in WebSphere Portal has many advantages over the earlier C2A technique.

• The newly introduced event-creation paradigm is available for both IBM and Java™ Specification Request (JSR) portlets, whereas the earlier C2A technique was only available to portlets that adhered to the IBM Portlet API.
  
• It supports client-side JavaScript C2A target actions in addition to the server-side actions. For example, when you select a menu item on the source portlet and the source data is passed to the corresponding target, the action that is triggered at the target portlet can be a server-side action or a JavaScript action.
  
• With the new Client-Side Click-to-Action technique, evaluation and execution of C2A sources and targets occurs in a browser. Source and target matching no longer requires processing on the server, and the technique also removes menu generation code from the server. This results in reduced server load.
  
• The menu markup is generated only when the C2A source menu icon is clicked.

All of these advantages lead to a highly reactive and responsive UI, without server round trips and page flickering. All in all, they produce a superior user experience.

Terminology

Figure 1 illustrates C2A components. Table 1 lists the terminology that will be used in this article for Client-Side Click-to-Action.

Figure 1. Client-side click-to-action




Table 1. Terminology

Term	Description
C2A source	Typed data that is semantically tagged as a C2A source.
C2A target	An action defined for a particular C2A source type.
Source portlet	A portlet that contains one or more C2A source object definitions.
Target portlet	A portlet that contains one or more C2A target action definitions. (Note: a portlet can be both a source and a target portlet).
C2A hover UI	The icon that appears next to a C2A source object, indicating that there is a menu associated with that object.
C2A pop-up menu	The menu that appears when you click the C2A hover UI. It may contain an optional menu header (see Figure 1 above).
Menu header	The area at the top of the menu that the C2A source may populate with markup. It is generally used to provide descriptive information about the source object.
Live Object Framework	C2A is implemented as a service in this framework.

 

Rational Application Developer tooling support for Client-Side Click-to-Action

The tooling support for Client-Side Click-to-Action in Rational Application Developer provides capabilities like intuitive wizards, palette drawer and menu bar items, automatic code generation, and potential data type matches. These functions help you create Client-Side Click-to-Action-enabled portlet applications with as much ease as possible.

The tools enable you to create a portlet that can:

• Send data to other portlets (source portlet).
  
• Receive data from other portlets, and then update its own view accordingly (target portlet).

A portlet can be both a source and target, sending data to one portlet and receiving data from another portlet.

---

Back to top

Sample applications

This article discusses two example applications to demonstrate the features of Client-Side Click-to-Action:

• The first application shows you how to send data from a source portlet to a target portlet, and then invoke a simple JavaScript action on the target portlet after it receives the data.

• The second example is a portlet application used by a shipping company to maintain the details of its orders and customers. Five portlets in this application will be discussed here.
  
  
  • The Orders portlet, which maintains the monthly details of the orders
    
  • The Order Details portlet, which shows the details of an order
    
  • The Account Details portlet, which shows the account details for an order
    
  • The Customer Details portlet, which shows the details of a particular customer
    
  • The Tracking Details portlet, which shows the tracking details of an order

In the shipping application, you will see how the Order Details and Tracking Details portlets can exchange data using Client-Side Click-to-Action. In response to that action, a server-side action can be invoked on the Tracking Details portlet.

If you use the tools provided by Rational Application Developer, the above tasks are simplified to a great extent.

Sample application 1

In this simple application, you can send your name from the source portlet to the target portlet. Upon receiving the value, the target calls a JavaScript that prints "Hello [your name]" on the target portlet.

Figure 2. The Display Myname sample

To achieve the above result, you will execute the following steps:

1. Create a new portlet project (C2ASource).
   
2. Create a new portlet (C2ATarget portlet) in the C2ASource portlet project.
   
3. Enable the C2ASource portlet to send data to C2ATarget portlet using Client-Side Click-to-Action.
   
4. Insert a Client-Side Click-to-Action menu header onto the source pop-up menu.
   
5. Enable the C2ATarget portlet to receive data from the C2ASource portlet using a Client-Side Click-to-Action.
   
6. Publish the portlet application on WebSphere Portal.

Create a C2A Source Portlet project

1. Select File > New > Project > Portlet Project and click Next . The New Portlet Project wizard launches. Enter the following information, as shown in Figure 3.
   1. Enter C2aSource as the Project name of the portlet.
      
   2. Select WebSphere Portal 6.1 as the Target Runtime .
      
   3. Select JSR 168 Portlet (in this example), JSR 286 Portlet , or IBM Portlet as the Portlet API.
      
   4. Select Faces portlet (in this example) or Basic portlet as the Portlet type .
2. Click Next , and then click Finish .

Figure 3. Specify a name and location for the new portlet project

Create the C2aTarget portlet

Create a new portlet (C2aTarget) in the C2aSource portlet project that you created previously.

1. Right-click the C2ASource project in the Project Explorer.
   
2. Select New > Portlet . The New Portlet wizard launches. Enter the following information, as shown in Figure 4.
   1. Enter C2ATarget as the Name of the portlet.
      
   2. Keep the Portlet type for the C2ATarget portlet the same as for the C2ASource portlet.
   
   
3. Click Next , and then click Finish .

Figure 4. Select a portlet project for the new portlet

Enable the C2ASource portlet to send data

Enable the C2ASource portlet to send data to the C2ATarget portlet using Client-Side Click-to-Action

1. Double-click the C2ASourceView.jsp to open it in the Page Designer.
   
2. Select the Portlet drawer in the Palette view.
   
3. Drag the Client-Side Click-to-Action Output Property menu item from the palette onto the C2ASourcePortletView.jsp, as shown in Figure 5.

Figure 5. Drag palette item to design tab

1. Alternatively, select Insert > Portlet > Client-Side Click-to-Action Output Property from the menu bar, as shown in Figure 6.

Figure 6. Select menu command

The Insert Client-Side Click-to-Action Output Property wizard is displayed.

You need to input the following two fields to enable a portlet to send data:

• Data Type URI: Type name describing the format and semantics of the data
  
• Value: Actual data that is passed to the target operation

To do so, follow these steps, as shown in Figure 7:

1. Specify http://C2Asource#Myname in the Data Type URI field.
   
2. Specify your name (or the value that you want to send to the target portlet) in the Value field, and then click Finish .

Figure 7. Describe the type of data the portlet can transfer

1. Save the C2ASourceView.jsp.
   
2. To see the inserted code, click the Source tab.

The Client-Side Click-to-Action source object code shown in Listing 1 is auto generated and inserted in the C2ASourceView.jsp.

Listing 1. Source object code

<div class="C2A:source"> <span class="C2A:typename" style="display: none">http://C2Asource#MyName</span> <span class="C2A:value" style="display: none">Charu</span> <span class="C2A:anchor">Anchor Data</span> </div>

 

As you can observe in this code, the <div> and <span> tags have been semantically tagged to provide their class attributes with special meanings, which is evaluated during DOM parsing by the LOF.

The Anchor Data is the default value inserted for the C2A hover UI String (that is, the value that shows up in the browser), indicating a C2ASource. When the portlet application is published on WebSphere Portal, hovering over the Anchor Data shows you the source portlet menu. The source menu has one entry for each target portlet that can consume the value sent by the source portlet.

You can change this value from Anchor Data to the value that you want as the C2A hover UI String (preferably your name in this scenario).

Figure 8 shows the Design view of the C2ASourceView.jsp.

Figure 8. C2aAnchor

Insert menu header

To insert the Client-Side Click-to-Action menu header to the source pop-up menu, follow these steps.

1. Double-click the C2ASourceView.jsp to open it in the Page Designer.
   
2. Select the Portlet drawer in the Palette view.
   
3. Drag the Client Side click-to-action Menu Header menu item from the palette onto the C2ASourcePortletView.jsp, as shown in Figure 9.

Figure 9. Drag menu item to Design tab

1. Alternatively you can select Insert > Portlet > Client-Side Click-to-Action Menu Header Property from the menu bar.

The Insert Menu Header wizard is displayed.

1. Specify Display Myname as the header contents, as shown in Figure 10, and click Finish .

Figure 10. Specify the menu header contents of the source portlet

1. Save the C2ASourceView.jsp.
   
2. To see the inserted code, click the Source tab.

The Client-Side Click-to-Action menu header code shown in Listing 2 is auto generated and inserted in C2ASourceView.jsp.

Listing 2. Menu header code

<p class="c2a:display" style="display: none"> Display Myname </p>

 

The Client-Side Click-to-Action source object code is updated, as shown in Listing 3.

Listing 3. Source object code

<div class="c2a:source"> <span class="c2a:typename" style="display: none">http://c2asource#MyName</span> <span class="c2a:value" style="display: none">Charu</span> <span class="c2a:anchor">Charu Malhotra</span> <p class="c2a:display" style="display: none"> Display My name </p> </div>

 

Enable the C2ATarget portlet to receive data

Enable the C2ATarget portlet to receive data from the C2ASource portlet using Client-Side Click-to-Action.

Design the C2ATarget portlet

(You can ignore the following steps if you have selected Basic portlet as the Portlet type in step 1 of the section "Create a C2A Source Portlet project ", because basic portlet already comes with a default form, text field, and submit button.)

1. Double-click the C2ASourceView.jsp to open it.
   
2. Switch to the Design view.
   
3. Select the Form Tags drawer in the Palette view.
   
4. Drag the Form object from the palette onto the C2ATargetView.jsp.
   
5. Now, drag the Text Field object from the palette onto this form.
   
6. The Insert Text Field dialog is displayed. Specify C2AInput in the Name field, and click OK .
   
7. Again, drag the Submit button object from the palette onto the previous form and next to the text field that you inserted, as shown in Figure 11.
   
8. The Insert Submit Button dialog is displayed. Specify my submit in the Name field and Submit in the Label field, and then click OK .

Figure 11. Design view of C2aTarget port let before enabling it as a C2a target

Enable the C2ATarget port let to receive data

Enable the C2ATarget portlet to receive data from the C2ASource Portlet.

1. Select the Portlet drawer in the Palette view.
   
2. Drag the Client-Side Click-to-Action Input Property menu item from the palette onto the Submit button that you created using the previous steps (or the default Submit button for basic portlets), as shown in Figure 12.

Figure 12. Drag the Input Property palette item

1. Alternatively, you can select Insert > Portlet > Client-Side Click-to-Action Input Property from the menu bar.

The Insert Client-Side Click-to-Action Input Property wizard is displayed.

Three inputs are required from the user to enable a portlet to receive data

• Data Type URI: Type a name describing the format and semantics of the data. This should exactly match the Data Type URI field value for the C2A source portlet.
  
• Action Value: The action to be executed when the value sent by the C2A source portlet reaches the target portlet. This can be a server-side action or a JavaScript action.
  
• Action Label: The label to be displayed as the C2A pop-up menu for this target. This label corresponds to an entry into the C2A source portlet pop-up menu, as shown in Figure 1 previously.

The Data Type URI field shows potential data type matches in the drop-down list, as shown in Figure 13.

1. Select http://C2Asource#Myname from the Data Type URI field drop-down menu, as shown in Figure 14, and then click Next .

Figure 13. Describe the type of data that your portlet can accept

1. For this scenario Specify javascript:void(0); in the Action Value field to avoid a round trip to the server. In the next section you will see how a JavaScript action can be invoked on the submit event of the form.
   
2. Specify Send My name to Target in the Action Label field, as shown in Figure 14, and then click Finish .

Figure 14. Specify action details

1. Save the C2ATargetView.jsp.
   
2. To see the inserted code, click the Source tab.

The Client-Side Click-to-Action target object code shown in Listing 4 is auto generated and inserted in the C2ATargetView.jsp.

Listing 4. Target object code

<form class="c2a:target" action="javascript:void(0);"> <input type="text" name="c2aInput" size="20" class="c2a:action-param"><br> <input type="submit" name="mysubmit" value="Submit"> <span class="c2a:typename" style="display: none">http://c2asource#MyName</span> <span class="c2a:action-label" style="display: none"> Send My name to Target</span> </form>

 

The c2aInput text field, which has been tagged as c2a:action-param, receives the value sent by the C2A source.

Figure 15 shows the Design view of the C2ATargetView.jsp.

Figure 15. Design view of C2aTarget portlet after enabling it as a C2a target

1. Switch to the Source view of C2ATargetView.jsp.
   
2. Add the following code and JavaScript action in the C2ATargetView.jsp above the form tag, as shown in Listing 5.

Listing 5. JavaScript action above the form tag

<b><div id="mydiv"></div></b> <br><br> <script type="text/javascript"> function displayName() { var name = window.ibm.portal.c2a.event.value; var myname=document.getElementById("mydiv"); myname.innerHTML= "Hello " +name +"!!"; myname.value="Hello " +name + "!!"; } </script>

 

This JavaScript prints "Hello [yourname]" when invoked by the target portlet.

1. Next, in the form tag, add the onsubmit="displayName();return false;" attribute.

This invokes the above JavaScript when the value from the C2A source portlet reaches the target portlet, as shown in Listing 6.

Listing 6. Value from source to target

<form class="c2a:target" οnsubmit="displayName();return false;" action= "javascript:void(0);"> <input type="text" name="c2aInput" id=mytext size="20" class="c2a:actionparam"><br> <input type="submit" name="mysubmit" value="Submit"> <span class="c2a:typename" style="display: none">http://c2asource#MyName</span> <span class="c2a:action-label" style="display: none" >Send Myname to Target </span> </form>

 

1. Save the C2ATargetView.jsp.

Publish the portlet application on WebSphere Portal

Now the portlet application is ready to be published on WebSphere Portal.

Right-click the C2ASource portlet project and select Run on Server. Figure 16 shows what the sample looks like when it is published.

Figure 16. Display Myname sample published on WebSphere Portal V6.1


Click to enlarge

Sample application 2

You have the following portlets in the Shipping Details portlet application:

• Orders: This portlet displays the summary of orders placed in a particular month. It serves as a C2A source, sending:
  • Order_ID to Order Details and Account Details.
    
  • Customer_ID to Customer Details.

• Order Details: This portlet displays the details for a particular order. It serves as a C2A target, receiving Order_ID from the Orders portlet. This article demonstrates how to enable this portlet to send Tracking _ID to Tracking Details portlet using the C2A source option.

• Account Details: This portlet displays the account details for a particular order. It serves as a C2A target, receiving Order_ID from the Orders portlet.

• Customer Details: This portlet displays the details for a particular customer. It serves as a C2A target, receiving Customer_ID from Orders portlet.

• Tracking Details: This portlet displays the details for a particular shipment. This article demonstrates how to enable it to receive Tracking_ID from the Order Details portlet using the C2A target option.

To begin, download the sample available at the end of this article and run it on WebSphere Portal.

The current scenario is that OrdersPortlet sends:

• Order_ID to Order Details and Account Details
  
• Customer_ID to Customer Details

When the sample is published on the server, perform the following steps:

1. Enter any month (for example, September ) in the text box displayed in OrdersPortlet, and then click Submit .The orders for that particular month are displayed.
   
2. When the order details display, hover over any Order_ID. A menu is displayed.
   
3. Click the Show Order Details menu item. the details of the particular order are displayed in the Order Details portlet.
   
4. Click the Show Account Details menu item. The account details of the particular order are displayed in the Account Details portlet.
   
5. Now hover over any Customer_ID, and you can see a menu.
   
6. Click the Show Customer Details menu item. The details of the particular customer are displayed in the Customer Details portlet.

Figure 17 shows what the sample looks like when it is published (before enabling Order Details as a C2aSource that sends Tracking_ID to Tracking Details).

Figure 17. Shipping Details sample

As you can see from the published sample, currently there is no communication between the Order Details portlet and the Tracking Details portlet.

Now you will learn how to enable the Order Details portlet as a C2A source that sends Tracking_ID to the Tracking Details portlet. The Tracking Details portlet in turn will be enabled as the C2A target that receives Tracking_ID from the Order Details portlet. After it receives Tracking_ID, a server-side action is invoked on the Tracking Details portlet that displays the details of the particular shipment tracking, as shown in Figure 18.

Figure 18. Shipping Details sample objective

To achieve the above result, execute the following steps:

1. Enable OrderDetail as a C2A source
   
2. Enable TrackingDetail as a C2A target
   
3. Publish the portlet application on WebSphere Portal.

Enable OrderDetail as a C2A source

1. Double-click OrderDetailsView.jsp to open it in the Page Designer.
   
2. Drag Client side Click-to-Action Output Property from the palette onto the Tracking_ID column in the Design view of OrderDetailsView.jsp.

Figure 19. Drag property to the Tracking_ID column

1. The Insert Client-Side Click-to-Action Output Property wizard is displayed. Fill in the values for the Data Type URI and Value fields, as shown in Figure 20, and then click Finish .

Figure 20. Enable OrderDetail as a C2A source

1. Open OrderDetailsView.jsp in the Design view, .
   
2. Change the Anchor value from Anchor Data to the value you want as the C2A Hover UI string. Preferably, keep the C2A Hover UI string the same as the C2A value being passed. For example, in the current scenario, the Tracking_ID being passed by the Order Details portlet should be displayed to the user.

Figure 21. C2aAnchor2

1. Open OrderDetailsView.jsp in the Source view. The code shown in Listing 7 is inserted.

Listing 7. Tracking ID code

<td> <div class="c2a:source"> <span class="c2a:typename" style="display: none"> http://clientsidec2a#TrackingID</span> <span class="c2a:value" style="display: none"><%=od.getTrackingId() %></span> <span class="c2a:anchor"><%=od.getTrackingId()%></span> </div> </td>

 

1. Similar to the Display Myname application, you can also insert a menu header to the source. Specify Send Tracking Id to Tracking Details as the header contents.
   
2. Save OrderDetailsView.jsp. The Client-Side Click-to-Action source object code is updated as shown in Listing 8.

Listing 8. Updated source object code

<td> <div class="c2a:source"> <span class="c2a:typename" style="display: none"> http://clientsidec2a#TrackingID</span> <span class="c2a:value" style="display: none"> <%=od.getTrackingId() %></span> <span class="c2a:anchor"><%=od.getTrackingId()%></span> <p class="c2a:display" style="display: none"> Send Tracking Id to Tracking Details</p> </div> </td>

 

Enable TrackingDetail as a C2A target

1. Double-click and open TrackingDetailEntry.jsp in the Page Designer
   
2. Drag the Client-Side Click-to-Action Input Property menu item from the palette onto the Submit button in the Design view of TrackingDetailEntry.jsp file, as shown in Figure 22.

Figure 22. Palette DND on TrackingDetail

The Insert Client-Side Click-to-Action Input Property wizard is displayed.

1. Select http://clientsideC2A#TrackingID from the Data Type URI drop-down, as shown in Figure 23, and then press Next .

Figure 23. Enable TrackingDetail as C2A target 1

1. For this scenario, leave the default value in the Action Value field.
   
2. Specify Show Tracking Details in the Action Label field, as shown in Figure 24, and click Finish .

Figure 24. Enable TrackingDetail as C2A target 2

1. Open TrackingDetailEntry.jsp in the Source view to see the inserted code, as shown in Listing 9.

Listing 9. Updated TrackingDetail source code

<FORM method="POST" enctype="application/x-www-form-urlencoded" name="TrackingDetails" class="c2a:target" action="<%= tdb.getActionURL() %>"> <LABEL class="wpsLabelText" for="<%= TrackingPortlet.TRACKING_ID %>"> Enter tracking id to display details:</LABEL><BR/> <INPUT name="<%= TrackingPortlet.TRACKING_ID %>" type="text" class="wpsEditField c2a:action-param"/><BR/> <INPUT class="wpsButtonText" name="tracking details" type="submit" value="Submit"/> <span class="c2a:typename" style="display: none"> http://clientsidec2a#TrackingID</span> <span class="c2a:action-label" style="display: none">Show Tracking Details</span> </FORM>

 

Note: Change the name of the submit button from submit to tracking details and save TrackingDetailEntry.jsp.

Currently in WebSphere Portal, the submit button cannot be named "Submit" for Client-Side Click-to-Action target code to work properly.

1. Repeat these steps for TrackingView.jsp.

Publish the portlet application on WebSphere Portal

Now the portlet application is ready to be published on WebSphere Portal.

1. Right-click the portlet project and select Run on Server . Figure 25 shows what the sample looks like when it is published.

Figure 25. Shipping Details sample published on WebSphere Portal


Click to enlarge

---

Back to top

Inserting a Person Menu and extending the Person Menu in a portlet application

Following is some basic information about the components of the Person Menu in Rational Application Developer and WebSphere Portal.

The Person Java™Server Page (JSP™) tag provides contextual collaboration functionality related to a named person. It generates the HTML that renders the specific set of actions to display on the Person Menu. It was originally implemented as a server-side JSP tag that cannot be called from JavaScript code. In an attempt to minimize the server load for better performance and scalability, and in order to support Ajax clients, the Person JSP tag has been updated in WebSphere Portal to have a JavaScript API that can be called in the client.

The updated Person Menu displays a set of contact information about the selected person by specifying hCard attributes (hCard is the HTML representation of vCard).

The Person Menu extension allows you to extend the Person Menu, by enabling you to write JavaScript for actions that can be executed, or actions that are targeted. Rational Application Developer provides the necessary tooling support for the same.

Live Object Framework (LOF) and Semantic Tagging

The person names are semantically tagged using the standard hCard micro format, and hence behave as live objects in the system. The Person service that enables the Person Menu for hCards in the page is plugged in to the Live Object Framework (LOF).

Advantages over the original Person JSP tag

• The new semantic tagging-based Person Menu provides the same functionality as the traditional JSP Person tag, but with a better user experience:
  • It shows hover and pop-up on each hCard.
    
  • It provides access to actionable menu items like Show Profile, Send E-mail, and so on.

• The person information is retrieved only when the pop-up for the person is shown on the portal, and there is minimal server load until the person's name is clicked. Due to this on-demand data retrieval, there is no wasteful server work for person names that never get clicked.
  

• The Person Menu extension allows you to extend the Person Menu. You can add more than one extension. It also allows you to customize the look and feel and user registry.

Sample application

Now you will create a simple application to demonstrate how Rational Application Developer simplifies the task of inserting the Person Menu, and then extending it using the Person Menu extension in a portlet application.

Adding actions to the Person Menu

To design this application you will execute the following steps:

1. Create a WebSphere Portal targeted portlet project.
   
2. Insert a Person Menu in the portlet .jsp file.
   
3. Extend the Person Menu by inserting Person Menu extension code in the portlet .jsp file.
   
4. Provide the JavaScript for the Person Menu extension.

After designing the portlet application, publish it on WebSphere Portal.

Portlet project creation

1. Select File > New > Project > Portlet Project , and then press Next . The New Portlet Project wizard is displayed.
   
2. Enter PersonMenuExample as the Name of the portlet.
   
3. Select the WebSphere Portal 6.1 as the Target Runtime .
   
4. Select JSR 168 Portlet , JSR 286 Portlet , or IBM Portlet as the Portlet API.
   
5. Select Faces or Basic as the Portlet type .
   
6. Press Next , and then press Finish .

Insert a Person Menu

1. Double-click to open PersonMenuExampleView.jsp in the Page Designer.
   
2. Select the Portlet drawer in the Palette view.
   
3. Drag the Person Menu object from the Palette view onto the PersonMenuExampleView.jsp, as shown in Figure 26.

Figure 26. Person Menu palette item

1. Alternatively you can select Insert > Portlet > Person Menu from the menu bar. The intuitive Insert Person Menu wizard is displayed.
   
2. Specify the following hCard attributes, as shown in Figure 27.
   • Name
     
   • e-mail
     
   • Address (optional)
     
   • Phone number (optional)

Figure 27. Specify person menu attributes

1. Click Finish and save PersonMenuExampleView.jsp.
   
2. Open PersonMenuExampleView.jsp in the Source view. The code shown in Listing 10 has been inserted.

Listing 10. Inserted source code

<div class="vcard"> <span class="fn">Charu Malhotra</span> <span style="display: none"class="email">charumalhotra@in.ibm.com</span> </div>

 

Insert the Person Menu Extension

Continue with the above scenario.

1. Again, select the Portlet drawer in the Palette view.
   
2. Drag the Person Menu Extension object from the Palette view onto the PersonMenuExampleView.jsp, as shown in Figure 28.

Figure 28. Person Menu Extension palette item

1. Alternatively you can select Insert > Portlet > Person Menu Extension from the menu bar. The intuitive "Insert Person Menu Extension" wizard is displayed (see Figure 29).
   

Figure 29. Specify person menu extension attributes

The following inputs are required from you to insert a Person Menu Extension:

• Action details ID: The tooling support auto generates the action id for you. It must be unique for a particular Person Menu Extension.

• JavaScript : The JavaScript name that has the action that will be invoked when the menu item is selected. This should be available at the following directory:

[WebSphere Portal Server Home]/ui/wp.tagging.liveobject/semTagEar/Live_Object_Framework.ear/liveobjects.war/javascript.

• Label: A label for the Person Menu Extension.
  
• Description: A description for the Person Menu Extension.

• Specify ShowIf: This function decides the visibility of the Person Menu Extension.
  

• Specify Action: This is the function that is executed when the Person Menu Extension is clicked. The argument of the function should be @@@ARGS@@@ .
  

1. Click Finish and save PersonMenuExampleView.jsp.
   
2. Open PersonMenuExampleView.jsp in the Source view. The code shown in Listing 11 is auto generated.

Listing 11. Auto-generated source code

<div class="com.ibm.portal.action" style="display: none"> <span class="action-id">action_0</span> <span class="action-impl">/javascript/TestAction.js</span> <span class="action-context">person</span> <span class="action-label">Test Action</span> <span class="action-description">This is a test action for adding a Person Menu Extension </span> <span class="action-showif">javascript:TestAction.showif</span> <span class="action-url">javascript:TestAction.execute(@@@ARGS@@@)</span> </div>

 

The JavaScript for the Person Menu Extension (TestAction.js, as specified previously) should be available at the following directory:

[WebSphere Portal Server Home]

/ui/wp.tagging.liveobject/semTagEar/Live_Object_Framework.ear/liveobjects.war/javascript.

The sample contents for TestAction.js will be like that shown in Listing 12.

Listing 12. TestAction.js sample contents

var TestAction = { showif: function(person) {return true; }, execute: function(person) { alert("TestAction executed for: " + person.fn); } }

 

This will simply generate an alert when the new Test Action menu item is selected.

Publish the portlet application on WebSphere Portal

Now the portlet application is ready to be published on WebSphere Portal.

1. Right-click the PersonMenuExample portlet project and select Run on Server . Figure 30 shows what the sample looks like when it is published.

Figure 30. Person Menu sample published on WebSphere Portal

---

Back to top

Using Ajax proxy in portlet applications

Ajax allows Web pages to load data or markup fragments from a server using asynchronous requests that are processed in the background. Therefore, the requests do not interfere with the Web page that is currently displayed in the browser.

Ajax applications

You can use Ajax to increase the responsiveness and usability of a portlet application significantly. You do this by exchanging small amounts of data with the server, and consequently refreshing only small parts of the markup.

Same-origin policy

Ajax-based Web applications sometimes want to do Ajax requests to servers different from the server that served the HTML document.

For example, suppose you are designing a Web application that you want to:

1. Use an external representational state transfer (REST) service, such as Google suggestions, Yahoo spell-checking, and so on.
   
2. Use some remote corporate REST service available on the intranet.
   
3. Include news feeds from an external server (like CNN).

Restriction on XMP HTTP requests

In order to prevent malicious Ajax code served from one server from using your browser as the basis for attacking other servers, requests are only allowed to the server that served the current document, as shown in Figure 31. This same-origin policy prevents client-side scripts (in particular, JavaScript) from loading content from a different origin comprising protocol, domain name, and port.

Figure 31. Same-origin policy

Ajax proxy

To overcome the same-origin policy restriction, WebSphere Portal offers a solution that is based on a server-side HTTP proxy, the Ajax proxy layer. The Ajax proxy layer intercepts the calls, and retrieves the content from the remote site, as shown in Figure 32. It also allows for these resources to be cached in a central server. This security model allows administrators to restrict access to trusted origins in a very flexible way.

Figure 32. Ajax proxy layer

Sample application

The AjaxProxyPortletSample application used in this article consists of a portlet that accesses foreign domains using XMLHttpRequests. In order to overcome the same-origin policy, the portlet uses the Ajax proxy layer to access these domains.

1. Select the category (Rational or Lotus ) from the drop-down box, as shown in Figure 33.
   
2. Next, click the Get the articles button. The portlet gets the feeds of developerWorks articles (Rational or Lotus) from the IBM Website. It then displays the links to the topics.

Figure 33. Sample Ajax proxy

The complete sample is available for download at the end of this article. This article covers the Ajax proxy tooling support in Rational Application Developer. The implementation perspective is discussed only in brief.

The following sections discuss how you can:

• Enable Ajax proxy support for a new portlet project.
  
• Register the proxy servlet in the Web deployment descriptor.
  
• Specify Ajax proxy configuration parameters.
  
• Send an XMP HTTP request through an Ajax proxy.
  
• Publish the AjaxProxyPortletSample application on WebSphere Portal.
  
• Enable Ajax proxy support for an existing portlet project.
  
• Disable Ajax proxy support for an existing portlet project.

Enable Ajax proxy support for a new portlet project

1. Select File > New > Project > Portlet Project and then press Next . The New Portlet Project wizard is displayed, as shown in Figure 34.
   
2. Enter AjaxProxyPortletSample as the Name of the portlet.
   
3. Select WebSphere Portal 6.1 as the Target Runtime .
   
4. Select JSR 168 Portlet , JSR 286 Portlet , or IBM Portlet as the Portlet API .
   
5. Select Faces , Basic , Empty , or Struts as the Portlet type .

Figure 34. New portlet project with Ajax proxy enabled

1. Click Show Advanced Settings . The Project Facet page is displayed.
   
2. Expand Web 2.0 facet and select the Ajax proxy check box, as shown in Figure 35. Click OK .

Figure 35. Project Facets page

1. Press Next , and then press Finish .
   
2. Proxy servlet is registered in the Web deployment descriptor. Expand the Web Content > WEB-INF folders, and double-click Web.xml .
   
3. The Web deployment Descriptor is displayed. Click the Servlet tab, as shown in Figure 36.

Figure 36. Web deployment descriptor showing servlets and JavaServer Pages (JSPs)


Click to enlarge

1. The Ajax Proxy servlet with the class name com.ibm.wps.proxy.servlet.ProxyServlet gets registered in the Web.xml.

(Note: If you need to access resources that require authentication, you can specify a second servlet mapping that is associated with a security constraint. To specify a new servlet mapping, click the Add button in the URL Mappings section shown above in Figure 36. This invokes the Add Servlet Mapping dialog.)

1. Click the Source tab in Web Deployment Descriptor view to see the code added in Web.xml, as shown in Listing 13.

Listing 13. Added code in Web.xml

<servlet> <servlet-name>ProxyServlet</servlet-name> <servlet-class>com.ibm.wps.proxy.servlet.ProxyServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>ProxyServlet</servlet-name> <url-pattern>/proxy/*</url-pattern> </servlet-mapping>

 

1. The Ajax proxy configuration file is created. Expand the Web Content > WEB-INF folders, as shown in Figure 37.

Figure 37. Ajax proxy configuration file

1. Double click proxy-config.xml, which opens the Ajax Proxy Configuration Editor window shown in Figure 38.

Figure 38. Specify paths that map to a URL on a remote domain

1. Using the proxy-config.xml, you can specify the Ajax proxy configuration parameters. First, you can add an item to the proxy rules, as shown in Figure 39.

Figure 39. Add proxy rules

Context path mappings

A mapping element is used to map incoming requests to a target URL based on their context path. Therefore, each mapping element needs to specify a contextpath attribute (and optionally a URL attribute), as shown in Figure 40.

Figure 40. Specify context path mapping


Click to enlarge

Access policy

The policy element is used to define an access policy for a specific URL pattern, as shown in Figure 41. It includes the following sub-elements, as shown in Figure 42:

• Actions
  
• Headers
  
• Mime-types
  
• Cookies
  
• Users

Figure 41. Specify an access policy


Click to enlarge


Figure 42. Specify policy elements

General configuration parameters

You can specify the HTTP-related parameters, such as:

• Socket-timeout
  
• Retries
  
• Max-total-connections
  
• Max-connections-per-host

Sending an XML HTTP request

Suppose that you have created a context mapping in the proxy-config.xml file, such as that shown in Listing 14.

Listing 14. Context mapping

<proxy:mapping contextpath="/proxy" url="*"/>

 

Context path: /proxy

URL: *

Now, if you want to get the response from the http://www.ibm.com/developerworks/myfeed.rss site through the proxy servlet, then you have to create the XHR request by constructing its URL as follows:

http://www.myhostname.com/wps/myapplication/proxy/http/www.ibm.com/developerworks/myfeed.rss .

This complete URL contains the encoded path of the URL http://www.ibm.com/developerworks/myfeed.rss (that is, the http:// part has been replaced with http/)

You may achieve this encoding in your JavaScript file by constructing the function as shown in Listing 15.

Listing 15. Replace characters in the URL

encodeURL: function(url) { return url.replace(/:/, "/"); }

 

This produces a context mapping, like that shown in Listing 16.

Listing 16. Context mapping produced by the specified function

<proxy:mapping contextpath="/dw" url="http://www.ibm.com/developerworks/*"/>

 

Context path: /dw

URL: http://www.ibm.com/developerworks/*

In this case, if you want to get the response from the http://www.ibm.com/developerworks/myfeed.rss site through a proxy servlet, then you have to create the XHR request by constructing its URL as follows:

http://www.myhostname.com/wps/myapplication/dw/myfeed.rss

The proxy.js file in the AjaxProxyPortletSample contains the code that performs the following operations:

• Encoding the URL
  
• Constructing the XHR object for this URL
  
• Sending the XHR request to the server, and loading the response
  
• Parsing the response to display it in the AjaxProxyPortletSampleView.jsp file

To have a complete look at the JavaScript file, expand the Web Content > JS folders in the AjaxProxyPortletSample, and then open proxy.js.

Publish the portlet application on WebSphere Portal

1. Right-click the AjaxProxyPortletSample and select Run on Server .
   

1. When the project is published, select the category (Rational or Lotus ) from the drop-down list.
   

1. Next, click Get the articles . The sample shows the links to the latest topics in the selected category in response.

When you click the Get the articles button, the XMLHttpRequest object is created using a URL that corresponds to the selected topic (Rational or Lotus). This request is then passed to the ProxyServlet, which in turn delegates it to the target server, retrieves the response and, finally, returns the XML response back to the client browser. The JavaScript then parses and displays this response in a user friendly manner, as shown in Figure 43.

Figure 43. Ajax proxy portlet sample published on WebSphere Portal

Enabling Ajax proxy support for an existing portlet project

1. Right-click the project and select Properties > Project Facets . The Project Facet window appears.
   
2. Expand Web 2.0 and select the Ajax proxy check box, and then click OK.

Disabling Ajax proxy support for an existing portlet project

1. Right-click the project and select Properties > Project Facets . The Project Facet window is displayed.
   
2. On the Project Facets page, clear Ajax proxy (as shown in Figure 44), and then press OK .
   
3. Observe that the proxy-config.xml is deleted from the WEB-INF folder, and the ProxyServlet entry is deleted from Web.xml.

Figure 44. Disabling Ajax support

---

Back to top

Using client-side programming model support in WebSphere Portal

Previous versions of WebSphere Portal required that a request be sent to the server for each portlet operation. For example, if you changed the portlet window state to minimize or maximize, a submit request had to be sent to the server and the response sent back to your browser. This would cause a page refresh, and only subsequently was the portlet shown in the maximized or minimized state. Typically these types of server-side operations require repeated round trips to the server.

To reduce this type of server traffic, WebSphere Portal now supports a client-side programming model in which portlet state changes can be performed more efficiently on the client side.

To achieve this, Rational Application Developer provides the necessary tooling support for a client-side programming model.

The following sections discuss these topics:

1. Create a client side programming model support-enabled portlet project.
   
2. Use client-side programming model support to retrieve portlet preferences in basic portlet projects.
   
3. Publish the portlet application on WebSphere Portal.

Client-side programming model support for a new portlet project

Follow these steps to create a client-side programming model support-enabled portlet project.

1. Select File > New > Project > Portlet Project and press Next . The New Portlet Project wizard is displayed.
   
2. Enter ClientSideSample as the Name of the portlet.
   
3. Select WebSphere Portal 6.1 as the Target Runtime .
   
4. Select JSR 168 Portlet or JSR 286 Portlet as the Portlet API .
   
5. Select Basic as the Portlet type .
   
6. Press Next three times. The Advanced Settings page is displayed, as shown in Figure 45.

Figure 45. Client-side support-enabled portlet project creation wizard

1. The Client Side Capabilities check box under Web2.0 Portlet Feature group is selected by default. Selecting this enables the client-side programming model support for a new portlet project. Click Finish .

The ClientSideSample portlet project is created, and ClientSideSampleView.jsp opens in the Page Designer.

To see the code that is inserted, click the Source tab, as shown in Listing 17.

Listing 17. Auto-generated client-side code

<%@ taglib uri=http://www.ibm.com/xmlns/prod/websphere/portal/v6.1/portlet-client-model prefix="portlet-client-model" %> <portlet-client-model:init> <portlet-client-model:require module="ibm.portal.xml.*"/> <portlet-client-model:require module="ibm.portal.portlet.*"/> </portlet-client-model:init>

 

The taglib shown in Listing 18 is added in the ClientSideSampleView.jsp file.

Listing 18. The taglib added to ClientSideSampleView.jsp

<%@taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v6.1/portlet-client-model" prefix="portlet-client-model" %>

 

The tag shown in Listing 19 is also added in the Java™Server Page (JSP) file

Listing 19. Tag added to JSP file

<portlet-client-model:init> <portlet-client-model:require module="ibm.portal.xml.*"/> <portlet-client-model:require module="ibm.portal.portlet.*"/> </portlet-client-model:init>

 

This means that:

• The taglib includes the necessary markup and artifacts needed to use the required module on the client.
  
• The ibm.portal.portlet.* module enables you to use PortletWindow, PortletPreference, PortletState and XMLPortletRequest on the client.
  
• The ibm.portal.xml.* module allows the use of XSLT and XPath on the client.

Using client-side programming model support to retrieve portlet preferences in basic portlet projects

Now you will see how to use client-side programming model support to retrieve portlet preferences on the client side, as shown in Figure 46. This action used to happen on the server side. Continue with the ClientSideSample project created previously.

1. Open the Portlet Deployment Descriptor.
   
2. Click the Portlets tab and select the portlet (ClientSideSample).
   
3. Move to the Persistent Preference Store section and add a preference (name it MyPreference ).
   
4. Give a value to this preference.

Figure 46. Add a preference in the Portlet Deployment Descriptor

1. Open the ClientSideSampleView.jsp file.
   
2. Open the Page Data view.
   
3. Expand the Page Data view and select the PortletPreferences node.
   
4. Right-click the Preferences node and select New > PortletPreferences , as shown in Figure 47.

Figure 47. Add a preference in the Page Data view

1. Create a new preference variable in the Add Attribute dialog, as shown in Figure 48. Give this preference the same name that you specified previously for the preference created in the Portlet Deployment Descriptor (that is, name it MyPreference ).

Figure 48. Add an attribute to portletPreferences

1. Open ClientSideSampleView.jsp.
   
2. Drag MyPreference from under the PortletPreferences node in the Page Data view¸ as shown in Figure 49, and drop it on ClientSideSampleView.jsp.

Figure 49. Drag a preference from the Page Data view

The Insert Java Bean dialog is displayed, as shown in Figure 50.

Figure 50. Configure data controls

1. Press Finish .
   
2. To see the code that is inserted click the Source tab, as shown in Listing 20.

Listing 20. Inserted code for MyPreference

<script type="text/javascript"> var preferenceJSONObject= {"bindings": [{ "pref":"MyPreference","id":"ibm__pref_MyPreference_uq_1"} ] }; function <portlet:namespace/>_getPref(portletWindow, status, portletPrefs) { if (status==ibm.portal.portlet.PortletWindow.STATUS_OK) { portletWindow.setAttribute("preferences", portletPrefs); var portletPref_ =portletPrefs; var len = preferenceJSONObject.bindings.length; for(var i=0; i<len ; i++) { var pref = preferenceJSONObject.bindings[i].pref; var pref_val = portletPref_.getValue(pref,""); document.getElementById(preferenceJSONObject.bindings[i].id).innerHTML=pref_val; } } else { alert("error loading feed"); } } function callOnLoad(){ <portlet:namespace/>_portletWindow =new ibm.portal.portlet.PortletWindow ("<%=portletWindowID%>"); <portlet:namespace/>_portletWindow.getPortletPreferences(<portlet:namespace/>_getPref); } dojo.addOnLoad(callOnLoad); </script>

 

The above auto-generated code retrieves portlet preferences on the client side.

Note: The auto-generated code may incorrectly generate dojo_101.addOnLoad(callOnLoad); in place of the correct dojo.addOnLoad(callOnLoad);

If the incorrect code is generated in the JSP, you have to manually correct it so that when the application is published it runs properly on WebSphere Portal.

The preferenceJSONObject contents are shown in Listing 21.

Listing 21. Contents of preferenceJSONObject

var preferenceJSONObject= {"bindings": [ {"pref":"MyPreference","id":"ibm__pref_MyPreference_uq_1"} ] };

 

The HTML code shown in Listing 22 is also added in the source view.

Listing 22. Generated HTML code

<table> <tbody> <tr> <td align="left">MyPreference:</td> <td> <div id="ibm__pref_MyPreference_uq_1"></div> </td> </tr> </tbody> </table>

 

1. Similarly, you can add another preference (MyPreference2) in the Portlet Deployment Descriptor (specifying a value for it) and also add the same preference in the Page Data view (in the same way as you did previously for MyPreference.
   
2. Open the Design view. Drag this preference into the JSP as you did previously.
   
3. Now open the Source view.

You can see that the preferenceJSONObject contents are now updated, as shown in Listing 23.

Listing 23. Updated JSONObject contents

var preferenceJSONObject= {"bindings": [ {"pref":"MyPreference2","id":"ibm__pref_MyPreference2_uq_1"}, {"pref":"MyPreference","id":"ibm__pref_MyPreference_uq_1"} ] };

 

Publish the portlet application on WebSphere Portal

1. Right-click the ClientSideSample Portlet project and select Run on Server .
   
2. You can observe that the preference values that you specified in the Portlet Deployment Descriptor Preference Store are displayed correctly, as shown in Figure 51.

Figure 51. ClientSideSample published on WebSphere Portal

---

Back to top

What you have learned

The tools provided by Rational Application Developer simplify the development of rich, interactive, and responsive portlet and portal-based applications. They exploit the benefits of the client-side programming model, Client-Side Click-to-Action, Person Menu, Person Menu Extension, and Ajax proxy. You need to customize only the code generated according to the requirements of your application.

 

Resources

Learn

• Learn more in the IBM WebSphere Portal Version 6.1 Information Center where you can find information about planning, installing, configuring, administering, developing, and troubleshooting.
  
• Explore the IBM Rational Application Developer Version 7.5 Information Center to learn more..
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
• Explore the Rational Application Developer Version 7.5 Information Center to find in-depth information.
  
• Subscribe to the IBM developerWorks newsletter , a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  
• Subscribe to the developerWorks Rational zone newsletter . Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  
• Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
  
• Browse the technology bookstore for books on these and other technical topics.