Understanding the IBM Sales Center for WebSphere

Commerce's user interface framework

Bhadri Madapusi
WebSphere Commerce
IBM Toronto Lab

Lorilee Jarosinski
WebSphere Commerce
IBM Toronto Lab

August 9, 2006

© Copyright International Business Machines Corporation 2006. All rights reserved.

This article describes the IBM® Sales Center for WebSphere® Commerce’s user
interface framework. The IBM Sales Center is a rich-client application that is intended
for customer service representatives in a company’s call center. Customer service
representatives can use the IBM Sales Center to efficiently create customers, orders,
quotes, and returns in WebSphere Commerce using a user-friendly interface.

In this article, the architecture of the user interface framework and widget life cycle and
behavior are explained in the context of a use case. Typical customization scenarios are
described within the user interface framework.

This article is for developers and architects who want to understand the IBM Sales
Center’s user interface framework. You should have some knowledge of the Eclipse Rich
Client Platform and the Standard Widget Toolkit.

Introduction ......................................................................................................................... 2
Problem definition and solution .......................................................................................... 2
Definitions and terms .......................................................................................................... 3
Example use case ................................................................................................................ 3
Overview of the framework architecture ............................................................................ 4
User interface element definitions................................................................................... 5
Managing the controls..................................................................................................... 7
User interface framework runtime .................................................................................. 8
Interpreting the declarations and creation of user interface elements ........................... 10
Managing widget life cycle and behavior ......................................................................... 10
User interface elements life cycle ................................................................................. 12
Creating and initializing user interface elements .............................................................. 12
Activating user interface elements .................................................................................... 12
Refreshing user interface elements ................................................................................... 13
Saving the value from a user interface element ................................................................ 14
Deactivating user interface elements................................................................................. 15
Disposing of user interface elements ................................................................................ 15
Widget manager input property..................................................................................... 16
Extending and customizing widgets.................................................................................. 17
Creating new widgets by extending existing widget..................................................... 17
Modifying properties of an existing widget .................................................................. 18
Deleting existing widgets .............................................................................................. 18
Modifying the behavior of an existing widget .............................................................. 19
Modifying the layout of existing widgets ..................................................................... 20
Reusing existing widgets from another place ............................................................... 20
Loading the samples.......................................................................................................... 21
Conclusion......................................................................................................................... 23
Resources .......................................................................................................................... 23
About the authors .............................................................................................................. 23

Introduction
The IBM Sales Center for WebSphere Commerce is an application for customer service
representatives to capture and manage customer orders. This application has a client
component and a server component. The client user interface is developed using the
Eclipse Rich Client Platform (RCP) and the Standard Widget Toolkit (SWT).

Organizations that use the IBM Sales Center will want to customize and extend the
client’s user interface, for example, to add custom fields and text that do not display by
default. A framework has been developed to minimize the customization and extension
work. This article will help developers understand the IBM Sales Center user interface
framework.

The IBM Sales Center user interface framework provides set of plug-in extension points,
other supporting classes, and a programming model that developers can use to create,
customize, and extend the contents of editors and dialogs inside the IBM Sales Center.

Problem definition and solution

The IBM Sales Center user interface framework is designed to solve the following
problems:

Problem: Organizations using the IBM Sales Center might want to customize and extend
the client user interface, especially the widgets and the behavior of the widgets in an
editor or a dialog. Customization that involves modifying or extending the default
shipped code cost time and money, and changes to the default shipped code, for example
in a fix pack or migration, may break the customization.
Solution: This user interface framework helps ensure that the customization is done
efficiently and will not be broken by future enhancements to the base code. The ability to
create, customize, and extend client user interface elements inside editors, dialogs, and
views uses as little code as possible. The framework is designed to reduce the
development effort for the following tasks:

• Change the layout of the user interface.

• Remove existing element or add new elements.
• Change the default behavior of an element.

Problem: The IBM Sales Center for WebSphere Commerce uses SWT to create the user
interface elements inside the editors and dialogs. To maintain the same look and feel, all
the user interface elements of the same type, for example, all text boxes must follow the
same pattern of creation and maintenance.

Solution: The IBM Sales Center user interface framework helps avoid the problem of
multiple developers using different approaches to creating and maintaining user interface
elements, which might result in duplication of code and non-conformance to user
interface standards. The framework is a common mechanism to create and maintain the
SWT elements, resulting in user interface standards conformance and reduction of code
duplication.

