Cooperative Portlet Source Builder

Cooperative Portlet Source Builder

In this topic ...

How do I...
Specifying Inputs

The Cooperative Portlet Source Builder allows you to creates portlets that can communicate with one another. In this situation, an action or event occurring in a source portlet can result in messages being sent to other portlets. These messages might update data or cause other display changes.
One or more cooperative portlets on a portal page can automatically react to changes from a source portlet triggered by an action or event in the source portlet. Portlets that are targets of the event can react so that users are not required to make repetitive changes or actions in other portlets on the page.
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 without the expectation of cooperation.
This Builder supports two kinds of inter-portlet communication formats:

* Standard (JSR 168) Implementations - For use in portlets built in accordance with the new (as of WebSphere Portal 5.1) JSR168 Portlet API
* Click-to-Acton (C2A) Implementations - For use in legacy portlets built in accordance with the deprecated IBM portlet API.

Note that Click-to-Action is a legacy WebSphere Portal feature that provides automatic front-end integration of portlets. Using C2A, users can transfer data from one portlet to another, and have the target portlet react to the data, thus causing information on the page to be refreshed. In the C2A mode, this Builder places the <C2A:encodeProperty> or <C2A:encodeProperties> tag on a model page. These tags are used to build a menu that can fire a C2A event to a target portlet on the same page that matches the specified type.

How do I...

Implement Inter-Portlet Communication?

Enable Click-to-Action?

Specifying Inputs

This Builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties input group, see Using the Builder Call Editor.
Review one of the Input tables below for the type of portlet communication you want to implement.

C2A Single Action Type Inputs

This type is used when running your portlet through the IBM Portal API.

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Type Select which type of tag to place on the model page:

C2A Single Action - To place a <C2A:encodeProperty> tag. Valid only in IBM Portlet API.
C2A Multiple Action - To place a <C2A:encodeProperties> tag
Property Broker Link - To place a link on a page that triggers a Property Broker Event
Property Broker Action - To place a link on a page that triggers a Property Broker Action

Page Location Use the Page Location input to specify the page or pages on which this builder call will place the Property Broker Link. See Locating control builders on pages for detailed documentation about the Page Location input and page location syntax.
Value Enter the value to be passed as an input to the target event action.
Example: ${Variables/orderLoopVar/order/orderID}
Namespace Enter the WSDL Namespace for the output type. This must match the namespace specified in the target model. This input is required.
Example: http://www.ibm.com/c2a/models
Broadcast This checkbox specifies if the source data can be broadcast to all target portlets on the page with matching data types.
Enable to allow the generated menu to display an additional item to broadcast to all matching targets.
Generate When Nested This checkbox specifies if this tag should generate markup when nested within a <c2a:encodeProperties> tag. Enable to generate markup.
Target Definition
Output Name Enter the name of the parameter that will be past to the target portlet. Example: OrderID
Output Name Type Enter the XML Schema Datatype name that was specified in the in the target model. This is a required input. Example: OrderIDType
Output Type This input allows you to select the XSD simple data type of the parameter that is passed to the target. The target portlet cannot receive objects from other portlets that are in a different WAR if the object's class file is not shared; the class file must be in a shared location. The default value is xsd:string.
Example: xsd:integer
Caption Enter the caption that will be used by the wiring tool to describe the name of the output parameter.
Example: Order ID

C2A Multiple Action Type Inputs

This type is used in portlets conforming to the IBM Portal API.

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Type Select which type of tag to place on the model page:

C2A Single Action - To place a <C2A:encodeProperty> tag. Valid only in IBM Portlet API.
C2A Multiple Action - To place a <C2A:encodeProperties> tag
Property Broker Link - To place a link on a page that triggers a Property Broker Event
Property Broker Action - To place a link on a page that triggers a Property Broker Action

Page Location Use the Page Location input to specify the page or pages on which this builder call will place the Property Broker Link.
See Locating Control Builders on Pages for detailed documentation about the Page Location input and page location syntax.
Value Specify a value to display just after the broadcast menu icon.
Example: ${Variables/displayName}
Caption Displays a caption on the generated menu.
The Builder will automatically generate a resource property file and create a key and value using the text entered. The property file name will be created using the model name and placed in the WEB-INF\classes\nls directory.
The resource file is generated by an Ant task in the build_deployment script. For example if your model was named: test/orders_source.model a file named WEB-INF\classes\nls\test\orders_source.properties will be created.
Example: Send All

Property Broker Link Type Inputs

This typle is used to add a link to a page. The link can be used to trigger a Property Broker event, which passes a property to any target portlets that has a wire connecting the source and target portlets.
Note that This is only available in a WebSphere JSR-168 portlet.
The link will be activated once a wire is created for a property from the source to the target portlet.

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Type Select which type of tag to place on the model page:

C2A Single Action - To place a <C2A:encodeProperty> tag. Valid only in IBM Portlet API.
C2A Multiple Action - To place a <C2A:encodeProperties> tag
Property Broker Link - To place a link on a page that triggers a Property Broker Event
Property Broker Action - To place a link on a page that triggers a Property Broker Action

Page Location Use the Page Location input to specify the page or pages on which this builder call will place the Property Broker Link.
See Locating Control Builders on Pages for detailed documentation about the Page Location input and page location syntax.
Namespace Enter the WSDL Namespace for the output type. This must match the namespace specified in the target model. This input is required.
Example: http://www.ibm.com/c2a/models
Output Definitions
Name Enter the name of the parameter to pass to the target portlet.
Example: OrderID
Output Name Type Enter the XML Schema Data type name that was specified in the in the target model. This is a required input and must match the targets output type name.
Example: OrderIDType
Output Type Select the XSD simple type of the value that is being passed to the target. We can also select the "xsd:anyType" when you are passing complex data, such as an XML structure. The default value is xsd:string.
Example: xsd:integer
Value Enter the value to be passed as an input to the target event action.
Note - If "xsd:anyType" is used as the Output Type the specified Value will not be place as a parameter on the link URL as it would be with simple types since request parameter must be strings. In this case the generated method action will contain the code to retrieve the value when the method is executed.
Example: ${Variables/orderLoopVar/order/orderID
Caption Enter the caption that will be used by the wiring tool to describe the name of the output parameter.
Example: Order ID

Property Broker Action Type Inputs

The Property Broker Action type is functionality identical to the Property Broker Link type, except a link is not placed on the page. The WSDL, and method action described in the Property Broker Link type will be generated.
Note that This is only available when running as a WebSphere JSR-168 portlet.
Selecting this type is useful if you want to provide your own UI for triggering the Property Broker event. For example you may want to trigger the event when an input form is being submitted.
Keep the following points in mind when using this type:

Add a parameter named ACTION_NAME to the UI action you plan to use to trigger the event (e.g. Link, Button). Set the value of the ACTION_NAME to the name of the generated action method (e.g. pbAction_OrderIDSource).

From your target action code (Method, Action List), either call the generated action method that places the property into the request, or set the request attribute(s) yourself

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Type Select which type of tag to place on the model page:

C2A Single Action - To place a <C2A:encodeProperty> tag. Valid only in IBM Portlet API.
C2A Multiple Action - To place a <C2A:encodeProperties> tag
Property Broker Link - To place a link on a page that triggers a Property Broker Event
Property Broker Action - To place a link on a page that triggers a Property Broker Action

Namespace Enter the WSDL Namespace for the output type. This must match the namespace specified in the target model. This input is required.
Example: http://www.ibm.com/c2a/models
Output Definitions
Name Enter the name of the parameter to pass to the target portlet. Example: OrderID
Output Name Type Enter the XML Schema Datatype name that was specified in the in the target model. This is a required input.
Example: OrderIDType
Output Type Select the XSD simple type of the value that is being passed to the target. We can also select the "xsd:anyType" when you are passing complex data, such as an XML structure. The default value is xsd:string
Example: xsd:integer
Value Enter an optional value that when specified will be passed as an input to the target event action. You may also leave this blank in order to manually pass the generated action method the desired value.
Note - If "xsd:anyType" is used as the Output Type and a "Value" is specified then the generated method action code will include the code to retrieve the value instead of being passed in to the method.
If "xsd:anyType" is used as the Output Type and a "Value" is not specified then the generated method action code will include a parameter of type Object for the data to be passed in. In this case the developer must call this method with the data they wish to pass to the target event.
Example: ${Variables/order}
Caption Enter the caption that will be used by the wiring tool to describe the name of the output parameter.
Example: Order ID

Input Name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Type	Select which type of tag to place on the model page: C2A Single Action - To place a <C2A:encodeProperty> tag. Valid only in IBM Portlet API. C2A Multiple Action - To place a <C2A:encodeProperties> tag Property Broker Link - To place a link on a page that triggers a Property Broker Event Property Broker Action - To place a link on a page that triggers a Property Broker Action
Page Location	Use the Page Location input to specify the page or pages on which this builder call will place the Property Broker Link. See Locating control builders on pages for detailed documentation about the Page Location input and page location syntax.
Value	Enter the value to be passed as an input to the target event action. Example: ${Variables/orderLoopVar/order/orderID}
Namespace	Enter the WSDL Namespace for the output type. This must match the namespace specified in the target model. This input is required. Example: http://www.ibm.com/c2a/models
Broadcast	This checkbox specifies if the source data can be broadcast to all target portlets on the page with matching data types. Enable to allow the generated menu to display an additional item to broadcast to all matching targets.
Generate When Nested	This checkbox specifies if this tag should generate markup when nested within a <c2a:encodeProperties> tag. Enable to generate markup.
Target Definition
Output Name	Enter the name of the parameter that will be past to the target portlet. Example: OrderID
Output Name Type	Enter the XML Schema Datatype name that was specified in the in the target model. This is a required input. Example: OrderIDType
Output Type	This input allows you to select the XSD simple data type of the parameter that is passed to the target. The target portlet cannot receive objects from other portlets that are in a different WAR if the object's class file is not shared; the class file must be in a shared location. The default value is xsd:string. Example: xsd:integer
Caption	Enter the caption that will be used by the wiring tool to describe the name of the output parameter. Example: Order ID