Using inter portlet communication

This feature applies to the Mainsoft for Java EE Portal Edition only.

Inter portlet communication, or IPC, refers to the ability of portlets on a portal page (or pages) to communicate with each other.

You may use Mainsoft to develop portlets that can interact by sending and receiving information from one to another, as well as with other JSR 168 portlets.

Using standard Web Service Definition Language (WSDL) files and Mainsoft.Web.UI.PortletPage methods, you can leverage the WebSphere Portal inter portlet communication capacities to create composite applications and workflows.

The development of IPC involves the following steps:

1. The source and the target portlets publish a WSDL file containing the definitions of the data passed between them.

2. The source portlet declares an IPC action, and sets the IPC data.

3. The target portlet retrieves the IPC data.

To better understand this topic, we recommend reading Portlet request processing before you continue.

Step 1: Publish WSDL files

The interaction between portlets is facilitated by a WebSphere Portal runtime entity called the property broker. Portlets subscribe to the property broker by publishing typed data items that they can share, either as a source portlet or as a target portlet. The subscription is done using standard WSDL files.

The source portlet declares a <portlet:action> element in a WSDL file with an <output> element, which defines the outbound IPC data:

• The name and the actionNameParameter attributes of the action element defined in the WSDL file are used later by the source and target portlets, as explained in the following steps. These attributes are also used by the property broker to identify a request as an IPC action.

• The boundTo parameter tells the property broker and the portlets where to store or retrieve the IPC data. It is usually set to request-attribute, to indicate that the property is passed as an attribute of the PortletRequest.

Here is a snippet of a source WSDL file, which will be used in the following step's examples

<binding
    name="SetItemParametersBinding"
      type="tns:ItemList_Service">
  <portlet:binding/>
  <operation name="SetItemParameters">
    <portlet:action name="ShowItemDetailsAction" type="standard" caption="ShowItemDetails.action" description="Show Item Details"
    actionNameParameter="ACTION_NAME"/>
    <output>
      <portlet:param name="PrmItemDetails" partname="ItemDetails" boundTo="request-attribute" caption="ItemDetails"/>
    </output>
  </operation>
</binding>

The target portlet declares a <portlet:action> element in another WSDL file, with an <input> element, which defines the inbound IPC data.

Here is a snippet of a target WSDL file:

<binding
    name="GetItemParametersBinding"
      type="tns:ItemDetails_Service">
  <portlet:binding/>
  <operation name="GetItemParameters">
    <portlet:action name="ShowItemDetailsAction" type="standard" caption="ShowItemDetails.action" description="Show Item Details"
    actionNameParameter="ACTION_NAME"/>
    <input>
      <portlet:param name="PrmItemDetails" partname="ItemDetails" caption="ItemDetails"/>
    </input>
  </operation>
</binding>

The portlets associate the WSDL files by specifying a com.ibm.portal.propertybroker.wsdllocation portlet preference, and setting its value to the WSDL file location:

<portlet-preferences>
    <preference>
      <name>com.ibm.portal.propertybroker.wsdllocation</name>
      <value>/P2PSearchResult.wsdl</value>
    </preference>
</portlet-preferences>

Step 2: Write source portlet code

We should distinguish between simple IPC actions that do not involve data binding, and IPC actions in which the IPC data passed between the source and target portlets comes from data binding evaluation.

Simple IPC actions

1. Declare an IPC action.

   The source portlet should declare an IPC action in the render phase. There are a few ways to declare the IPC action:

   • Using hidden fields.

     A hidden field in the page, with the same name and value as defined in the WSDL file, causes each POST request to be an IPC action.

     Here is an example for defining an IPC hidden field:

     <input type="hidden" name="ACTION_NAME" value="ShowItemDetailsAction" />

     ShowItemDetailsAction is the portlet action name defined in the WSDL file, ACTION_NAME is the actionNameParameter.

   • Using the ActionURL expression.

     Mainsoft added a new ASP.NET expression for creating portal action URLs. For more information about this expression, read Portal ASP.NET expressions.

     Use the ActionURL expression to indicate that a specific request will trigger an IPC action and assign it to a control.

     Here is an example for defining an ActionURL expression that triggers an IPC action when clicking an ASP.NET button control:

     <asp:Button ID="Button" runat="server" OnClick="Button_Click" Text="IPC submit" Width="100px" PostBackUrl="<%$ ActionURL: default.aspx,ACTION_NAME=ShowItemDetailsAction%>" />

