Example: Adding an action button to the Campaigns list page

This scenario is a generic example describing how to add an action button to a list page. You can adapt this scenario it to other components, with different targets by changing the appropriate assets.

The campaigns component in WebSphere Commerce organizes campaign activities, and acts as a method by which to sort statistical information associated with marketing efforts. Typically, it will not be necessary to customize the campaigns component.

This scenario adds an action button to the Campaigns list page, which links directly to the Web activity wizard. This customization is useful insofar as it provides another way of accessing this tool.

  1. Create a label for the new button. Labels for buttons, and all other interface elements are stored in properties files, which are also referred to as resource bundles. To protect your customized data from being overwritten during migration to a future version, or during installation of a future fix pack, separate your customization from the WebSphere Commerce assets. This procedure creates a properties file, in a new folder, within the WebSphere Commerce development environment:
    1. Open the WebSphere Commerce development environment
    2. Navigate to the WebSphereCommerceServerExtensionsLogic project.
    3. Navigate to the src folder.
    4. Right-click on the src folder, and select New, and then Package.
    5. In the Name Field on the New Java Package dialog, enter a unique name. For the purposes of this scenario, enter com.myCompany.campaigns.properties, where myCompany represents some custom directory name. Packages created by IBM, and included in WebSphere Commerce follow a naming convention which begins, "com.ibm..."
    6. Click Finish to create the package.
    7. Right-click on the com.myCompany.campaigns.properties folder, and select New, and then Other. In the New dialog, click Simple, File, and then Next.
    8. In the File name field, enter a unique name. For the purposes of this scenario, enter CampaignsRB_locale.properties, where locale represents the locale from which your business users will access the WebSphere Commerce Accelerator.
    9. Click Finish to create the file and open it in an editor.
    10. To simplify future maintenance, it is a good idea to include comments in this new file. This is optional, though strongly recommended. At the top of this file, include some comments similar to the following to clarify this file's purpose: 
      
#
# Customized properties for Campaigns
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
    11. Scroll down and create a "Button definitions" section for the file, and insert a label for your new button. This should look similar to the following sample: 
      
#
# Button definitions
#

newCustomActivity = Create Web Activity
    12. Save the file, but do not close the development environment.

    This addresses the label in the language for the locale you specified when you created the file. If you wanted to enter a string in more than one language, you would have to perform this step for each language, creating a file for each corresponding locale.

    If a business user attempts to access this page using a locale for which there is no explicit support, the tools framework will default to the CampaignsRB.properties file, which will not contain a corresponding string. You should ensure that you create a version of the properties file for every locale from which you expect users to access it.

  2. When you create a custom properties file, you must update the appropriate resources.xml file so that the new file is available to the tools within the component. This is not done within the development environment. To make this update:
    1. Create a new directory under the WC_eardir/xml directory. For the purposes of this scenario, name the directory, WC_eardir/xml/myCustomXML, where myCustomXML represents some custom directory name.
    2. Repeat this process until you have created the following path: 
      
WC_eardir/xml/myCustomXML/tools/campaigns/
    3. Copy the WC_eardir/xml/tools/campaigns/resources.xml file, and move the file to the WC_eardir/xml/myCustomXML/tools/campaigns/ directory.
    4. Open the new resources.xml file in an editor.
    5. Scroll down to the "Resource bundle" section of the file, and update the code so that it matches the following sample: 
      
<resourceBundle name="campaignsRB">
    <bundle>com.ibm.commerce.tools.campaigns.properties.CampaignsRB</bundle>
    <bundle>com.myCompany.campaigns.properties.CampaignsRB</bundle> 
</resourceBundle>
      where myCompany represents your company name.
    6. Save the file.
  3. Update the Campaign List definition XML file to add the new button, Create Web Activity. Again, to protect your customized data, it must be created in a safe place, separate from the WebSphere Commerce assets. This procedure creates a Campaign List XML definition file, in the same WC_eardir/xml/myCustomXML/tools/campaigns folder used in step 2. This is not done within the development environment. To add the button:
    1. Change to the WC_eardir/xml/tools/campaigns directory.
    2. Copy WC_eardir/xml/tools/campaigns/CampaignList.xml to the new WC_eardir/xml/myCustomXML/tools/Campaigns directory. Do not change the file name.
    3. Open the CampaignList.xml file in an editor.
    4. Scroll down to the code segment about buttons. Add the following code: 
      
<menu name="newCustomActivity"
    action="basefrm.newInitiative()"
    selection="single" />
      The value for the name attribute must match the value of the key that we inserted into the properties file in step 1. Also, the action matches the action defined in the Campaign Activity list page's corresponding XML file, also located in the WC_eardir/xml/tools/campaigns directory. This button performs the same function as the Create button on that page. Finally, we have set the value for the selection attribute to 'single', which means that the action is only available when a single campaign is selected. In other situations this value could be set to either 'none', or 'multiple', which would specify that the button was only available when either no campaigns were selected, or when more than one campaign was selected, respectively.
    5. Save the file.
  4. Creating a custom XML file in a custom directory requires that you update the instance XMLPath setting. This setting governs the locations in which the application attempts to locate XML files. It functions in a manner like a Java classpath setting. To update the XMLPath setting:
    1. Change to the WC_eardir/xml/config directory.
    2. Open the wc-server.xml file in an editor.
    3. Scroll down to the <ToolsGeneralConfig> section of the file, and update the XMLPath by specifying your custom directory name to the value. For example, if the original XMLPath value is 
      
