Creating Commerce Composer widget restriction groups

Create a widget restriction group to control the widgets that can be included within a layout template slot by using the Commerce Composer tool. When business users select to add widget to a layout template slot, only the widgets that a slot is restricted to use are available within Add Widgets to Slots window.

About this task

Widget restriction groups are used to restrict the slots in layout templates to include only widgets from defined widget groups. When a business user selects a template slot that is restricted to include only widgets in a widget restriction group, only the widgets within that group are available for the user to select in the Add Widgets to Slots window. If a widget is included within a widget restriction group, users can still include the widget in slots that are not restricted to that widget restriction group. For example, in a category page layout template you might want to restrict a slot in the left sidebar to include only the Category Navigation and the Facet Navigation widgets.

By default you can include a widget within the following widget groups and restrict a template slot to include only widgets that belong to one of the following groups:

AnyPage: Set of widgets for use on any page.
CategoryPage: Set of widgets for use on category pages.
CatalogEntryPage: Set of widgets for use on catalog entry pages.
SearchPage: Set of widgets for use on a search results page.
WidgetForTabTitle: Set of widgets for use as a tab title in a layout template that includes tabbed slots. By default, the Text Editor widget is included in this group and is available for use as a tab title. By default, this group is the only widget group that any template slots include as specified widget restriction group.

The widget restriction groups that are allowed to be included within a slot are defined for the slot in the PROPERTIES column of the PLWIDGETSLOT database table. You can add a widget to a widget restriction group by updating the definition XML for the widget. For a widget to be included in a template slot that is restricted, the value of the widget restriction group property in the widget definition XML must match the value of the widget restriction group property for the template slot in the PLWIDGETSLOT table. Administrators can use the Data Load utility to update the definition XML to update the groups to which a widget belongs. Administrators can also use the Data Load utility to update the widget restriction groups for a template slot within the PLWIDGETSLOT table.

Note: If you need to copy a Commerce Composer widget restriction group from one instance to another instance, you can use the Data Extract and Data Load utilities. Use the Data Extract utility to extract the layout template data, which includes the widget restriction group data. Then, use the Data Load utility to load only the widget registration and template wireframe slot definition data by specifying the -DLoadOrder parameter when you run the utility. For more information, see Extracting Commerce Composer data with the Data Extract utility.

Procedure

Define the widget restriction group for the layout template slot.