Definitions and terms

Widgets In this article, the terms widget and control are used interchangeably. For
and more information see the help section on Controls.
Controls
Definition The definition of a widget is similar to a template that describes a widget
vs. and its attributes. For example, a widget’s definition might dictate that a
Declaration widget must have a label field.

The declaration of a widget is an instance of a widget, including the

specific values for its attributes. For example, a widget’s declaration might
dictate that the label field’s name is “senderAddress”.

Example use case

This article will describe the IBM Sales Center user interface framework architecture
using the following use case: You must add a new editor page called the Gift Card
Information to the IBM Sales Center order editor. This page must have four fields as
illustrated in Figure 1. You must enable and disable the fields based on the state of the
order. The assets for this page are in the example plug-in project packaged in the
example.zip file. See the Loading the samples section for more information.
Figure 1. The gift card information page

Overview of the framework architecture

The IBM Sales Center user interface framework consists of a set of plug-in definitions
and supporting classes. The look and the layout of the user interface are defined in the
plug-in extensions. The life cycle and behavior of the user interface elements is managed
by the Java™ code in the supporting classes. The framework runtime interweaves the
user interface elements described in the plug-in extensions with the behavior defined in
the Java code to produce the layout and the behavior of the user interface elements in the
editors and dialogs. Figure 2 illustrates this interweaving.

Figure 2. Interweaving of presentation and behavior

User interface element

definition
(defined as plug-in
extensions)
Framework
runtime
Java Code
(Manager that handles
the life cycle and
behaviour of the user
interface elements)
User interface element definitions

The editors and the dialogs in the IBM Sales Center user interface are composed of a
collection of SWT widgets organized as a Composite.

The IBM Sales Center user interface framework provides the

com.ibm.commerce.telesales.widgets.controls plug-in definition to describe the widgets,
and the com.ibm.commerce.telesales.widgets.controlFactories plug-in definition to
describe the widget factory that creates the widgets. At runtime, a widget is created using
the factory with which it is associated. Having a factory create the widgets reduces
duplication of code and provides a common look and style for all the widgets created in
the IBM Sales Center.

Listing 1 illustrates the declaration for the user interface elements of gift card information
shown in Figure 1. Listing 1 also illustrates the declaration of the control factories
relevant to the user interface elements in Figure 1.

Listing 1. Declaration for the user interface elements and its factory
<extension point="com.ibm.commerce.telesales.widgets.controls">
<control text="OrderSummaryPage.giftCardTitle" type="label"
id="giftOrderTitleLabel" />
<control text="OrderSummaryPage.giftCardRecipientName" type="label"
id="recipientLabel"/>
<control type="text" id="recipientField" modelPath="salescontainer.receiptName"
userData="true" managerType="orderGiftPageManager"/>
<control text="OrderSummaryPage.giftCardSenderName" type="label"
id="senderLabel"/>
<control type="text" id="senderField" modelPath="salescontainer.senderName"
userData="true" managerType="orderGiftPageManager"/>
<control text="OrderSummaryPage.giftCardMessage1" type="label"
id="message1Label"/>
<control type="text" id="message1Field" modelPath="salescontainer.msgField1"
userData="trmanagerType="orderGiftPageManager"/>
<control text="OrderSummaryPage.giftCardMessage2" type="label"
id="message2Label"/>
<control type="text" id="message2Field" modelPath="salescontainer.msgField2"
userData="true" managerType="orderGiftPageManager"/>
<control type="composite" id="giftOrderGridComposite"
compositeDefinitionId="giftOrderGridCompositeDefinition"/>
</extension>

<extension point="com.ibm.commerce.telesales.widgets.controlFactories">
<controlFactory id="com.ibm.commerce.telesales.widgets.textControlFactory"
factoryClass="com.ibm.commerce.telesales.widgets.controls.TextControlDescriptorFac
tory" controlType="text"/>
<controlFactory id="com.ibm.commerce.telesales.widgets.labelControlFactory"
factoryClass="com.ibm.commerce.telesales.widgets.controls.LabelControlDescriptorFa
ctory" controlType="label"/>
<controlFactory id="com.ibm.commerce.telesales.widgets.compositeControlFactory"
factoryClass="com.ibm.commerce.telesales.widgets.controls.CompositeControlDescript
orFactory" controlType="composite"/>
</extension>

