Feature Pack 6 or later

Adding support for dynamic catalog entry recommendations in an e-Marketing Spot

Before a Marketing Manager or business user can take advantage of the dynamic recommend catalog entry action in a web activity, customization to store JSP pages can be required. As a store page developer, you can add support for using the dynamic recommend catalog entry action in an e-Marketing Spot. Support for this action must be added to the JSP file where the activity is to run.

Before you begin

Before you begin this task, ensure that you complete the following prerequisites:
  • Publish the Aurora starter store model.
    • If your deployed store is based on the WebSphere Commerce Feature Pack 5 Aurora starter store, you must complete the steps in this topic to add support for dynamic recommendations.
    • If you deploy a new store after you install WebSphere Commerce Feature Pack 6, the files that are modified in this topic are updated by default to support dynamic recommendations. If you want to add this support to a different JSP page, you can use this topic as a guide for customizing your JSP and JavaScript files.
  • Install WebSphere Commerce Feature Pack 6.
  • Identify the JSP file that you intend to use for displaying dynamic catalog entry recommendations.
Note: Dynamic catalog entry recommendations are not showcased on stores that are based on the Madisons starter store model.

About this task

By default, there are two sample JSP pages available in the Aurora starter store that are updated to support displaying dynamic catalog entry recommendations. To add this support you can customize one of the following JSP and the following JavaScript file, which provides the default support for a new store that is deployed and based on the Aurora starter store model:
JSP file Purpose
CategoryNavigationDisplay.jsp The JSP file that is used when a customer is browsing categories in a catalog in your store.
SearchResultsDisplay.jsp The JSP file that is used when a keyword search that uses search terms is performed.
These JSP files are in the following directory:
  • WebSphere Commerce DeveloperWCDE_installdir\workspace\Stores\WebContent\store_dir\Layouts
  • SolarisLinuxAIXWindowsWC_eardir\Stores.war\store_dir\Layouts
where store_dir is the directory name for your store.
You must also add support to the following JavaScript file:
JavaScript Purpose
ProductRecommendation.js The JavaScript file that defines the function for catalog entry recommendations.
This JavaScript file is in the following directory:
  • WebSphere Commerce DeveloperWCDE_installdir\workspace\Stores\WebContent\store_dir\javascript\widgets
  • SolarisLinuxAIXWindowsWC_eardir\Stores.war\store_dir\javascript\widgets
where store_dir is the directory name for your store.

