Create and test IBM iWidgets using Rational Application Developer

Rational Application Developer now includes tools to create, edit, deploy and test iWidgets

Learn to use rich IBM® Rational® Application Developer tools to create, edit, deploy, and test IBM® iWidgets. Learn to test the markup, wiring, and event handling capabilities of your iWidgets within Rational Application Developer without the need for a separate mashup center.


Prasad M. Kashyap (, Advisory Software Engineer, IBM China

photo of Prasad KashyapPrasad Kashyap works for Rational Application Developer within IBM. He designed and implemented the tools for Rational Application Developer that this tutorial covers.

07 September 2010

Also available in Chinese

Browser-based component model widgets

The word "widgets" can mean different things, but the most common definition in the context of software development is that a widget is a reusable component. Although we can create widgets from the Dojo toolkit, Swing Set, Standard Widget Toolkit, or Abstract Window Toolkit (AWT), and so forth, those widgets need a framework under which they can run. For example, Dojo widgets can run only if the core Dojo library is present.

There is another class of widgets that can be deployed once but embedded in any web application and can run in different browsers. These browser-based component models encapsulate web content and can be used in content presentation frameworks. They can be reused in building situational applications and in typical mashup environments.

These components act as a wrapper for any web content that you create. Any technology that can produce web content, such as servlets, JavaServer™ Pages (JSPs), HTML, PHP, CGI, and so on, can be wrapped. The component provides only a specification, and the descriptor is written to that specification. This descriptor wraps the web content and allows it to be placed in another application that can typically render web content.

Although the reusable nature is common across these component widgets, they also offer a rich set of other features that might be unique to them. These features are available only when they are deployed inside an application that runs the widget's container.

There are three such component models, listed here in decreasing order of popularity but not necessarily in the richness of their features or the merits of their technologies:

  • OpenSocial gadgets
  • IBM® iWidgets
  • OpenAjax mashable widgets

At the heart of all these widgets is just an XML file. This widget definition can be supported by JavaScript, CSS, JSP files, and so on. These files (the widgets) can be deployed as a WAR (web archive) file, on server A, for example. The URL address of the XML (on server A) is registered with the widget container on server B. Another application on server C can now embed this widget by using <script> tags.

OpenSocial gadgets

The OpenSocial gadgets trace their lineage to Google gadgets. The Google Maps gadget is one of the most popular and ubiquitous gadgets. This is an example of a gadget that is deployed in one web application but is embedded or reused in others. Google's gadgets were originally written to a specification that has now become outdated. Google, along with others, formed the OpenSocial Foundation (IBM is a member), which has a new core gadget specification. The OpenSocial gadget API is an extension to this core gadget API.

Gadgets run inside a gadget container. Apache's Shindig is an OpenSocial container, which means it can run OpenSocial gadgets, as well as core gadgets. Many open social websites, such as Orkut and hi5, have their own OpenSocial containers, too. Similar to legacy Google gadgets, many OpenSocial gadgets are freely developed and contributed by users around the world. Listing 1 shows an example of a simple Hello World gadget.

Listing 1. A Hello World gadget
<?xml version="1.0" encoding="UTF-8" ?> 
<Module> <ModulePrefs title="hello world example" /> <Content type="html"> <![CDATA[ <script type="text/javascript" src="optional.js" /> <script type="text/javascript> function dummy() { }; </script> Hello, world! ]]> </Content> </Module>

IBM iWidgets

IBM iWidgets are enterprise level, cross-browser component models that offer a rich set of features. They are written to the iWidget specification from IBM. The iWidgets run inside an iWidget container. The IBM® Lotus® Mashup Center can be used to create a situational application with mashed-up pages (pages that combine two or more applications or widgets). The mashed-up pages can be created by using iWidgets and OpenSocial gadgets. The iWidgets can be wired together so that they can exchange data. Listing 2 shows an example of a simple Hello World iWidget.

Listing 2. A Hello World iWidget
<?xml version="1.0" encoding="UTF-8" ?>
<iw:iwidget id="helloWorld" xmlns:xsi=""
supportedModes="view" mode="view" lang="en">
  <iw:resource src="optional.js" id="jsId" />
  <iw:content mode="view">
      <div>Hello World</div>

Many IBM products, such as WebSphere® Application Server Business Process Monitor and Lotus® ConnectionPlace, include a widget container. This enables the iWidgets to be run inside of these products, too.

Lotus has released Mashup Builder Version 2.2, which can run iWidgets written to the v2.0 specification.

There are quite a few tools to develop iWidgets, with varying degrees of complexity and features, such as these tools:

  • Lotus iWidget Factory
  • sMash from Project Zero
  • Domino Designer Version 8.1
  • IBM® Rational® Application Developer Version 7.5.4 or later

The Rational Application Developer iWidget tooling integrates well with other tools in this software to develop JavaScript, JSPs, and so forth. A novice iWidget developer can use the iWidget editor in this tool to help with validation and error corrections, and an advanced developer can find the content-assist and type-ahead features of the Dojo and iWidget APIs in the JavaScript files quite useful. Also, advanced developers can find a greater granularity of control over the iWidget files that get generated and ease-of-use in tweaking them.

After creating and editing the iWidget in Rational Application Developer, developers can then use the integrated iWidget client to test the iWidget. This test client obviates the need for a product such as Lotus Mashup Builder or WebSphere Application Server Business Process Monitor or other software that has a widget container. The developer can quickly and easily churn out tested iWidgets and later use them in any product. The test client can be used to test the iWidget markup and rendering for different modes under different widget sizes, to test the iWidget wiring, and to test the iWidget's event handlers.

OpenAjax mashable widgets

The OpenAjax Alliance seeks to standardize AJAX development. IBM is a founding member of this alliance. The final specification for OpenAjax Metadata 1.0 has been approved and released. The alliance maintains an open source reference implementation and test suite for various technologies relevant to OpenAjax Metadata 1.0. At this writing, the open source project provides:

  • A formal language schema, expressed in RELAX NG compact syntax
  • A client-side JavaScript implementation of an OpenAjax Widget loader
  • Sample OpenAjax widgets
  • A mashup-authoring environment that includes the OpenAjax Widget loader and uses OpenAjax Hub 2.0 as the secure mashup framework, where widgets are isolated from each other into secure sandboxes
  • API metadata converters, such as a tool that converts JavaScript files with JSDoc inline comments into the OpenAjax API metadata

The OpenAjax Hub 2.0 is used in the iWidget container of the IBM Mashup Center.

Creating an iWidget

In the previous section of this article, you learned about the different types of widgets, such as Dojo widgets, OpenSocial gadgets, IBM iWidgets and OpenAjax widgets. In this section, you will use tools in Rational Application Developer to create an iWidget.

Starting with Rational Application Developer v7.5.4, there are tools available to create, edit, and test iWidgets.

Create a web project with an iWidget facet

An iWidget can be created either in a static web project or a dynamic web project.

  1. In Rational Application Developer, select File > New > Project, and begin by creating one of these projects.
  2. Fill in the project name and target the project to an appropriate server run time that you want.
  3. Next, choose any configurations that you want, or simply use the default.
  4. Click the Modify button to add or remove facets. This button is to the right of the Configurations drop-down menu (see Figure 1).
Figure 1. Create new dynamic web project
New Dynamic Web Project wizard
  1. Find the iWidgets facet in the list and select the check box next to it (see Figure 2).
  2. Click OK to return to the project-creation wizard.
  3. Then click Finish to kick off the project creation process.
Figure 2. Add iWidget facet
Project Facets view

Larger view of Figure 2.

Create an iWidget inside of your project

  1. Select your project in the Enterprise Explorer and right-click on any selected item.
  2. From the drop-down menu, select New > iWidget (Figure 3).
Figure 3. Launch the iWidget wizard
Shows selections on drop-down menus

Larger view of Figure 3.

The New iWidget wizard opens, as shown in Figure 4.

Figure 4. "Create a new iWidget" view in the wizard
Simple Widget selected as widget type

The default iWidget name suggested is the name of the project with a running counter appended to it. You can change the name to anything that you choose. You can either append the file type, .xml, to your widget name or not, as you prefer.

The source folder is the folder in which your iWidget will be created. The prefilled default value for this field is the name of the folder selected in the Enterprise Explorer, which you right-clicked to launch this wizard, but only if that folder is a valid folder under the web root of your project. If it is not a valid folder, then the web root folder of your project is prefilled. Most commonly, this defaults to "WebContent."

You can change the name of the source folder and use the Browse button next to it to browse to a source folder. You cannot create a widget in the WEB-INF or META-INF directories. Validation checks will catch and flag such errors.

The iWidget type drop-down menu offers you a choice of four templates to choose from to start creating your iWidget. The templates give you a working copy of an iWidget XML and JavaScript with stubbed-out functions. These are the four templates available in this version:

  • Simple iWidget: A Hello World iWidget with no JavaScript
  • Event publisher iWidget: An iWidget with an event that sends out data
  • Event subscriber iWidget: An iWidget with an event that receives data
  • iWidget with JSP content:An iWidget whose markup is defined in an external JSP file. The JSP file is inserted by AJAX into the iWidget by a JavaScript file. This type does not show in a static web project.

The Edit check box adds a mode called "edit" to the iWidget that you are creating. A mode is a section of markup that an iWidget renders at run time. When an iWidget is running, you can switch between modes to display different markups. Some modes might not have any markup (or it could be hidden), yet might process something in the background. An iWidget can have many modes. The "view" mode is the default and the only required mode. The "edit" mode is another common mode. You can define any number of custom modes after the iWidget is created.

  1. You can now click Finish to let Rational Application Developer create your widgets.

The following artifacts are created:

  • iWidget XML file: This is the widget definition file.
  • JavaScript file: This file dojo declares your iWidget object that is placed in the iContext's scope. It contains stubs for the widget's predefined iEvents. This is not created for a simple iWidget type in the wizard.
  • JSP file: This is created only for the "iWidget with JSP content" template type in the wizard. This is used to show how the JavaScript can refer to other resources.
  • catalog.xml file: This file is created for the first time and then updated for every iWidget. It contains an entry for every iWidget. It is used when the iWidget is deployed to a Mashup Center.
  • file: This defines the context root and component name of the iWidget. It is used by the Mashup Center.

Editing an iWidget

The iWidget that you created from a template is just a stub. This section introduces you to the iWidget editor. It provides a safe and easy way to edit the iWidget description XML and thereby add, remove, or modify its functionality. The editor performs a few more validation checks that the Source view tab cannot catch.

Using the iWidget editor

As soon as the iWidget is created, the XML opens in the iWidget editor. By default, the iWidget XML file will always open in this editor (see Figure 5).

Figure 5. iWidget Editor view
A form to edit the iWidget definition

Larger view of Figure 5.

i18n alert

The labels in this editor correspond to the element and attribute names in the iWidget XML. Therefore, none of the labels in this editor are translated.

The tree at the left side of the editor shows the DOM elements inside of the iWidget XML. The input boxes to the right show the attributes for each selected element in the tree.

Labels for required fields are denoted with an asterisk. You can add elements to the tree by clicking the Add button to get the Add Item selection window (Figure 6).

Figure 6. Add Item view
List of options, Content selected

At least one Content element is required. View mode is also required.

The iWidget specification requires that an iWidget have at least one Content element, and that content element must have its mode attribute set to View. In short, an iWidget must have the View mode. If the View mode is deleted, then the editor flags an error (see Figure 7).

Figure 7. Error when all Content elements are deleted (View mode required)
Example of an error message

Larger view of Figure 7.

Modes must be unique

Modes are used to specify different markups. Multiple modes can be created by adding more content elements. When you add a new content element, select it in the tree and you will see its attributes on the right. You can either type in a name for the mode attribute or use the Set mode helper. For this example, click the Set mode helper.

Figure 8. Set Mode view
Setting a new mode, iWidget Editor window

Larger view of Figure 8.

The modes must be unique within that XML document. If this restriction is violated, the editor flags an error.

Figure 9. Error message if the mode is not unique
Small error notice pops up

Larger view of Figure 9.

All defined modes must be listed in the supportedModes attribute

  1. All the modes in the iWidget definition XML should also be listed as a string, separated by a blank space, in the supportedModes attribute of the root element. (See the field labeled "Supported Modes" in Figure 5.)

As soon as a new mode is created, the editor reminds you to synchronize the Supported Modes field (Figure 10).

Figure 10. Synchronize Supported modes reminder message
Supported Modes must list all defined modes

Larger view of Figure 10.

  1. Click the Update button next to the Supported Modes field to see your new mode displayed in the list.
  2. The Mode field is a drop-down menu that shows all of the modes defined in the iWidget XML. Select the mode that you want your iWidget to render when it first loads. By default, this is the View mode.

Testing an iWidget

In this section, you will import a sample iWidget that is included in Rational Application Developer and run it on the Rational Application Developer Universal Test Client for iWidgets. An iWidget is actually meant to be run in an IBM Mashup Center or in an IBM product that includes the iWidget container. But the test client provides a similar environment in which the iWidget can be run.

The test client can be used to test the following features of your iWidget:

  • Markup and rendering
  • Mode switching
  • Event handling
  • Event publishing
  • Event subscription

The reason that we are deploying the StockWidgetSample application for this example is because it has a full iWidget sample. All of the features of the Universal Test Client can be better explored and understood with a full iWidget under test.


Import the application

Import the file into Rational Application Developer (see Downloads section).

Create a server

If you do not have a server instance already created for deployment, you must now create one.

  1. Click the Servers tab and go to the Servers view.
  2. Right-click inside of that view and select New.
  3. In the wizard that pops up, expand the IBM group, and choose the AJAX Test Server (ATS).
  4. Then click Finish.

The AJAX Test Server is available only from Rational Application Developer v8.0 and later. For Rational Application Developer v7.5, you can use the "J2EEPreview Server" under the Basic category or any of your favorites.

Deploy the sample application

  1. Deploy the StockWidgetSample application to the server instance that you created in the previous step.
  2. Right-click on the server and select Add and Remove.
  3. In the wizard that pops up, add the StockWidgetSample application and click Finish.
  4. Start the server: Right-click on the server instance that you created, and select Start.

Launch the iWidget in the Universal Test Client for iWidgets

  1. In Enterprise Explorer, expand the WebContent directory of the sample application.
  2. Right-click on the stock.xml file and select Run As > Run on Server.
  3. In the wizard page that opens, choose the AJAX Test Server or any other server in which you have deployed your sample.
  4. Click Finish.

This will launch the stock.xml iWidget in the Universal Test Client for iWidgets.

Test client features

Let's look at the various features of the test client.

Widget name

In the toolbar at the top of the widget (Figure 11), the widget name is shown with a hyperlink. This name is the unique ID of the iWidget.

Figure 11. Name of the widget under test
Toolbar segment with iWidget name

Click the link to open the widget that is deployed on the server. This can be used to confirm that the widget from your workspace was deployed and synchronized with the server.

Show the URL

This icon (Figure 12), which is in the toolbar bar on the top of the widget, can be used to show the URL of the test client. Click the icon to see the URL in a pop-up window. You can copy and paste this URL to your favorite browser for purposes such as debugging.

Figure 12. Show URL icon
Globe icon

Refresh the iWidget

The icon in Figure 13, which you can find in the top toolbar, can be used to refresh just the iWidget, without reloading the entire test client.

Figure 13. Refresh Widget icon
Refresh symbol, with two arrows

Show Modes

This icon (Figure 14) is visible only if the iWidget has more than one mode. Clicking on this icon will produce a drop-down list of modes. Use this to switch between the modes.

Figure 14. Show Modes list icon
Pencil on paper icon to get the list

Resize the iWidget

You can resize the iWidget window and move it around by using the "handle" in the bottom-right corner of the iWidget pane (Figure 15). This is useful to see how the contents in your iWidget will render when the iWidget is sized differently or when it is sized at its final runtime settings (for example, in a Mashup Center).

Figure 15. Resize Handle icon
Triangle of dots to grab in lower-right corner

Test a sample iWidgetNow, test the stock iWidget.

Rending the markup

The iWidget is rendered in the top window of the test client, using the DOM markup in the stock.xml file and the styling from the stock.css file.

  1. Tweak the markup in the stock.xml file or the style attributes in the style sheet.
  2. Wait until the server automatically synchronizes, or republish it yourself.
  3. Reload the test client by using the (internal) browser's Reload icon, or refresh the iWidget by using the test client's Refresh icon.

You will see your changes rendered.

Switching modes

Using the Modes icon, switch between the various modes. See how the content in different modes will render for a given iWidget size. For this sample stock widget, you can switch to the Edit mode and change the broker preference. When you submit your preference, the widget reloads the View mode with data from the new broker.

Handling events

Apart from the iWidget sending and receiving events, which you will see later on, the iWidget can handle various standard events, such as onLoad, onUnload, onView, and so forth. The stock.js file has event handlers stubbed out for all of these kinds of events. Tweak these with the event handler. Put an alert or a console.debug (string) statement in them. Synchronize your changes with the server and reload or refresh the iWidget. When those events are fired, you can test your handler.

Event wiring

In a typical mashup environment, an iWidget is usually wired to other iWidgets so that they can communicate by publishing and subscribing to events from each other. The data that the iWidgets exchange is called payload. A payload can be of standard type, such as string, date, or time, or it can be a custom data structure. You can simulate the publishing and subscription of events from your iWidget in the test client. Events can be wired only under any of the following conditions.

  • If their payload types match
  • If at least one of the widgets participating in the wiring has the payload type of "Any" (an Any payload type is like a wildcard that can map to any other payload type)

Event Explorer

The test client provides an Event Explorer iWidget (Figure 16). This is the right-most widget of the three widgets in the bottom row of the test client. This widget will be maximized only if the iWidget has events to publish. All publishing events from the widget under test will be wired to the Event Explorer widget. The Event Explorer widget receives events of the Any payload type. Although it can receive events from almost all publishing widgets, it needs to convert the data to a string to display it. It looks for and uses the toString() function on the incoming data.

The stock widget sends an event of the stockData custom payload type. But stockData has a toString() function that the Event Explorer can use.

Figure 16. Event Explorer
The Event Explorer widget receives data

Event Generator

The test client can be used to simulate the handling of data by the widget under test when the events come over a wire. If the widget under test has events that handle data, then the Event Generator widget and Event Log widget are maximized in the bottom row of the test client, as Figure 17 shows. Otherwise, they remain minimized.

Figure 17. Event Generator and Event Log widgets
Helper widgets generate data for the test widget

Larger view of Figure 17.

The Event Generator widget is to the left and can send events to the test widget. The Event Log widget at the right logs the events that were sent to the test widget.

For every event that the test widget handles, the Event Generator widget has a corresponding event of the same payload type. These events are wired together. Also, the Event Generator widget has another event of the Any payload type, which is wired to all events in the test widget.

Figure 18. Events sent from the generator widget
Specific events in the test widget can be targeted

When each event is selected in the drop-down menu of the Event Target column, the event's payload type displays in the Data Type column. In the Data column, the input field changes appropriately. For example, if the payload type is Time, then the input field changes to a time picker Dojo dijit. If the payload type is Date, then the input field changes to a calendar dijit. So an appropriate payload type is sent over the wire from the generator widget to the test widget.

The event wiring section, previously, has the conditions under which two events can be wired. As long as the conditions are met, the widget container will allow the wiring to take place. However, that by itself will not mean that the valid data is coming over the wire. The event handler in the widget that is receiving the event must check for validity of the data as soon as it receives it.

For example:

  1. Select the Time event in the drop-down menu of the Event Target column, and the input field in the Data column will change to a time-picker dijit.
  2. Pick a time to see it in the input field.
  3. Now mess it up by adding alpha characters in it.

The dijit will warn you that the field value is invalid. When the event is sent to the test widget, the test widget should know how to recognize and handle such invalid data, , but the stock widget does not recognize and handle such invalid data just to prove this point.

  1. Use the Add Event button to add another similar row.

Now multiple event targets can be targeted at the same time. When you click Send Events, data will be sent to the event targets selected in each row.

The check box icon in the beginning of the row can be used to enable or disable the row. Data from disabled rows will now be sent when the Send Events button is clicked.

The trash can icon in the end of the row can be used to delete the row.

Event Log widget

The Event Log widget keeps a log of all the events that were sent from the Event Generator. Multiple rows in the table can be selected. When the Resend button is clicked, those events are again sent to the test widget. The Clear button clears the table. See Figure 17.

For more useful information on these topics, check the Resources section, where you will also find links to learn more ways that you can use Rational Application Developer,


Sample file for this articleStockWidgetSample.zip11KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Create and test IBM iWidgets using Rational Application Developer