The IBM Sales Center user interface framework uses the SWT layout architecture to
position the widgets. You can describe the layouts using the
com.ibm.commerce.telesales.widgets.typeLayouts plug-in definition, where type is either
form, grid, row, or stack. The layouts are set on a SWT Composite. In this framework,
SWT Composites are described using the
com.ibm.commerce.telesales.widgets.compositeDefinitions plug-in definition. Listing 2
illustrates the declaration for the layout and the composite definition relevant to the user
interface elements shown in Figure 1.

Listing 2. The declaration for the composite definition and layout

<extension point="com.ibm.commerce.telesales.widgets.compositeDefinitions">
<gridCompositeDefinition id="giftOrderGridCompositeDefinition"
layoutId="com.ibm.commerce.telesales.ui.impl.tableCompositeGridLayout">
<row id="giftOrderGridCompositionRow">
<control controlId="giftOrderTitleLabel"
dataId="com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"
/>
</row>
<row id="giftOrderRecipientGridCompositionRow">
<control controlId="recipientLabel"
dataId="com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
<control controlId="recipientField"
dataId="com.ibm.commerce.telesales.ui.impl.findTextFieldGridData"/>
</row>
<row id="giftOrderSenderGridCompositionRow">
<control controlId="senderLabel"
dataId="com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
<control controlId="senderField"
dataId="com.ibm.commerce.telesales.ui.impl.findTextFieldGridData"/>
</row>
<row id="giftOrderMsg1GridCompositionRow">
<control controlId="message1Label"
dataId="com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
<control controlId="message1Field"
dataId="com.ibm.commerce.telesales.ui.impl.findTextFieldGridData"/>
</row>
<row id="giftOrderMsg2GridCompositionRow">
<control controlId="message2Label"
dataId="com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
<control controlId="message2Field"
dataId="com.ibm.commerce.telesales.ui.impl.findTextFieldGridData"/>
</row>
</gridCompositeDefinition>
</extension>

<extension point="com.ibm.commerce.telesales.widgets.gridLayouts">
<gridLayout
id="tableCompositeGridLayout"
marginHeight="0"
verticalSpacing="5"
horizontalSpacing="5"
marginWidth="8"
makeColumnsEqualWidth="false"/>
</extension>
Figure 3 illustrates how the above plug-ins are associated with each other.

Figure 3. Relationship between the user interface element plug-in definitions

composed Plug-in definitions

of
controls controlFactories
SWT created
Composite composed using
of

compositeDefinitions xxxLayouts
Editors / described
Dialogs layed out
using using

Managing the controls

The life cycle and the behavior of the widgets inside of an editor or a dialog are managed
by widget managers. The widget managers are plain old Java code. For a widget manager
to control a set of widgets, the widgets must be associated with the compositeDefinitions
that you use to compose an editor or a dialog. The association between
compositeDefinitions and widget managers is described using the
com.ibm.commerce.telesales.managedComposite plug-in definition. The encapsulation of
composite description and its managers is called a managed composite and is represented
in the framework as ManagedComposite class. The list of widget managers present in the
system is defined using the com.ibm.commerce.telesales.widgets.widgetManagers plug-
in definition. Listing 3 illustrates the declaration for the managed composite for the
composite giftOrderGridComposite. Figure 4 illustrates the relationship between an
editor or a dialog and its managed composite.

Listing 3. The declaration for the gift card managed composite

<extension
point="com.ibm.commerce.telesales.widgets.managedComposites">
<managedComposite compositeId="giftOrderGridComposite"
id="orderGiftPageManagedComposite">
<widgetManager id="orderGiftPageManager" />
</managedComposite>
</extension>

<extension
point="com.ibm.commerce.telesales.widgets.widgetManagers">
<widgetManager
managerClass="example.OrderGiftPageManager"
id="orderGiftPageManager"/>
</extension>
Figure 4. Relationship between an editor or a dialog and its managed composite
composed of
one
compositeDefinitions

managedComposite

managed by
widgetManagers
Editors / managed by
Dialogs multiple

User interface framework runtime

The user interface framework runtime is responsible for:

1. Interpreting the widget, composite, and layout declarations defined in the plug-ins
and creating the appropriate widgets and layouts using the factory methods.
2. Controlling the life cycle of the widgets by delegating to the appropriate widget
managers defined in the plug-ins.

