Quick iWidgets using Rational Application Developer Web 2.0 tools

This article introduces the Web 2.0 tools included with IBM® Rational® Application Developer, which you can use to build iWidget applications quickly.


Ling Luo (luol@cn.ibm.com), Staff Software Engineer, IBM

author photo Luo Ling is an expert on Dojo toolkit development and accessibility technology. He is now focusing on business analysis technologies.

Irma (I.G.) Sheriff (irma@ca.ibm.com), Senior Software Engineer, IBM

author photoIrma Sheriff is a senior software engineer at the IBM Toronto lab. She works on Java and web application development as part of the IBM Software Metrics and Analytics Tooling team. She is currently working on IBM Cognos Framework modeling and is also interested in Web 2.0 and mashup technologies.

15 February 2011

Also available in Chinese Portuguese

iWidget introduction

In general, a widget is a portable, reusable application or piece of dynamic content that can be placed into a web page, receive input, and communicate with an application or with another widget.

An iWidget is a web application that works within the framework that is defined by the IBM® iWidget specification. It is a reusable component that can be deployed in web applications. As a browser-based component model that encapsulates web content, it can be reused in content presentation frameworks. It acts as a wrapper for any web content that you create, such as servlets, JavaServer Pages (JSP) files, HTML, PHP, or CGI.

Widgets often extend a server-side component or are associated with a server-side data source. For example, you can associate a widget with a back-end data source so that users can explore the data within the data source. The iWidget component provides a descriptor that wraps the web content and allows it to be placed in another application that can render the web content.

An iWidget is an XML file. It can contain markup tags that are rendered and can be supported by JavaScript files for dynamic client-side scripting and CSS files for applying styles. JSPs, HTML, or HTML fragments can contain markups, too, which can also be written in Ajax. After the iWidget is in the framework, it can generate and receive client-side events, as specified in the widget wrapper. There are two types of events:

  • A published event, which means that the iWidget publishes some data by this event
  • A handled event, which means the iWidget receives some data from other iWidgets

iWidget specification

The IBM iWidget specification defines a standard way to wrap web content for participation in a mashup environment. The browser-oriented components provide either a logical service to a web page or visualization for users.

The iWidget specification defines characteristics of HTML markup, metadata formats, and JavaScript services for enabling aggregation of iWidget components into a single web application.

The widget specification provides a standard event mechanism, iEvent, that allows iWidgets from disparate sources to communicate with each other. The specification also provides a context mechanism, iContext, which manages the iWidget. This context includes any user interface (UI) controls, coordination between iWidgets, and interaction with the back-end service.

Rational Application Developer Web 2.0 tools

IBM® Rational® Application Developer V8 includes a set of Ajax, Dojo toolkit, and HTML development tools for building Web 2.0 applications using JavaScript, XML, HTML, and CSS. The core HTML, CSS, and JavaScript tools are part of the open source Eclipse Web Tools project.

Development and deployment of IBM iWidgets involves using these application development tools:

  • iWidget creation wizard
  • Integrated test client with debugging support
  • iWidget deployment to IBM Lotus Mashup Center
  • iWidget use in a regular web page

An iWidget facet is available to static or dynamic web projects. It provides templates for creating various types of widgets and can be used by novice or experienced developers.

Creating an iWidget by hand

We begin by showing you how to create a simple Hello World iWidget without using any of the Rational Application Developer Web 2.0 tools.

Create the project

To create an iWidgets project, follow these steps:

  1. Open Rational Application Developer with a new, clean workspace.
  2. From the main menu, select File > New > Project.
  3. In the New Project window, select Dynamic Web Project from the Web folder.
  4. In the New Dynamic Web Project window (Figure 1), enter the project name, for example, com.ibm.demo.helloWorld (see Figure 1). Note: It's not necessary to create a new Enterprise Archive (EAR) project to create IBM Mashup Center iWidgets.
  5. Then click Finish.

The project will be created and displayed in Rational Application Developer.

Figure 1. New Dynamic Web Project window
Dialog window

Create iWidget specific files

A widget requires only a widget definition file, which is an XML file based on the iWidget specification. The XML file specifies the widget resources, data, events, and HTML markup mode. You might also have an optional JavaScript file defining a class that is instantiated to provide functionality for the iWidget.

