IBM Rational Application Developer Version 7.5 Portal Toolkit

IBM Rational Application Developer Version 7.5Portal Toolkit: Part 3. Web 2.0 portlet and portalprogramming support for IBM WebSphere PortalVersion 6.1Skill Level: Intermediate

Charu Malhotra ([email protected])Associate Software EngineerIBM Corporation

26 May 2009

This article describes the Web 2.0 tooling support introduced in IBM® Rational®Application Developer V7.5 for portlet and portal applications targeted on IBM®WebSphere® Portal V6.1 and higher. To help you understand this tooling supportbetter, the author also discusses the basics and benefits of the Web 2.0-basedtechnologies.

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

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

• Design portlets that interact using Client-Side Click-to-Action, which is anew event paradigm introduced in WebSphere Portal V6.1 for cooperation

Part 3. Web 2.0 portlet and portal programming support for IBM WebSphere Portal Version 6.1 Trademarks© Copyright IBM Corporation 2009. All rights reserved. Page 1 of 73

mailto:[email protected]

http://www.ibm.com/developerworks/ibm/trademarks/

http://www.ibm.com/legal/copytrade.shtml

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 preferencesefficiently, performing portlet state changes on the client side.

This article discusses the above four topics in order. For each, it begins bydescribing a particular Web 2.0-based technology, followed with simple examplesthat 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 responsiveportlet and portal-based applications, exploiting the benefits of the tooling support forsemantic tagging, Ajax proxy, and the Client-side programming model.

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

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

Click-to-action (C2A)

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

Client-side click-to-action

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

The main purpose of semantic tags is to re-use the normal content of an HTMLdocument, and to annotate it with meta-information that is evaluated duringDocument 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

developerWorks® ibm.com/developerWorks




defines C2A sources as live objects in the system. The root element of a semantictag is marked by adding a specific class to the element, which is specified by the liveobject 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 hasmany advantages over the earlier C2A technique.

• The newly introduced event-creation paradigm is available for both IBMand Java™ Specification Request (JSR) portlets, whereas the earlier C2Atechnique was only available to portlets that adhered to the IBM PortletAPI.

• It supports client-side JavaScript C2A target actions in addition to theserver-side actions. For example, when you select a menu item on thesource 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 actionor a JavaScript action.

• With the new Client-Side Click-to-Action technique, evaluation andexecution of C2A sources and targets occurs in a browser. Source andtarget matching no longer requires processing on the server, and thetechnique also removes menu generation code from the server. Thisresults in reduced server load.

• The menu markup is generated only when the C2A source menu icon isclicked.

All of these advantages lead to a highly reactive and responsive UI, without serverround 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 usedin this article for Client-Side Click-to-Action.

Figure 1. Client-side click-to-action

ibm.com/developerWorks developerWorks®




Table 1. TerminologyTerm Description

C2A source Typed data that is semantically tagged as a C2Asource.

C2A target An action defined for a particular C2A sourcetype.

Source portlet A portlet that contains one or more C2A sourceobject definitions.

Target portlet A portlet that contains one or more C2A targetaction definitions. (Note: a portlet can be both asource and a target portlet).

C2A hover UI The icon that appears next to a C2A sourceobject, indicating that there is a menu associatedwith that object.

C2A pop-up menu The menu that appears when you click the C2Ahover UI. It may contain an optional menu header(see Figure 1 above).

Menu header The area at the top of the menu that the C2Asource may populate with markup. It is generallyused to provide descriptive information about thesource object.

Live Object Framework C2A is implemented as a service in thisframework.

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

The tooling support for Client-Side Click-to-Action in Rational Application Developerprovides capabilities like intuitive wizards, palette drawer and menu bar items,automatic code generation, and potential data type matches. These functions helpyou create Client-Side Click-to-Action-enabled portlet applications with as muchease 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 viewaccordingly (target portlet).

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

Sample applications

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

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

• The second example is a portlet application used by a shipping companyto maintain the details of its orders and customers. Five portlets in thisapplication 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 anorder

• The Customer Details portlet, which shows the details of a particularcustomer

• The Tracking Details portlet, which shows the tracking details of anorder

In the shipping application, you will see how the Order Details and Tracking Detailsportlets can exchange data using Client-Side Click-to-Action. In response to thataction, 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 aresimplified to a great extent.

Sample application 1

In this simple application, you can send your name from the source portlet to thetarget 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 usingClient-Side Click-to-Action.

4. Insert a Client-Side Click-to-Action menu header onto the source pop-upmenu.

5. Enable the C2ATarget portlet to receive data from the C2ASource portletusing 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 NewPortlet Project wizard launches. Enter the following information, as shownin Figure 3.