Procedure

  1. Define the Ajax URL for refreshing the catalog entry recommendation. By refreshing the recommendations, the catalog entries that display are continually refreshed. They are refreshed based on the browsing or navigation choices that are made by the customer that is viewing your store.
    1. In your file management program, navigate to the directory that contains the store JSP Page that you are adding support into:
      For example,
      • WebSphere Commerce DeveloperWCDE_installdir\workspace\Stores\WebContent\store_dir\Layouts
      • SolarisLinuxAIXWindowsWC_eardir\Stores.war\store_dir\Layouts
      where store_dir is the directory name for your store.
    2. Locate the JSP file that you want to add support to and open the file for editing.
    3. Locate the section of code in your file that defines the location where you want to include an e-Marketing Spot that displays dynamic catalog entry recommendations. Define how to handle dynamic recommendations.
    4. Add the code to define the Ajax URL.
      The following code defines this Ajax URL in your JSP file:
      <wcf:url var="ProdRecommendationRefreshViewURL" value="ProductRecommendationView" type="Ajax">
        <wcf:param name="emsName" value="${emsNameTemp}Row4_CatEntries" />
        <wcf:param name="pageSize" value="4" />
        <wcf:param name="commandName" value="CategoryDisplay" /> 
        <wcf:param name="langId" value="${langId}" />
        <wcf:param name="storeId" value="${storeId}" />
        <wcf:param name="catalogId" value="${catalogId}" />
        <wcf:param name="categoryId" value="${WCParam.categoryId}" />
        <wcf:param name="urlLangId" value="${urlLangId}" />
      </wcf:url>

      For example, in the SearchResultsDisplay.jsp file the preceding code is included after the code that defines the display of search results for products and content.

      The URL type is Ajax. All of the parameters included within the preceding code are mandatory parameters:
      Parameter Description
      pageSize This parameter indicates the number of catalog entries to be returned for displaying a page.
      emsName The e-Marketing Spot name.
      commandName The command name.
      langId The language identifier. This identifier is used to scope the results of the catalog entry recommendations by what language they are browsing.
      storeId The store identifier. This identifier is used to scope the results of the catalog entry recommendations by what store they are browsing.
      catalogId The catalog identifier. This identifier is used to scope the results of the catalog entry recommendations by what catalog they are browsing.
      categoryId The category identifier. This identifier is used to scope the results of the catalog entry recommendations by what category they are in.
      urlLangId The language identifier from the URL. This identifier is used to scope the results of the catalog entry recommendations by what language they are browsing.

      For more information, see Tag: url

    5. Save your changes. Keep your file open for editing.
  2. Include the JavaScript file for catalog entry recommendations in the JSP file for displaying your dynamic recommendations. To include this JavaScript file, add the following code after your code for defining the Ajax URL:
    <script type="text/javascript" src="${jsAssetsDir}javascript/Widgets/ESpot/ProductRecommendation.js"></script>
    Save your changes. Keep your file open for editing.
  3. Define a refresh controller within the JavaScript file that defines the catalog entry recommendation function. This new refresh controller is to be used to refresh the catalog entry recommendations. navigate to the directory that contains the store JSP Page that you are adding support into:
    1. Navigate to the directory that contains your JavaScript file:
      For example,
      • WebSphere Commerce DeveloperWCDE_installdir\workspace\Stores\WebContent\store_dir\Layouts
      • SolarisLinuxAIXWindowsWC_eardir\Stores.war\store_dir\Layouts
      where store_dir is the directory name for your store.
    2. Open the ProductRecommendation.js file for editing.
    3. After the code that defines your catalog entry recommendation function, add the following code that defines the refresh controller:
      // Declare refresh controller
      wc.render.declareRefreshController({
        id: "prodRecommendationRefresh_controller",
        renderContext: wc.render.getContextById("searchBasedNavigation_context"),
        url: "",
        formId: ""
        
        ,renderContextChangedHandler: function(message, widget) {
          var controller = this;
          var renderContext = this.renderContext;
          var resultType = renderContext.properties["resultType"];
          if(resultType == "products" || resultType == "both"){
            widget.refresh(renderContext.properties);
            console.log("espot refreshing");
          }
        }
      });

      This code calls the wc.render.declareRefreshController Ajax function and defines the refresh controller as prodRecommendationRefresh_controller. For more information, see AJAX framework

    4. Save and close your file.
  4. In your JSP file, add code for using your new refresh controller for catalog entry recommendations. To use this controller in your JSP file, add the following code, after the code for define the Ajax URL:
    <script type="text/javascript"> 
      dojo.addOnLoad(function(){
      wc.render.getRefreshControllerById('prodRecommendationRefresh_controller').url = '${ProdRecommendationRefreshViewURL}';
      });
    </script>

    This code snippet calls the wc.render.getRefreshControllerById Ajax function and defines the refresh controller as ProdRecommendationRefresh_controller in your JSP file. This code also sets the URL for the controller as a previously defined URL, such as ProdRecommendationRefreshViewURL.

  5. Define a refresh area in your JSP file for displaying the catalog entry recommendation. To define this area, add the following lines of code into your file after the code for using your refresh controller:
    <div class="widget_product_listing_position">
      <c:if test="${!env_fetchMarketingDetailsOnLoad}">
        <div dojoType="wc.widget.RefreshArea" id="CategoryProductRecommendationESpot_Widget" controllerId="prodRecommendationRefresh_controller">
        <% out.flush(); %>
        <c:import url="${env_jspStoreDir}Widgets/ESpot/ProductRecommendation/ProductRecommendation.jsp">
          <c:param name="pageSize" value="4" />
          <c:param name="emsName" value="${emsNameTemp}Row4_CatEntries" />
          <c:param name="errorViewName" value="AjaxOrderItemDisplayView" />
          <c:param name="pageView" value="miniGrid"/>
        </c:import>
        <% out.flush(); %>
        </div>
      </c:if>
    </div>

    This code defines a refresh area user interface widget. For example, dojoType="wc.widget.RefreshArea". Use this widget to refresh the catalog entry recommendations. This code also defines the controller for the refresh area to be previously created controller controllerId="prodRecommendationRefresh_controller". For more information, see User interface widgets

  6. Save and close your file.
  7. Modify your JSP file to ensure that your e-Marketing Spot displays correctly:
    1. In your file management program, navigate to the directory that contains your display JSP file:
      For example,
      • WebSphere Commerce DeveloperWCDE_installdir\workspace\Stores\WebContent\store_dir\Widgets\CatalogEntry\CatalogEntryDisplay.jsp
      • SolarisLinuxAIXWindowsWC_eardir\Stores.war\store_dir\Widgets\CatalogEntry\CatalogEntryDisplay.jsp
      where store_dir is the directory name for your store.
    2. Locate your JSP file and open the file for editing.
    3. Locate the code that determines how content displays in your e-Marketing Spot:
      <%@ include file="ext/CatalogEntryDisplay_UI.jsp">  
      Add the following code before the code you located:
      <div class="product">
      Add the following code after the code that determines how content displays in your e-Marketing Spot.
      </div>
    4. Save your changes and close your file.
      Your modified file code can resemble the following code:
      <div class="product">
        <%@ include file="ext/CatalogEntryDisplay_UI.jsp">
        <c:if test = "${param.custom_view ne 'true'}">
          <c:choose>
            <c:when test = "${param.pageView == 'sidebar'}">
              <%@ include file="CatalogEntryDisplay_SideBarView_UI.jsp" %>
            </c:when>
            <c:when test = "${param.pageView == 'grid'}">
              <%@ include file="CatalogEntryDisplay_GridView_UI.jsp" %>
            </c:when>
            <c:when test = "${param.pageView == 'list'}">
              <%@ include file="CatalogEntryDisplay_ListView_UI.jsp" %>
            </c:when>
            <c:when test = "${param.pageView == 'miniList'}">
              <%@ include file="CatalogEntryDisplay_MiniListView_UI.jsp" %>
            </c:when>
            <c:when test = "${param.pageView == 'miniGrid'}">
              <%@ include file="CatalogEntryDisplay_MiniGridView_UI.jsp" %>
            </c:when>
            <c:otherwise>
              <%-- Default to mini grid view... --%>
              <%@ include file="CatalogEntryDisplay_MiniGridView_UI.jsp" %>
            </c:otherwise>
          </choose>
        </c:if>
      </div>

What to do next

Confirm with your Marketing Manager or business user that they can include the action to recommend catalog entries within a web activity in an e-Marketing Spot on your updated store page. Ensure that your Marketing Manager or business user confirms that the catalog entry recommendations change based on the browsing choices they make when the activity is tested.