2. Set the IPC data.

   The source portlet should set the IPC data in the processAction phase. In the simple IPC scenarios, the code for setting the IPC data should be placed in the event handler of the control that triggers the IPC action (for example, in Button_Click). The IPC data is usually set as an attribute of PortletRequest. You may use the boundTo attribute in the WSDL file to define where the data will be bound. For more information, read Assigning property values.

   Here is a code sample:

   protected void Button1_Click(object sender, EventArgs e)
   {
       string searchText = this.TextBox1.Text;
       PortletRequest.setAttribute("PrmItemDetails", searchText);
   }

Data-binding IPC actions

1. Declare an IPC action.

   Common data-binding scenarios involve rendering of different items inside data bound controls. You may want the clicking of an item in the data bound control to trigger an IPC action. We recommend implementing such a scenario by using the LinkButton control or by using regular links.

   • Using LinkButton controls.

     1. Add a LinkButton control to the template code of the data bound control.

     2. Set the PostBackUrl property of the LinkButton control to the ActionURL expression.

     3. Set the data binding information in the CommandArgument property of the LinkButton control.

     The following code shows how to declare an IPC action using a LinkButton control; it sends customer ID information and triggers a ShowItemDetailsAction IPC action:

     <ItemTemplate>
         <asp:LinkButton ID="LinkButton1" runat="server" CommandArgument='<%# Eval("CustomerId") %>'
           CommandName="CUSTOMERID" OnCommand="LinkButton_Command" PostBackUrl="<%$ ActionURL: Default.aspx,ACTION_NAME=ShowItemDetailsAction %>">
           <%# Eval("CustomerName") %>
         </asp:LinkButton>
     </ItemTemplate

   • Using links.

     You can generate links that are bound to a specific data and that trigger IPC actions. To do this, use the Mainsoft.Web.UI.PortletPage.PrepareActionURL method.

     For example:

     <a runat="server" href='<%# PrepareActionURL("Default.aspx?CustomerId =" + Eval("CustomerId") + ",ACTION_NAME= ShowItemDetailsAction")%>' >Show details</a>

2. Set the IPC data.

   The source portlet should set the IPC data in the processAction phase.

   1. When declaring the IPC action using a LinkButton control, the code should be placed in the LinkButton_Command method. Here is a code sample that shows how it is done:

      protected void LinkButton_Command(object sender, CommandEventArgs e)
      {
           string commandArg = ((LinkButton)sender).CommandArgument;
           PortletRequest.setAttribute("PrmItemDetails", commandArg));
      }

   2. When declaring the IPC action using a link, place the code in one of the Page life cycle methods that run in the processAction phase, usually in Page_Load. Here is a code sample that shows how it is done:

      protected void Page_Load(object sender, EventArgs e)
      {
           if (IsInProcessAction)
             PortletRequest.setAttribute("PrmItemDetails", Request.Params["CustomerId"]));
      }

Step 3: Write target portlet code

The target portlet can identify a request as an IPC request, if the following conditions are met:

• The portlet is in the processAction phase.

• The portlet request contains a request parameter with a key set to the actionNameParameter attribute, and its value set to the name attribute, both defined in the target portlet's WSDL file.

The target portlet retrieves the IPC data, usually from the request attributes. The parameter is manipulated, if necessary, and persisted, to be displayed in the render phase.

You may use one of the persistence methods explained in Portlet request processing.

Here is a code sample that demonstrates this; place the code in one of the Page handling events that run in the processAction phase, usually in Page_Load:

protected void Page_Load(object sender, EventArgs e)
{
    if (IsInProcessAction)// this is a processAction request
    {
        // Verify this is an IPC action of the expected type 
        if (Request.Params["ACTION_NAME"]== "ShowItemDetailsAction")
        {
           // Persist the IPC parameter
           SetRenderParameter("ItemDetails", Request.Params["PrmItemDetails"]);
        }
    }
}

Related Sections

Portal how-to's

Learn how to address the most common portal application development tasks.