The framework is invoked when the ManagedCompositeFactory.

createManagedComposite method runs to create the SWT Composite that contains the
content of an editor or a dialog. Typically, a call to the
ManagedCompositeFactory.createManagedComposite method is made in either
xxxDialog.createDialogArea or xxxEditorPage.createPageContent, where xxx is the
editor or dialog type, such as FindProduct, with the help of the editor page base class,
TelesalesConfigurableEditorPage.createPageContent. The call to the
ManagedCompositeFactory.createManagedComposite method creates the appropriate
widgets and layouts using the factory methods and associates the managers that control
the life cycle to the widgets. Figure 8 illustrates the class and the sequence diagram for
the framework invocation.
Figure 8. Class and the sequence diagram for the framework invocation

To construct the user interface element shown in Listing 2, the

GiftInformationEditorPage class must call the
ManagedCompositeFactory.createManagedComposite as illustrated in Listing 4.

Listing 4. Code snippet for the GiftInformationEditorPage

public class GiftInformationEditorPage extends TelesalesConfigurableOrderPage {

/**
* Gift page managed composite name. Value is
<code>example.orderGiftPageManagedComposite</code>.
*/
public static final String MANAGED_COMPOSITE_ID = "example.orderGiftPageManagedComposite";
/**
* Creates an editor page instance.
*/
public GiftInformationEditorPage () {
super();
}
/**
* Creates the order shipment information page content. This method calls the
* <code>ManagedCompositeFactory</code> to create the page content
* @param parent parent composite.
* @return Composite that contains the page contents.
* @see com.ibm.commerce.telesales.ui.editors.EditorPage
*/
protected Control createPageContent(Composite parent) {
WidgetManagerInputProperties widgetManagerInputProperties =
getWidgetManagerInputProperties();
return super.createPageContent(parent);
}
/**
* Returns the button bar managed composite ID. Subclasses must implement this method.
* @return the button bar managed composite ID
*/
protected String getPageContentManagedCompositeId() {
return MANAGED_COMPOSITE_ID;
}
}

For the complete listing of the above code snippet see the example.zip file.
Interpreting the declarations and creation of user interface
elements

The managed composite declarations and user interface element declarations are
processed by the framework in the following order:

1. The managed composite declaration is read first. In the gift card information
example, the managed composite orderGiftPageManagedComposite is read first.

2. The composite in the managed composite is then constructed by obtaining the

information about the composite from the composite definition. In the gift card
information example, the composite giftOrderGridComposite, which is associated
with the managed composite orderGiftPageManagedComposite managed
composite, is constructed using the composite definition
giftOrderGridCompositeDefinition.

3. While the composite is constructed, the widgets in the composite definition are
constructed by their associated factories. In the gift card information example, the
giftOrderTitleLabel, recipientLabel, recipientField controls and so on are
constructed by the factory associated with the control based on their type attribute
in the declaration. As per the declaration in Figure 2, the giftOrderTitleLabel
which is a type of label, will be created by the factory
LabelControlDescriptorFactory.

4. Once the widgets are constructed, the display layout is set on the composite that
controls them. In the gift card information example, the layout
tableCompositeGridLayout layout is set on the composite
giftOrderGridComposite.

5. The manager that manages the composite is associated with the composite. In the
gift card information example, the manager example.OrderGiftPageManager is
associated with the composiste giftOrderGridComposite.

6. The framework then passes the control to the Eclipse editor or dialog framework
to display the controls on an editor or a dialog.

Managing widget life cycle and behavior

The widget life cycle is managed by the manager associated with the managed composite.
The manager is responsible for the initialization, disposal, activation, deactivation,
refreshing, and saving of the widgets' content.

You can associate a managed composite with one or more widget managers. If a
managed composite is associated with more than one widget manager, then the widgets
and the managers should establish a contract with each other so that one widget is
handled by one manager. The widget establishes the contract with the manager by having
the manager name as the value of managerType. The manager reciprocates by managing
only the widgets that has its name as the managerType value.

In the gift card information example, the recipientField establishes the contract with the
example.OrderGiftPageManager by having the orderGiftPageManager as the value for its
managerType property. At runtime, the example.OrderGiftPageManager must check if
the recipientField widget’s managerType matches its name before it manages the widget.
The code snippet in Listing 5 illustrates how the example.OrderGiftPageManager class
checks for the widgets that it should handle during widget initialization.

