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:
<iw:content mode="view"> --> this view displays company name, stock price and
broker name <! [CDATA [
<div><span id="company" class="companyLabel">loading...</span>
Stock Quote: <span id="stock">loading...</span></div>
<div>Broker:
<span id="broker">loading...</span></div>
<div><input type="button"
name="send" value="Send Data"
onclick="iContext.iScope().sendData()"/></div>
<div><input type="button" name="configure" value="Edit Broker"
onclick="iContext.iScope().editBroker()"/></div>
]]>
</iw:content>
<iw:content mode="edit"> --> this view could be
used to edit broker <! [CDATA [
<div> <select class="brokerSelection"
size="1">
<option value="Etrade">Etrade</option>
<option selected value="Ameritrade">Ameritrade</option>
</select> </div>
<div><input type="button" name="done"
value="Done" onclick="iContext.iScope().switchBroker();"/></div>
]]>
</iw:content>
<iw:content mode="print"> --> this view could be used to edit broker
<! [CDATA [
print mode
]]>
</iw:content>
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:
this.iContext.iEvents.fireEvent("onModeChanged",null, "{newMode:'edit'}");
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. |