HCL Commerce Developer

Generating Commerce Composer widget source code

Use the Java Emitter Template (JET) PageComposer Resource pattern to generate source code files that you can use as a starting point for creating a custom Commerce Composer widget. To use this pattern, you must create a pattern input file that contains the information that is required to generate the source code files.

Procedure

  1. Start HCL Commerce Developer.
  2. Create a temporary project in your HCL Commerce Developer workspace. This project is used as the target location where the Java Emitter Template (JET) Transformation generates the source code files for creating your widget.
    1. Right-click within the Enterprise Explorer view. Select New > Project.
    2. In the New Project wizard, expand General. Select Project. Click Next.
    3. For the Project name field, enter a name for the temporary project.
      For example, NewWidgetProject.
    4. Click Finish.
  3. In your temporary NewWidgetProject project, create an XML file to use as a pattern input file for the JET Transformation. The pattern input XML file that you create is used by the JET Transformation to create the widget source code files by using the properties and attributes that you specify within the file. The JET Transformation creates all of the files and code that is required to create a widget. The input file can be copied and edited for future use to help you generate the source code for creating other custom widgets.
    1. Right-click the temporary NewWidgetProject project. Select New > File.
    2. In the New File wizard, ensure that your temporary project is selected as the parent folder. Enter a File name for the pattern input XML file.
      For example, NewWidgetPatternInputFile.xml.
    3. Click Finish.
    4. Right-click your new pattern input XML file within your temporary project. Select Open With > XML Editor.
    5. Copy the following code into the file: 
      <pageLayout vendor="" targetFolder="">
  <widget>
    <widgetDef 
     identifier="" UIObjectName="" 
     displayName="" description="" 
     widgetDisplayGroups=""> 
     widgetRestrictionGroups="" >
      <property name=""	displayName=""/>
      <property name=""	displayName=""/>
    </widgetDef>
    <widgetGroup identifier="" displayName="" />
  </widget>