XMLPath="tools;tools/devtools;WEB-INF/xml/tools;WEB_INF"
      and your custom directory is myCustomXML, then change the XMLPath value to 
      
XMLPath="myCustomXML/tools;tools;tools/devtools;WEB-INF/xml/tools;WEB_INF"
    4. Save the file.
    Changing the XMLPath setting in the instance configuration file enable this customization only for the single instance. All other instances will not include this new button. If you have multiple instances to which you want to apply the customization, you must repeat this step for each instance.

    Attention: Applying fix packs, or performing migration might overwrite any changes made to this file.

  5. Update the CampaignList.jsp with a new algorithm to handle the new button. To protect the custom code, this procedure creates a new JSP which contains the logic:
    1. In the WebSphere Commerce development environment, navigate to the CommerceAccelerator/Web Content/tools directory.
    2. Right-click on the folder, and select New, and then Folder. In the Folder name field, enter custom.
    3. Navigate to the Web Content/tools/campaigns folder.
    4. Right-click on the CampaignList.jsp file, and select Copy.
    5. Right-click on the Web Content/tools/custom folder, and select Paste.
    6. Navigate to the Web Content/tools/custom folder.
    7. Double-click the new file to open it in an editor.
    8. Update your JSP. Scroll down to the section of the file in which the JavaScript functions are defined, and update it so that it contains the following JavaScript (lines may be split here for presentation purposes): 
      
function newInitiative () {
    var url = "<%= UIUtil.getWebappPath(request) %>DialogView?XMLFile=campaigns.InitiativeDialog";
    top.setContent("<%= UIUtil.toJavaScript((String)campaignsRB.get(CampaignConstants.MSG_CREATE_INITIATIVE)) %>", url, true);
}

      This code can be found in the InitiativeList.jsp file in the same directory, and copied from that source.

    9. Also, because the custom file is in a different location, you have to update the following path in the JSP to reflect the original location. Search for the following include statement: 
      
<%@ include file="common.jsp" %>
      and change it to: 
      
<%@ include file="../campaigns/common.jsp" %>
    10. Save the file, but do not close the development environment.
  6. Update the view that corresponds to the page in the Struts configuration file to map the new JSP file to their corresponding view. The CampaignListView command must be overwritten in the configuration file. Add the entries to the struts-config-ext.xml file to point to your customized JSP page. All customization changes should be made in struts-config-ext.xml, not to struts-config.xml. To register the new views:
    1. In the WebSphere Commerce development environment, navigate to the CommerceAccelerator/Web Content/WEB-INF folder.
    2. From the struts-config-ext.xml file's pop-up menu, select Open.
    3. Add the following code:
    
<global-forwards>
   <forward name="CampaignListView" path="/tools/custom/CampaignList.jsp" 
      className="com.ibm.commerce.struts.ECActionForward" /> 
</global-forwards>
  7. Test your customization in your development environment. To complete this test:
    1. Stop and restart your development WebSphere Commerce instance. Refer to the for details about how to stop and restart this instance.
    2. Launch the WebSphere Commerce Accelerator.
    3. From the Marketing menu, select Campaigns. The new button should display on this page.
    4. Select a campaign, and click the new Create Web Activity button. This should launch the Web activity wizard. If this works, then the customization has been a success, and you can proceed to propagate all of the changes you made to the development environment to the production environment as detailed in the following steps. If this fails, you will have to determine the cause of the error, and debug.
  8. Export the updated assets:
    1. Right-click the new CampaignList.jsp file and select Export. The Export Wizard opens.

      In the Export wizard:

      1. Select File system and click Next.
      2. The CampaignList.jsp is selected.
      3. Navigate to the WebSphereCommerceServerExtensionsLogic/src/com /myCompany/campaigns/properties folder, and select the myCampaignsRB_locale.properties file.
      4. Select Create directory structure for selected files.
      5. In the To directory field, enter a temporary directory into which these resources will be placed. For example, enter C:\ExportTemp\StoreAssets
      6. Click Finish.
      7. If prompted, create the specified directory.
  9. Transfer the updated assets to the production environment. To transfer the files:
    1. On the target machine, locate the WebSphere Commerce instance .ear directory, WC_eardir.
    2. Copy the files exported in step 9, above, into the following directories:
      CampaignList.jsp
      WC_eardir/CommerceAccelerator.war/tools/custom
      myCampaignsRB_locale.properties
      WC_instance_name.ear/properties/com/myCompany/campaigns /properties
    3. Transfer the following files to your production environment:
      /xml/myCustomXML/tools/campaigns/CampaignList.xml
      Copy to WC_installdir/xml/tools/custom
      /xml/WC_eardir/xml/tools/campaigns/resources.xml
      Copy to WC_eardir/xml/tools/campaigns
    4. Update the WebSphere Commerce configuration file, so that it reflects the updated XMLPath value.
    5. Copy your change to the Struts configuration file, to your production environment.
  10. Package and deploy the updated assets.
  11. Restart your WebSphere Commerce instance.