Listing 5. Code snippet that makes sure the manager handles the right widget
public class OrderGiftPageManager extends StandardWidgetManager {
/**
* Order shipment page manager type. Value is
<code>"orderGiftPageManager"</code>.
*/
public static final String MANAGER_TYPE_ORDER_GIFT_PAGE =
"orderGiftPageManager";
/**
* Field type property name. Value is <code>"fieldType"</code>. This
property is associated with
* a field control. The value of this property is used to uniquely
identify the control.
*/
public static final String INPUT_PROP_FIELD_TYPE = "fieldType";
/**
*Recipient text identifier's <code>fieldType</code> property value.
Value is * <code>"recipientField"</code>.
*/
public static final String RECIPIENT_TEXT = "recipientField";
public OrderGiftPageManager() {
setManagerType(MANAGER_TYPE_ORDER_GIFT_PAGE);
}
/**
* Initialize the specified control.
*/
public void initControl(ConfiguredControl configuredControl) {
if (configuredControl != null &&
configuredControl.getManagerType().equals(getManagerType()))
{
String fieldType = (String)

configuredControl.getProperty(INPUT_PROP_FIELD_TYPE);
if (RECIPIENT_TEXT.equals(fieldType)) {
initRecipientControl(configuredControl);
} else if ( …
}
}
super.initControl(configuredControl);
}
}
…
}

All the managers must implement the IWidgetManager class. The IBM Sales Center user
interface framework provides the following widget managers: AbstractWidgetManager
and StandardWidgetManager. The AbstractWidgetManager is a convenient base class
that other managers can use. The StandardWidgetManager is the default manager
provided by the framework. The framework uses this manager to manage the widgets that
have a value for managerType property.

User interface elements life cycle

A widget’s life cycle is tied to the life cycle of an editor page or a dialog. The
ManagedComposite acts as the mediator between an editor page or a dialog, and the
managers that are associated with the managed composite. Each editor page or a dialog is
associated with a managed composite.

Creating and initializing user interface elements

The user interface’s elements and managers are created and initialized when an editor or
a dialog page is created and is encapsulated in the ManagedComposite class. The
managers must provide implementation for its initialization (in IWidgetManager.init) and
must provide implementation for the initialization of the widgets it manages
(IWidgetManager.initControl). Typically, the addition of listeners to the widgets must be
done during the initialization of the widgets. Figure 6 illustrates the initialization call
sequence.

Figure 6. Widget and Manager initialization call sequence

Activating user interface elements

An editor (or the pages in the editor) or a dialog is activated when it gets focus from the
mouse or keyboard. Whenever an editor or a dialog is activated, the user interface
elements in the editor or the dialog may be activated and refreshed to react to any state
changes. For widgets to react to state changes, the managers must provide
implementation for the IWigetManager.activate and IWidgetManager.refreshControl
methods. The sequence diagram in Figure 6 illustrates the initialization call sequence.

In the gift card information example, the widgets in the gift card information editor page
of the order editor must enable or disable themselves when the editor page is activated
based on the state of the order. This implementation is provided in the
OrderGiftPageManager.refreshControl method (see the code in the example.zip file).

The sequence diagram in Figure 7 illustrates the activation call sequence.

Figure 7. Widget activation call sequence

Refreshing user interface elements

The state and content of the widgets in an editor or a dialog can change frequently. For
example, a widget may be enabled are disabled based on some external state, or based on
another widget in the same editor. You must implement all refreshes to the widgets in the
IWidgetManager.refreshControl method. By default, the framework calls the managed
composite’s refresh as follows:

1. After an editor or a dialog page is created.

2. When an editor or a dialog is activated.
3. When an editor or a dialog is refreshed.
4. When IWidgetManager.EVENT_REFRESH is fired.
5. When WidgetManagerInputProperties is modified.
You can refresh the widgets at anytime. The sequence diagram in Figure 7 also illustrates
the refresh call sequence.

Saving the value from a user interface element

You must save the value that is entered in a widget back to the model object. The
implementation to save the values from the widget to the model object must be in the
IWidgetManager.SaveControl and IWidgetManager.SaveColumnText method. The
StandardWidgetManager provides a default implementation for these methods by saving
the value in the widget to the path specified by the modelPath. The widgets in the gift
card information page use the default implementation to save the data into its model
object.

The framework calls the IWidgetManager.SaveControl method whenever