If you want to deploy your iWidget through the MashupHub, you will need to include two additional files in the WEB-INF directory in addition to web.xml:

  • mashup.properties
  • catalog.xml(see Figure 2)
Figure 2. com.ibm.demo.helloWorld Project files
Mashup Properties and Enterprise Explorer views

To create each of the following files, right-click the parent folder and select New > File.


Create this file under the <project_root>/WebContent/WEB-INF folder.

This properties file (see code Listing 1) should contain two key value pairs:

  • The contextRoot property, which defines the context root for the WAR project
  • The componentName property, which is used by the server during the deployment process.
Listing 1. mashup.properties file
contextRoot=demo/hello componentName=com.ibm.demo.helloWorld


Create this file under the <project_root>/WebContent/WEB-INF folder.

This catalog.xml file contains the iWidget's description and specifies how to access the widget definition XML file (see Listing 2). Each iWidget in the WAR project should have its own entry in the catalog.xml file. The iWidget declaration should follow the IBM Mashup Center requirements and, therefore, contain widget-specific tags, such as title, description, definition, and icon. It provides a place for the globalized title and description information about each widget in the WAR file.

Listing 2. catalog.xml file
<?xml version="1.0" encoding="UTF-8"?> <catalog>
<category name="Demo"> <entry id="HelloWidget" unique
name="HelloWidget"> <title> <nls-string
lang="en"> Hello iWidgets</nls-string> </title>
<description> <nls-string lang="en">iWidget, created by
RAD</nls-string> </description>
</entry> </category> </catalog>

The definition entry points to the iWidget's definition file, and the icon entry points to the image for the iWidget. Both records for the file paths are relative to the <project_root>/WebContent directory.

Definition file

To create this file:

  1. Right-click the <project_root>/WebContent folder and select New > File.
  2. Enter the name of the definition file in the File Name field (for example, HelloWorld.xml), and click Finish.


  • The name of the XML file and its location must match the values specified in the catalog.xml file.
  • The definition file must follow the iWidget specification. The main entries here are <iw:iwidget> and <iw:content> (see Listing 3). The definition file contains the HTML for the widget's user interface.
Listing 3. Definition file
<iw:iwidget id="HelloWorld" 
iScope="HelloWorld" allowInstanceContent="true" 
supportedModes="view edit"
mode="view" lang="en"
> <iw:resource id="jsId" src="HelloWorld.js"
/> <iw:content mode="view"> <![CDATA[ <div
style="color: #aa00ff;" Hello! </div> ]]>
</iw:content> </iw:iwidget>

The <iw:resource> tag is not required. An iWidget can be created that contains only an XML file (for example, when a script is not needed or it is written inside a <script> tag in the XML file). It is best to separate JavaScript code from the widget definition XML file.

The value inside of the tag refers to the iWidget's main resource file, and the path is relative to the declaration file itself. Files referenced by <iw:resource> are loaded by the widget runtime before the widget life cycle starts. You can also use the <iw:resource> tag to load CSS files.

The iScope attribute value of <iw:iwidget> refers to the iWidget's main class. This class is declared in one of the resource files, and its name must match the value of the iScope attribute.

The mode is an iWidget piece of the iContext managed state that tells the iWidget what type of markup to generate for the user. View mode uses normal markup, and Edit mode uses markup for editing the iWidget attributes. If a widget does not support Edit mode, the Edit Settings option on the context menu is disabled. The View mode is required.

Only the View and Edit modes are currently supported in IBM Mashup Center. According to the iWidget specification, widgets can have additional modes, though.

Resource file

To create the resource file:

  1. Right-click the <project_root>/WebContent folder and select New > File.
  2. Enter the name of the resource file, and click Finish; the file displays in Rational Application Developer.

The name of the resource file and its location should match the value specified in the <iw:resource> tag in the definition file covered previously. The only IBM Mashup Center product limitation is that the main class (defined in the <iScope> attribute value of the definition file) must be a Dojo class.

  1. Now add the iWidget's JavaScript source code, shown in Listing 4.
Listing 4. HelloWorld.js source
Dojo.declare("HelloWorld", null, { Id: null, onLoad: function() { 
alert("Hello World!"); } });

Deployment Descriptor file