Create a CSV file for updating the layout template slot definition for the slot that you want to restrict to include only the widgets within a group.
Your CSV file must include values for all mandatory columns, and include the existing values for any defined optional columns. If you do not include these values, the Data Load utility overwrites the existing values. Your CSV file must include the widget restriction group name within the column that loads into the PROPERTIES column of the PLWIDGETSLOT table. You must redefine the wireframe for the slot and append the widget restriction group to that wireframe definition. Use a comma-separated list within quotation marks to include both properties in a CSV file. Use the following format to define the value for this column:
```
"xLocation:00;yLocation:00;width:00;height:00;allowedWidgetGroups:WidgetGroupIdentifier"
```
Where WidgetGroupIdentifier is the value of the identifier that you want to name your new widget restriction group.
For example, the following CSV file updates a slot within the layout template DefaultSearchResultLayout to be restricted to include widgets that belong to the SearchPage widget restriction group.
```
LayoutName,AdminName,SlotAdminName,SlotID,SlotType,SlotProperty
DefaultSearchResultLayout,SearchResultPageContainer,8,8,1,"xLocation:40;yLocation:164;width:126;height:54;allowedWidgetGroups:SearchPage"
```
You can define multiple widget restriction groups for a slot and include more rows to define the widget restriction groups for other slots that you want to restrict.
For more information about completing this CSV file, see slotDefinition input file.
Configure the Data Load utility to load this CSV file into your WebSphere Commerce database with the Data Load utility.
To load this information, you must have the required data load configuration files. By default, sample configuration files are available for you to use to load layout template information.
Locate the sample wc-dataload-template.xml load order configuration file. Go to the following directory within a file manager utility:
- WC_installdir/components/foundation/samples/DataLoad/CommerceComposer/template
- WC_installdir\components\foundation\samples\DataLoad\CommerceComposer\template
- WCDE_installdir\components\foundation\samples\DataLoad\CommerceComposer\template
Copy this file. Update the copied sample load order configuration file to point to your CSV file instead of the default slotDefinition.csv file. Comment out the remaining CSV files so that only your CSV file loads when you run the Data Load utility. The load order configuration file identifies the order that the Data Load utility loads the sample CSV files. The load order file also identifies the appropriate business object configuration file to use to load each input file. For more information about load order configuration files, Configuring the data load order.
Locate the sample wc-dataload-env.xml environment configuration file. Go to the following directory within a file manager utility:
- WC_installdir/components/foundation/samples/DataLoad/CommerceComposer
- WC_installdir\components\foundation\samples\DataLoad\CommerceComposer
- WCDE_installdir\components\foundation\samples\DataLoad\CommerceComposer
Update the file to match the values for your environment. Ensure that the correct Business Context and Database values are specified. For more information, see Configuring the data load environment settings.
Locate the sample wc-loader-widgetslot.xml business object configuration file. Go to the following directory within a file manager utility:
- WC_installdir/components/foundation/samples/DataLoad/CommerceComposer
- WC_installdir\components\foundation\samples\DataLoad\CommerceComposer
- WCDE_installdir\components\foundation\samples\DataLoad\CommerceComposer
If you did not name the columns within your CSV file to be different from the column names that are identified within the slotDefinition input file topic, you do not need to change this file. If you did use different column names, you must copy this file and update the copy to configure the file to match your new column names. For more information about configuring this file, see Configuring the business object configuration file.
Run the Data Load utility to define the widget restriction group for the template slot.
1. Open a command-line utility and go to the appropriate directory:
  - WC_installdir/bin
  - WC_installdir\bin
  - WCDE_installdir\bin
2. Enter the following command to run the data load order file to load the updated template slot definition information:
  - ./dataload.sh ../components/foundation/samples/DataLoad/CommerceComposer/template/wc-dataload-template.xml
  - dataload.bat ..\components\foundation\samples\DataLoad\CommerceComposer\template\wc-dataload-template.xml
  - dataload ..\components\foundation\samples\DataLoad\CommerceComposer\template\wc-dataload-template.xml
3. Verify the results of the load process by reviewing the data load summary report. For more information about the location and contents of this summary report, see Verifying the results of the data load.
  You can also verify that the widget restriction group is defined as a property for the template slot by running the following SQL statements against your WebSphere Commerce database:
```
select * from PLWIDGETSLOT;
```
  Ensure that the data within your CSV input file exists within the PLWIDGETSLOT database tables.

Update the definition XML for any appropriate widgets to include the widgets within your new widget restriction group.

Create a CSV input file to update the definition XML of each widget that you want to include within the widget restriction group.
Your CSV file must identify the widget restriction groups for a widget as a property name-value pair within the definition XML that loads into DEFINITIONXML column of the PLWIDGETDEF database table.
Use the following format to define the definition XML and widget restriction group property for a widget:
```
<Definition> <widget-property name="widgetRestrictionGroups"><value>WidgetGroupIdentifier</value></widget-property> </Definition>
```
Where
name

The name of the property. In this instance, you must specify the name as "widgetRestrictionGroups".

