Registering a Commerce Composer layout template

Use the Data Load utility to register our custom layout template within the Commerce Composer framework and have the store subscribe to the layout template. A store must subscribe to the template before users can select the template to begin composing a page layout for that store.

Task info

Before we can use a layout template within the Commerce Composer tool, we must register the template with the Commerce Composer framework. The framework maintains a single registry, which includes all of the registered templates and widgets that can be used on a page for a store. When you run the Data Load utility to register a layout template and subscribe a store to that layout template, the utility loads the following information.

• Since the container for a layout template is an empty widget, the Data Load utility loads the information to register your template into the PLWIDGETDEF and
  PLWIDGETDEFDESC database tables.

• Information to subscribe a store to the template into the PLSTOREWIDGET database table.

• Information to define the wireframe that displays in the Commerce Composer tool for the template and any slot restrictions into the PLWIDGETSLOT database table.

  Note: The wireframe displays only within the Commerce Composer tool as a visual representation of how a layout template displays when all of template slots are populated. This wireframe is not connected to the actual arrangement of the widgets on a store page. Depending on how a business user constructs a layout, the actual display of the layout can differ significantly from the visual representation of the template that a wireframe provides. The wireframe is used only within the Commerce Composer tool to help business users select the appropriate template to construct a layout and to select slots for including widgets within a layout.

• Information to define the template into the PAGELAYOUT database table.

Procedure

1. Create the CSV files and Data Load utility configuration files for loading your layout template information. To help us create these files, WebSphere Commerce provides sample files for loading layout template information. Use these sample files to model your CSV and configuration files.

   1. Create a directory to include the CSV files and Data Load utility configuration files for loading layout template information. We can create this directory anywhere within your file system, however for the following steps a template-MyCompany directory is created within the WCDE_installdir\samples\DataLoad\CommerceComposer directory.

   2. Go to the WCDE_installdir\samples\DataLoad\CommerceComposer\template directory. This directory includes the sample CSV files and load order configuration file for loading template information.

   3. Copy the following files:

      • registerWidgetdef.csv

      • slotDefinition.csv

      • subscribeWidgetdef.csv

      • template.csv

      • wc-dataload-template.xml

   4. Add the copied files into your directory for layout template Data Load utility files.

   5. Optional: Copy the business object configuration files for loading layout template information from the WCDE_installdir\samples\DataLoad\CommerceComposer directory. This directory includes the remaining sample configuration files for loading template information. If we are not customizing these files, we can use the files in the CommerceComposer directory and do not need to copy the files. If you do want to update these files, copy the following files into your new directory.

      • wc-dataload-env.xml

      • wc-loader-registerWidgetdef.xml

      • wc-loader-subscribeWidgetdef.xml

      • wc-loader-template.xml

      • wc-loader-widgetslot.xml

Update the CSV input files to include your layout template information

2. Prepare the data load input file containing the identifier, descriptive, and definition information for registering your layout template container.

   1. Open the registerWidgetDef.csv file for editing. By default, this file includes the required columns for registering a template and data for loading sample template containers.

   2. Delete the sample data within this file. Do not remove any of the columns. Add the data for our custom layout template container into the file. Within your CSV file, we must set the following column values

      • Set a value that for the WidgetDefIdentifier that is unique within the list of all layout template containers and Commerce Composer widgets.

      • Set the value of the WidgetVendor column to be your company name.

      • Set the WidgetType value to be 2. This column identifies the type of widget that we are registering. A widget can be either a Commerce Composer widget (value of 1), or a layout template container (value of 2).

      • Set the value for the WidgetPath to be the relative path to the container JSP file for our layout template. This path is relative from the workspace_dir\Stores\WebContent directory. Use forward slashes in the file path.

      • Set the value for the WidgetDefinitionxml to be an empty element.

      • Set the value for the WidgetState column to 1 to indicate that the container registration is active.

      For example, your complete registerWidgetDef.csv CSV can resemble the following code:

      WidgetDefIdentifier,WidgetVendor,WidgetType,WidgetPath,WidgetDefinitionxml,WidgetState,Delete
      MyCustomLayoutTemplateContainer,MyCompany,2,Container-vendor/MyCustomLayoutTemplate.jsp,<Definition></Definition>,1,

      For more information about the information to include within this file, see registerWidgetdef input file.

   3. Save and close the file.

