Defining custom page modes

When developing widgets, you may want to implement the ability to switch between multiple modes, for example edit and view modes. This article provides some suggestions for how to accomplish this.

Let's use a scenario as an example. Let's say you are creating a widget that allows users to view IBM stock quote data from multiple brokers.

Now let's look at the widget definition XML file that controls the mode-switching code. Here is an example of how you can define the content for the two modes:

 

<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
 

The widget allows users to select among multiple brokers and display the latest data for each broker. Here is what the widget looks like in view mode:



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 drop-down list, as shown here:



When the widget in view mode fires the onModeChanged event, the widget framework catches the event, and it essentially 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 the iWidget encapsulation class, gets broker from some specified attributes, and finally sets the broker to 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 
 = 0;i--) { 

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

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

               
    element.options[i].selected = true; 

              } 

          } 

     } 

Now, still in edit mode, let's 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 the 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.

You can retrieve the current mode of your widget by using the following API:
 

var mode = iContext.getiDescriptor().getItemValue("mode");

You can also use other page components such as the skin widget to switch the widget mode by using the following API:
 

serviceManager.getService("eventService").fireEvent(targetWidget,"onModeChanged",
"{newMode:'edit'}"); 

In addition, you can add a root node to the event payload so that the new mode gets rendered under the new root node, as shown here:

serviceManager.getService("eventService").fireEvent(targetWidget,"onModeChanged",
"{newMode:'edit',rootElementId:domNode}");