IWidgetManager.EVENT_SAVE fires or when the ManagedComposite.Save method
runs. The StandardWidgetManager calls the manager’s save method whenever the widget
(valid only for text and combo widgets) is modified.

You can call the ManagedComposite.Save method anytime to save the values based on
your requirements. For example, in the gift card information page, the page contents are
saved to the model when the Submit button or Save and Close button is selected. When
the Submit button is selected the OrderEditorButtonManager fires the
EVENT_ID_SUBMIT_ORDER. When the Save and Close button is selected, the
OrderEditorButtonManager fires the EVENT_ID_CLOSE_ORDER. The
GiftInformationEditorPage class handles these events by calling the framework save
method.

The sequence diagram in Figure 8 illustrates the save call sequence for saving the widgets
in the gift card information page.
Figure 8. Sequence diagram for saving the gift card information

Deactivating user interface elements

An editor (or the pages in the editor) or a dialog is deactivated when it loses focus. The
framework provides a call back to the widget manager whenever an editor (or the pages
in the editor) or a dialog is deactivated. The widget manager may choose to make state
changes to the widgets it manages upon deactivation. The sequence diagram in Figure 9
illustrates the deactivation call sequence.

Figure 9. Widget manager deactivation sequence

Disposing of user interface elements

You must dispose of the user interface elements when an editor or a dialog is closed. The
framework provides a call back to the widget manager whenever an editor (or the pages
in the editor) or a dialog is disposed. Typically during disposal, the widget manager must
remove all the listeners that were added to the widgets during initialization. The sequence
diagram in Figure 10 illustrates the disposal call sequence.

Figure 10. Widget disposal call sequence

Widget manager input property

In the gift card information page, you may want to disable the sender name, message1,
and message2 widget if the recipient name widget contains no data. One strategy is to
disable the sender name, message1, and message2 in the recipient name widget’s modify
listener. However, this strategy is flawed because if either the sender name, message1, or
message2 widget is removed from the user interface using the IBM Sales Center
customization strategy, then the widget may not be initialized and will not be available to
the recipient name widget’s modify listener. This triggers a runtime exception.

To accomplish the use case described above without directly referencing one widget in
the other, the framework provides a model object called WidgetManagerInputProperties.
This object facilitates communication between the widgets in an editor or a dialog and the
framework by calling the manager’s refresh method whenever the object is modified. The
manager must refresh the widgets that it manages appropriately based on the change to
property.

The above mentioned use case is coded in the OrderGiftPageManager class using the
WidgetManagerInputProperties model object instead of directly referencing one widget
in the other. The recipient name widget’s modify listener adds the recipient name
widget’s value into the WidgetManagerInputProperties model object, which triggers the
manager’s refresh method. In the refresh method, the manager enables the sender name,
message1, and message2 widget if the WidgetManagerInputProperties model object
contains the recipient name value. To view this source code, load the sample plug-in as
described in the Loading the sample code section.

The WidgetManagerInputProperties model object is also used to pass any input to the
managers from the Eclipse RCP editor and dialog framework.
Extending and customizing widgets
The IBM Sales Center user interface framework allows the following customization
inside editors and dialogs:

• Create new widgets by extending existing widget.

• Modify properties of an existing widget.
• Delete existing widgets.
• Modify the behavior of an existing widget.
• Modify the layout of existing widgets.
• Reuse existing widgets in another place.

The following use cases describe the above mentioned customization and extension in the
context of the gift card information example, and how the IBM Sales Center user
interface framework supports this customization and extension. To view the source for
the extension, create a plug-in named example.extension in your IBM Sales Center
development environment, and unzip the contents of the example.extension.zip file.

Creating new widgets by extending existing widget

Use case: Create a new widget with the same look as the recipient name label and text,
but with a different behavior than the existing recipient name.

Framework support: The controls plug-in definition, compositeDefinition plug-in

definition, and managedComposite plug-in definition all have an attribute called
referenceId. At runtime, the framework first checks if the controls declarations, the
ompositeDefinition declarations, or the managedComposite declarations have value for
referenceId. If the declarations have value for the referenceId, then the referencing
declaration will inherit the properties and attributes from the reference declaration.
Anything defined in the referencing declaration will override the value inherited from the
reference declaration.

