iWidget Overview

This section provides a quick description of the iWidget specification and a simple example of an iWidget.  

The iWidget specification is an IBM standard for defining a common format for widgets. The iWidget specification is implemented in several IBM products, including IBM Lotus® Connections 2.5. To view the complete iWidget specification document, go to the following Web address: http://www-10.lotus.com/ldd/mashupswiki.nsf/dx/iwidget-spec-v1.0.pdf/$file/iwidget-spec-v1.0.pdf  

Lotus Connections supports version 1.0 of the iWidget specification.  

The iWidget XML descriptor  
The core component of any iWidget is its XML descriptor.  

Here is an example of the XML definition of a very basic iWidget. This widget displays the string "Hello world". When the user clicks the Click me button, the string "button clicked" is displayed under the button.

XML definition of a very basic iWidget  

<iw:iwidget name="helloWorld" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"

      iScope="HelloWorldWidgetClass" supportedModes="view">

      <iw:resource uri="helloworld.js" />            

      <iw:content mode="view">

        <![CDATA[

            <div id="root">

                  Hello World! <br/>

                  <button id="click" onclick="iContext.iScope().onClickButton()">Click me!</button>

                  <div id="placeHolder"></div>

            </div>

        ]]>

     </iw:content>    

</iw:iwidget>

  

        
This XML definition includes the following attributes.  

Table 1: iWidget attributes    

Attribute	Description
iScope	The name of an instance of the declared JavaScript™ class. This class is the JavaScript class written by the widget developer, which implements the logic behind the widget.   An instance of this class is automatically created by the iWidget framework and associated with the iWidget. The code of the backing class can be implemented in one of the JavaScript resource files using the iw:resource attribute.
iw:resource	Points to the resources needed by the iWidget. These resources are loaded dynamically and evaluated by the iWidget framework.
iw:content	Provides the widget markup (HTML code) and displays it to the end-user. There can be several different modes corresponding to different views supported by the widget.

 

The following screenshot shows how the widget is rendered when deployed in Lotus Connections.   

 
Note: The XML descriptor only defines the body part of the widget. The title bar and chrome around the widget body rendered using the above code sample are generated and added automatically by the Lotus® Connections widget framework.  


iContext and iScope objects  
The iWidget framework automatically inserts an object name, iContext, in to each widget iScope object as a member (this.iContext). The iContext can be used by the widget developer to interact with the iWidget framework, as in the onClickButton method in the following example.  

Declaration of the iScope class in "pure" JavaScript

var HelloWorldWidgetClass = function(){

      this.onLoad = function(){

            // your initialization code here

      }

     

      this.onClickButton = function(){         

            this.iContext.getElementById("placeHolder").innerHTML = "button clicked";

      }

}

 

Declaration using the Dojo JavaScript toolkit

dojo.provide("HelloWorldWidgetClass");

 

dojo.declare("HelloWorldWidgetClass", null,{

      onLoad: function () {

            // your initialization code here

      },

 

      onClickButton: function(){

            this.iContext.getElementById("placeHolder").innerHTML = "button clicked";

      }

});

 

Name-value pairs with itemsets  
An item set is a set of name-value pairs that is managed by the iWidget framework. You can declare item sets in the XML definition of your widgets.  

For example:

<iw:itemSet id="itemSet1">

      <iw:item id="item1" value="value1" />

      <iw:item id="item2" value="value2" />

</iw:itemSet>

 

ItemSets can be manipulated in your code using the iContext object associated with the i Scope object of the widget.  

For example:  

var item1Value = this.iContext.getItemSet("itemSet1").getItemValue("item1");

this.iContext.getItemSet("itemSet1").setItemValue("item1", "new value");

 

More details on the operations allowed on the itemset objects can be found in the iWidget specification document.    

ItemSets are used in Lotus Connections as a way to provide the widget with information related to the e mbedding environments, that is, the Home page, Profiles, and Communities features.    

ItemSets can also be managed, allowing the widget developer to persist preferences across sessions.
 
Widget mode
Lotus Connections supports the standard view and edit modes, as defined in the iWidget specification. The iWidget is responsible for providing a way to go back to the normal (or any other) view. An iWidget can switch modes programmatically by firing an onModeChanged event.  
   
For example:  

this.exitEditUI = function (controlObj)  
{  
     this.iContext.iEvents.fireEvent("onModeChanged", "", "{'newMode': '" +  
     this.iContext.constants.mode.VIEW + "'}");  
};

 
 

 

Parent topic  
Lotus Connections iWidget Development Guide  

Related topics  
Common iWidget Support in Lotus Connections  
iWidget Support in the Home Page  
iWidget Support in Profiles and Communities  
Best practices for iWidget development  

   

Authors: Vincent Burckhardt and Ronny A Pena