3. Prepare the data load input file for subscribing a store to your layout template container.

   1. Open the subscribeWidgetdef.csv file for editing. By default, this file includes the required columns for subscribing a store to a template and includes sample data.

   2. Delete the sample data within this file. Do not remove any of the columns. Add the data for our custom layout template container into the file. Within your CSV file, we must set the following column values

      • Set the value for the WidgetDefIdentifier to be the same value that you set within the registerWidgetDef.csv file.

      • Do not set a value for the WidgetDefinitionxml column.

      • Set the value for the WidgetState column to 1 to indicate that the store subscription is active.

      • You do not need to set the ID value for the store within this file. By default, the Data Load utility subscribes the store that is configured within the Data Load utility environment configuration file to the layout template. We can set a different store to subscribe to the template by updating the environment configuration file.

      For example, your complete subscribeWidgetdef.csv CSV can resemble the following code:

      WidgetDefIdentifier,WidgetDefinitionxml,WidgetState,Delete
      MyCustomLayoutTemplateContainer,,1

      For more information about the information to include within this file, see subscribeWidgetdef input file.

   3. Save and close the file.

4. Prepare the data load input file that defines the template information. This information includes the layout template name and description, both of which displays for the template in the Commerce Composer tool.

   1. Open the template.csv file for editing. By default, this file includes the required columns for defining the template and includes sample data.

   2. Delete the sample data within this file. Do not remove any of the columns. Add the data for our custom layout template into the file. Within your CSV file, we must set the following column values

      • Set the value of the LayoutName column to be the reference name for the template that we are defining the wireframe for. This value displays in Management Center to identify the template. The value for this column must match the value that you set within the slotDefinition.csv file.

      • Set the value for the Description column to be the string of text that we want to display for the layout template within the Commerce Composer tool. This description displays within the New Layout Template Selection window for our custom layout template.

      • Set the value for the DeviceClass column to identify the type or types of device classes that users can design a page layout for when they use our custom layout template. We can define a layout template to be used for creating layouts for Web, Mobile, or Any devices.

      • Set the value of the State column to be 1 to activate your layout template for use in composing a page layout.

      • Set the IsTemplate value to be TRUE. This value indicates that your are loading a layout template.

      • Set the IsDefault value to be FALSE. This column value indicates whether we are loading a default layout.

      • Set the value of the ParentWidgetDefIdentifier and AdminName columns to be the administrative name for the container in this template. Set this name to be the same as the WidgetDefIdentifier that you set in the registerWidgetDef.csv file.

      For example, your complete template.csv CSV can resemble the following code:

      LayoutName,Description,DeviceClass,State,IsTemplate,IsDefault,ParentWidgetDefIdentifier,AdminName,Delete
      "Any page, seven slots, tabs","Seven-slot template with a row of four tabs. Can be used for any page.",Any,1,TRUE,FALSE,MyCustomLayoutTemplateContainer,MyCustomLayoutTemplateContainer,

      For more information about the information to include within this file, see template input file.

   3. Save and close the file.

5. Prepare the data load input file for loading the slot definition information

   1. Open the slotDefinition.csv file for editing. By default, this file includes the required columns for defining the overall template wireframe that displays for the template within the Commerce Composer tool. This file also loads any slot restrictions for the template. The sample CSV file also includes data for defining the slots for a sample template.

   2. Delete the sample data within this file. Do not remove any of the columns. Add the data for our custom layout template container into the file. Within your CSV file, we must set the following column values

      • Set the value of the LayoutName column to be the reference name for the template that we are defining the wireframe for. This value displays in Management Center to identify the template. The value for this column must match the value that you set within the template.csv file.

      • Set the value of the AdminName column to be the administrative name for the container in this template. Set this name to be the same as the WidgetDefIdentifier that you set in the registerWidgetDef.csv file.

      • Set the value of the SlotAdminName to be the display name for the slot. The value for this column displays in the Commerce Composer tool within the wireframe to identify the slot.

      • Set the value of the SlotID column to be the value of the internal slot name.

      • Set the SlotType column to be 1. This column is reserved for IBM internal use. The value must be set to 1

      • Within the value for the SlotProperty column, define the coordinates for the layout template wireframe and identify and restriction groups for the template. Use the following format:

        "xLocation:00;yLocation:00;width:00;height:00,allowedWidgetGroups:WidgetGroupIdentifier"

        For instance to include a restriction group to restrict a slot to use only the widgets that are intended for use as a tabbed slot title, use allowedWidgetGroups:WidgetForTabTitle. For more information about widget restriction groups, see Creating Commerce Composer widget restriction groups.To define your wireframe, the maximum width is 166 and the maximum height is 218. Divide your wireframe to include the layout template slots. For tabbed slots append dottedRightBorder:true to the coordinates system to add a dotted line to the column. This dotted line identifies the column as a tabbed slot.Tip: Consider using an image editor that displays coordinates to help you set the coordinates for our template wireframe. In the image editor, draw your as we want it to display in the Commerce Composer tool. Use the coordinates for this image as the coordinates of the wireframe in your CSV input file.

      The following code defines the slotDefinition.csv CSV file for loading the Any page, seven slots, tabs layout template:

      LayoutName,AdminName,SlotAdminName,SlotID,SlotType,SlotProperty
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,1,1,1,xLocation:0;yLocation:0;width:83;height:20
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,2,2,1,xLocation:83;yLocation:0;width:83;height:20
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Title 3",Title3,1,xLocation:0;yLocation:20;width:40;height:20;allowedWidgetGroups:WidgetForTabTitle
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Title 4",Title4,1,xLocation:40;yLocation:20;width:43;height:20;allowedWidgetGroups:WidgetForTabTitle
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Title 5",Title5,1,xLocation:83;yLocation:20;width:43;height:20;allowedWidgetGroups:WidgetForTabTitle
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Title 6",Title6,1,xLocation:126;yLocation:20;width:40;height:20;allowedWidgetGroups:WidgetForTabTitle
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Tab 3",3,1,xLocation:0;yLocation:40;width:40;height:50;dottedRightBorder:true
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Tab 4",4,1,xLocation:40;yLocation:40;width:43;height:50;dottedRightBorder:true
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Tab 5",5,1,xLocation:83;yLocation:40;width:43;height:50;dottedRightBorder:true
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,"Tab 6",6,1,xLocation:126;yLocation:40;width:40;height:50
      "Any page, seven slots, tabs",MyCustomLayoutTemplateContainer,7,7,1,xLocation:0;yLocation:90;width:166;height:128

      For more information about the information to include within this file, see slotDefinition input file.

   3. Save and close the file.

