Cooperative portlet reference

---

• JSP tags used by source portlets

• WSDL reference for cooperative portlets
  • Extensions to the <binding> element
  • WSDL Extension Schema

 

JSP tags used by source portlets

The following tags are used by source portlet JSPs.

<c2a:encodeProperty/>

Uses source data and type information to insert markup that displays the Click-to-Action icon, generating a pop-up menu. The type, namespace, and value attributes are required. The tag can optionally pass the source information to an enclosing <c2a:encodeProperties/> tag to generate the markup. This would typically be used to support the scattering of several sources to multiple actions at once.

Usually, any property which may be described using an XML type, following the type restrictions, is a candidate for being tagged as a C2A source. It usually does no harm to tag as many sources in the JSPs that qualify, as the Click-to-Action icon is not generated for sources which do not have any matching actions on the page. Tagging all sources which meet the type restrictions maximizes the potential applicability of Click-to-Action to the application as it is deployed in a variety of settings.

It is usually appropriate to locate this tag close to a visual representation of the source data, if such is present on the page. The following are attributes of encodeProperty.

Attribute	Value
type	Specifies the type of data sent by the source portlet. Required. The data type is defined in the WSDL. The Click-to-Action runtime uses type and namespace attributes to match source data to actions on targets.
name	Specifies the unique name of the source property. Although not required, this parameter must be provided to allow wires to be created between cooperative portlets.
namespace	Specifies the namespace for the type. Required. This attribute is used to group related types in a single domain.
value	Specifies the data to be sent by the source portlet. Required. The Click-to-Action runtime sends the value of the user's selections to the target actions. In the sample below, value is the order detail retrieved from the OrderDetailBean.
broadcast	Indicates whether the source data can be broadcast to all target portlets with matching actions. False is the default setting. Optional. If the value is true, the generated menu displays an additional item to broadcast the source to all matching targets.
generateMarkupWhenNested	Indicates that this tag should generate markup even when nested within the <c2a:encodeProperties/> tag. This attribute is optional; the default is false. If this tag is not nested, the attribute is ignored.

<c2a:encodeProperties/>

Used to enclose normal HTML markup and one or more encodeProperty tags with the markup.

This tag is provided to support the scatter scenario, where a user can optionally send more than one unit of data to target portlets. This may be used to enclose several <c2a:encodeProperty/> tags, each of which is used to contribute a single source data object for the scatter. Each enclosed encodeProperties tag must specify a different value for the type attribute. At the point where the encodeProperties tag is closed, an icon is placed, which, when clicked, displays a menu within a single item. When the item is selected, each action that matches any of the encoded property values is simultaneously invoked. This tag takes the following attributes:

Attribute	Value
caption	Displays a caption on the generated menu. Required. A caption should be a short description of the action or actions resulting when a user selects that option from the menu. A default caption is used if none is provided. If internationalization is to be used, replace spaces in the caption text with periods.
description	An attribute of the encodeProperties tag. Optional. Not currently used. This tag provides a longer description of an action or actions. This option aides the user in deciding whether to invoke an action or not. If internationalization is to be used, replace spaces in the caption text with periods.

 

WSDL reference for cooperative portlets

WSDL is often used in the context of Web Services, in order to define interfaces implemented by a Web Service. Usually, a SOAP binding is used to specify the concrete realization of the interface by a Web Service which supports the SOAP protocol. The following shows how Click-to-Action uses some of the elements in the WSDL document. The extensions to the <binding> element are described and the complete schema for WSDL Extensions is provided.

• <types>

  For cooperative portlets, this declares the data type of the data to be transfered. The data type is declared using XML Schema Datatypes (XSD, see the XSD specification). There may be multiple types defined in the document.

  The following shows the declaration for the TrackingIDType used in the <c2a:encodeProperty/> Example.

      <types>
        <xsd:simpleType name="TrackingIDType">
          <xsd:restriction base="xsd:string">
          </xsd:restriction>
        </xsd:simpleType>
      </types>
      

• <message>

  Input messages can contain only one part.

• <operation>

  Provides an abstract definition of a Click-to-Action operation. Note the restriction on input messages above.

• <portType>

  Defines an abstract collection of operations. The operations must be defined in the document. One operation corresponds to each action on the Click-to-Action enabled portlet. Only actions that are to be enabled for Click-to-Action should be declared.

• <binding>

  The binding element is extended to associate portlet actions with operations. For each operation, the portlet action name must be provided. The portlet action name may be specified using the name attribute of the action tag in the binding section of the WSDL file. If it is omitted, the name attribute from the operation tag is used as the portlet action name.

  For each operation parameter, the action parameter name must be provided. The portlet parameter name may be specified using the name attribute of the param tag in the binding section of the WSDL file. If it is omitted, the name attribute of the part tag associated with the param tag is used as the portlet parameter name.

  Further, the boundTo attribute may be used to specify where the parameter will be bound. Choices are request-parameter, request-attribute, session-attribute, or action-attribute.

  The <binding> element includes cooperative portlet extensions, which are described in Extensions to the <binding> element. shown in the WSDL Example.

