Registering a Commerce Composer widget

Use the Data Load utility to register your widget in the Commerce Composer framework and have your store subscribe to your widget.

Before you begin

Ensure that you complete the task to define the storefront assets for your Commerce Composer widget.

About this task

Before you can use your custom widget in the Commerce Composer tool, you must register the widget with the Commerce Composer framework. The framework maintains a single registry, which includes all of the registered widgets and the stores that can use the widgets on pages. To register a widget, use the Data Load utility to load the widget identifier and definition XML into the PLWIDGETDEF database table.
If your widget must display content in multiple languages load the relationship between the widget description that is stored within the PLWIDGETDEF table and the language of the information. You must load this relationship information into the PLWIDGETDEFDESC table. The language for the widget information is associated with an entry in the LANGUAGE database table.
You must also have a store subscribe to the widget before you can use the widget in a page layout for that store. Use the Data Load utility to load a store subscription to your widget. This subscription relationship is stored in the PLSTOREWIDGET database table.

Procedure

Prepare the data load input file that contains the identifier, descriptive, and definition information for your custom widget.
1. Go to the directory where the JET Transformation generated the source code files.
  workspace_dir\target_folder\DataLoad\widget
  Where
  
  target_folder
  
  The folder or project that you specified as the value for the targetFolder parameter in the pattern input XML file. If you did not specify a value for the targetFolder parameter, the target_folder is the folder or project where the pattern input XML file is located.
2. Open the registerWidgetDef.csv file for editing. By default, the generated CSV file includes information that you specified in the pattern input XML file. The JET Transformation uses the content of your pattern input file to set values for the mandatory columns in the CSV file.
  For information about the columns in the generated CSV file and the data that you can include for the columns, see registerWidgetdef input file.
3. Specify whether the widget is to be a site-level or store-level widget. If you want your widget to be a store-level widget, set the value of the WidgetStoreUniqueID or WidgetStoreIdentifier column in the CSV file to be the ID for the store. If you want your widget to be site-level, do not set a value for either of these columns. By default, the JET Transformation specifies the value to set your widget as a site-level widget.
4. Optional: Update the CSV file to include any more configurable properties that must be included in the widget definition XML for your custom widget. The widget definition XML must be included as the value for the WidgetDefinitionXML column in the CSV file.
  To include more configurable properties for your widget, use the format:
```
<widget-property name="" required="" datatype=""/> 
```
  Where
  
  name
  
  The name of the property.
  
  required
  
  Identifies whether the property is mandatory and must have a value. Set the value for this attribute to be true if the property must have a value that is set by a user.
  
  datatype
  
  The data type of the value that the property expects to be set as the value. For example, the datatype can be String, Boolean, or Integer.
  
  For example,
```
<widget-property name="storeId" required="false" datatype="java.lang.String"/> 
```
  For each configurable property that you set within the definition XML, the Management Center object and properties view definitions for your widget must support the properties. The storefront asset definitions for the widget must also support handling or displaying the configured data that returns. For examples of configurable properties that you can set for your widget, review the configurable properties for the widgets that are provided by default with HCL Commerce. For more information, see Commerce Composer widget properties.
5. Update the definition XML within the CSV to include your widget within any more widget restriction groups.
  By default, the definition XML includes the widget restriction groups that you set for the widget when you generated the source code. Use a comma separated list to include your widget within more widget restriction groups. The definition XML for a widget that is included within two widget restriction groups can resemble the following code:
```
<Definition>
  <widget-property name="widgetRestrictionGroups"> 
    <value>CategoryPage,CatalogEntryPage, AnyPage</value>
  </widget-property>
</Definition>
```
6. Optional: Update the widget definition XML in the CSV file to include any CSS, images, JavaScript files, or predefined properties.
  Use the following format to set the value for the properties or files:
```
<widget-property name="" value=""/> 
```
  Where
  name
  
  Either the name of the predefined property or the include declaration to identify the asset type that is being included. For example, to include a JavaScript file, specify _pgl:javaScriptInclude.
  
  value
  The setting for the predefined properties, or the path to the CSS, image, or JavaScript file. If you are including assets, you can specify multiple values. For example:
  <widget-property name="_pgl:javaScriptInclude"> <value>${jsAssetsDir}javascript/Widgets/swipe.js</value> <value>${staticAssetContextRoot}/Widgets/Common/javascript/Recommendation.js</value>