In the example.extension plug-in project, you can find the following control declaration
that extends the existing recipient name widget, but uses the StandardWidgetManager to
provide its behavior. By default, this extended widget is always enabled.
<control referenceId="recipientLabel" id="referencedRecipientLabel"/>
<control
managerType="standard"
modelPath="salescontainer.receiptName"
referenceId="recipientField"
id="referencedRecipientField">
Modifying properties of an existing widget

Use case: The label text “Name of Sender” must be modified to “Sender’s Name”.

Framework support: The framework provides the system configurator framework,

which you can modify for an existing widget. You can use the system configurator
framework on any plug-in definition that has an identifier. For each declaration, the
framework runtime will check the configurator file for a replacement. If there is a
replacement, then the framework runtime uses the replacement identifier declaration.

In the example.extension plug-in project, you can find the following control declaration
that extends the existing sender name label to provide the new text for the label property.
<control text="Sender's Name" type="label" id="modifiedSenderLabel"/>

In the system configuration file, usually called config.ini, you can see the following
definition:
example.senderLabel=example.extension.modifiedSenderLabel

When the framework reads the example.senderLabel declaration, it replaces the

example.senderLabel declaration with the declaration of
example.extension.modifiedSenderLabel, which displays the new label text instead of the
old one.

The replacement identifier example.extension.modifiedSenderLabel may be a dynamic

identifier, in which case the framework will resolve the replacement identifier using the
resolver class before executing the declaration.

For example, if you want the label to change based on the store type (B2B or B2C), then
you can create two separate sender label descriptor: one for B2B and one for B2C. Then
you can use the dynamic resolver class StoreTypeSensitiveIdResolver to resolve the label
at runtime based on the store type.

Deleting existing widgets

Use case: Delete the Message 1 widget.

Framework support: The framework provides the system configurator framework, to

delete an existing widget. To delete a widget, assign a null value to the widget identifier
in config.ini. The following declaration in the system configurator file, usually called
config.ini, will delete the message 1 widget:

message1Label=null
message1Field=null
At runtime, the framework will remove all the widgets assigned with null from the
composite.

Modifying the behavior of an existing widget

Use case: Modify the behavior of the sender’s name.

Framework support: You can accomplish this in the same way as Modify properties of
an existing widget. In this case, you have to modify the managerType of the senderName
field using the same mechanism described in Modify properties of an existing widget and
provide an implementation for the new manager.
<control
referenceId="example.senderField"
id="referencedSenderField"
managerType="senderFieldManager">
</control>

In the system configuration file, usually called config.ini, add the following text:
example.senderField=example.extension.referencedSenderField.

For the framework to pick up the new manager, create a new managed composite that
refers to the existing managed composite, and add the new manager to this new managed
composite as follows:
<extension
point="com.ibm.commerce.telesales.widgets.managedComposites">
<managedComposite id="extendedOrderGiftPageManagedComposite"
referenceId="example.orderGiftPageManagedComposite">
<widgetManager id="senderFieldManager" />
</managedComposite>
</extension>

<extension point="com.ibm.commerce.telesales.widgets.widgetManagers">
<widgetManager
managerClass="example.SenderFieldManager"
id="senderFieldManager"/>
</extension>

You must let the framework know that it has to use the new managed composite instead
of the old one using the system configurator file, usually called config.ini.
example.orderGiftPageManagedComposite=example.extension.extendedOrderGi
ftPageManagedComposite

At runtime, the framework will use the managers in

example.orderGiftPageManagedComposite to manage the widgets, except the
senderName field. The framework will use example.SenderFieldManager to manage
the sender field.
Note: The manager has to respect the contract between the widget and itself and manage
only the widgets it is supposed to manage. This is done by the line in red in the code
snippet illustrated Listing 5.

Modifying the layout of existing widgets

Use case: Add the referencedRecipientLabel and the

referencedRecipientField to the Gift Card Information page.

Framework support: Change the composite definition using the referenceId and system
configurator as follows:
<extension
point="com.ibm.commerce.telesales.widgets.compositeDefinitions">
<gridCompositeDefinition
referenceId="example.giftOrderGridCompositeDefinition"
id="extendedGiftOrderGridCompositeDefinition">
<row id="referencedGiftOrderRecipientGridCompositionRow">
<control controlId="referencedRecipientLabel"
dataId=
"com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
<control controlId="referencedRecipientField"
dataId=
"com.ibm.commerce.telesales.ui.impl.findTextFieldGridData"/>
</row>
</gridCompositeDefinition>
</extension>