If you are familiar with WSDL, you might notice that the service section (enclosed by the <service> element in WSDL) is not used in the C2A action declaration file. This is because the file is associated with a specific portlet implementing the operations defined in the file through external means (an entry in the portlet.xml file associated with the portlet).

 

Extensions to the <binding> element

The <binding> element has been extended to support cooperative portlets. Each extension element is prefixed with "portlet:", which refers to the C2A namespace, http://www.ibm.com/wps/c2a. The "portlet:" prefix is used to identify the extension elements in this section, but a different name may be used for the prefix as long as it refers to the C2A namespace. The elements are described below. See WSDL Extension Schema

• <portlet:binding>

  This must be the first child element of the WSDL <binding> element. Its presence identifies the section as a C2A binding extension for portlet action invocation. The element has the following attribute.

  • style

    Deprecated. Specifying style="struts" indicates that Struts actions are being declared. Instead, use type=struts on the <portlet:action> element for this purpose.

• <portlet:action>

  This must be the first child element of any WSDL <operation> element in the binding section. It contains the following attributes:

  • name

    the portlet action name. If this is omitted, the name of the associated operation element is used as the portlet action name.

  • caption

    a short string about the action suitable for displaying in the portlet user interface. For translated captions, indicate in dotted format the name of the key in the resource bundles from which the caption is to be obtained. See Internationalization support for more information.

  • type

    Indicates one of the following values:

    • default indicates a DefaultPortletAction object is used. This object is deprecated but still supported for migration purposes.
    • simple indicates a simple portlet action String is used.
    • struts indicates a Struts action is used. See Struts integration with cooperative portlets for more information.

  • description

    a text description of the action. For translated descriptions, indicate in dotted format the name of the key in the resource bundles from which the description is to be obtained. See Internationalization support for more information.

  • activeOnStartup

    Indicate either "true" or "false". If false, the action must be programmatically activated in each session. If true (default), the action is active as soon as the portlet is initialized.

  • selectOnMultipleMatch

    In the case that multiple actions match based on the data type for the portlet, this attribute can be used to indicate which action to trigger. Multiple matching actions can occur when a user broadcasts an action on a source. If not specified, the default is false. In the case where no single action is set to true, the data is not delivered to the target.

    In the following example from TrackingC2A.wsdl, There are two actions declared: trackingDetails and routingDetails. selectOnMultipleMatch is used to indicate that the trackingDetails should be used in the case of a multiple match.

        <binding name="TrackingBinding" type="tns:Tracking_Service">
          <portlet:binding/>
          <operation name="trackingDetails">
            <portlet:action caption="Tracking Details"
                            description="Get tracking details for specified tracking id"
                            selectOnMultipleMatch="true"/>
            <input>
              <portlet:param name="trackingId" partname="trackingId"/>
            </input>
            <output>
              <portlet:param name="customerName" partname="custName" boundTo="session"/>
            </output>
          </operation>
          <operation name="routingDetails">
            <portlet:action caption="Routing Details"
                            description="Get routing details for specified tracking id"/>
            <input>
              <portlet:param name="trackingId" partname="trackingId"/>
            </input>
          </operation>
        </binding>
    
        

• <portlet:param>

  This must appear as a child element in the <input> or <output> subelements of the <operation> element in the binding. It specifies the parameters consumed (if enclosed in the <input> element) or produced (if enclosed in the <output> element) by the portlet action. At present, we restrict the number of parameters consumed to at most one. The number of parameters produced can be any number. It has the following attributes:

  • name

    the name of the parameter. If omitted, the name attribute value of the part element is used as the parameter name.

  • partname

    fers to a part element of the input or output for the operation.
            It may be omitted if the input or output has a single part.
        
    boundTo 
    
     specifies where the parameter value is bound.
            Currently, this attribute can specify one of the following values only:
            
    
    
            
    request-parameter : This specifies that the value is bound as a parameter in the PortletRequest object.
                This is the default value if the boundTo attribute is omitted.
                Note that for output parameters, a different value should usually be specified as the default PortletRequest
                implementation provided by WebSphere Portal does not allow parameters to be set during action processing.
            
    request-attribute : This specifies that the value is bound as an attribute in the PortletRequest object.
            
    session : This specifies that the value is bound to the PortletSession object.
            
    action : This specifies that the value is bound to a portlet action.
            
    
    
        
        
    

 

WSDL Extension Schema

