Generate Commerce Composer widget source code

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

Procedure
Start WebSphere Commerce Developer.
Create a temporary project in the WebSphere 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.

Right-click within the Enterprise Explorer view. Select New > Project.
In the New Project wizard, expand General. Select Project. Click Next.
For the Project name field, enter a name for the temporary project. For example, NewWidgetProject.
Click Finish.
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 created is used by the JET Transformation to create the widget source code files 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.
Right-click the temporary NewWidgetProject project. Select New > File.
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.
Click Finish.
Right-click your new pattern input XML file within your temporary project. Select Open With > XML Editor.
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>
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 our 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, we can set the value for the target folder to be the temporary project createdd. 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 containing the pattern input XML file for the JET Transformation.
widgetDef (widget) No
If we are creating a widget, we must include this element.
If we 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 WebSphere 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. We 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 creating the object definition file that defines the widget for Management Center, we 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. We 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 our 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 our 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 our widget. Include a separate property element within the widgetdef element for each property to specify for our widget. when specifying a property, the JET tool adds the property to the definition XML for our 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 our custom widget. For example, numberOfContentToDisplay.
The name and corresponding value for the property is included within the generated widget definition XML file for our 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. We 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 we can set for our widget, review the properties available and used for the widgets provided by default. See Commerce Composer widget properties.
displayName (property) Yes (if the property element is included.) The display name of a property for our 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. We 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.
If we are using 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: 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. We can use any name, but the name must be unique for the store. By default, WebSphere 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, WebSphere Commerce includes the following widget display group display names:

Widgets for any page
Category Page Widgets
Search Results Page Widgets
Catalog Entry Page Widgets

We can include multiple properties for our 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 our widget within the pattern input file, we can use the JET Transformation to make creating the definition XML for our widget within the registerWidgetdef.csv file easier.
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>
Use the JET Transformation to generate the source code files for creating our custom widget.

Right-click your pattern input XML file. Select Run As > Run Configurations.
In the Run Configurations wizard, double-click JET Transformation from the list of filters. The configuration options for the JET Transformation display.
Ensure that the value of the Name field is the name of your pattern input XML file.
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
In the Transformation section, select com.ibm.commerce.toolkit.internal.pattern.pageLayout for the value of the ID field.
Optional: Specify the severity level for the Display Message logging. The default value is information.
Click Apply > Run. The JET Transformation generates the file directories and files for our custom widget at the location you specified in the targetFolder parameter in the pattern input XML file.
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 specified as the value for the targetFolder parameter in the pattern input XML file. If we 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 our 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
Next topic: Defining storefront assets for a Commerce Composer widget

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

Related tasks
Creating Commerce Composer widgets

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 our 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, we can set the value for the target folder to be the temporary project createdd. 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 containing the pattern input XML file for the JET Transformation.
widgetDef (widget)	No If we are creating a widget, we must include this element. If we 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 WebSphere 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. We 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 creating the object definition file that defines the widget for Management Center, we 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. We 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 our 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 our 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 our widget. Include a separate property element within the widgetdef element for each property to specify for our widget. when specifying a property, the JET tool adds the property to the definition XML for our 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 our custom widget. For example, numberOfContentToDisplay. The name and corresponding value for the property is included within the generated widget definition XML file for our 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. We 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 we can set for our widget, review the properties available and used for the widgets provided by default. See Commerce Composer widget properties.
displayName (property)	Yes (if the property element is included.)	The display name of a property for our 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. We 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. If we are using 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: 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. We can use any name, but the name must be unique for the store. By default, WebSphere 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, WebSphere Commerce includes the following widget display group display names: Widgets for any page Category Page Widgets Search Results Page Widgets Catalog Entry Page Widgets