Defining a Commerce Composer widget manager class

A widget manager handles the persistence and retrieval of widget extended data other than basic widget properties. You can use a widget manager to add more logic when you are creating, updating, or deleting a widget.

When a Management Center user saves widget property settings, the values for the properties are saved in the PLWIDGETNVP database table. If your widget has properties that must have values that are saved in a different table than the PLWIDGETNVP table, define a widget manager class to handle saving the values for your widget properties. The widget manager class is also used for retrieving the saved property value information from the database. When you define your widget manager class, you must extend the default widget manager class. You must also register your custom widget manager within the definition XML for your widget. If your widget has property values that are saved in only the PLWIDGETNVP table, you do not need to define a custom manager class. By default, when no widget manager class is defined for a widget, the widget uses the com.ibm.commerce.pagelayout.widget.management.impl.DefaultWidgetManager class.

The following diagram shows the hierarchy of the widget manager classes that are used within the Commerce Composer framework. When you are creating a custom widget, use the widget manager that extends the fewest classes and still provides the functionality that you need to handle the properties for your widget. Your widget can use any of the widget manager classes within the following diagram, however the four most common widget manager class that might consider using are highlighted.
Widget manager class inheritance.

Where

1 DefaultWidgetManager: Used by all widgets that do not need to write property data in the marketing subsystem. This manager is the default widget manager class that is associated with widgets when no widget manager class is specified. This widget manager provides basic validation capabilities that are based on the widget property declaration within the widget definition XML. This widget manager reads and persists widget name-value pair information into the PLWDIGETNVP database table.
2 MarketingWidgetManager: Used when a widget needs a display title, or needs an e-Marketing Spot associated with the widget. This widget manager class is the base widget manager for all widgets that use marketing objects. This widget manager provides common functions such as creating e-Marketing Spots for a widget. This widget manager allows widgets to include a display title. If your widget needs an e-Marketing Spot or a display title, consider the use of this widget manager.
3 DefaultContentWidgetManager: Used when a widget must save associated products, categories, or content. Each widget that uses marketing default content can use this super class to create, read, update, and delete default marketing content. This widget manager references the associated content by using extended data from the widget. Default content can be categories, products, or marketing content.
4 DefaultContentAndWebActivityWidgetManager: Used when a widget must have an associate web activity to define marketing rules. If a widget uses a web activity to populate the widget, this class manages the e-Marketing Spot that associates the widget with the web activity.

You can review the widget manager classes for the widgets that are provided by default to help you create your own custom class. The following table identifies the widget manager classes that are available by default:

Default widget manager classes for Commerce Composer widgets.
Widget manager class	Widgets that use the class
com.ibm.commerce.pagelayout.widget.management.impl.CategoryRecommendationWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentAndWebActivityWidgetManager class.	Category Recommendation widget
com.ibm.commerce.pagelayout.widget.management.impl.ContentRecommendationWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentAndWebActivityWidgetManager class.	Content Recommendation widget
com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentAndWebActivityWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentWidgetManager class.	No widget directly uses this class. However, some widgets use a manager class that extends this class.
com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.MarketingWidgetManager class.	No widget directly uses this class. However, some widgets use a manager class that extends this class.
com.ibm.commerce.pagelayout.widget.management.impl.DefaultWidgetManager	The following widgets use the default widget manager class to handle any properties that are defined for the widget. By default, not all widgets have properties defined. Associated Assets widget Breadcrumb Trail widget Category Navigation widget Components widget Defining Attributes widget Descriptive Attributes widget Discounts widget E-Marketing Spot widget Facebook Activity widget Facebook Like widget Facet Navigation widget Full Image widget Heading widget Inventory Availability widget Long Description widget Merchandising Associations widget Name, Part Number, and Price widget Search Summary widget Shopper Actions widget Short Description widget Site Content List widget Site Map widget
com.ibm.commerce.pagelayout.widget.management.impl.IBMProductRecommendationsWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.MarketingWidgetManager class.	IBM Product Recommendations widget
com.ibm.commerce.pagelayout.widget.management.impl.MarketingWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultWidgetManager class.	No widget directly uses this class. However, some widgets use a manager class that extends this class.
com.ibm.commerce.pagelayout.widget.management.impl.ProductListingWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentWidgetManager class.	Catalog Entry List widget
com.ibm.commerce.pagelayout.widget.management.impl.ProductRecommendationWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentAndWebActivityWidgetManager class.	Catalog Entry Recommendation widget
com.ibm.commerce.pagelayout.widget.management.impl.RichTextWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.MarketingWidgetManager class.	Text Editor widget
com.ibm.commerce.pagelayout.widget.management.impl.RotatingContentWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.DefaultContentAndWebActivityWidgetManager class.	Content Carousel widget
com.ibm.commerce.pagelayout.widget.management.impl.URLLinkWidgetManager This class extends the com.ibm.commerce.pagelayout.widget.management.impl.MarketingWidgetManager class.	Links widget