The following is the schema for the extensibility elements introduced for the portlet action invocation using Click-to-Action. Lines have been broken to allow viewing on the printed page.

<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               targetNamespace="http://www.ibm.com/wps/c2a"
               xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:schemaLocation="http://schemas.xmlsoap.org/wsdl/ 
                                   http://schemas.xmlsoap.org/wsdl/ 
                                   http://www.w3.org/2001/XMLSchema 
                                   http://www.w3.org/2001/XMLSchema.xsd" 
               xmlns:portlet="http://www.ibm.com/wps/c2a">
   <!-- The binding element indicates that the binding section contains custom 
        extensions describing a mapping of operations to portlet actions.  This 
        must be placed within a WSDL binding element. -->
   <element name="binding" type="portlet:bindingType"/>
   <complexType name="bindingType">
      <!-- DEPRECATED, retained for compatibility with version 4. Use the type 
           attribute with the action element instead.  Set value to be "struts" 
           for a portlet implemented using the struts framework. -->
      <attribute name="style" type="string" use="optional"/>
   </complexType>
   <!-- The action element is used to provide all the information about the 
        portlet action necessary for the property broker to invoke it. This must 
        be placed within an wsdl:operation element in the wsdl:binding section. -->
    <complexType name="actionType">
       <sequence>
    <!-- The param element is used to indicate information about the input
    or output property associated with the action and the mechanism for
    passing parameters to or from the action. It must be placed within a
    wsdl:input or wsdl:output element. -->
          <element name="param" type="portlet:paramType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
         <!-- The name of the action. Will be set as the portlet action name.  
           If omitted, the name of the corresponding operation element will be
           used as the action name. -->
       <attribute name="name" type="string" use="optional"/>
          <!-- default, simple, and struts are currently recognized values, with default 
               being the default. Is used to specify whether the DefaultPortletAction, 
               simple portlet action, or struts action mechanism is used to invoke the 
               portlet action. Note that the use of DefaultPortletAction is deprecated, and 
               the default is set to this value for backwards compatibility.  We encourage 
               setting this to simple to avoid future migration issues. -->
       <attribute name="type" type="string" use="optional" default="default"/>
          <!-- A short name for  the action which is displayed to the end-user.  If a 
               message resource file is provided for the portlet, the value is used as a key
               to retrieve a translated string -->
       <attribute name="caption" type="string" use="optional"/>
          <!-- A description for  the action which is displayed to the end-user. If a 
               message resource file is provided for the portlet, the value is used as a key 
               to retrieve a translated string -->
       <attribute name="description" type="string" use="optional"/>
          <!-- If more than one portlet action can simultaneously process a property 
               value, only those with the invokeOnMultipleMatch attribute set to true will 
               be invoked -->
       <attribute name="selectOnMultipleMatch" type="boolean" use="optional" default="false"/>
          <!-- If the activeOnStartup attribute is true, the action may be selected for 
               invocation at any time unless programmatically deactivated on a per-session 
               basis.  If the activeOnStartup is false, the action may not be selected for 
               invocation, unless programmatically activated on a per-session basis -->
       <attribute name="activeOnStartup" type="boolean" use="optional" default="true"/>
          <!-- The param element indicates how the parameter is to be delivered to the 
               portlet action or retrieved from it once the action has executed -->
    </complexType>
    <complexType name="paramType">
        <!-- The name of the parameter which will be used on action invocation. If 
             omitted, the partname is used. This name will also be set as the name of the 
             corresponding property.  See a description of properties in the programming 
             model document. -->
        <attribute name="name" type="string" use="optional"/>
        <!-- The name of the corresponding part. May be omitted only if there is a 
             single parameter for the action, in which case it will be inferred from the 
             associated operation definition -->
        <attribute name="partname" type="string" use="optional"/>
        <!-- Where to place the parameter prior to invoking the action (in case of in 
             parameters), or where to look for it after invoking the action (in case of 
             out parameters).  request-attribute, request-parameter, session, and action 
             are allowed values. -->
        <attribute name="boundTo" type="string" default="request-parameter"/>
        <!-- The java class for the parameter. The default is java.lang.String. 
             Currently this is not used, but may be used in future for validation -->
        <attribute name="class" type="string" default="java.lang.String"/>
        <!-- A short name for  the parameter which is displayed to the end-user. If a 
             message resource file is provided for the portlet, the value is used as a 
             key to retrieve a translated string -->
        <attribute name="caption" type="string" use="optional"/>
        <!-- A description for  the parameter which is displayed to the end-user. If a 
             message resource file is provided for the portlet, the value is used as a key 
             to retrieve a translated string -->
        <attribute name="description" type="string" use="optional"/>
    </complexType>
</xsd:schema>

See also

• Struts Portlet Framework
• WSDL Specification
• XSD specification