Adding Management Center support for a Commerce Composer widget

Update the Management Center framework to support displaying your custom widget in the Commerce Composer tool. By adding support for your widget, Management Center users can access and use your custom widget in the Commerce Composer tool. Users can then specify properties for the widget, associate content with the widget, and use the widget in page layouts.

Create the object definition and properties view definition for your widget to add support for your widget in the Management Center framework.

Before you begin

Procedure

Copy the generated source code files for adding Management Center support into the default HCL Commerce Developer file structure.
1. Go to the project where the JET Transformation generated the source code files. Copy the following file structure and files that are within the target folder:
  - target_folder\LOBTools\WebContent\WEB-INF\src\xml\vendor\pagelayout\widgetDefinitions\UIObjectName\WidgetObjectDefinition.xml
  - target_folder\LOBTools\WebContent\WEB-INF\src\xml\vendor\pagelayout\widgetDefinitions\UIObjectName\WidgetPropertiesView.xml
  - target_folder\LOBTools\WebContent\WEB-INF\src\xml\vendor\pagelayout\widgetDefinitions\WidgetGroupIdentifier\WidgetGroup.xml
  - target_folder\LOBTools\src\com\vendor\commerce\pagelayout\client\lobtools\properties\PageLayoutLOB_en_US.properties
  - target_folder\LOBTools\src\com\vendor\commerce\pagelayout\client\lobtools\properties\PageLayoutLOB.properties
  Where
  
  vendor
  
  The value for the vendor 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.
2. Merge the copied file structure and files into the default HCL Commerce Developer workspace file structure. Do not overwrite any files or folders.
Update the object definition for your custom widget.
The object definition adds support for your custom widget object within the Management Center framework.
1. Go to the merged LOBTools\WebContent\config\vendor\pagelayout\widgetDefinitions\UIObjectName directory.
2. Open the generated WidgetObjectDefinition.xml file for editing. By default the generated file contains the following code to define the object definition for your widget.
```
<?xml version="1.0" encoding="UTF-8"?>



<Definitions>
  <WidgetObjectDefinition package="CMC/pagelayout"
1  
  definitionName="cmc/pagelayout/LayoutWidget_UIObjectName" 
2
  parentDefinition="cmc/pagelayout/BasePageLayoutPrimaryObjectDefinition"
  baseDefinition="cmc/pagelayout/BaseLayoutWidget"
3
  objectType="UIObjectName"
  gridPropertiesDefinition="plmWidgetProperties_UIObjectName"
4
    widgetDisplayGroups="Search"
5
  iconPath="/images/pagelayouts/widgetIcons/identifier.png"
6
    <CreateService baseDefinition="plmBaseCreateLayoutWidget" />
    <UpdateService baseDefinition="plmBaseUpdateLayoutWidget" />
    <Xml name="template">
      <sequence>0</sequence>
    </Xml>		
  </WidgetObjectDefinition>
</Definitions>
```
  Where
  
  UIObjectName
  
  The value for the UIObjectName parameter within the pattern input XML file.
  
  identifier
  
  The value for the identifier parameter within the pattern input XML file.
  - 1 The name of the definition for your custom widget object definition. By default the name is cmc/pagelayout/LayoutWidget_UIObjectName.
  - 2 The names for the parent and base object definitions. The definition names must be included for Management Center to be able to retrieve the object definition for your custom widget. The JET Transformation includes the default cmc/pagelayout/BasePageLayoutPrimaryObjectDefinition definition as the value for the parentDefinition field and includes the cmc/pagelayout/BaseLayoutWidget definition name as the default value for the baseDefinition field.
  - 3 The widget object type and name of the properties definition for your custom widget. By default the widget object type is the value that you set for the UIObjectName parameter in the pattern input XML file. By default, the gridPropertiesDefinition is cmc/pagelayout/LayoutWidget_UIObjectName.
  - 4 The widget display group or groups that the widget is included within.
  - 5 The file path to the icon that is to display for your custom widget within the Add Widgets to Slots window. By default, the JET Transformation defines the icon for the widget to be /images/pagelayouts/widgetIcons/identifier.png. No actual image file is created. You must change the value for the iconPath to point to an actual image file or rename an image file to be identifier.png.
  - 6 The create and update services that are needed for Management Center users to use your widget in the Commerce Composer tool.
3. Update the object definition file to change any of the default generated values or to define more properties.
  When you include a new property for your widget, you must prefix your widget property with the xWidgetProp_ prefix. For example, <xWidgetProp_titleText>. You must include this prefix so the property can be passed by using the userData web services.
  For example, you can update the generated file to include your widget in additional widget display groups with the following code:
