(Developer)

Add Management Center support for a Commerce Composer widget

Update the Management Center framework to support displaying our custom widget in the Commerce Composer tool. By adding support for our widget, Management Center users can access and use our 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 our widget to add support for your widget in the Management Center framework.

Before beginning

• Register your Commerce Composer widget.

Procedure

1. Copy the generated source code files for adding Management Center support into the default WebSphere 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 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.

   2. Merge the copied file structure and files into the default WebSphere Commerce Developer workspace file structure. Do not overwrite any files or folders.

2. Update the object definition for our custom widget. The object definition adds support for our 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 our widget.

      <?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"
       1   
        definitionName="plmLayoutWidget_UIObjectName" 
       2 
        parentDefinitionName="plmBasePageLayoutPrimaryObjectDefinition"
        baseDefinitionName="plmBaseLayoutWidget"
       3 
        objectType="UIObjectName"
        gridPropertiesDefinitionName="plmWidgetProperties_UIObjectName"
       4 
          widgetDisplayGroups="Search"
       5 
        iconPath="/images/pagelayouts/widgetIcons/identifier.png"
       6 
          <CreateService baseDefinitionName="plmBaseCreateLayoutWidget" />
          <UpdateService baseDefinitionName="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 our custom widget object definition. By default the name is plmLayoutWidget_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 our custom widget. The JET Transformation includes the default plmBasePageLayoutPrimaryObjectDefinition definition as the value for the parentDefinitionName field and includes the plmBaseLayoutWidget definition name as the default value for the baseDefinitionName field.

      • 3 The widget object type and name of the properties definition for our 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 gridPropertiesDefinitionName is plmLayoutWidget_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 our 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. We 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 our widget, we must prefix your widget property with the xWidgetProp_ prefix. For example, <xWidgetProp_titleText>. We must include this prefix so the property can be passed using the userData web services.For example, we 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

      We 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, define the object definition for the new group.

   4. Set any default values for our widget properties within your object definition. We 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, we 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"?>
      
      <!--
       =================================================================
        Licensed Materials - Property of IBM 
        WebSphere Commerce
      
        (C) Copyright IBM Corp. 2013 All Rights Reserved.
      
        US Government Users Restricted Rights - Use, duplication or
        disclosure restricted by GSA ADP Schedule Contract with   IBM Corp.
       =================================================================
      -->
      <Definitions>
      
      	<WidgetObjectDefinition package="plm"
      		definitionName="plmLayoutWidget_PageHeadingWidget" 
      		baseDefinitionName="plmBaseLayoutWidget"
      		parentDefinitionName="plmBasePageLayoutPrimaryObjectDefinition"
      		objectType="PageHeadingWidget"
      		gridPropertiesDefinitionName="plmWidgetProperties_PageHeadingWidget"
      		iconPath="/images/pagelayouts/widgetIcons/header.png"
      		widgetDisplayGroups="CategoryPage,CatalogEntryPage"
      		helpLink="concepts/cpzwidheading.htm">
      
      		<CreateService baseDefinitionName="plmBaseCreateLayoutWidget" />
      		<UpdateService baseDefinitionName="plmBaseUpdateLayoutWidget" />	
      		
      		<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.