For examples of the properties that these classes handle for the widgets that are available by default with WebSphere Commerce, see Commerce Composer widget properties.

Procedure

Create a file to define the implementation class for your widget manager. In your new file, extend the DefaultWidgetManager class.
To extend the DefaultWidgetManager class, add the following code in your new file:
```
/**
* This is the widget manager associated with my custom widget.
* It creates, updates, deletes and gets data for my custom widget.
*/
public class CustomWidgetManager extends DefaultWidgetManager {
```
Override one or more of the methods of the DefaultWidgetManager class to define how your manager class is to handle properties for your widget.
These methods include the following methods:
- createExtendedData
- updateExtendedData
- deleteExtendedData
- retrieveExtendedData
Within these methods the following parameters are included:

LayoutType

The Layout noun that is passed in.

WidgetType

The noun part of the Layout noun that represents the widget.

ExtendedDataType

An element of the WidgetType noun part. It contains the data to be created.

PageLayoutWidget

The physical data object of the widget. It has all the data that is stored in the database for this widget.

For example, the following method overrides the createExtendedData method to define how to create a URL link for a widget:
```
public void createExtendedData(LayoutType aLayout, WidgetType aWidget, ExtendedDataType aExtData, PageLayoutWidget aWidgetSDO)
throws LayoutException {

// Always call super method first so that common extended data type will be handled.
super.createExtendedData(aLayout, aWidget, aExtData, aWidgetSDO);

String dataType = aExtData.getDataType();
// Check if the extended data type is 'IBM_CustomURL'
if (PageLayoutFacadeConstants.WIDGET_EXT_DATA_TYPE_CUSTOM_URL.equals(dataType)) {
String uniqueId = createURLLink(aWidget, aExtData, aWidgetSDO);

// Return the unique id of the extended data back.
aExtData.setUniqueID(uniqueId);
}
```
The createURLLink method calls Marketing service to create marketing content to store the URL.

Use the following format to specify a widget manager class:

<widget-manager j2ee=""/>

For example, the following code specifies the widget manager class

<Definition>
<widget-manager j2ee="com.ibm.commerce.pagelayout.widget.management.impl.URLLinkWidgetManager"/>
...
</Definition>

The following code is a sample widget definition XML file that defines a widget manager for the Links widget:

<Definition>
  <widget-property name="widgetRestrictionGroups">
    <value>AnyPage,CatalogEntryPage,CategoryPage,SearchPage</value>
  </widget-property>
  <widget-manager j2ee="com.ibm.commerce.pagelayout.widget.management.impl.URLLinkWidgetManager"/>
  <widget-property name="requireEMS">
    <value>true</value>
  </widget-property>
  <widget-property name="serializeActionPath">
    <value>SerializeLayoutWidget-URLLinkWidget</value>
  </widget-property>
  <widget-property name="isURLLink">
    <value>true</value>
  </widget-property>
  <widget-property name="emsName" required="false" datatype="java.lang.String"/>