```
widgetDisplayGroups=" "
```
  Where
  widgetDisplayGroups
  
  Display groups are used to organize widgets into groups that Management Center users can use to filter the list of widgets in the Add Widgets to Slots window. These groups are sets of widgets that are restricted to only the slots that include the group in the value for the allowedWidgetGroups slot property. By default, the following widget display groups are available:
  
  AnyPage
  
  CategoryPage
  
  CatalogEntryPage
  
  SearchPage
  
  You can include your widget in multiple groups. For more information about widget groups, see Widget groups.
  If you include your widget within a display group that is not available by default, you must define the object definition for the new group.
4. Set any default values for your widget properties within your object definition.
  You can set default properties in case a business user does not set values for the widget properties when they include the widget in a layout. To set a default layout for a property, you must set a value within the definition of the property. For example, the following code snippet defines default values for the widget orientation, page size, and sequence properties.
```
<Xml name="template">
<xWidgetProp_widgetOrientation>horizontal</xWidgetProp_widgetOrientation>
<xWidgetProp_pageSize>4</xWidgetProp_pageSize>
<sequence>0</sequence>
</Xml> 
```
5. Save the file.
  As an example, the following code is the object definition for the Heading widget. This definition includes properties to include the widget within two widget display groups and two widget restriction groups:
```
<?xml version="1.0" encoding="UTF-8"?>


<Definitions>

	<WidgetObjectDefinition package="CMC/pagelayout"
		definitionName="cmc/pagelayout/LayoutWidget_PageHeadingWidget" 
		baseDefinition="cmc/pagelayout/BaseLayoutWidget"
		parentDefinition="cmc/pagelayout/BasePageLayoutPrimaryObjectDefinition"
		objectType="PageHeadingWidget"
		gridPropertiesDefinition="cmc/pagelayout/{{WidgetProperties_PageHeadingWidget}}}}{{"
		iconPath="/images/pagelayouts/widgetIcons/header.png"
		widgetDisplayGroups="CategoryPage,CatalogEntryPage"
		helpLink="concepts/cpzwidheading.htm">

		<CreateService baseDefinition="cmc/pagelayout/BaseCreateLayoutWidget" />
		<UpdateService baseDefinition="cmc/pagelayout/BaseUpdateLayoutWidget" />	
		
		<Xml name="template">
			<sequence>0</sequence>
			<xWidgetProp_titleText></xWidgetProp_titleText>
		</Xml>		
	</WidgetObjectDefinition>

</Definitions>
```
  For an example of an object definition for a widget that supports web activities, see the Content Recommendation widget definition: LOBTools\WebContent\config\commerce\pagelayout\widgetDefinitions\ContentRecommendationWidget\WidgetObjectDefinition.xml
For more information about object definition files, see Object definitions.
Update the properties view definition for your custom widget.
This definition file specifies how to render the Management Center properties view for your widget. The properties view contains the configurable properties that business users can set for your widget. These properties are used to provide the required information for determining the widget UI provider, and the data that is used in the widget.
1. Go to the merged LOBTools\WebContent\config\vendor\pagelayout\widgetDefinitions\UIObjectName directory.
2. Open the generated WidgetPropertiesView.xml file for editing.
  By default, the generated file contains the following code to define the properties view for your widget.
```
<?xml version="1.0" encoding="UTF-8"?>

<Definitions>
1
  <GridObjectProperties definitionName="cmc/pagelayout/WidgetProperties_UIObjectName">
    <dependency localName="pageLayoutResources" moduleName="cmc/pagelayout/PageLayoutResources"/>
    <dependency localName="customPageLayoutResources" moduleName="cmc/pagelayout/CustomPageLayoutResources"/>
    <PropertyPane>
2
      <PropertyGroup name="widgetProperties" collapsable="false" 
             groupTitle="${PageLayoutResources.widgetPropertiesPrompt}">
        <PropertyInputText name="${PageLayoutResources.widgetNamePrompt}" propertyName="widgetName"
        promptText="${PageLayoutResources.widgetNamePrompt}" />
        <PropertyInputText propertyName="xWidgetProp_widgetOrientation" 
          promptText="${customPageLayoutResources.widgetOrientationPrompt}" />
        <PropertyInputText propertyName="xWidgetProp_numberOfContentToDisplay" 
          promptText="${customPageLayoutResources.numberOfContentToDisplayPrompt}" />
      </PropertyGroup>
3
      <PropertyGroup name="contentProperties" collapsable="false" 
            groupTitle="${PageLayoutResources.widgetContentPrompt}">
        <PropertyStaticText text="${customPageLayoutResources.UIObjectNameContent}" />
      </PropertyGroup>
    </PropertyPane>
  </GridObjectProperties>
</Definitions>
```
  - 1 The GridObjectProperties element defines the properties view for including your widget within the Layout slots and widgets table in the Design Layout tab within Management Center. This properties view is defined to be a collapsible view within the table. The view can be opened and closed by clicking the triangle icon on each row of the table.
  - 2 The widgetPropeties PropertyGroup defines the Widget Properties section within the properties view that is defined by the GridObjectProperties element. The properties in this section are used to determine how the widget displays in the store. Management Center users use these properties to determine the UI provider for the widget when users can determine the rendering style.
    For examples of configurable properties that you can set for your widget, review the configurable properties for the widgets that are provided by default with HCL Commerce. For more information, see Commerce Composer widget properties
    You can define these properties to display to users in Management Center in different ways. For instance, you can use radio buttons, check boxes, combination boxes, and more.
  - 3 contentProperties PropertyGroup defines Widget Content section in the GridObjectProperties view. Management Center users use these properties to determine the actual content of the widget to be displayed in the store page.
