Updating a catalog store page to use the Commerce Composer framework

You can modify existing catalog store JSP pages to use the GetPageDesign service to retrieve the appropriate page design and content to render your store page.

About this task

Within the Commerce Composer framework, a page is a URL, with no content. The content of a page is defined by the page layout when the layout is assigned to the page. A layout is a layout template that has widgets, which are included within the layout template slots. The widgets are used to add the content for the page.

The following steps modify a store catalog page JSP file to use the GetPageDesign service and to follow the structure for a catalog page that the Commerce Composer framework expects. Your modified JSP page no longer defines any content for display. The content is determined when a layout is assigned to your modified page with Commerce Composer tool. If no layout is assigned, your modified page uses the default layout that you subscribed your store to use in an earlier task. If you do not update your catalog page JSP files, your store cannot display a Commerce Composer layout for the catalog pages.

Procedure

Modify the display JSP file for your store page to use the GetPageDesign service that retrieves Commerce Composer assets for rendering your store page.
1. Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
2. Go to the directory that includes the main JSP for your store page.
3. Open the file for editing.
4. Update the file to use the GetPageDesign service to retrieve the appropriate layout data for your store page.
  For more information about the GetPageDesign service, see GetPageDesign service algorithm.
  
  For a code example that uses this service, see Product details sample code for supporting getpageDesign service. This code defines the use of the GetPageDesign service to retrieve product details and widget data for a Product Details page.
5. Update your storefront page JSP to replace any CatalogNavigationView BOD service to use the corresponding new search server REST service to retrieve data from WebSphere Commerce search for the catalog object that displays on your store page.
  By including the call to the REST service in your JSP file, you can improve your storefront performance. With the REST service call at this level, you can avoid having each separate widget on your catalog page call the REST service to retrieve the same data. For more information about updating the storefront services to retrieve data from WebSphere Commerce search, see Migrating WebSphere Commerce search customization assets.
  
  For a code example that uses the ProductViewHandler REST service, see Product details sample code for supporting getpageDesign service.
6. If you are including the E-Marketing Spot widget in your widget library, add code to your catalog JSP pages to set the value of the emsNameLocalPrefix variable.
  This variable is required to support the page-specific e-Marketing Spot option that the E-Marketing Spot widget provides. When Management Center users add this widget to a layout and select the Page-specific e-Marketing Spot option, the Commerce Composer framework generates a name for the e-Marketing Spot in each page that the layout is assigned to. The name is formed by combining a unique prefix for each page and a suffix that the Management Center user specifies. Within the <head> element of your catalog page JSP files, you must add code to set the prefix for your catalog pages.
  The following example code from the ProductDisplay.jsp file for the Aurora starter store uses a REST call to set the emsNameLocalPrefix value for page-specific e-Marketing Spots:
```
<c:set var="emsNameLocalPrefix" value="${fn:replace(subCategory.catalogGroupView[0].identifier,' ','')}" scope="request"/>
<c:set var="emsNameLocalPrefix" value="${fn:replace(emsNameLocalPrefix,'\\\\','')}"/>
```
  As you can see in the previous example, the Aurora starter store uses the category name as the prefix for all product pages. You can change the code to use the product part number instead so that each product page has a different e-Marketing Spot. To get this result, change the previous code snippet to look like this instead:
```
<c:set var="emsNameLocalPrefix" value="${partNumber}" scope="request"/>
<c:set var="emsNameLocalPrefix" value="${fn:replace(emsNameLocalPrefix,'\\\\','')}"/>
```
  To see an example that sets the prefix for a category page instead of a product page, search for emsNameLocalPrefix in the CategoryNavigationDisplay.jsp file for the Aurora starter store.
