Creating a new Commerce Composer Widget

From feature pack 7 of WCS 7 onwards, a new feature called commence composer is introduced which will help the business to change the layout & alignment of widgets without much involvement from IT team. Widgets are independent components which can be plugged anywhere and will perform the pre-defined functionalities.

WCS feature pack 7 and later versions are coming with a set of pre-defined layouts and widgets which can be applied on the browse pages. Even we can define our own custom layouts & widgets, if the ones provided by WCS doesn’t fit into our requirement.

Given below are the steps to be followed for creating a new widget. 

1. Generating commerce composer widget source

We use a Java Emitter Template (JET) Transformation to generate the source code files that are required to create a Commerce composer widget.

•  Create a new project in the Websphere commerce workspace.
• Inside this project folder, create a pattern input file for JET Transformation. Contents of the input XML file should be as follows:

<pageLayout vendor="TestCompany">   <Widget>     <widgetDef identifier="Test"      UIObjectName="TestWidget"       displayName="Sample widget"    description="This widget is for learning purpose" > </widgetDef>  </widget> </pageLayout>

            Where

           

Property	Values
Vendor	The name of your company
Identifier	The external reference name for the widget or container definition. This must be unique.
UIObjectName	The name that identifies the Management Center object and object definition of this widget.
DisplayName	The language-specific display name of the widget
Description	The language-specific description for the widget.

• Right click the pattern input file and run JET Transformation.
• The JET Transformation generates a set of file directories and files that can be used to create the custom widget. The generated file directories contain three main folders: LOBTools, Stores and DataLoad.

2. Defining the Storefront assets for a site-level widget

• Copy the generated source code files for your widget storefront assets from your project folder to the appropriate location within the default Stores project.
• Modify the source files to suit the functionality of the widget.
• All the JSPs, JSPFs, images and property files required by the widget should be moved to this location.

3. Testing the widget in the store

•  Import the base JSP of the widget in any of the available pages of your store. Suppose, Test.jsp corresponds to the base JSP of the custom widget. This file can be imported in TopCategoriesDisplay.jsp which is the base JSP of default Home page.
•  Navigate to the Home Page in the site and debug the widget source files in case of errors.

 4. Loading widget into the database by using data load utility

In this step, Data load utility is used to register the custom widget and to make the store to subscribe to the widget.

• Open the new project folder created for the custom widget.
• Open the registerWidgetdef.csv for editing. This input file is used to load widget definition into PLWIDGETDEF and PLWIDGETDEFDESC database tables. This file is also used to register the custom widget within the Commerce composer framework. The file should contain the following property definitions:

Property	Value
WidgetDefIdentifier	The external reference name for the widget definition. This value should be unique.
WidgetDisplayName	The name that displays within the Commerce Composer tool in Management Center to help business users identify the widget.
WidgetUIObjectName	The name that identifies the Management Center object and definition of the widget.
WidgetVendor	The name of the company or vendor that created the widget.
WidgetType	The type of the widget. The possible values for the property are: 1 - Widget 2 - Container Ensure that the specified value is 1.
WidgetPath	The relative path to the entry point top-level JSP file for the widget.
WidgetDefinitionxml	The XML definition for the dynamic properties of the widget.
WidgetState	The state of the widget registration. The possible values for the property are: ·         1-Active ·         2-Inactive Set the value as 1.
WidgetStoreUniqueID	The unique reference number of the store in which you are registering the widget. Possible values are: ·          0 – Site Level Widget ·         Store Identifier – Store Level Widget
WidgetDescription	The description that displays for the widget within the Commerce Composer tool in Management Center to help business users identify the widget
Delete	A flag that indicates whether to delete the widget definition. Possible values are 0 and 1. ·         Specify 1 to delete the widget. ·         The default value is 0, which indicates that the Data Load utility is to load the information for the row into the database.

• Open the subscribeWidgetdef.csv file for editing. The subscribeWidgetdef.csv input file loads data into the PLSTOREWIDGET database table. This input file is used to subscribe additional stores to the widget. This CSV input file can also be used to override the definition xml of the widget for a store. The file should contain the following property definitions:

Property	Value
WidgetDefIdentifier	The external reference name for the widget definition
WidgetDefinitionxml	The XML definition for the dynamic properties of the widget
WidgetState	The state of the widget registration. The possible values for the property are:           1 – Active           2 - Inactive
Delete	A flag that indicates whether to delete the widget definition. Possible values are 0 and 1. Specify 1 to delete the widget. The default value is 0, which indicates that the Data Load utility is to load the information for the row into the database.

• In the DataLoad directory within the new project directory, open the wc-dataload-env.xml file for editing. The wc-dataload-env.xml file is the data load environment configuration file that is generated to help to configure and run the Data Load utility. Update the file to match your database and environment settings.
• Stop the WCS Test server. Run the following command to load the input CSV files to register the  widget and to have a store subscribe to the widget:

Dataload.bat workspace_dir\NewWidgetProject\DataLoad\widget\wc-dataload-widget.xml

5. Extending resource bundle and properties files