</Definition>

Use the Data Load utility to load the widget definition into the WebSphere Commerce database to register your widget manager along with your custom widget.
For more information about registering your widget, see Registering a Commerce Composer widget.

In the WidgetObjectDefinition.def file for your widget, include a service to invoke the createExtendedDataService service.

The WidgetObjectDefinition.def file includes the definition of the input field variables for your widget. This object definition file also defines the services for creating, updating, and deleting data for your widget. When you add extended data for your widget, you must define a create service within this file to save the extended data. By including the following code you create such a service that invokes the createExtendedDataService service.

<!---
This definition defines the custom URL child object
-->
<ChildObjectDefinition definitionName="plmURLLinkCustomURL"
 objectType="URLLinkCustomURL" idProperty="extDataId"
 displayName="${plmPageLayoutResources.customURL}"
 icon="URLIcon">
 
<!--- Create service. -->
<CreateService url="/cmc/CreateWidgetExtendedData">
  <ServiceParam name="storeId"/>
  <ServiceParam name="dataStoreId" parameterName="dataStoreId" parentProperty="true" 
    resolvePrimaryParent="true" propertyName="objectStoreId">
    <EnablementCondition checkObjectDefinition="true" conditionId="objectTypeCondition" 
      enablementValue="URLLinks" negate="true" propertyName="objectType" 
      parentProperty="true" resolvePrimaryParent="false"/>
  </ServiceParam>
  <ServiceParam name="pageLayoutId" propertyName="pageLayoutId" parentProperty="true" />
  <ServiceParam name="type" value="IBM_CustomURL"/>
  <ServiceParam name="widgetId" propertyName="widgetId" parentProperty="true" objectPath="LayoutWidgetAlias"/>
  <ServiceParam name="languageId" resolvePrimaryParent="false" parentProperty="true" propertyName="languageId"/>
</CreateService>

Where:

<ServiceParam name="type" value=""/>: The type of the extended data for the widget, for example <ServiceParam name="type" value="IBM_CustomURL"/>

The service call to invoke the createExtendedDataService sends the following URL parameters

urlType=
sequenceOrder=
xExtData_urlText=
languageId=-
pageLayoutId=
timeZoneId=
requestIdentifier=
identityId=
identitySignature=
type=
locale=
storeId=
widgetId=

For example,

urlType=custom
sequenceOrder=1
xExtData_urlText=cnn
languageId=-1
pageLayoutId=10601
timeZoneId=America/New_York
requestIdentifier=1
identityId=95121
identitySignature=********
type=IBM_CustomURL
locale=en_US
storeId=10001
widgetId=6201

The request BOD of the createExtendedData service call can resemble the following request:

<oa:Change>
  <oa:ActionCriteria>
    <oa:ActionExpression actionCode="Add" 
     expressionLanguage="_wcf:XPath">/Layout[1]/Widget[1]/ExtendedData[1]</oa:ActionExpression>
  </oa:ActionCriteria>
</oa:Change>
<_pgl:Layout>
  <_pgl:LayoutIdentifier>
    <_wcf:UniqueID>10601</_wcf:UniqueID>
  </_pgl:LayoutIdentifier>
  <_pgl:Widget>
    <_pgl:WidgetIdentifier>
      <_wcf:UniqueID>6201</_wcf:UniqueID>
    </_pgl:WidgetIdentifier>
    <_pgl:ExtendedData sequenceOrder="1.0">
      <_pgl:DataType>IBM_CustomURL</_pgl:DataType>
      <_pgl:Attributes language="-1">
        <_pgl:Attribute name="url">cnn.com</_pgl:Attribute>
        <_pgl:Attribute name="urlText">cnn</_pgl:Attribute>
      </_pgl:Attributes>
    </_pgl:ExtendedData>
  </_pgl:Widget>
</_pgl:Layout>

For more information about creating the object definition for your widget, see Adding Management Center support for a Commerce Composer widget.