Implementing inter-portlet communication

 

 

In this topic ...

 

How do I...

Use Cooperative Portlets

Use Click-to-Action Portlets

There are two ways we can set up inter-portlet communications:

  • Using Cooperative Portlets   - Available in portlets built to the IBM Standard (JSR 168) Portlet API

  • Using Click-to-Action Portlets - Available in portlets built using the deprecated IBM (legacy) Portlet API

Note: If you use IBM WebSphere Portal 6 or later, Cooperative Portlets are recommended.

 

How do I Use Cooperative Portlets?

Cooperative portlets are available in WebSphere Portal version 5.1 and later. cooperative portlets can interact with each other to share information. One or more target portlets on a portal page can automatically react to changes from a source portlet. when the source portlet triggers an action or an event.

Portlets that are targets of this event can react so that users are not required to make repetitive changes or actions in other portlets on the page. This provides a coordinated and consistent behavior between the portlets on the page and enhances user experience.

Cooperation between source and target portlets is facilitated by a WebSphere Portal runtime entity called the Property Broker. Portlets on a page can cooperate in this way even if they were developed independently, without awareness of other cooperative portlets.

The following tasks represent the most common Cooperative Portlet features you will use when building a portlet.

 

Create a Cooperative Portlet Target Model

When developing a cooperative portlet application, develop a target portlet first. By doing so, we can define the type of data or events you want to receive. This approach will simplify your design decisions when developing source portlets. To develop a target portlet, add the following to your model:

  1. Add a Cooperative Portlet Target Builder to your model and use this Builder to define the event.

You must specify the Event Name, Input Name, Input Type, Input Type Name, Namespace and Caption inputs.

It is also important to remember that the Input information in the Cooperative Portlet Target Builder must match the Output information specified in the Cooperative Portlet Source Builder of any source portlets that wish to interact.

  1. Next add an Event Handler Builder to the model. The Event Handler will perform an action when an event occurs.

In this case, you want to make sure that the Event Name input matches the Event Name input from your Cooperative Portlet Target Builder to ensure that the event will trigger the action.

Note: Prior to specifying the Event Handler Builder, you should develop the method or page that the Event Handler will execute. This will allow you to select the event from the Action drop-down list in the Event Handler Builder Call Editor, rather than typing it in manually.

  1. Finally, add a Portlet Adapter Builder to the model.

This Builder call provides your model with a portlet title so that the portlet can be added to a page in WebSphere Portal. Since cooperative portlets were designed to function in a WebSphere Portal environment, it is important to remember this simple, but important step.

 

Create a Cooperative Portlet Source Model

Once you have developed a cooperative portlet target model we can develop a source portlet. To develop a source portlet, add the following to the portlet model:

  1. Add a Cooperative Portlet Source Builder to the model and use this Builder to add either a C2A Single Action menu, or Property Broker link to a specified location on a page in your model.

    Note that The Property Broker Link functionality is available only for JSR-168 portlets. C2A menu functionality is available only for non JSR-168 portlets.

Make sure to specify the page location in your model on which the menu or link will appear, and specify the value to be passed to the target portlet. It is also important to remember that the Output information in the Cooperative Portlet Source Builder must match the Input information specified in the Cooperative Portlet Target Builder of your target model.

  1. Add a Portlet Adapter Builder to the model.

This Builder call provides your model with a portlet title so that the portlet can be added to a page in WebSphere Portal. Since cooperative portlets were designed to function in a WebSphere Portal environment, it is important to remember this simple, but important step.

 

Send Cooperative Portlet Events to Target Portlets

Since cooperative portlets use the WebSphere Portal Property Broker technology, sending events to multiple target portlets is as easy as sending events to a single portlet. To send events to multiple portlets, we need not change your source portlet. To send an event to multiple portlets:

  1. Add additional cooperative portlet targets, with the same Input Type information, to a portal page.

When broadcasting to multiple portlets, remember the outputs type information in the Cooperative Portlet Source Builder must match the input type information specified in the Cooperative Portlet Target Builder.

 

Deploy a Cooperative Portlet WAR

Remember to rebuild (and redeploy) the portlet WAR after adding the Cooperative Portlet Builders to your model. We can not add Cooperative Portlet Builders to your portlet models, save them, and then run portlets that exhibit the new functionality. This is because cooperative portlets describe target and source information using a WSDL definition file. The WSDL files must be added to the portlet WAR file prior to deployment. Rebuilding the portlet WAR will add the WSDL definitions and associated resource text files to it.

Note: If you have previously built and deployed the portlet WAR without cooperative portlets functionality, the portlet WAR must be removed and re-deployed for cooperative portlets features to function properly. You must also re-deploy the war if you make any changes that cause the generate WSDL file to change, or if you make a change to any related resource strings (i.e. caption text).

Note: When using cooperative portlets with the Property Broker actions (JSR-168), use the WebSphere Portal Portlet Wiring Tool to connect the source and target portlets after deploying the WAR and placing your cooperative portlets on a portal page.

To re-deploy a portlet WAR to which cooperative portlets features have been added:

  1. Develop or modify the model representing the portlet.

  2. Modify the project and de-select the "Automatically Deploy Portlet WAR to WebSphere Portal" option.

  3. Log in to the Portal and manually uninstall the Portlet WAR using the portal server's administration tool.

  4. Modify the project and check the "Automatically Deploy Portlet WAR to WebSphere Portal" option. This will re-deploy the Portlet War automatically.