7. Add the following code into the end of the header section of the file. This code indicates that the JSP file must include the specified "pageDesign" JavaScript. This code is required for all pages that use the Commerce Composer framework to determine the design and content to display on the page.
```
<wcpgl:jsInclude varPageDesignDetails="pageDesign"/>
```
8. Delete all of the code that comprises the <body> element of your JSP file except for the code that defines the Header and Footer sections of your store page.
9. Include the following code between the sections of code that defines the Header and Footer of your page. This code indicates where on your store page, the Commerce Composer framework inserts the content of the Commerce Composer layout that is assigned to the page.
```
<c:set var="rootWidget" value="${pageDesign.widget}"/>
<wcpgl:widgetImport uniqueID="${rootWidget.widgetDefinitionIdentifier.uniqueID}" debug=false/>
```
10. Add caching support for your store page JSP file.
  Add the following code to the end of the <body> element before the end tag for the element:
```
<wcpgl:pageLayoutCache pageLayoutId="${pageDesign.layoutID}"/>
```
  For more information, see Commerce Composer layout caching and invalidation.
11. Save and close the main JSP file for your store page.
Add the store environment setup JSP fragments for the Aurora starter store to your store directory structure.
1. In a file manager, go to the tempAuroraDir\StoreAssetsDir\Common directory, where tempAuroraDir is the temporary directory where you extracted the Aurora.sar archive.
2. Copy the EnvironmentSetup.jspf and JSTLEnvironmentSetup.jspf files.
3. Go to the corresponding directory for your store.
  For example, the workspace_dir\Stores\WebContent\store\Common directory. If the Common folder does not exist for your store directory, create this folder.
4. Add the copied files into the Common folder for your store.
5. In the Enterprise Explorer view, browse to the Common directory for your store. Open the EnvironmentSetup.jspf file for editing.
6. Remove any include statements in this file and remove any references to the SterlingConfiguratorIntegrationSetup.jspf file.
7. Save and close the file.
8. Browse to the workspace_dir\Stores\WebContent\store\include directory for your store. Open the EnvironmentSetup.jspf file for editing.
9. Remove any inNonSSLAcceleratorPort and inSSLAcceleratorPort setup references to avoid potential conflicts with the JSTLEnvironmentSetup.jspf file that you copied from the Aurora.sar archive.
10. Save and close the file.
Remove any referenced JSP files or JSP fragments that define how to display content on your page that a Commerce Composer widget already provides. By removing the duplicate functionality, you can ensure that the page uses Commerce Composer widgets and create a cleaner organization of code.
1. Go to the Stores\WebContent\store\include directory.
2. Open the LayoutContainerTop.jspf file for editing.
3. Remove any references to the LeftSidebarDisplay.jspf file.
4. Open the LayoutContainerBottom.jspf file for editing.
5. Remove any references to the RightSidebarDisplay.jspf file.
6. Open the HeaderDisplay.jspf file for editing.
7. Remove any references to the BreadCrumbTrailDisplay.jsp file.
8. Save and close the files.
Note: Depending on the store page that you are converting to support Commerce Composer, you might need to complete extra steps. For an example of updating the Product Details page of the Madisons starter store to support entitled items, see Updating a Madisons store catalog page to use Commerce Composer.

Verify that your updated catalog page can display a Commerce Composer layout on your storefront.

Open the Commerce Composer tool.
Select your store from the Store list.
Create a layout for your store. Assign the layout to your catalog page.
Preview the page to ensure that the page uses the assigned Commerce Composer layout.
1. To preview the store page that contains the layout, click Save and Preview.
2. If the Store Preview Options window is displayed:
  1. From the Store URL list, select the page to preview.
  2. Expand Options, click Specify the date and time, and then specify the start date for your layout.
  3. Click Launch Store Preview.
3. In store preview, review your page to ensure that the page displays the layout. Your page, however, might not display all widgets and content in the layout correctly now. You must still update your store directory to include any dependent JavaScript and CSS files that your store pages require and to remove any errors. If your page does display a resemblance of the Commerce Composer layout, your page JSP file is successfully updated to use the GetPageDesign service.