Example: Adding an action button to the Campaigns list page

Example: Adding an action button to the Campaigns list page

The campaigns component in WebSphere Commerce, when considered without the associated components, serves to organize campaign activities, and act as a method by which to sort statistical information associated with marketing efforts.
Since the campaigns component has little effect on the functionality of your marketing efforts, it is not a component for which you will likely find a lot of need for customization. The scenario detailed below is a generic example of how you can add an action button to a list page. While the details of this customization scenario are specific to the campaigns components, you can adapt it to other components, with different targets by making the changes to the appropriate assets.
This scenario adds an action button to the Campaigns list page, which links directly to the Web activity wizard. This is useful insofar as it provides another way of accessing this tool.
Create a label for the new button. WebSphere Commerce design separates program logic from displayed strings, so 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, or some similar event, it must be created in a safe place, separate from the WebSphere Commerce assets. This procedure creates a new properties file, in a new folder, within the WebSphere Commerce development environment:
Open the WebSphere Commerce development environment (Start > Programs > IBM WebSphere Commerce development environment) and switch to the

J2EE Perspective Project Navigator view

Express Project Navigator view.
Navigate to the WebSphereCommerceServerExtensionsLogic project.
Navigate to the src folder.
Right-click on the src folder, and select New, and then Package.
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..."
Click Finish to create the package.
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.
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.
Click Finish to create the file and open it in an editor.
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
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
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
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.
When you create a custom properties file, 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:
Create a new directory. For the purposes of this scenario, name the directory, /myCustomXML/, where myCustomXML represents some custom directory name.
Repeat this process until you have created the following path:
/myCustomXML/tools/campaigns/
where myCompany represents some custom directory name.
Copy the /WCDE_installdir/xml/tools/campaigns/resources.xml file, and move the file to the /myCustomXML/tools/campaigns/ directory.
Open the new resources.xml file in an editor.
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 custom directory name.
Save the file.
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 new Campaign List XML definition file, in the same /myCustomXML/tools/campaigns/ folder used in step 2. This is not done within the development environment. To add the button...
Change to the /WCDE_installdir/xml/tools/campaigns directory.
Copy /WCDE_installdir/xml/tools/campaigns/CampaignList.xml to the new /myCustomXML/tools/Campaigns/ directory. Do not change the file name.
Open the CampaignList.xml file in an editor.
Scroll down to the code segment about buttons. Add the following code:
<menu name="newCustomActivity"
    action="basefrm.newInitiative()"
    selection="single" />
Note that the value for the name attribute must match the value of the key that we just 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 /WCDE_installdir/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.
Save the file.
When you create a custom XML file to update the interface, update the appropriate resources.xml file so that the new user interface displays as expected. This is not done within the development environment. To make this update:
Change to the /myCustomXML/tools/campaigns/ directory.
Open the resources.xml file in an editor.
Scroll down to the "XML file mappings" section of the file, and update the campaign list entry so that it matches the following sample:
<resourceXML name="CampaignList"
    file="/myCustomXML/tools/campaigns/CampaignList.xml" />
where myCustomXML represents your custom directory name.
Save the file.
Create 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 will attempt to locate XML files. It functions in a manner similar to a Java classpath setting. This is not done within the development environment. To update the XMLPath setting:
Change to the /WCDE_installdir/instances/instance/xml/ directory.
Open the instance.xml file in an editor.
Scroll down to the "ToolsGeneralConfig" section of the file, and update the XMLPath by prepending the following to the value:
/myCustomXML/tools;
where myCustomXML represents the absolute path to your custom directory, including the drive letter.
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, repeat this step for each instance.
Attention
Applying fix packs, or performing migration may overwrite any changes made to this file.
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:
In the WebSphere Commerce development environment, navigate to the CommerceAccelerator/Web Content/tools directory.
Right-click on the folder, and select New, and then Folder. In the Folder name field, enter custom.
Navigate to the Web Content/tools/campaigns folder.
Right-click on the CampaignList.jsp file, and select Copy.
Right-click on the Web Content/tools/custom folder, and select Paste.
Navigate to the Web Content/tools/custom folder.
Double-click the new file to open it in an editor.
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.
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" %>
Save the file, but do not close the development environment.
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...

In the WebSphere Commerce development environment, navigate to the CommerceAccelerator/Web Content/WEB-INF folder.
From the struts-config-ext.xml file's pop-up menu, select Open.
Add the following code:
<global-forwards>
   <forward name="CampaignListView" path="/tools/custom/CampaignList.jsp" 
      className="com.ibm.commerce.struts.ECActionForward" /> 
</global-forwards>
Test your customization in your development environment. To complete this test:

Stop and restart your development WebSphere Commerce instance. Refer to the for details about how to stop and restart this instance.
Launch the WebSphere Commerce Accelerator.
From the Marketing menu, select Campaigns. The new button should display on this page.
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.

Export the updated assets:

Right-click the new CampaignList.jsp file and select Export. The Export Wizard opens.
In the Export wizard:

Select File system and click Next.
The CampaignList.jsp is selected.
Navigate to the WebSphereCommerceServerExtensionsLogic/src/com /myCompany/campaigns/properties folder, and select the myCampaignsRB_locale.properties file.
Select Create directory structure for selected files.
In the To directory field, enter a temporary directory into which these resources will be placed. For example, enter C:\ExportTemp\StoreAssets
Click Finish.
If prompted, create the specified directory.

Transfer the updated assets to the production environment. To transfer the files:

Stop the WebSphere Commerce instance that is running within WAS.
On the target machine, locate the WebSphere Commerce instance .ear directory, WC_eardir.
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.ear/properties/com/myCompany/campaigns /properties

Transfer the following files to your production environment:

/myCustomXML/tools/campaigns/CampaignList.xml

Copy to WC_installdir/xml/tools/custom

/WCDE_installdir/xml/tools/campaigns/resources.xml

Copy to WC_installdir/xml/tools/campaigns

Update the WebSphere Commerce configuration file, so that it reflects the updated XMLPath value.
Propagate your change to the Struts configuration file to the production database.
Restart your WebSphere Commerce instance.
Related concepts

Struts configuration files
Related reference

Assets used by the Campaigns component