When developing widgets, you might want to implement the ability to switch among various modes, for example, edit, view, help, and print modes. This article provides some suggestions about how to switch widget modes.

When developing widgets, you might want to implement the ability to switch among various modes, for example, edit, view, help, and print modes. This article provides some suggestions about how to switch widget modes.

By default, widgets that are provided with Mashup Center provide the ability for you to switch between edit and view modes. When the widget is in view mode, you can click the display menu and select Edit Settings to open the widget in edit mode. Both widget modes are visible on the page. However, only the edit mode has focus. After you edit the settings and click Save, the onModeChanged event gets fired, and the edit mode closes, leaving only the view mode available on the page.

Now let us talk about how you can add custom modes such as view and edit modes to your widgets

Step 1: Updating the widget definition file

The first step in the process of creating custom modes is to update the widget definition XML file (widget.xml) that controls the mode-switching code. Here is an example of how you can define the content for three modes: view, edit, and print:

Step 2: Defining event handlers for each mode

After you update the widget definition file, the next step is to define the event handlers for each custom mode. To help illustrate how to accomplish this, let us look at an example widget that allows users to view IBM® stock quote data from multiple brokers. You can select among multiple brokers and display the latest data for each broker. Here is what the widget looks like in view mode:

Notice how the widget's default broker is Ameritrade. Now let's look at what happens when you want to select a different broker.

When you click Edit Broker, the widget fires the following onModeChanged event:

As a result, the widget switches to edit mode. In edit mode, you can select a different broker in a list, as shown here:

When the widget in view mode fires the onModeChanged event, the widget framework replaces the widget in view mode with the widget in edit mode. The framework also invokes the event handler of the onedit event, which is used to initialize the data for the new mode. In the following example, the onedit event is defined in an encapsulation class, gets broker from some specified attributes, and finally sets the broker to be the default one:

onedit:function(){

var element = this.iContext.getElementByClass("brokerSelection");

var attributesItemSet = this.iContext.getiWidgetAttributes();

var broker = attributesItemSet.getItemValue("broker");

if (typeof broker == "undefined" || broker == null) return;

element = element [0];

for (var i=element.options.length-1; i <em </em>= 0;i--) {

var value = element.options [i].value;

if (value != null && value == broker) {

element.options [i].selected = true;

}

}

}

Now, still in edit mode, let us say you select Etrade as the broker and click Done. This switches the widget back to view mode, as shown here:

In this case, the widget defines an onview event handler in an encapsulation class. This reinitializes the data for the widget in view mode so that the data that is changed in edit mode can be picked up in view mode.

Step 3: Using APIs

See the following table for how to use APIs:

Table 1. APIs

API

Description

this.iContext.iEvents.fireEvent

("onModeChanged",

null, "{newMode:'edit'}");

Switches widget modes.

var mode = iContext.getiDescriptor

().getItemValue

("mode");

Retrieves the current widget mode.

serviceManager.getService

("eventService").fireEvent

(targetWidget,"onModeChanged",

"{newMode:'edit'}");

Invokes new widget modes in other page components such as the skin widget.

serviceManager.getService

("eventService").fireEvent

(targetWidget,"onModeChanged",

"{newMode:'edit'

,rootElementId:domNode}");

Provides a root node in the event payload so that the new widget mode gets rendered under the new root node.