Registering a Commerce Composer widget

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

Before beginning

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

Task info

• Before we can use our custom widget in the Commerce Composer tool, we 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 stored within the PLWIDGETDEF table and the language of the information. We 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.

• We must also have a store subscribe to the widget before we 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

1. Prepare the data load input file containing the identifier, descriptive, and definition information for our 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 specified as the value for the targetFolder parameter in the pattern input XML file. If we 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 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 we 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 we 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 we 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 our 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 our 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 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 our 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 we can set for our widget, review the configurable properties for the widgets provided by default with WebSphere Commerce. 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 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 we are including assets, we 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. We can use a widget manager to add any additional logic when we 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 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 our 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 our custom widget. If the action path that you specify does not exist, add a entry into the struts configuration file to create the action path for our 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 our 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>  

2. Prepare the data load input file that includes the information to have the store subscribe to our 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 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 we can include for the columns, see subscribeWidgetdef input file.

   3. Ensure that the value for the WidgetDefIdentifier column is the correct identifier for our 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 specified for the identifier parameter in the pattern input XML file for the JET transformation.

   4. Save the file.

3. Configure the Data Load utility to load our custom widget information. The JET Transformation generates the data load configuration files 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 the database and environment settings. See Configure the data load environment settings. We can enter a value for the 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. We can find the value for the store identifier within the IDENTIFIER column of the STOREENT database table.

   4. Save your file.

4. 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 specified as the value for the targetFolder parameter in the pattern input XML file. If we 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

Previous topic: Defining storefront assets for a Commerce Composer widget
Next topic: Adding Management Center support for a Commerce Composer widget

Related concepts
Developing Commerce Composer assets
Commerce Composer widget architecture
Commerce Composer overview

Related tasks
Creating Commerce Composer widgets