a. Enter C2aSource as the Project name of the portlet.

b. Select WebSphere Portal 6.1 as the Target Runtime.

c. Select JSR 168 Portlet (in this example), JSR 286 Portlet, or IBMPortlet as the Portlet API.

d. Select Faces portlet (in this example) or Basic portlet as thePortlet 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 createdpreviously.

1. Right-click the C2ASource project in the Project Explorer.

2. Select New > Portlet. The New Portlet wizard launches. Enter thefollowing information, as shown in Figure 4.

a. Enter C2ATarget as the Name of the portlet.

b. Keep the Portlet type for the C2ATarget portlet the same as forthe 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 usingClient-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 fromthe palette onto the C2ASourcePortletView.jsp, as shown in Figure 5.

Figure 5. Drag palette item to design tab





4. Alternatively, select Insert > Portlet > Client-Side Click-to-ActionOutput 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 thedata

• Value: Actual data that is passed to the target operation

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





5. Specify http://C2Asource#Myname in the Data Type URI field.

6. Specify your name (or the value that you want to send to the targetportlet) in the Value field, and then click Finish.

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

7. Save the C2ASourceView.jsp.

8. To see the inserted code, click the Source tab.

The Client-Side Click-to-Action source object code shown in Listing 1 is autogenerated 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 beensemantically tagged to provide their class attributes with special meanings, which isevaluated 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 portletapplication is published on WebSphere Portal, hovering over the Anchor Data showsyou the source portlet menu. The source menu has one entry for each target portletthat can consume the value sent by the source portlet.

You can change this value from Anchor Data to the value that you want as theC2A 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.


3. Drag the Client Side click-to-action Menu Header menu item from thepalette onto the C2ASourcePortletView.jsp, as shown in Figure 9.

Figure 9. Drag menu item to Design tab





4. Alternatively you can select Insert > Portlet > Client-SideClick-to-Action Menu Header Property from the menu bar.

The Insert Menu Header wizard is displayed.

5. Specify Display Myname as the header contents, as shown in Figure10, and click Finish.

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





6. Save the C2ASourceView.jsp.


The Client-Side Click-to-Action menu header code shown in Listing 2 is autogenerated 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 usingClient-Side Click-to-Action.

Design the C2ATarget portlet

