Example: Altering the relative field locations on the Content dialog

The content component in WebSphere Commerce acts as a repository for any marketing collateral, including images and flash animations, that is designed to support a campaign. Content displays in the space defined by either a content spot, or an e-Marketing Spot, and is obtained from the commerce database when the commerce server renders the page. Each content may be associated with a click action, which is a URL that specifies an action to perform when a customer clicks on the content.

If the content dialog does not display the various fields in the order that you find appropriate, you have the ability to change their relative position. The scenario detailed below moves the File Location field below the Marketing Text field.

To change the default order of the fields on the Content dialog:

  1. Update the Content dialog XML definition file to enable the additional fields. To protect your customized definition file, it should be move to a safe place, separate from the WebSphere Commerce assets. This procedure creates a new content XML definition file, in a new WC_eardir/xml/myCustomXML/tools/campaigns folder. This is not done within the development environment. To add the button, do the following:
    1. Create a new directory under the WC_eardir/xml directory. For the purposes of this scenario, name the directory, WC_eardir/xml/myCustomXML/tools/campaigns/, where myCustomXML represents some custom directory name.
    2. Change to the WC_eardir/xml/tools/campaigns directory.
    3. Copy WC_eardir/xml/tools/campaigns/CollateralUniversalDialog.xml to the new WC_eardir/xml/myCustomXML/tools/Campaigns directory. Do not change the file name.
    4. Open the CollateralUniversalDialog.xml file in an editor.
    5. Locate the following XML element (lines broken for display purposes):
      
      <section name="imageDescriptionSection" enabled="true" expand="false">
      
         <element name="collateralURLSegment"
            type="custom"
            page="/tools/campaigns/CollateralURLSegment.jsp" />
      
         <element name="location"
            type="text"
            label="collateralLocationPrompt"
            value="collateral.location"
            property="size=&quot;50&quot; maxlength=&quot;254&quot;" />
      
         <element name="marketingText"
            type="textarea"
            label="collateralMarketingTextPrompt"
            property="cols=&quot;50&quot; rows=&quot;5&quot; wrap=&quot;physical&quot; 
               onKeyDown=&quot;limitTextArea(this.form.marketingText, 4000);&quot; 
               onKeyUp=&quot;limitTextArea(this.form.marketingText, 4000);&quot;" />
      
      </section>
      

      Update the code block to change the display order. The updated code block will resemble the following:

      
      <section name="imageDescriptionSection" enabled="true" expand="false">
      
         <element name="collateralURLSegment"
            type="custom"
            page="/tools/campaigns/CollateralURLSegment.jsp" />
      
         <element name="marketingText"
            type="textarea"
            label="collateralMarketingTextPrompt"
            property="cols=&quot;50&quot; rows=&quot;5&quot; wrap=&quot;physical&quot; 
               onKeyDown=&quot;limitTextArea(this.form.marketingText, 4000);&quot; 
               onKeyUp=&quot;limitTextArea(this.form.marketingText,4000);&quot;" />
      
         <element name="location"
            type="text"
            label="collateralLocationPrompt"
            value="collateral.location"
            property="size=&quot;50&quot; maxlength=&quot;254&quot;" />
      
      </section>
      
    6. Save the file.
  2. When you create a custom XML file to update the interface, you must 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:
    1. Change to the WC_eardir/xml/tools/campaigns directory.
    2. Copy WC_eardir/xml/tools/campaigns/CollateralUniversalDialog.xml to the new WC_eardir/xml/myCustomXML/tools/Campaigns/ directory. Do not change the file name.
    3. Open the new resources.xml file in an editor.
    4. Scroll down to the "XML file mappings" section of the file, and update the Content dialog entry so that it matches the following sample:
      
      <!-- Content dialog -->
      <resourceXML name="CollateralUniversalDialog"
          file="/xml/myCustomXML/tools/campaigns/CollateralUniversalDialog.xml" />
      

      where myCustomXML represents your custom directory name.

    5. Save the file.
  3. 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 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:
    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/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 may overwrite any changes made to this file.

  4. Test your customization in your development environment. To complete this test:
    1. Stop and restart your development WebSphere Commerce instance.
    2. Launch the WebSphere Commerce Accelerator.
    3. From the Marketing menu, select Content.
    4. Click New to create a new content. The new fields should display on the resulting Content dialog. 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.
  5. 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. Transfer the following files to your production environment:
      /xml/myCustomXML/tools/campaigns/CollateralUniversalDialog.xml
      Copy to WC_installdir/xml/tools/custom
      /xml/myCustomXML/tools/campaigns/resources.xml
      Copy to WC_installdir/xml/tools/custom
    3. Update the WebSphere Commerce configuration file, so that it reflects the updated XMLPath value.
  6. Package and deploy the updated assets.
  7. Restart your WebSphere Commerce instance.