</pageLayout>
    6. Update the copied code to specify the information that the JET Transformation is to use to create your widget source code. Ensure that you include any required information.
      Note: Do not include spaces or special characters in the values for the following parameters. Including spaces or special characters for these parameters can cause errors:
      • vendor (pageLayout)
      • targetFolder (pageLayout)
      • identifier (all instances)
      • UIObjectName (widgetDef)
      • name (property)
      Widget information that can be included with the pattern input XML file:
      Input file parameter Required Description
      vendor (pageLayout) Yes The name of your company. For example, myCompany.

      The value for this attribute is included as the value for the WidgetVendor column within the generated registerWidgetdef.csv file. The registerWidgetdef.csv is used to register your custom widget with the Commerce Composer framework.
      targetFolder (pageLayout) No The folder or project path where the source code files are to be generated. The path to the target folder is relative to your workspace directory". For example, you can set the value for the target folder to be the temporary project that you created. If your project is a top-level directory within your workspace, specify the name of your project, such as NewWidgetProject, as the target folder.

      If the value for the attribute is not specified, the files are generated within the same folder or project that contains the pattern input XML file for the JET Transformation.
      widgetDef (widget) No

      If you are creating a widget, you must include this element.

      If you are using this pattern XML and the JET Transformation to create only the files for defining a widget display group do not include this element. For more information about defining widget groups, see Creating Commerce Composer widget groups.

      		 Element that includes attributes to define the widget definition. This definition must be loaded into the HCL Commerce database with the Data Load utility to register your widget. This information is also used to help define the corresponding widget object in the Commerce Composer tool.
      identifier (widgetDef) Yes The external reference name for the widget or container definition. You can use any name, but the name must be unique for the store. For example, myNewContentRecommendationWidget.

      The value for this attribute is included as the value for the WidgetDefIdentifier column within the generated registerWidgetdef.csv file.
      UIObjectName (widgetDef) Yes The name that identifies the Management Center object and object definition of this widget. For example, myNewContentRecommendationWidgetObject.

      When you create the object definition file that defines the widget for Management Center, you must specify this name for the ui_object_name attribute in the XML code. The value for this attribute is included as the value for the WidgetUIObjectName column within the generated registerWidgetdef.csv file.
      displayName (widgetDef) Yes The language-specific display name of the widget. For example, My New Content Recommendation Widget.

      This name displays in the Commerce Composer tool to help business users identify the widget. The value for this attribute is included as the value for the WidgetDisplayName column within the generated registerWidgetdef.csv file.
      description (widgetDef) Yes The language-specific description for the widget. For example, This widget displays marketing content, such as ads, on a store page. You can specify an empty string as the value.

      The value for this attribute is included as the value for the WidgetDescription column within the generated registerWidgetdef.csv file.
      widgetDisplayGroups (widgetDef) No Used to organize widgets in the Commerce Composer tool to help Management Center users filter the list of widgets in the Add Widgets to Slots window. When this is specified, an entry to define these groups is added to the generated object definition for your widget. For more information about defining widget display groups for widget, see Widget groups.
      widgetRestrictionGroups (widgetDef) No Used to restrict the slots in layout templates to include only widgets from defined widget groups. When this is specified, an entry identifying these groups is added to the definition XML for your widget within the registerWidgetDef.csv file. For more information about defining widget restriction groups for a widget, see Widget groups.
      property (widgetDef) No Include this element to generate property information for your widget. Include a separate property element within the widgetdef element for each property that you want to specify for your widget. When you specify a property, the JET tool adds the property to the definition XML for your widget that is within the registerWidgetDef.csv file. An entry is also added to the generated Management Center definition files to help you define the property.
      name (property) Yes (if the property element is included.) The name of a property for your custom widget. For example, numberOfContentToDisplay.

      The name and corresponding value for the property is included within the generated widget definition XML file for your custom widget.

      If you specify a property name in the pattern input file, a property input type is generated for the property in the properties view definition file. The generated input type for the property is PropertyInputText by default. You can modify the properties view definition file to change the default input type to meet your widget requirements.

      If no properties are specified, the generated widget source code creates a widget that displays the message 'Hello, world!' when the widget is included on a store page.

      As an example of the properties that you can set for your widget, review the properties that are available and used for the widgets that are provided by default. For more information, see Commerce Composer widget properties.
      displayName (property) Yes (if the property element is included.) The display name of a property for your custom widget. The display name is the name of the property that displays in Management Center. For example, Maximum number of content to display.
      inputType (property) No The input type for the property in Management Center. The generated input type for the property is PropertyInputText by default. You can modify the properties view definition file to change the default input type to meet your widget requirements.
      widgetGroup (widget) No
      If your widget is included within a widget display group that is not provided by default, include this widgetGroup element. By including this element, the JET Transformation generates the source code to help you define your new widget display group.
      Note: If you are including your widget within a new widget restriction group, do not include and information for the group within this element.
      		 Grouping widgets can be used to determine which widgets show in the Add Widgets to Slots window in the Commerce Composer tool.
      Note: If you want to include your widget in multiple new widget display groups, include the information for only one display group in this element. The JET Transformation creates the source code to define only one widget display group. To include your widget in more widget display groups, update the generated source code.
      identifier (widgetGroup) Yes (if the widgetGroup element is included.) The external reference name for the widget display group. You can use any name, but the name must be unique for the store. By default, HCL Commerce includes the following widget display group identifiers:
      • AnyPage
      • CategoryPage
      • SearchPage
      • CatalogEntryPage
      displayName (widgetGroup) Yes (if the widgetGroup element is included.) The language-specific display name of the widget display group. By default, HCL Commerce includes the following widget display group display names:
      • Widgets for any page
      • Category Page Widgets
      • Search Results Page Widgets
      • Catalog Entry Page Widgets

      You can include multiple properties for your custom widget in the input file. Each of the properties that you specify are included within the generated widget definition XML file. This definition XML is included as the value for the WidgetDefinitionxml column in the registerWidgetdef.csv file. If you specify all of the properties for your widget within the pattern input file, you can use the JET Transformation to make creating the definition XML for your widget within the registerWidgetdef.csv file easier.

    7. Save and close the file.
      The following code provides an example of an updated pattern input XML file:
      <pageLayout vendor="myCompany" targetFolder="NewWidgetProject">
  <widget>
    <widgetDef identifier="myNewContentRecommendationWidget"  
     UIObjectName="myNewContentRecommendationWidgetObject" 
     displayName="My New Content Recommendation Widget" 
     description="This widget displays marketing content, such as ads, on a store page"
     widgetDisplayGroups="AnyPage,SearchPage" 
     widgetRestrictionGroups="AnyPage,SearchPage" >
      <property name="widgetOrientation"	
       displayName="Widget Orientation"/>
      <property name="numberOfContentToDisplay"	
       displayName="Maximum number of content to display"/>
    </widgetDef>
    </widget>
