Copy WebSphere Commerce site-level widgets

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

Important: By default, we cannot modify the source code for any Commerce Composer widget that is provided by WebSphere Commerce. The functionality of these widgets is provided as-is to help business users design pages for the store. However, we can customize the appearance of these widgets on the store pages by changing the CSS for the store. The source code for widgets provided by WebSphere 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.


Task info

The process to copy the assets for a widget that is provided by WebSphere Commerce to create our 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 to copy instead of generating our own custom source code. Include the copied assets within a new folder for our 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 we 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 provided by default with WebSphere Commerce.

    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 we are converting the format for our CSV file, update any column values that we 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 our 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:

    If we are using copying a widget to change only the storefront assets and behavior of the widget, we can use the Management Center display and interactions for the widget that you copied for our 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 our CSV file. For example, if we 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 we are copying any of the following widgets to replace the provided widget, update the struts configuration to use your widget.

    Identify the struts configuration entry for our widget within the workspace_dir\Stores\WebContent\WEB-INF\struts-config-widgets.xml file (for WebSphere 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 the store from the provided widget when you subscribe the store to your copy of the widget.

  6. Update or create layouts for the store pages to include your new widget instead of the default-provided widget that you copied.


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


Related tasks
Adding Management Center support for a Commerce Composer widget
Creating Commerce Composer widgets


Related reference
Best practices for developing Commerce Composer assets