Use the Data Load utility to register your widget in the Commerce Composer
framework and have your store subscribe to your 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.
-
Go to the directory where the JET Transformation generated the source code files.
WCDE_installdir\workspace\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.
-
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.
-
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.
- 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 WebSphere Commerce.
For more information, see Commerce Composer widget properties.
-
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>
- 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>
- 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.
-
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.
-
Go to the
WCDE_installdir\workspace\target_folder\DataLoad\widget
directory
-
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.
-
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.
-
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.
-
Go to the
WCDE_installdir\workspace\target_folder\DataLoad
directory.
-
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.
-
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.
-
Save your file.
-
Run the Data Load
utility.
-
In a command-line utility, go to the
WCDE_installdir\bin directory.
-
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.
-
Verify the results of
the data load.