Configure and run the Data Load utility

6. Configure the environment settings for running the Data Load utility.

   1. Open the wc-dataload-env.xml data load environment configuration file for editing. This file configures the Data Load utility environment variables, such as the database settings, ID resolver, and data writer.

   2. Update the file to match the database and environment settings. See Configure the data load environment settings. We can enter a value for the store identifier in this file or enter the store identifier when you run the Data Load utility to load the CSV files. The store identifier is used to identify the store that subscribes to your layout template. The store identifier is case-sensitive. We can find the value for the store identifier within the IDENTIFIER column of the STOREENT database table.

      If we are using using the extended sites business model and want this layout template to be available to all of your extended sites, use the store identifier for the storefront asset store. Alternatively, we can use a store identifier of a specific extended site if we want the layout template to be available only to that extended site.

   3. Save your file.

7. Optional: Configure the load order for when you run the Data Load utility. This configuration identifies the sequence that the Data Load utility loads your CSV input files. If you included your new directory for layout template information within the WCDE_installdir\components\foundation\samples\DataLoad\CommerceComposer directory, and did not move the business object configuration files, or rename the CSV input files, you do not need to update this file.

   1. Open the wc-dataload-template.xml file for editing.

   2. Update the values for each businessObjectConfigFile and location attribute to reference the correct location and names for our files.

   3. Save and close the file.

   For more information about working with this file, see Configure the data load order.

8. Optional: Configure the business object configuration files for loading your layout template information. By default, you do not need to update these files to load your layout template information. For more information if you do want to update these files, see Configure the business object configuration file. The following files are the business object configuration files used to load layout template information:

   • wc-loader-registerWidgetdef.xml

   • wc-loader-subscribeWidgetdef.xml

   • wc-loader-template.xml

   • wc-loader-widgetslot.xml

9. Run the Data Load utility.

   1. In a command-line utility, go to the WCDE_installdir\bin directory.

   2. Run the following command to load the input files to register and define your layout template, and have the store subscribe to the template.

      dataload.bat ..\samples\DataLoad\CommerceComposer\template-MyCompany\wc-dataload-template.xml Where

      template-MyCompany

      The folder createdd to include your layout template CSV files.

   3. Verify the results of the data load.

   For more information about using Data Load utility to load layout template information, see
   Sample: Loading Commerce Composer layout templates.

What to do next

With your layout template registered, defined, and subscribed to by a store, the layout template is available for use in the Commerce Composer tool and the storefront. Use the Commerce Composer tool to compose a page layout that uses your new layout template and preview the layout to ensure that your layout template displays correctly.

Previous topic: Defining the storefront assets for Commerce Composer layout templates
Next topic: Testing a custom layout template in Management Center

Related concepts
Layout assignments for category pages
Layout assignments for catalog entry pages
Layout assignments for search terms
Pages and page creation
Commerce Composer layout architecture
Layouts, layout templates, and default layouts