As shown in Listing 5, edit the web.xml file contained in the <project_root>/WebContent folder to use the welcome list to expose the widget definition file, rather than index.html inside of the WAR package.

Listing 5. web.xml source
<?xml version="1.0" encoding="UTF-8"?> <web-app id="WebApp_ID"
version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
<display-name> Hello World Widget</display-name>
</welcome-file-list> </web-app>

Other files

In the iWidget project, many other files can exist and can be used to customize the iWidget. This will be explained in further detail in the next example, where we put the Rational Application Developer Web 2.0 tools into practice.

Create the iWidget WAR file

To create the WAR file used for deployment to an IBM product that has the iWidget Container, follow these steps:

  1. Right-click <project_root> (the project name) and select Export > WAR file from the drop-down menus (see Figure 3).
Figure 3. Select the WAR file to export
Two drop-down menus
  1. From the next window, expand the Web folder, select the WAR file item, and then click Next.
  2. In the window that displays next, enter the destination information and click Finish.

The WAR file is created in the destination folder.

A quicker way of creating an iWidget

Rational Application Developer Web 2.0 tools provide a quick way of creating iWidgets from scratch. Here are the steps:

  1. Open Rational Application Developer integrated development environment (IDE). (See Figure 4.)
Figure 4. Rational Application Developer IDE
screen capture of workspace
  1. Right-click the Enterprise Explorer view and select New > Project (Figure 5).
Figure 5. Create a project
Explorer view plus two drop-down menus
  1. In the New iWidget Project window, expand the Web folder, choose iWidget Project and then click Next (see Figure 6).
Figure 6. New Project window
Select a Wizard view

In the next window, New iWidget Project, there are two types of technologies to chooose from as the kinds that you want to use with iWidgets (Figure 7). The "Web technologies" option covers only Ajax, HTML, CSS and "etc." technologies. If you chose that one, the project hierarchy should look like Figure 8 after you have created the project.

Figure 7. New iWidget Project dialog
Two options for technology to use with iWidgets
Figure 8. Web technology type project structure
Web technology type project structure
  1. This type of iWidget is not a dynamic Web project, so it could not be exported as a WAR file. Therefore, choose the second type Web and JavaEE technologies.
  2. In the next dialog window for creating an iWidget project (Figure 9), enter the iWidget name. You can choose its runtime target and decide whether to add this project into an EAR file.
Figure 9. New iWidget properties dialog window
Shows options described
  1. If you want to manage the version of the technologies used in this iWidget, click the Manage Features button.
  2. Click Finish.
  3. In the Project Facets window, you can adjust the version of the technologies used in this iWidget.
  4. When you are finished, click OK (see Figure 10).
Figure 10. Project Facets view
Facet and Version columns with check boxes

The project hierarchy should now be like Figure 11.

Figure 11. Final project structure
Enterprise Explorer view

The iWidget project is quickly and automatically created just the same as the one that we did by hand, but easier and faster.

The iWidget Editor

Rational Application Developer 8.0 provides an iWidget editor that you can use to visually fill in the iWidget properties(see Figure 12).

Figure 12. iWidget editor
screen capture of the editor
  1. To add resource files, click Add (see Figure 13), and then click OK.
  2. Then enter the resource attributes to add to this iWidget.
Figure 13. Add resources in the iWidget editor
Editor view overlaying the Explorer view
  1. Add the other resource files, such as CSS files.

Deploy and test the iWidget

  1. To deploy the iWidget on the Lotus Mashup Center server: First set up a Mashup Center server and start it.
  2. Then create a server in Rational Application Developer: Right-click on any blank place in Servers view and click New > Server (see Figure 14).
Figure 14. Create a new server
Create a new server
  1. In the Server list dialog window, choose the Lotus Mashup Center server and fill in the correct host name.
  2. Remember to click Test connection to verify your inputs (Figure 15).
Figure 15. Test the server connections
Test server connections

You're almost finished. Now it's test time.

  1. Right-click the iWidget project and select Run as > Run on server.
  2. Choose the Mashup Center server defined previously, and then go to the Mashup page to test your iWidget (see Figure 16).
Figure 16. Test the iWidget on the Lotus Mashup Center.
Test iWidget on Lotus Mashup Center



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=Quick iWidgets using Rational Application Developer Web 2.0 tools