Copying HCL Commerce site-level widgets

You can copy and modify an existing Commerce Composer widget to use as a model to create your own custom widget. If you need a widget that provides almost the same functionality of a widget that is provided by HCL Commerce, the recommended best practice is to copy the assets for the provided widget. You can then use the copied assets to model your own custom widget that is a copy of the default-provided widget. With your custom version of the widget, you can then modify your widget to meet your store design and functionality requirements.

Important: By default, you cannot modify the source code for any Commerce Composer widget that is provided by HCL Commerce. The functionality of these widgets is provided as-is to help business users design pages for your store. However, you can customize the appearance of these widgets on your store pages by changing the CSS for your store. The source code for widgets that are provided by HCL Commerce can be updated by future releases, such as required or recommended maintenance fixes. Any custom modifications to these default-provided widgets would be overwritten by such updates.

About this task

The process to copy the assets for a widget that is provided by HCL Commerce to create your own custom version of this widget is similar to the process for creating a widget. For more information about creating, registering, and subscribing to a new widget, see Creating Commerce Composer widgets. To copy an existing widget, follow these instructions with the following changes:

Procedure

  1. Copy the storefront assets for the widget that you want to copy instead of generating your own custom source code. Include the copied assets within a new folder for your custom widget in your widgets-vendor folder. Edit the copied assets to customize the storefront display and behavior for this new widget.
  2. Create a registerWidgetDef.csv CSV file to use for registering the new widget within the Commerce Composer framework.
    For more information about the data to include in this file, see registerWidgetdef input file.
    Tip: Copy and edit the registration information for the widget that you are copying to help you define the registration information for your new widget. Retrieve the registration information for the widget from the following file. This file includes the registration information for the widgets that are provided by default with HCL Commerce.
    • WCDE_installdir\schema\xml\wcs.features_bootstrap.xml
    When you copy and edit the information, ensure that you convert the information format for use in a CSV file.
    For example, the registration information for the facet navigation widget in the store enhancements bootstrap XML file resembles the following code snippet: 
    
<plwidgetdef 
 plwidgetdef_id="-2004" 
 storeent_id="0" 
 identifier="FacetNavigation_701" 
 ui_object_name="FacetNavigationWidget" 
 vendor="ibm" 
 widgettype="1" 
 jsppath="/Widgets_701/com.ibm.commerce.store.widgets.FacetNavigation/FacetNavigation.jsp"
 definitionxml="
 &lt;Definition&gt;
  &lt;widget-property name=&quot;widgetRestrictionGroups&quot;&gt;
   &lt;value&gt;CategoryPage,SearchPage&lt;/value&gt;
  &lt;/widget-property&gt;
  &lt;widget-property name=&quot;widgetOrientation&quot; &gt;
   &lt;value&gt;vertical&lt;/value&gt;
  &lt;/widget-property&gt;
  &lt;widget-property name=&quot;_pgl:javaScriptInclude&quot;&gt;
   &lt;value&gt;
    ${staticAssetContextRoot}${env_siteWidgetsDir}com.ibm.commerce.store.widgets.CatalogEntryList/javascript/SearchBasedNavigationDisplay.js
   &lt;/value&gt;
  &lt;/widget-property&gt;
 &lt;/Definition&gt;
 "
 state="1"
 createdate="2012-06-25 17:29:25.562"
 lastupdate="2012-06-25 17:29:25.562"
/>
    When you are converting the format for your CSV file, update any column values that you want or need to change. Ensure that you change the values for any column that points to the storefront asset files for the widget that you copied to point to the location for the files for your new widget. For example, update the value for the WidgetPath column to point to the storefront asset JSP file that you copied and edited. After you convert the format for this registration information, your CSV file can resemble the format of the following sample registerWidgetDef.csv file:
    Note: If you are copying a widget to change only the storefront assets and behavior of the widget, you can use the Management Center display and interactions for the widget that you copied for your copy of the widget. To keep the existing Management Center support intact, do not change the value for the WidgetUIObjectName column when you convert the ui_object_name element for your CSV file. For example, if you are copying the facet navigation widget, keep the value for the WidgetUIObjectName column to be FacetNavigationWidget.
  3. Run the Data Load utility to load the CSV file to register your widget.
  4. If you are copying any of the following widgets to replace the provided widget, update the struts configuration to use your widget.
    • Catalog Entry List widget
    • IBM Product Recommendations widget
    • Site Content List widget
    • Catalog Entry Recommendation widget
    • Associated Assets widget
    • Inventory Availability widget
    Identify the struts configuration entry for your widget within the workspace_dir\Stores\WebContent\WEB-INF\struts-config-widgets.xml file (for HCL Commerce Version 9.0.0.x), or workspace_dir\Stores\WebContent\WEB-INF\classes\struts-wcs-stores-widgets.xm (for Version 9.0.1+). Review the entry for the widget your are copying and create an equivalent entry to point to your widget JSP path.
  5. Unsubscribe your store from the provided widget when you subscribe your store to your copy of the widget.
  6. Update or create layouts for your store pages to include your new widget instead of the default-provided widget that you copied.