</pageLayout>
  4. Use the JET Transformation to generate the source code files for creating your custom widget.
    1. Right-click your pattern input XML file. Select Run As > Run Configurations.
    2. In the Run Configurations wizard, double-click JET Transformation from the list of filters. The configuration options for the JET Transformation display.
    3. Ensure that the value of the Name field is the name of your pattern input XML file.
    4. In the Main tab, ensure that the value of the Transformation Input field is the file path within your workspace to the pattern input XML file.
      For example, NewWidgetProject\NewWidgetPatternInputFile.xml
    5. In the Transformation section, select com.ibm.commerce.toolkit.internal.pattern.pageLayout for the value of the ID field.
      Note: The com.ibm.commerce.toolkit.internal.pattern.pageLayout_9.0.0.0.zip and com.ibm.commerce.toolkit.internal.pattern.rest_9.0.0.0.zip are located in the ${WCDE_install}/setup/plugins folder. Unzip these files and manually move their jar files to the ${RAD_install}/plugins folder to make ID available.
      This is a workaround for earlier versions of HCL Commerce 9.
      1. From the version 8 toolkit, copy {WCDE_V8Install}/setup/plugins/com.ibm.commerce.toolkit.internal.pattern.pageLayout.zip to the version 9 toolkit {WCDE_V9Install}/setup/plugins folder.
      2. Run the setupPlugins.bat script from the {WCDE_V9Install}/bin folder.

      For more information, see http://www-01.ibm.com/support/docview.wss?uid=swg1JR59956.

    6. Optional: Specify the severity level for the Display Message logging. The default value is information.
    7. Click Apply > Run.
      The JET Transformation generates the file directories and files for your custom widget at the location you specified in the targetFolder parameter in the pattern input XML file.
    8. Verify that the JET Transformation created the following directories and files.
      Where
      vendor
      The value for the vendor parameter within the pattern input XML file.
      identifier
      The value for the identifier parameter within the pattern input XML file.
      UIObjectName
      The value for the UIObjectName parameter within the pattern input XML file.
      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.
      WidgetGroupIdentifier
      The value for the identifier element within the widgetGroup element within the pattern input XML file.
      If the JET Transformation did not create the files, ensure that you included all of the mandatory properties within your pattern input file and that your pattern file is structured correctly. Then, run the JET Transformation again.
      Storefront asset files for defining your widget
      identifier.jsp
      File location - target_folder\Stores\WebContent\Widgets-vendor\com.vendor.commerce.store.widgets.identifier\identifier.jsp
      identifier_Data.jspf
      File location - target_folder\Stores\WebContent\Widgets-vendor\com.vendor.commerce.store.widgets.identifier\identifier_Data.jspf
      identifier_UI.jspf
      File location - target_folder\Stores\WebContent\Widgets-vendor\com.vendor.commerce.store.widgets.identifier\identifier_UI.jspf
      MyWidgetText_en_US.properties
      File location - target_folder\Stores\WebContent\Widgets-vendor\Properties\MyWidgetText_en_US.properties
      MyWidgetText.properties
      File location - target_folder\Stores\WebContent\Widgets-vendor\Properties\MyWidgetText.properties
      Additional file directories for containing storefront assets:
      • target_folder\Stores\WebContent\Widgets-vendor\com.vendor.commerce.store.widgets.identifier\javascript
      • target_folder\Stores\WebContent\Widgets-vendor\Common
      • target_folder\Stores\WebContent\Widgets-vendor\images
      Data Load utility files for registering and subscribing stores to your widget
      registerWidgetdef.csv
      File location - target_folder\DataLoad\widget\registerWidgetdef.csv
      subscribeWidgetDef.csv
      File location - target_folder\DataLoad\widget\subscribeWidgetDef.csv
      wc-dataload-widget.xml
      File location - target_folder\DataLoad\widget\wc-dataload-widget.xml
      wc-dataload-env.xml
      File location - target_folder\DataLoad\wc-dataload-env.xml
      wc-loader-registerWidgetdef.xml
      File location - target_folder\DataLoad\wc-loader-registerWidgetdef.xml
      wc-loader-subscribeWidgetdef.xml
      File location - target_folder\DataLoad\wc-loader-subscribeWidgetdef.xml
      Files for adding Management Center support for your widget
      PageLayoutLOB_en_US.properties
      File location - target_folder\LOBTools\src\com\vendor\commerce\pagelayout\client\lobtools\properties\PageLayoutLOB_en_US.properties
      PageLayoutLOB.properties
      File location - target_folder\LOBTools\src\com\vendor\commerce\pagelayout\client\lobtools\properties\PageLayoutLOB.properties
      WidgetObjectDefinition.xml
      File location - target_folder\LOBTools\WebContent\config\vendor\pagelayout\widgetDefinitions\UIObjectName\WidgetObjectDefinition.xml
      WidgetPropertiesView.xml
      File location - target_folder\LOBTools\WebContent\config\vendor\pagelayout\widgetDefinitions\UIObjectName\WidgetPropertiesView.xml