(You can ignore the following steps if you have selected Basic portlet as the Portlettype in step 1 of the section "Create a C2A Source Portlet project", because basicportlet 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 Namefield, and click OK.

7. Again, drag the Submit button object from the palette onto the previousform 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 theName 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.


2. Drag the Client-Side Click-to-Action Input Property menu item from thepalette 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





3. Alternatively, you can select Insert > Portlet > Client-SideClick-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 thedata. This should exactly match the Data Type URI field value for theC2A source portlet.

• Action Value: The action to be executed when the value sent by the C2Asource portlet reaches the target portlet. This can be a server-side actionor 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 portletpop-up menu, as shown in Figure 1 previously.

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

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

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

5. For this scenario Specify javascript:void(0); in the Action Valuefield to avoid a round trip to the server. In the next section you will seehow a JavaScript action can be invoked on the submit event of the form.

6. Specify Send My name to Target in the Action Label field, as shownin Figure 14, and then click Finish.

Figure 14. Specify action details





7. Save the C2ATargetView.jsp.


The Client-Side Click-to-Action target object code shown in Listing 4 is autogenerated 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 thevalue 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





9. Switch to the Source view of C2ATargetView.jsp.

10. Add the following code and JavaScript action in the C2ATargetView.jspabove 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.

11. Next, in the form tag, add the onsubmit="displayName();returnfalse;" attribute.

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





Listing 6. Value from source to target

<form class="c2a:target" onsubmit="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>

12. 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 showswhat the sample looks like when it is published.

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

Larger view of Figure 16.

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 particularmonth. 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. Itserves as a C2A target, receiving Order_ID from the Orders portlet. Thisarticle demonstrates how to enable this portlet to send Tracking _ID to



fig16_lg.html



Tracking Details portlet using the C2A source option.

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

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

• Tracking Details: This portlet displays the details for a particularshipment. This article demonstrates how to enable it to receiveTracking_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 onWebSphere 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 inOrdersPortlet, and then click Submit .The orders for that particular monthare displayed.

2. When the order details display, hover over any Order_ID. A menu isdisplayed.

3. Click the Show Order Details menu item. the details of the particularorder are displayed in the Order Details portlet.

4. Click the Show Account Details menu item. The account details of theparticular 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 theparticular customer are displayed in the Customer Details portlet.

Figure 17 shows what the sample looks like when it is published (before enablingOrder 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 communicationbetween the Order Details portlet and the Tracking Details portlet.

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

Figure 18. Shipping Details sample objective





To achieve the above result, execute the following steps:

7. Enable OrderDetail as a C2A source

8. Enable TrackingDetail as a C2A target


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 ontothe Tracking_ID column in the Design view of OrderDetailsView.jsp.

Figure 19. Drag property to the Tracking_ID column





3. 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 inFigure 20, and then click Finish.

Figure 20. Enable OrderDetail as a C2A source





4. Open OrderDetailsView.jsp in the Design view, .

5. Change the Anchor value from Anchor Data to the value you want asthe C2A Hover UI string. Preferably, keep the C2A Hover UI string thesame as the C2A value being passed. For example, in the currentscenario, the Tracking_ID being passed by the Order Details portletshould be displayed to the user.

Figure 21. C2aAnchor2





6. Open OrderDetailsView.jsp in the Source view. The code shown inListing 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>

7. Similar to the Display Myname application, you can also insert a menuheader to the source. Specify Send Tracking Id to Tracking





Details as the header contents.

8. Save OrderDetailsView.jsp. The Client-Side Click-to-Action source objectcode 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 thepalette onto the Submit button in the Design view ofTrackingDetailEntry.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.

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

Figure 23. Enable TrackingDetail as C2A target 1



http://clientsidec2a/#TrackingID



4. For this scenario, leave the default value in the Action Value field.

5. Specify Show Tracking Details in the Action Label field, as shown inFigure 24, and click Finish.

Figure 24. Enable TrackingDetail as C2A target 2





6. Open TrackingDetailEntry.jsp in the Source view to see the insertedcode, 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 idto 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 andsave TrackingDetailEntry.jsp.

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





7. Repeat these steps for TrackingView.jsp.



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

Figure 25. Shipping Details sample published on WebSphere Portal


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

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

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

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

The Person Menu extension allows you to extend the Person Menu, by enabling youto 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 enablesthe Person Menu for hCards in the page is plugged in to the Live Object Framework



fig25_lg.html



(LOF).

Advantages over the original Person JSP tag

• The new semantic tagging-based Person Menu provides the samefunctionality as the traditional JSP Person tag, but with a better userexperience:

• It shows hover and pop-up on each hCard.

• It provides access to actionable menu items like Show Profile, SendE-mail, and so on.

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

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

Sample application

Now you will create a simple application to demonstrate how Rational ApplicationDeveloper simplifies the task of inserting the Person Menu, and then extending itusing 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 theportlet .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. TheNew 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 PortletAPI.

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.


3. Drag the Person Menu object from the Palette view onto thePersonMenuExampleView.jsp, as shown in Figure 26.

Figure 26. Person Menu palette item





4. Alternatively you can select Insert > Portlet > Person Menu from themenu bar. The intuitive Insert Person Menu wizard is displayed.

5. Specify the following hCard attributes, as shown in Figure 27.

• Name

• e-mail

• Address (optional)

• Phone number (optional)

Figure 27. Specify person menu attributes





6. Click Finish and save PersonMenuExampleView.jsp.





7. Open PersonMenuExampleView.jsp in the Source view. The code shownin 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">[email protected]</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 thePersonMenuExampleView.jsp, as shown in Figure 28.

Figure 28. Person Menu Extension palette item





4. Alternatively you can select Insert > Portlet > Person Menu Extensionfrom the menu bar. The intuitive "Insert Person Menu Extension" wizard isdisplayed (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 foryou. It must be unique for a particular Person Menu Extension.

• JavaScript: The JavaScript name that has the action that will be invokedwhen the menu item is selected. This should be available at the followingdirectory:





[WebSphere Portal ServerHome]\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 MenuExtension.

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

5. Click Finish and save PersonMenuExampleView.jsp.

6. Open PersonMenuExampleView.jsp in the Source view. The code shownin 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 specifiedpreviously) 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.



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

Figure 30. Person Menu sample published on WebSphere Portal

Using Ajax proxy in portlet applications

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





Ajax applications

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

Same-origin policy

Ajax-based Web applications sometimes want to do Ajax requests to serversdifferent 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 asGoogle 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 yourbrowser as the basis for attacking other servers, requests are only allowed to theserver that served the current document, as shown in Figure 31. This same-originpolicy prevents client-side scripts (in particular, JavaScript) from loading contentfrom 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 solutionthat is based on a server-side HTTP proxy, the Ajax proxy layer. The Ajax proxylayer intercepts the calls, and retrieves the content from the remote site, as shown inFigure 32. It also allows for these resources to be cached in a central server. Thissecurity model allows administrators to restrict access to trusted origins in a veryflexible way.

Figure 32. Ajax proxy layer

Sample application

The AjaxProxyPortletSample application used in this article consists of a portlet thataccesses foreign domains using XMLHttpRequests. In order to overcome thesame-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, asshown in Figure 33.

2. Next, click the Get the articles button. The portlet gets the feeds ofdeveloperWorks articles (Rational or Lotus) from the IBM Website. It thendisplays the links to the topics.

Figure 33. Sample Ajax proxy





The complete sample is available for download at the end of this article. This articlecovers the Ajax proxy tooling support in Rational Application Developer. Theimplementation 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. TheNew 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 PortletAPI.

5. Select Faces, Basic, Empty, or Struts as the Portlet type.

Figure 34. New portlet project with Ajax proxy enabled





6. Click Show Advanced Settings. The Project Facet page is displayed.

7. Expand Web 2.0 facet and select the Ajax proxy check box, as shown in





Figure 35. Click OK.

Figure 35. Project Facets page









8. Press Next, and then press Finish.

9. Proxy servlet is registered in the Web deployment descriptor. Expand theWeb Content > WEB-INF folders, and double-click Web.xml.

10. The Web deployment Descriptor is displayed. Click the Servlet tab, asshown in Figure 36.

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


11. The Ajax Proxy servlet with the class namecom.ibm.wps.proxy.servlet.ProxyServlet gets registered in the Web.xml.

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

12. Click the Source tab in Web Deployment Descriptor view to see the codeadded in Web.xml, as shown in Listing 13.



fig36_lg.html



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>

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

14. Double click proxy-config.xml, which opens the Ajax Proxy ConfigurationEditor window shown in Figure 38.





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

15. Using the proxy-config.xml, you can specify the Ajax proxy configurationparameters. First, you can add an item to the proxy rules, as shown inFigure 39.

Figure 39. Add proxy rules





Context path mappings

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

Figure 40. Specify context path mapping






Access policy

The policy element is used to define an access policy for a specific URL pattern, asshown 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



fig40_lg.html




Figure 42. Specify policy elements



fig41_lg.html



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, suchas 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 thehttp://www.ibm.com/developerworks/myfeed.rss site through the proxy servlet, thenyou 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 URLhttp://www.ibm.com/developerworks/myfeed.rss(that is, the http:// part has beenreplaced with http/)

You may achieve this encoding in your JavaScript file by constructing the function asshown 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 thehttp://www.ibm.com/developerworks/myfeed.rss site through a proxy servlet, thenyou 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 thefollowing operations:

• Encoding the URL



http://www.ibm.com/developerworks/myfeed.rss

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


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


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



• 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.jspfile

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


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

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

3. Next, click Get the articles. The sample shows the links to the latesttopics in the selected category in response.

When you click the Get the articles button, the XMLHttpRequest object is createdusing a URL that corresponds to the selected topic (Rational or Lotus). This requestis 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 clientbrowser. The JavaScript then parses and displays this response in a user friendlymanner, 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. TheProject 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. TheProject 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

Using client-side programming model support in WebSpherePortal

Previous versions of WebSphere Portal required that a request be sent to the serverfor each portlet operation. For example, if you changed the portlet window state tominimize or maximize, a submit request had to be sent to the server and theresponse sent back to your browser. This would cause a page refresh, and onlysubsequently was the portlet shown in the maximized or minimized state. Typicallythese 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 efficientlyon the client side.

To achieve this, Rational Application Developer provides the necessary toolingsupport 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 preferencesin basic portlet projects.


Client-side programming model support for a new portlet project

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

1. Select File > New > Project > Portlet Project and press Next. The NewPortlet 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, asshown in Figure 45.

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





7. The Client Side Capabilities check box under Web2.0 Portlet Featuregroup is selected by default. Selecting this enables the client-sideprogramming model support for a new portlet project. Click Finish.

The ClientSideSample portlet project is created, and ClientSideSampleView.jspopens 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

<%@ tagliburi=http://www.ibm.com/xmlns/prod/websphere/portal/v6.1/portlet-client-modelprefix="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

<%@tagliburi="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 therequired module on the client.

• The ibm.portal.portlet.* module enables you to usePortletWindow, PortletPreference, PortletState and XMLPortletRequeston the client.

• The ibm.portal.xml.* module allows the use of XSLT and XPath onthe client.

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

Now you will see how to use client-side programming model support to retrieveportlet preferences on the client side, as shown in Figure 46. This action used tohappen on the server side. Continue with the ClientSideSample project createdpreviously.





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

5. Open the ClientSideSampleView.jsp file.

6. Open the Page Data view.

7. Expand the Page Data view and select the PortletPreferences node.

8. Right-click the Preferences node and select New > PortletPreferences,as shown in Figure 47.





Figure 47. Add a preference in the Page Data view

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

Figure 48. Add an attribute to portletPreferences

10. Open ClientSideSampleView.jsp.

11. Drag MyPreference from under the PortletPreferences node in the PageData viewÂ¸ as shown in Figure 49, and drop it onClientSideSampleView.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





12. Press Finish.

13. To see the code that is inserted click the Source tab, as shown in Listing20.

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 generatedojo_101.addOnLoad(callOnLoad); in place of the correctdojo.addOnLoad(callOnLoad);

If the incorrect code is generated in the JSP, you have to manually correct it so thatwhen 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>

14. Similarly, you can add another preference (MyPreference2) in the PortletDeployment Descriptor (specifying a value for it) and also add the samepreference in the Page Data view (in the same way as you did previously





for MyPreference.

15. Open the Design view. Drag this preference into the JSP as you didpreviously.

16. Now open the Source view.

You can see that the preferenceJSONObject contents are now updated, as shown inListing 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"}]

};


1. Right-click the ClientSideSample Portlet project and select Run onServer.

2. You can observe that the preference values that you specified in thePortlet Deployment Descriptor Preference Store are displayed correctly,as shown in Figure 51.

Figure 51. ClientSideSample published on WebSphere Portal





What you have learned

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





Downloads

Description Name Size Downloadmethod

Ajax proxy portlet sample AjaxProxyPortletSample.zip 5024KB HTTP

Shipping details sample ShippingDetailsSample.zip 57KB HTTP

Information about download methods



http://download.boulder.ibm.com/ibmdl/pub/software/dw/rational/zip/AjaxProxyPortletSample.zip

http://download.boulder.ibm.com/ibmdl/pub/software/dw/rational/zip/ShippingDetailsSample.zip

http://www.ibm.com/developerworks/library/whichmethod.html



Resources

Learn

• Learn more in the IBM WebSphere Portal Version 6.1 Information Center whereyou can find information about planning, installing, configuring, administering,developing, and troubleshooting.

• Explore the IBM Rational Application Developer Version 7.5 Information Centerto learn more..

• Visit the Rational software area on developerWorks for technical resources andbest practices for Rational Software Delivery Platform products.

• Explore the Rational Application Developer Version 7.5 Information Center tofind in-depth information.

• Subscribe to the IBM developerWorks newsletter, a weekly update on the bestof developerWorks tutorials, articles, downloads, community activities, webcastsand events.

• Subscribe to the developerWorks Rational zone newsletter. Keep up withdeveloperWorks Rational content. Every other week, you'll receive updates onthe latest technical resources and best practices for the Rational SoftwareDelivery Platform.

• Subscribe to the Rational Edge newsletter for articles on the concepts behindeffective software development.

• Browse the technology bookstore for books on these and other technical topics.

Get products and technologies

• Download trial versions of IBM Rational software.

Discuss

• Participate in the discussion forum for this content.

• Join the developerWorks Community in forums, blogs, podcasts, wikis, andmore.

About the author

Charu Malhotra



http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1m0/index.jsp

http://publib.boulder.ibm.com/infocenter/radhelp/v7r5/index.jsp

http://www.ibm.com/developerworks/rational

http://publib.boulder.ibm.com/infocenter/radhelp/v7r5/index.jsp?topic=/com.ibm.rad.legal.doc/helpindex_rad.html

https://www.ibm.com/developerworks/newsletter/

https://www.ibm.com/developerworks/newsletter/

http://www.ibm.com/developerworks/rational/rationaledge/

http://www.ibm.com/developerworks/apps/SendTo?bookstore=safari

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX01&S_CMP=ART

http://www.ibm.com/developerworks/forums/dw_forum.jsp?forum=375&cat=5

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX01&S_CMP=ART



Charu Malhotra is a software engineer who develops the portal andportlet tooling components of Rational Application Developer. Shefocuses on Web 2.0 tooling support and bridge support for JSF portlets.Charu works in the IBM labs in Delhi, India.

Trademarks

IBM and the IBM logo are trademarks of International Business MachinesCorporation in the United States, other countries or both.Java and all Java-based trademarks and logos are trademarks of Sun Microsystems,Inc. in the United States, other countries, or both.





Documents

IBM Rational Application Developer Version 7.5 Portal Toolkit