• Copy the generated resource bundle and properties file into your default directory workspace structure. I.e. Copy the ‘Testcompany’ directory from workspace_dir\NewWidgetProject\LOBTools\src\com and paste it in the path workspace_dir\LOBTools\Java Resources\src directory. Refresh the LOBTools directory within default workspace. Ensure that com.mycompany.commerce.pagelayout.client.lobtools.properties package exists in the LOBTools\Java Resources\src directory.
• Expand the com.mycompany.commerce.pagelayout.client.lobtools.properties package in LOBTools\Java Resources\src directory. Open the PageLayoutLOB.properties and PageLayoutLOB_en_US.properties files for editing. Define any additional translatable text for the new widget by adding code into both these files.
• Copy the generated resource bundle extension into your default workspace directory structure and register the new widget specific properties files. I.e. copy the mycompany directory from NewWidgetProject\LOBTools\WebContent\WEB-INF\src\lzx and paste it in the location LOBTools\WebContent\WEB-INF\src\lzx directory.
• Update the default Commerce Composer resource bundle library to include the new resource bundle extension. Copy the generated code that includes the new widget resource bundle from NewWidgetProject\LOBTools\WebContent\WEB-INF\src\lzx\commerce\pagelayout\PageLayoutExtensionsLibrary.lzx and paste it in the file LOBTools\WebContent\WEB-INF\src\lzx\commerce\pagelayout\ PageLayoutExtensionsLibrary.lzx The generated code can resemble the following:

<library> <! -- Include the file to add any custom libraries. -->   <include href="../../mycompany/pagelayout/mycompanyPageLayoutResourceBundle.lzx"/> </library>

6. Define the object definition for widget

• The object definition adds support for the widget object within the Management Center framework.
•  Copy the generated object definition files for the custom widget into the default workspace directory structure. i.e. Copy the testcompany directory from NewWidgetProject\LOBTools\WebContent\config and paste it in the location LOBTools\WebContent\config
• Go to the directory LOBTools\WebContent\config\mycompany\pagelayout\widgetDefinitions\testWidget and open the file WidgetObjectDefinition.def for editing. By default, a sample code will be generated for the widget object definition.

<? Xml version="1.0" encoding="UTF-8"?> <! -- The following code is created as example. Modify the generated code and add any additional required code.  --> <Definitions>   <WidgetObjectDefinition package="plm"     definitionName="plmLayoutWidget_TestWidget"     parentDefinitionName="plmBasePageLayoutPrimaryObjectDefinition"     baseDefinitionName="plmBaseLayoutWidget"     objectType="TestWidget"     gridPropertiesDefinitionName="plmWidgetProperties_TestWidget"     iconPath="/images/pagelayouts/widgetIcons/Test.png">         <CreateService baseDefinitionName="plmBaseCreateLayoutWidget" />     <UpdateService baseDefinitionName="plmBaseUpdateLayoutWidget" />         <Xml name="template">       <sequence>0</sequence>     </Xml>                        </WidgetObjectDefinition>   </Definitions>

Where

Property	Values
iconPath	The file path to the icon that displays for the custom widget within the Add Widgets to Slots window in the Commerce Composer tool.
objectType	The widget object type and the name of the properties definition for the custom widget.
parentDefinitionName	The widget definition name for the parent widget definitions. The definition name must be included so that the object definition can be retrieved for use in Management Center for the custom widget.
plmLayoutWidget_HomePageDetailWidget	The definition name for the object definition of the custom widget, which must be unique in your workspace.

7. Define the properties view definition for widget

• The properties view definition file specifies how to render the Management Center properties view for a widget. It contains the configurable properties that business users can set when the widget is included in a page layout.
• Go to the location LOBTools\WebContent\config\mycompany\pagelayout\widgetDefinitions\TestWidget directory within the default workspace directory structure and open the WidgetPropertiesView.def file for editing.
• The default code generated for this file can resemble the following:

<? Xml version="1.0" encoding="UTF-8"?> <! -- The following code is created as example. Modify the generated code and add any additional required code. --> <Definitions> <GridObjectProperties definitionName="plmWidgetProperties_TestWidget">   <PropertyPane>     <PropertyGroup name="widgetProperties" collapsable="false" groupTitle="${plmPageLayoutResources.widgetPropertiesPrompt}">       <PropertyInputText name="${plmPageLayoutResources.widgetNamePrompt}" propertyName="widgetName"       promptText="${plmPageLayoutResources.widgetNamePrompt}" />     </PropertyGroup>     <PropertyGroup name="contentProperties" collapsable="false" groupTitle="${plmPageLayoutResources.widgetContentPrompt}">       <PropertyStaticText text="${mycompanyPageLayoutResources.TestWidgetContent}" />     </PropertyGroup>   </PropertyPane> </GridObjectProperties> </Definitions>

8. Test the new widget in management center

• Open Commerce Composer Tool in Management center.
• Select any layout from Layouts folder.
• In the ‘manage layout’ section assign a page to the layout selected.
• In the ‘Design layout’ section click on any of the slots of the wireframe.
• A popup with the title ‘Add widgets to slots’ appears. It contains the list of all widgets available in the store. Check if the newly created widget is available in the list.
• If yes, click on the widget and select OK.
• Click on save and launch preview to see the widget.

If you are developing widget for the first time and looking for simple steps to achieve this in WCS 8, refer my latest post http://myjavakitchentime.blogspot.com/2016/09/in-one-of-my-earlier-post-i.html .