7. Optional: If your widget must handle data other than properties that are stored in the PLWIDGETNVP database table, specify a widget manager in the widget definition XML in the CSV file to handle the data.
  A widget manager handles the persistent storage and retrieval of extended widget data other than basic widget properties. You can use a widget manager to add any additional logic when you are creating, updating, or deleting a widget. For example, the Links widget includes a Display title when the widget displays on a store page. The Display title is a piece of marketing content that displays in the widget. When a Management Center user sets the content that is used for the Display title, a widget manager must be used to save the setting. To identify a widget manager, include the following code in the widget definition XML:
  widget-manager j2ee element
  The value for this element specifies the widget manager class for a widget. Use the following format to set the widget manager class:
  <widget-manager j2ee=""/>
  For example, the following code specifies the widget manager for the Content Recommendation widget:
  <widget-manager j2ee="com.ibm.commerce.pagelayout.widget.management.impl.ContentRecommendationWidgetManager"/>
  requireEMS property
  If your widget requires an e-Marketing Spot to display the data that your widget generates, include this property. For example, if your widget generates data through a marketing activity, such as content or catalog entry recommendations, your widget must use an e-Marketing Spot to display the generated data. This property identifies that the Commerce Composer framework must create an e-Marketing Spot for the widget to use to display data. Use the following code, with the property value set to true, to create an e-Marketing Spot for your widget:
  <widget-property name="requireEMS"> <value>true</value>
  serializeActionPath property
  The value for this property defines the action path within the struts configuration file for your custom widget. If the action path that you specify does not exist, you must add a entry into the struts configuration file to create the action path for your widget. This struts configuration file maps the action path to a JSP. This JSP file is then called by the SerializeLayoutWidget.jspf file to handle your widget data that is not stored in the PLWIDGETNVP table. Use the following format to specify the serialize action page in the definition XML:
  <widget-property name="serializeActionPath"> <value></value>
  For example, the serialize action path for the Content Recommendation widget is specified with the following property:
  <widget-property name="serializeActionPath"> <value>SerializeLayoutWidget-ContentRecommendationWidget</value>
  For more information about widget manager, see Defining a widget manager.
8. Save the file.
  As an example to help you specify the definition XML for your widget, the following code is the definition XML for the Heading widget which contains no configurable properties. This definition XML defines only the widget restriction groups that the Heading widget is included within.
```
<Definition>
  <widget-property name="widgetRestrictionGroups"> 
    <value>CategoryPage,CatalogEntryPage</value>
  </widget-property>
</Definition>
```
  The following code is the definition XML for the Content Recommendation widget, which supports web activities:
```
<Definition>
  <widget-property name="widgetRestrictionGroups">
    <value>AnyPage,CatalogEntryPage,CategoryPage,SearchPage</value>
  </widget-property>
  <widget-manager j2ee="com.ibm.commerce.pagelayout.widget.management.impl.ContentRecommendationWidgetManager"/>
  <widget-property name="requireEMS">
    <value>true</value>
  </widget-property>
  <widget-property name="requireDefaultContent">
    <value>true</value>
  </widget-property>
  <widget-property name="serializeActionPath">
    <value>SerializeLayoutWidget-ContentRecommendationWidget</value>
  </widget-property>
  <widget-property name="emsName" required="false" datatype="java.lang.String"/>
  <widget-property name="widgetOrientation" >
    <value>horizontal</value>
  </widget-property>
  <widget-property name="pageSize">
    <value>4</value>
  </widget-property>
  <widget-property name="displayPreference">
    <value>1</value>
  </widget-property>
  <widget-property name="showFeed">
    <value>false</value>
  </widget-property>
  <widget-property name="_pgl:javaScriptInclude">
    <value>${staticAssetContextRoot}/Widgets/com.ibm.commerce.store.widgets.ContentRecommendation/javascript/video.js</value>
  </widget-property>
</Definition>  
```
Prepare the data load input file that includes the information to have your store subscribe to your custom widget.
1. Go to the workspace_dir\target_folder\DataLoad\widget directory
2. Open the subscribeWidgetDef.csv file for editing. By default, the generated CSV file includes the information that you specified in the pattern input XML. The JET Transformation uses the content of your pattern file to set values for the mandatory columns in the CSV file.
  For information about the columns in the generated CSV file and the data that you can include for the columns, see subscribeWidgetdef input file.
3. Ensure that the value for the WidgetDefIdentifier column is the correct identifier for your widget. This name must match the value of the WidgetDefIdentifier column in the registerWidgetdef.csv file. By default the value for this column is the value that you specified for the identifier parameter in the pattern input XML file for the JET transformation.
4. Save the file.
Configure the Data Load utility to load your custom widget information.
The JET Transformation generates the data load configuration files that are required to load your widget registration and subscription information.
1. Go to the workspace_dir\target_folder\DataLoad directory.
2. Open the generated wc-dataload-env.xml data load environment configuration file for editing.
  The file configures the Data Load utility environment variables, such as the database settings, ID resolver, and data writer.
3. Update the file to match your database and environment settings.
  For more information, see Configuring the data load environment settings. You can enter a value for your store identifier in this file or enter the store identifier when you run the Data Load utility to load the CSV files. The store identifier is used to identify the store that subscribes to your widget. The store identifier is case-sensitive. You can find the value for your store identifier within the IDENTIFIER column of the STOREENT database table.
4. Save your file.
Run the Data Load utility.
1. In a command-line utility, go to the WCDE_installdir\bin directory.
2. Run the following command to load the input files to register and subscribe to your widget:
  dataload.bat ..\workspace\target_folder\DataLoad\widget\wc-dataload-widget.xml
  Where
  
  target_folder
  
  The folder or project that you specified as the value for the targetFolder parameter in the pattern input XML file. If you did not specify a value for the targetFolder parameter, the target_folder is the folder or project where the pattern input XML file is located. If you moved the generated configuration and data load input files, specify the appropriate directory path to your data load order file.
3. Verify the results of the data load.
For more information about using Data Load utility to load widget information, see Sample: Loading Commerce Composer widgets