In the system configuration file, usually called config.ini, see the following text:
example.giftOrderGridCompositeDefinition=example.extension.extendedGift
OrderGridCompositeDefinition.

Reusing existing widgets from another place

Use case: Use the “Confirm By Email” widget from the Payment editor page on the Gift
Card Information page.

Framework support: All the widgets and layouts have a unique identifier. Reusing a
widget is as simple as using the identifier in the desired editor or dialog. For this use case,
we reuse the com.ibm.commerce.telesales.ui.impl.orderEmailRow row to include
the Confirm By Email widget from the Payment editor page into the Gift Card
Information page.
<extension
point="com.ibm.commerce.telesales.widgets.compositeDefinitions">
<gridCompositeDefinition
referenceId="example.giftOrderGridCompositeDefinition"
id="extendedGiftOrderGridCompositeDefinition">
 <row id="referencedGiftOrderRecipientGridCompositionRow">
<control controlId="referencedRecipientLabel"
dataId=
"com.ibm.commerce.telesales.ui.impl.requiredLabelGridData"/>
<control controlId="referencedRecipientField"
dataId=
"com.ibm.commerce.telesales.ui.impl.findTextFieldGridData"/>
</row>
<row
referenceId="com.ibm.commerce.telesales.ui.impl.orderEmailRow">
</row>
</gridCompositeDefinition>
</extension>

In the above section, you saw how using referenceId, system configurator framework,
and dynamic identifier can perform a number of simple customization and extension to
the user interface elements.

Loading the samples

The sample code provided demonstrates the user interface changes described in this
article. The code is not an end-to-end example of a Gift Card information scenario and
does not include any command implementation to support Gift card information function.

There are two sample files: sample.zip and sample.extension.zip. The sample.zip file
contains a plug-in that defines a new order editor page called the Gift card information,
including the fields and labels on the page. The sample.extension.zip file contains
extensions to the code in the sample.zip file, as described in this article.

To load the sample files into your IBM Sales Center development environment:

1. Unzip the sample.zip file to a temporary directory.

2. Create a plug-in:
a. Open your IBM Sales Center development environment
b. Click File > New > Plug-in Project.
c. In the New Plug-in Project wizard, in the Project name field, enter
example.
d. Select the Create an OSGi bundle manifest for the plug-in check box.
e. Click Next.
f. Click Finish.
3. Import the sample code:
a. In the Project Explorer view, right-click on the example plug-in and select
Import.
b. Select File system and click Next.
c. In the From directory field, navigate to the temporary directory into
which you unzipped the sample.zip file.
d. Select all the files as shown in Figure 11.
Figure 11. Selecting files

e. Click Finish.
4. Repeat Steps 1-3 with the example.extension.zip file.

Tip: To run the IBM Sales Center client with only the example plug-in and not the
example.extensions plug-in:

1. Click Run > Run.

2. In the Plug-ins tab, select Choose plug-ins and fragments to launch from the
list.
3. Clear the check box next to the example.extensions plug-in.
4. Click Apply.
Conclusion
This article introduced the IBM Sales Center user interface framework. The framework
helps developers maintain a common look and feel in the user interface, and ensures that
any customization is made efficiently and is not broken by future changes to the base
code. User interface elements have a life cycle that is managed by the widget manager,
which can include events such as activation, refresh, saving a value, deactivation, and
disposal. You can easily extend and customize widgets, frequently using the system
configurator. A few typical widget customization scenarios were also discussed.

Resources
WebSphere Commerce V6 Information Center provides information and tutorials on the
IBM Sales Center customization.

About the authors

Bhadri Madapusi is a Software Developer working in the IBM Toronto Lab. He earned
his MSc in Information Systems from BITS, India, and his MSc in Computer Science
from Queens University, Canada. His interests include software modeling, design
patterns, and data management. You can reach him at bhadrim@ca.ibm.com.

Lorilee Jarosinski is a Software Developer at the IBM Toronto Lab. You can reach her
at ljrojas@ca.ibm.com.

Trademarks

DB2, IBM, and WebSphere are trademarks or registered trademarks of IBM Corporation
in the United States, other countries, or both.
Windows and Windows NT are registered trademarks of Microsoft Corporation in the
United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of
Sun Microsystems, Inc. in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of
others.

IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml