Understanding the IBM Sales Center for WebSphere Commerce's user interface framework

Understanding the IBM Sales Center for WebSphere Commerce's user interface framework

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 and

Controls

Definition vs.

Declaration

In this article, the terms widget and control are used interchangeably. For more information see the help section on Controls .

The definition of a widget is similar to a template that describes a widget and its attributes. For example, a widget’s definition might dictate that a 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= "tr managerType= "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 of

Plug-in definitions controls controlFactories

SWT

Composite composed of created using compositeDefinitions xxxLayouts

Editors /

Dialogs described using layed out 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

plugin 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 /

Dialogs managed by 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

*/ getWidgetManagerInputProperties(); return super.createPageContent(parent);

} protected Control createPageContent(Composite parent) {

WidgetManagerInputProperties widgetManagerInputProperties =

/**

* 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 [email protected]

.

Lorilee Jarosinski is a Software Developer at the IBM Toronto Lab. You can reach her at [email protected]

.

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

Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project