Develop > Presentation layer > Customize IBM Sales Center > Controls

Managed composites and widget managers

The individual user interface elements in the IBM Sales Center user interface are controls, for example, labels and entry fields. However, the groups of controls in the IBM Sales Center, for example, a group of labels and fields where a user enters address information, are known as composite controls. A composite control can be combined with one or more widget managers to create a managed composite. A managed composite is declared using the com.ibm.commerce.telesales.widgets.managedComposites extension point. A managed composite is constructed using the managed composite factory. Initialization information will be passed to the managed composite factory and will be available to the widget managers. The composite and its child controls are constructed and events are delegated to the widget managers. There will be several levels of composite controls including other composite controls before you reach a top level composite control that will be the composite referred to in the managed composite. The widget managers will be responsible for supplying behavior for all of the controls under this top level composite.

The behavior of the controls on the IBM Sales Center user interface is managed by widget managers. A widget manager is declared using the com.ibm.commerce.telesales.widgets.widgetManagers extension point. Widget managers initialize, refresh, save, and dispose of configured controls. They are also responsible for providing the content of table cells. Complex behavior can be added to controls by widget managers by adding listeners and handlers to the control during initialization. A standard widget manager is provided with the IBM Sales Center and is used with standard controls and tables. When a configured control is defined, it can be declared with a manager type. The manager type is read by the widget manager to decide if the control should be managed by the widget manager. Widget managers will only manage controls that have a manager type that they recognize. If a control does not declare a manager type, then it is assumed to be "standard".

Widget managers and managed composites

• Widget managers

  • Java code used to manage the behavior of widgets

  • Can only manage widgets associated with composite definitions

  • Extension point: com.ibm.commerce.telesales.widgets.widgetManagers

• Managed composites

  • The association between widget managers and composite definitions

  • Extension point: com.ibm.commerce.telesales.managedComposite

Widget managers and widget lifecycle

Widget managers are responsible for managing the widget lifecycle:

• Initialization

• Disposal

• Activation

• Deactivation

• Refresh

• Saving of contents

More than one widget manager can be associated with a managed composite:

• Widget should be handled by only one manager

• Widgets specify a managerType during declaration

  • Widget manager should check this value before acting on the widget

    if (configuredControl != null && configuredControl.getManagerType().equals(getManagerType()))
    

Widget manager hierarchy

A new widget manager must implement the IWidgetManager interface.

Start by extending the StandardWidgetManager class.

This provides the appropriate framework for managing the lifecycle of the widgets.

• AbstractWidgetManager implements the IWidgetManager interface

• StandardWidgetManager provides additional methods useful for customizations

Widget manager key methods

The widget manager is responsible for determining how the controls will behave based on system events. Init, dispose and refresh are key events that happen and these methods should be overwritten in a custom widget manager to respond accordingly.

• init(ConfiguredComposite, WidgetManagerInputProperties)

  • Initializes the WidgetManager

• deactivate()

  • Called when the editor or dialog loses focus

• initControl(ConfiguredControl)

  • Initializes the individual controls

  • Checks to see if the manager is of the right type

  • Can add listeners if required

• disposeControl(ConfiguredControl)

  • Remove resources related to the control

  • Can remove listeners that were added during initControl()

• refreshControl(ConfiguredControl)

  • Refreshes the control based on information found in the widget manager's input properties

  • Can enable a field based on a value

  • Can set focus on a field

Saving values from a user interface element

StandardWidgetManager

provides a default implementation of the saveControl

and saveColumnText

methods.

These methods automatically save the data in the control to the modelPath

location defined in the attribute on the control. Refresh may be called when:

• An editor or dialog page is created, activated or refreshed

• An IWidgetManager.EVENT_REFRESH is fired

• WidgetManagerInputProperties is modified

Values entered in a widget must be saved to the model object. There are two methods that you can use to save:

• IWidgetManager.saveControl or IWidgetManager.saveColumnText

  • saveControl called when the framework fires IWidgetManager.EVENT_SAVE or ManageComposite.save runs

• By using the modelPath property defined on the control extension point StandardWidgetManager provides the default implementation to save to the modelPath

  <control type="text" id="recipientField"
  modelPath="salescontainer.receiptName"
   userData="true" managerType="orderGiftPageManager"/>
  

Widget manager input property

Every WidgetManager contains a WidgetManagerInputProperties object. WidgetManagerInputProperties is used to facilitate communication between widgets in a dialog or editor. Any time the WidgetManagerInputProperties is changed, the refresh method on the WidgetManager is called. This allows the developer to determine how to respond to changes in the input properties.

• Facilitates communication between widgets in an editor or dialog

• Widget manager's refresh method is called when the object is modified

• Prevents hard coding relationships between widgets

Example: WidgetManagerInputProperties

Listeners are used to capture events when an object changes. The listener, recipientModifyListener_, retrieves the widget manager's WidgetManagerInputProperties object and sets the value of the text in the recipient text field as a property on WidgetManagerInputProperties.

When the widget manager needs to check a value in the input properties, use the getData() method to retrieve the value. Remember, calling setData() on WidgetInputProperties will automatically invoke the refresh method on the WidgetManager causing the refreshControl() method to be called.

You create a listener to capture a text change and set the widget manager's input properties. The code exists inside of the widget manager. The method, getInputProperties(), retrieves the widget manager's input properties, for example:

private ModifyListener recipientModifyListener_ = new
ModifyListener(){
                public void modifyText(ModifyEvent e){
                        Text text = (Text) e.widget;                        
getInputProperties().setData(RECIPIENT_NAME_VALUE, text.getText());                 }               
        };

To check the value in the input properties use: Object object = getInputProperties().getData(RECIPIENT_NAME_VALUE);

Extend and customizing widgets

• Create new widgets by extending an 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

Related concepts

Controls

Input properties and model path

New and existing widget managers

Dialogs

Editors

Overview of customizing IBM Sales Center

Related tasks

Declare a widget manager

Replace a widget manager

Declare a managed composite

Modify a managed composite

Modify a dialog

Modify a page in an editor

Add a dialog

Move a user interface element between dialogs or editor pages

+

Search Tips   |   Advanced Search