value
The identifiers of all widget restriction groups that the widget belongs within. Use a comma-separated list to include more groups. For example, the following definition XML defines that a widget belongs to three widget restriction groups:
<Definition> <widget-property name="widgetRestrictionGroups"><value>SearchPage,CatalogEntryPage,AnyPage</value></widget-property> </Definition>
You can add more <widget-property> elements within this definition XML to add more properties for your widget. For more information, see Registering a Commerce Composer widget
The following CSV file updates the definition XML for the SearchSummaryWidget to be within the SearchPage and AnyPage widget restriction group. This CSV includes the column names and a single record, which is separated across three lines for readability. When load your CSV input file, do not separate a single record across multiple lines.
```
WidgetDefIdentifier,WidgetStoreUniqueID,WidgetUIObjectName,WidgetType,WidgetVendor,WidgetPath,WidgetState,WidgetDefinitionxml,WidgetDisplayName,WidgetDescription,Delete
SearchSummary,0,SearchSummaryWidget,1,ibm,/Widgets/com.ibm.commerce.store.widgets.SearchSummary/SearchSummary.jsp,1,
<Definition><widget-property name="widgetRestrictionGroups"><value>SearchPage,AnyPage</value></widget-property></Definition>,Search Summary Widget,	
'Displays the search term that the customer used, the number of search results, and offers suggested search terms when there are no matches.'  
```
You can include a widget within multiple restriction groups in your CSV file. Include more rows to include more widgets within widget restriction groups.
For more information about completing this CSV file, see registerWidgetdef input file.
Configure the Data Load utility to load this CSV file into your WebSphere Commerce database with the Data Load utility.
To load this information, you must have the required data load configuration files. By default, sample configuration files are available for you to use to load widget definition information.
Locate the sample wc-dataload-widget.xml load order configuration file. Go to the following directory within a file manager utility:
- WC_installdir/components/foundation/samples/DataLoad/CommerceComposer/widget
- WC_installdir\components\foundation\samples\DataLoad\CommerceComposer\widget
- WCDE_installdir\components\foundation\samples\DataLoad\CommerceComposer\widget
Copy this file. Update the copied sample load order configuration file to point to your CSV file instead of the default registerWidgetdef.csv file. Comment out the remaining CSV files so that only your CSV file loads when you run the Data Load utility.
The Data Load utility uses the same wc-dataload-env.xml environment configuration file that you used to load the template slot information to load the widget definition information.
Locate the sample wc-loader-registerWidgetdef.xml business object configuration file. Go to the following directory within a file manager utility:
- WC_installdir/components/foundation/samples/DataLoad/CommerceComposer
- WC_installdir\components\foundation\samples\DataLoad\CommerceComposer
- WCDE_installdir\components\foundation\samples\DataLoad\CommerceComposer
If you did not name the columns within your CSV file to be different from the column names that are identified within the registerWidgetdef input file topic, you do not need to change this file. If you did use different column names, you must copy this file and update the copy to configure the file to match your new column names.
Run the Data Load utility to define the widget restriction group for the widget.
1. Open a command-line utility and go to the appropriate directory:
  - WC_installdir/bin
  - WC_installdir\bin
  - WCDE_installdir\bin
2. Enter the following command to run the data load order file to load the updated widget definition information:
  - ./dataload.sh ../components/foundation/samples/DataLoad/CommerceComposer/widget/wc-dataload-widget.xml
  - dataload.bat ..\components\foundation\samples\DataLoad\CommerceComposer\widget\wc-dataload-widget.xml
  - dataload ..\components\foundation\samples\DataLoad\CommerceComposer\widget\wc-dataload-widget.xml
3. Verify the results of the load process by reviewing the data load summary report.
  You can also verify that the widget restriction group is defined as a property for the template slot by running the following SQL statements against your WebSphere Commerce database:
```
select * from PLWIDGETDEF;
select * from PLWDIGETDEFDESC;
```
  Ensure that the data within your CSV input file exists within the database tables.
Verify that the updated layout template slots are restricted in the Commerce Composer tool to include only the widgets that you included within your new widget restriction groups. To verify that the widget group is created and applied successfully, create a layout in the Commerce Composer tool. When you are creating this layout, select to use your updated layout template. When you select to populate the update template slot, ensure that only the widgets within your new widget group are available for you to include within the template slot.