3. Update the properties view definition for our custom widget. This definition file specifies how to render the Management Center properties view for our 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 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="plmWidgetProperties_UIObjectName">
          <PropertyPane>
       2 
            <PropertyGroup name="widgetProperties" collapsable="false" 
                   groupTitle="${plmPageLayoutResources.widgetPropertiesPrompt}">
              <PropertyInputText name="${plmPageLayoutResources.widgetNamePrompt}" propertyName="widgetName"
              promptText="${plmPageLayoutResources.widgetNamePrompt}" />
              <PropertyInputText propertyName="xWidgetProp_widgetOrientation" 
                promptText="${mycompanyPageLayoutResources.widgetOrientationPrompt}" />
              <PropertyInputText propertyName="xWidgetProp_numberOfContentToDisplay" 
                promptText="${mycompanyPageLayoutResources.numberOfContentToDisplayPrompt}" />
            </PropertyGroup>
       3 
            <PropertyGroup name="contentProperties" collapsable="false" 
                  groupTitle="${plmPageLayoutResources.widgetContentPrompt}">
              <PropertyStaticText text="${mycompanyPageLayoutResources.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 we can set for our widget, review the configurable properties for the widgets provided by default with WebSphere Commerce. See Commerce Composer widget properties

        We can define these properties to display to users in Management Center in different ways. For instance, we 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"?>
      
      <!--
       =================================================================
        Licensed Materials - Property of IBM 
        WebSphere Commerce
      
        (C) Copyright IBM Corp. 2013 All Rights Reserved.
      
        US Government Users Restricted Rights - Use, duplication or
        disclosure restricted by GSA ADP Schedule Contract with   IBM Corp.
       =================================================================
      -->
      <Definitions>
      
      	<GridObjectProperties definitionName="plmWidgetProperties_PageHeadingWidget">
      		<PropertyPane>
      			<PropertyGroup name="widgetProperties" collapsable="false" 
                                          groupTitle="${plmPageLayoutResources.widgetPropertiesPrompt}">
      				<PropertyInputText name="${plmPageLayoutResources.widgetNamePrompt}" propertyName="widgetName"
      					extendedHelpText="${plmPageLayoutResources.extendedHelpText_pageHeadingWidgetWidgetName}" 
      					promptText="${plmPageLayoutResources.widgetNamePrompt}" />
      			</PropertyGroup>
      			
      			<PropertyGroup name="widgetContent" collapsable="false" 
                                          groupTitle="${plmPageLayoutResources.widgetContentPrompt}">
      				<PropertyStaticText text="${plmPageLayoutResources.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

4. Optional: If we are including your widget within a display group that is not available by default, define the object definition for the new group. We must also update the properties file to include the text for our new widget display group or groups. We can update this file to include this information when we 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="plm"
          definitionName="WidgetGroupIdentifierWidgetGroup"
          parentDefinitionName="plmNewPageLayoutWidgetDialog"
          identfider="WidgetGroupIdentifier" 
          displayName="${vendorPageLayoutResources.widgetGroupDisplayName_WidgetGroupIdentifier}">
        </LayoutWidgetGroup>
      </Definitions>

      If you did not specify the widgetGroup element within the pattern input XML file, we must create this file.

   3. Verify that the appropriate values for our new widget display group are correctly defined within the WidgetGroupIdentifierWidgetGroup.xml file.

   4. 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 we 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 define.

5. Update the properties file to include the text for our 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 specified for the description parameter in the pattern input XML file.

      name

      The name of a property for our 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 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.

      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 our widget that is not included within the generated file. Ensure that you include text for any property that is defined for our widget. This text displays for our widget in the storefront and in the Widget Information dialog in store preview. To set the text for our widget properties, use the format

      name=displayName

      Where name matches the property name that we 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 our 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 our widget display group properties, use the format

      widgetGroupDisplayName_identifier=displayName

      Where identifier matches the property name that we 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 our 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.

6. 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.

7. Register the Commerce Composer resource bundle wherever it is used. 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>

8. 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 our 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 available by default in the Commerce Composer tool are responsive, we can update your new custom widget to also be responsive.

To deploy your widget from a development environment to a production environment, we must use the WebSphere Commerce Build and Deployment tool. See Deploying Commerce Composer assets.

Previous topic: Registering a Commerce Composer widget
Next topic: Updating a widget to create a responsive widget

Previous topic: Registering a Commerce Composer widget
Next topic: Updating a widget to create a responsive widget

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

Related tasks
Creating Commerce Composer widgets
Copying WebSphere Commerce site-level widgets