Subsequent changes to the cooperative portlets models can then be deployed to the portal server using the Designers automatic deployment features.

If auto-deployment is NOT enabled in the project, portlet deployment steps are:

  1. Develop or modify the model representing the portlet.

  2. Uninstall the Portlet WAR using the portal server's administration tool.

  3. Use the Designer's Rebuild WAR | Portlet WAR right-click Project Menu choice to rebuild the WAR.

  4. Manually install the Portlet WAR using the portal server's administration tool.

 

How do I Use Click-to-Action Portlets?

Click-to-Action (C2A) is a feature of WebSphere Portal that allows data to be transferred and shared among multiple WebSphere portlets via UI elements such as drop-down menus. Development of portlets containing C2A functionality using the WebSphere Portlet Factory Designer is not much different than developing any other kind of portlet using Designer

The following tasks represent the most common C2A features you will use when building a portlet:

 

Create a Click to Action receiver portlet

When developing a C2A application, develop a receiver portlet first. By doing so, we can define the type of data or events you want to receive. This approach will simplify your design decisions when developing sender portlets. To develop a receiver portlet, add the following to your model:

  1. Add a C2A Event Declaration Builder to your model and use this Builder to define a C2A event.

You must define the Event Name, Input Name, Input Type Name, Namespace and Caption inputs. The same Input Type Name must be used by any sender portlets that wish to interact with this receiver portlet. In addition, make sure that the Input Type you choose matches that of the data the portlet will receive.

  1. Next add an Event Handler Builder to the model. The Event Handler will perform an action when an event occurs.

In this case, you want to make sure that the Event Name input matches the Event Name input from your C2A Event Declaration Builder to ensure that the C2A event will trigger the action.

Note: Prior to specifying the Event Handler Builder, you should develop the method or page that the Event Handler will execute. This will allow you to select the event from the Action drop-down list in the Event Handler Builder Call Editor, rather than typing it in manually.

  1. Finally, add a Portlet Adapter Builder to the model.

This Builder call provides your model with a portlet title so that the portlet can be added to a page in WebSphere Portal. Since C2A was designed to function in a WebSphere Portal environment, it is important to remember this simple, but important step.

 

Create a Click to Action sender portlet

Once you have developed a receiver portlet we can develop a sender portlet. To develop a sender portlet, add the following to the sender portlet model:

  1. Add a C2A Menu Builder to the model and use this Builder to add a C2A menu to a page.

Make sure to specify the page in your project on which the menu will appear and the tag within that page on which the menu will be associated with. It is also important to remember that the Input Type Name must match the Input Type Name of the C2A Event Declaration from your receiver portlet.

  1. Add a Portlet Adapter Builder to the model.

This Builder call provides your model with a portlet title so that the portlet can be added to a page in WebSphere Portal. Since C2A was designed to function in a WebSphere Portal environment, it is important to remember this simple, but important step.

 

Send a Click to Action event to multiple portlets

Since C2A technology follows a broadcaster/listener(s) paradigm, sending C2A events to multiple portlets is as easy as sending C2A events to a single portlet. To send C2A events to multiple portlets, we need not change your sender portlet at all. When broadcasting to multiple portlets, remember the following about the C2A Event Declaration Builder in each of your receiver portlets:

  • Input Type - The type entered in this input to the C2A Event Declaration Builder must match the type of the input that will be passed to the Event Handler from the C2A source. For example, if a value of type xsd:string will be passed from the C2A source, that must be reflected in this input.

  • Input Type Name - The value entered in this input must match the value entered in the Input Type Name input from the C2A Menu Builder in your sender portlet model.

 

Deploy a Click to Action Portlet

Remember to rebuild and redeploy the portlet WAR after adding the C2A Builders to your model. We can not just add C2A Builders to your portlet models, save them, then run portlets that exhibit the new functionality. This is because C2A describes target portlet actions using WSDL definitions, and these WSDL files must be added to the portlet WAR file. Rebuilding the portlet WAR will add these definitions to it.

Note: It is important to remember that if you have previously built and deployed the portlet WAR without C2A functionality, the portlet WAR must be removed and re-deployed for C2A features to function properly.

To re-deploy a portlet WAR to which C2A features have been added:

  1. Develop or modify the model representing the portlet.

  2. Modify the project and de-select the "Automatically Deploy Portlet WAR to WebSphere Portal (version 5.x only)" option.

  3. Log in to the Portal and manually uninstall the Portlet WAR using the portal server's administration tool.

  4. Modify the project and check the "Automatically Deploy Portlet WAR to WebSphere Portal (version 5.x only)" option. This will re-deploy the Portlet War automatically.

Subsequent changes to the C2A models can then be deployed to the portal server using the Designers automatic deployment features (WebSphere 5 only).

If auto-deployment is NOT enabled in the project, portlet deployment steps are:

  1. Develop or modify the model representing the portlet.

  2. Uninstall the Portlet WAR using the portal server's administration tool.

  3. Use the Designer's Rebuild WAR | Portlet WAR right-click Project Menu choice to rebuild the WAR.

  4. Manually install the Portlet WAR using the portal server's administration tool.