Example: Adding a user interface element using default WebSphere Commerce customization fields

Many WebSphere Commerce database tables have extra columns available for customization; these columns are labeled FIELD x, for example FIELD1, FIELD2, and FIELD3. You can use these fields to add custom data to existing IBM Sales Center messages without making any changes to WebSphere Commerce Server. To do this customization, use the UserData element combined with existing custom controller command request parameters.

The following tables show some objects commonly customized in the IBM Sales Center. Note that these tables are only examples; you can customize other fields, provided that the tables contain customizable columns (FIELD1, FIELD2, and FIELD3).

For the Address model object:

For the Customer model object:

For the Organization model object:

For the Product model object:

For example, the USERS table has three fields: FIELD1, FIELD2, and FIELD3 which are not used by WebSphere Commerce and can be used for customization. These fields are exposed in the WebSphere Commerce controller commands by assigning the values to predefined request parameters. In the case of the USERS table, the "UserRegistrationAdminAddCmd" controller command will map the "userField1", "userField2", and "userField3" request parameters to the corresponding custom fields in the USERS table.

These custom fields and custom controller command parameters can be used to customize IBM Sales Center by taking advantage of the UserData mappings that have been declared as part of the mappings found in:

• WC_eardir/xml/messaging/webservice_SOABOD_template.xml
• workspace_dir\wc\xml\messaging\webservice_SOABOD_template.xml

For example, adding the following UserData element to the CreateCustomer BOD message will cause "SILVER" to be saved in FIELD1 of the USERS table:

<wc:UserData>
   <wc:UserDataField
name="userField1">SILVER</wc:UserDataField>
</wc:UserData>

The response builders have been coded to populate the UserData element with the relevant custom field information, so once the value "SILVER" is saved into FIELD1 of the USERS table, the ShowCustomer response message will include a user data field where userField1 has a value of "SILVER".

The service request handlers in the IBM Sales Center client have also been designed to handle the management of new data in the UserData area of the Business Object Documents without modification. The request handlers create the request messages using data found in model objects and transform the response back into model objects. Model object properties can be marked as UserData properties. This tells the request handlers to include these properties in the UserData area for requests. Any fields found in the UserData element in the response will be stored in the relevant model object and marked as user data properties. If a chosen property name corresponds to a custom controller command request property, then a new property can be sent to the server and returned in the response without making any changes on the server or to the request handlers on the client.

The IBM Sales Center client includes support for marking properties as user data properties when the value is saved into the model. By choosing an existing custom controller command request property as the name of the model object property, then a new field can be added to the user interface without making any changes to the model, request handler, or server.

The following example adds a new field "Preferred customer rating" to the Identity page of the Customer editor. The field is a combo box that has three possible values: GOLD, SILVER, and BRONZE. The selected value is stored in USERS.FIELD1 because the property name is "userField1". This is the plugin.xml of a new plugin called 'extensions':

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin>

   <!--
     Configurator extension point. The configurator file
     must include the following entries to replace the default
     and B2B customer identity composite definitions with the
     ones defined in this plug-in.
        
    
com.ibm.commerce.telesales.ui.impl.customerIdentityCompositeDefinition.default=extensions.customerIdentityCompositeDefinition.default
    
com.ibm.commerce.telesales.ui.impl.customerIdentityCompositeDefinition.B2B=extensions.customerIdentityCompositeDefinition.B2B
   -->
   <extension
         point="com.ibm.commerce.telesales.configurator">
      <configurator path="config"/>
   </extension>

   <!-- Composite definitions for the Customer editor's
"Identity" page. -->
   <extension
point="com.ibm.commerce.telesales.widgets.compositeDefinitions">
      <formCompositeDefinition
         id="customerIdentityCompositeDefinition.default"
        
referenceId="com.ibm.commerce.telesales.ui.impl.customerIdentityCompositeDefinition.default">
         <control
controlId="customerPreferredCustomerComposite">
            <topAttachment
               offset="15"
              
relativeControlId="com.ibm.commerce.telesales.ui.impl.customerPrimaryContactComposite"/>
            <leftAttachment
               offset="0"
               numerator="0"/>
            <rightAttachment
               offset="-15"
               numerator="50"/>
         </control>
      </formCompositeDefinition>

      <formCompositeDefinition
         id="customerIdentityCompositeDefinition.B2B"
        
referenceId="com.ibm.commerce.telesales.ui.impl.customerIdentityCompositeDefinition.B2B">
         <control
controlId="customerPreferredCustomerComposite">
            <topAttachment
               offset="15"
              
relativeControlId="com.ibm.commerce.telesales.ui.impl.customerPrimaryContactComposite"/>
            <leftAttachment
               offset="0"
               numerator="0"/>
            <rightAttachment
               offset="-15"
               numerator="50"/>
         </control>
      </formCompositeDefinition>
   </extension>

   <!-- Control and composite definitions for the preferred
customer area on the Customer editor "Identity" page. -->
   <extension
point="com.ibm.commerce.telesales.widgets.controls">
      <control
         id="customerPreferredCustomerComposite"
         type="composite"
        
compositeDefinitionId="customerPreferredCustomerCompositeDefinition"/>
      <control
         id="customerPreferredCustomerLabel"
         type="label"
         text="Preferred customer rating"
         font="org.eclipse.jface.bannerfont"/>
      <!-- The new combo field sets userData to "true" and uses
"userField1" as the property name. -->
      <control
         id="customerPreferredCustomerField"
         type="combo"
         tooltip="Preferred customer rating"
         modelPath="customer.userField1"
         userData="true"
         editable="false">
         <property name="list">
            <value>GOLD</value>
            <value>SILVER</value>
            <value>BRONZE</value>
         </property>
      </control>
   </extension>
   <extension
point="com.ibm.commerce.telesales.widgets.compositeDefinitions">
      <gridCompositeDefinition
         id="customerPreferredCustomerCompositeDefinition"
        
layoutId="com.ibm.commerce.telesales.ui.impl.standardGridLayout">
         <row id="customerPreferredCustomerRow">
            <control controlId="customerPreferredCustomerLabel"
dataId="com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
            <control controlId="customerPreferredCustomerField"
dataId="com.ibm.commerce.telesales.ui.impl.requiredFieldGridData"/>
         </row>
      </gridCompositeDefinition>
   </extension>

</plugin>