3. Optional: Change the default generated values for properties or include more definition properties.
4. Optional: Include code to validate the widget property values that a user sets.
5. Save the file.
  As an example, the following code is the properties view definition for the Heading widget:
```
<?xml version="1.0" encoding="UTF-8"?>

<Definitions>

	<GridObjectProperties definitionName="cmc/pagelayout/WidgetProperties_PageHeadingWidget">
             <dependency localName="pageLayoutResources" moduleName="cmc/pagelayout/PageLayoutResources"/>
		<PropertyPane>
			<PropertyGroup name="widgetProperties" collapsable="false" 
                                    groupTitle="${PageLayoutResources.widgetPropertiesPrompt}">
				<PropertyInputText name="${PageLayoutResources.widgetNamePrompt}" propertyName="widgetName"
					extendedHelpText="${PageLayoutResources.extendedHelpText_pageHeadingWidgetWidgetName}" 
					promptText="${PageLayoutResources.widgetNamePrompt}" />
			</PropertyGroup>
			
			<PropertyGroup name="widgetContent" collapsable="false" 
                                    groupTitle="${PageLayoutResources.widgetContentPrompt}">
				<PropertyStaticText text="${PageLayoutResources.pageHeadingWidgetContentHeading_SameName}"/>
			</PropertyGroup>
		</PropertyPane>
	</GridObjectProperties>

</Definitions>
```
  For an example of an object definition for a widget that uses marketing activities, see the Content Recommendation widget definition
  - LOBTools\WebContent\WEB-INF\src\xml\commerce\pagelayout\widgetDefinitions\ContentRecommendationWidget\WidgetPropertiesDefinition.xml
Optional: If you are including your widget within a display group that is not available by default, define the object definition for the new group. You must also update the properties file to include the text for your new widget display group or groups. You can update this file to include this information when you are completing the following step.
1. Go to the LOBTools\WebContent\config\vendor\pagelayout\widgetDefinitions directory.
2. Open the WidgetGroupIdentifierWidgetGroup.xml file for editing, where WidgetGroupIdentifier is the value for the identifier element within the widgetGroup element within the pattern input XML file.
  This file generates only when you include the widgetGroup element in the pattern input XML file. Your generated file can resemble the following code:
```
<?xml version="1.0" encoding="UTF-8"?>
<Definitions>
  <LayoutWidgetGroup package="CMC/pagelayout"
    definitionName="cmc/pagelayout/WidgetGroupIdentifierWidgetGroup"
    parentDefinition="cmc/pagelayout/NewPageLayoutWidgetDialog"
    identfider="WidgetGroupIdentifier" 
    displayName="${customPageLayoutResources.widgetGroupDisplayName_WidgetGroupIdentifier}">
  <dependency localName="customPageLayoutResources" moduleName="cmc/pagelayout/CustomPageLayoutResources"/>
  </LayoutWidgetGroup>
</Definitions>
```
  If you did not specify the widgetGroup element within the pattern input XML file, you must create this file.
3. Verify that the appropriate values for your new widget display group are correctly defined within the WidgetGroupIdentifierWidgetGroup.xml file.
4. If you want to include your widget in an additional new display group, make a copy of the WidgetGroupIdentifierWidgetGroup.xml within the widgetDefinitions directory. Rename the WidgetGroupIdentifier portion of the file name to be the value of the identifier for the display group that you are defining. Open the copied file for editing. Replace the values within the file with the values for the additional new widget display group. Repeat this step for each additional new widget display group that you must define.
Update the properties file to include the text for your widget. A properties file is a resource bundle that contains translatable text for objects that display in Management Center.
1. Go to the LOBTools\Java Resources\src\vendor.commerce.pagelayout.client.lobtools.properties directory.
2. Open the generated PageLayoutLOB.properties file for editing.
  By default the JET Transformation includes the following translatable text in the file:
```
# Widget properties view
UIObjectNameContent=description
namePrompt=displayName
widgetGroupDisplayName_WidgetGroupIdentifier=widgetGroupDisplayName
```
  Where
  
  UIObjectName
  
  The value for the UIObjectName parameter within the pattern input XML file.
  
  description
  
  The value that is specified for the description parameter in the pattern input XML file.
  
  name
  
  The name of a property for your custom widget. This name matches the name for the property that is generated in the properties view definition file. For example, numberOfContentToDisplay.
  
  displayName
  
  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.
  
  WidgetGroupIdentifier
  
  The value for the widget display group identifier element within the widgetGroup element within the pattern input XML file. The widgetGroupDisplayName_WidgetGroupIdentifier property and value generates only when you include the widgetGroup element in the pattern input XML file.
  
  widgetGroupDisplayName
  
  The value for the widget display group displayName element within the widgetGroup element within the pattern input XML file.
  
  For example,
```
# Widget properties view
myNewContentRecommendationWidgetObjectContent=This widget displays marketing content, such as ads, on a store page. 
widgetOrientationPrompt=Widget Orientation
numberOfContentToDisplayPrompt=Maximum Number of content to display
widgetGroupDisplayName_MyCompanyWidgets=My company widgets
```
3. Update the file to include any translatable text for your widget that is not included within the generated file.
  Ensure that you include text for any property that is defined for your widget. This text displays for your widget in the storefront and in the Widget Information dialog in store preview. To set the text for your widget properties, use the format
```
name=displayName
```
  Where name matches the property name that you defined within the properties view definition file. The value for the displayName is the text that displays in Management Center for the object. For example,
```
# Widget properties view
UIObjectNameContent=description
widgetOrientationPrompt=Widget Orientation
widgetOrientation_horizontal=Horizontal
widgetOrientation_vertical=Vertical
numberOfContentToDisplayPrompt=Maximum Number of content to display
```
  A Management Center user can select the Horizontal widget orientation and set the Maximum number of content to display to be 5. In store preview, if the Management Center user opens the Widget Information window for your widget, the window shows the following display names and values:
```
Widget orientation: Horizontal
Maximum number of content to display: 5 
```
4. Optional: Update the file to include the translatable text for any new widget display groups that is not included within the generated file.
  To set the text for your widget display group properties, use the format
```
widgetGroupDisplayName_identifier=displayName
```
  Where identifier matches the property name that you defined within the properties view definition file. The value for the displayName is the text that displays in Management Center for the object.
5. Save your file.
6. Optional: Repeat the preceding steps to edit the PageLayoutLOB_en_US.properties file to include any translatable text for the United States English language.
7. Optional: Create properties files to define the translatable text for your widget in the other languages that Management Center must support. Create the files within the LOBTools\Java Resources\src\com.vendor.commerce.pagelayout.client.lobtools.properties directory.
Create a resource bundle extension and register your properties files within the resource bundle.
Resource bundles contain locale-specific objects. By using resource bundle files, text can be easily translated into different languages.

For example, by adding a dependency in your widget definition file:


<dependency localName="customPageLayoutResources" moduleName="cmc/pagelayout/customPageLayoutResources"/>

Then, define a resource bundle XML file and map it the properties file:


<Definitions>
   <ResourceBundle baseName="com.yourcompany.commerce.pagelayout.client.lobtools.properties.CustomPageLayoutLOB" 
      definitionName="cmc/pagelayout/customPageLayoutResources" singletonDefinition="true"/>
</Definitions>

Test and preview your widget to ensure that your widget is available for use on store page layouts in Management Center.
1. Create a layout that includes your custom widget. Your custom widget should be available in the Add Widgets to Slots window.
  
  If you included the widget within widget display groups, ensure that your widget displays in the list of widgets for the appropriate display groups.
  
  If you included the widget within widget restriction groups, ensure that the widget can be included in a layout template that is restricted to use only widgets within that widget restriction group. For more information about making a layout template that is restricted to a widget restriction group, see Creating Commerce Composer layout templates.
2. Preview the page by using store preview. Verify that your widget displays correctly.

What to do next

Since all widgets and layout templates that are available by default in the Commerce Composer tool are responsive, you can update your new custom widget to also be responsive.

To deploy your widget from a development environment to a production environment, you must use the HCL Commerce Build and Deployment tool. For more information, see Deploying Commerce Composer assets.