Setting up an IBM Rational Application Developer-based iWidget development environment

When widgets are developed for deployment on IBM® Mashup Center, two IBM development tools can be used, the IBM Mashup Center widget factory or IBM Rational® Application Developer. This article explains how to set up IBM Rational Application Developer so that it can be used to create iWidgets for deployment in IBM Mashup Center.

Denitsa Tsolova, Software Engineer, Musala Soft

Denitsa Tsolova is a Software Engineer with Musala Soft. She joined the Musala Soft jump start (jStart) team in early 2008 and participated in development and documentation of multiple iWidgets for IBM Mashup Center. She has more than three years of professional experience as a developer and extensive experience in teaching computer science. She has a B.S. in Informatics from Sofia University, Bulgaria.



Milen Penchev, Software Engineer, Musala Soft

Milen Penchev is a Software Engineer with Musala Soft, joining the Musala Soft jStart team in February 2008. He has participated in the development and documentation of multiple mashups and widgets for IBM Mashup Center. Milen has delivered several conference presentations to support IBM partners and clients in getting started with widget development. He has more that two years of professional experience in software development and has a B.S in Computer Systems and Technologies from Technical University in Sofia, Bulgaria.



Anislav Atanasov, Team Leader, Musala Soft

Anislav Atanasov is a Team Leader with Musala Soft. In March 2007 he started helping the IBM jStart team in developing mashups based on QEDWiki; after IBM Mashup Center was introduced, he developed several widgets and mashups. Anislav’s experience includes working with J2EE, Eclipse RCP, and Web 2.0. He has a B.S. in Computer Science and an M.S. in Software Engineering from Sofia University, Bulgaria.



Sam Thompson, Senior IT Architect, IBM

Sam Thompson is a Senior IT Architect in IBM Software Group’s Emerging Technologies Group. Since joining IBM in 1980 he has held various technical and management positions in VM product development. In 1992, he moved to the Systems Management Development Lab in Raleigh, North Carolina, helping bring several SystemView products to market. When SystemView merged with Tivoli Systems, he traveled the world as a technical evangelist, explaining the merger, the new Tivoli strategy and products, and the convergence strategy for the IBM and Tivoli workgroup products. In March 1997 he helped form the IBM's Emerging Technologies jStart group, which works with IBM's clients to help them architect and build solutions that use XML, Java, Web services, rich client, autonomic computing, Web 2.0, Ajax, and mashup technologies.



20 October 2009

Also available in Chinese Japanese Spanish

Introduction

The purpose of this article is to describe the configuration steps necessary to set up IBM Rational Application Developer so that it can be used to create iWidgets for deployment in IBM Mashup Center.

Prerequisites

To get the most from this article, you should have the following software installed:

  • IBM Mashup Center 1.1. Note that the installation directory of IBM Mashup Center is hereafter referred to as <imc_dir>.
  • IBM Rational Application Developer. Because IBM Mashup Center runs on IBM WebSphere® Application Server V6.1, the version of Rational Application Developer must be one that can use WebSphere Application Server V6.1. Rational Application Developer 7.5 was used for this article.

Environment settings

First, open Rational Application Developer. Though it is possible to reuse an existing workspace, for the purposes of this article, we use a new, clean workspace. There are no limitations for the workspace’s location on the file system.

Creating a server instance

Create a server instance of Mashup Center’s WebSphere Application Server in Rational Application Developer, as follows:

  1. Open the Servers view in Rational Application Developer. This view automatically displays when the Java™ Platform, Enterprise Edition (Java EE) perspective is opened; however, if the Servers view does not display, from the Windows menu, select Show View - Other.
  2. From the window that displays (see figure 1), expand the Server folder and select the Servers option.
  3. Right-click this view and select New - Server.
  4. In the New Server window that displays, set the Server’s host name field to localhost. For the server type, from the IBM folder, select WebSphere Application Server v6.1 (see figure 1).

    Figure 1. New Server window
    New Server window
  5. Enter a server name of your choice in the Server name field.
  6. In the Server runtime environment field, select the WebSphere Application Server environment that was installed with IBM Mashup Center. Click Next.

    NOTE: If such an environment does not exist, create one by clicking the Add button (refer to the next section for the configuration steps).

  7. In the New Server Runtime Environment window, enter a name for the new server environment in the Name field; for example, enter IMC Server Runtime 6.1 (see figure 3).
  8. In the Installation directory field, browse to the AppServer folder under the IMC installation directory (<imc_dir>\AppServer).

    Note that this window displays only if you clicked the Add button on the previous window, to create a new server environment.

  9. After all fields are completed, click Finish. In the Define New Server window, click Next.
  10. In the WebSphere Server Settings window, define the necessary settings (see figure 2). For example, here we used mm_profile for the WebSphere profile name. Also, be sure to enable the options for Automatically determine connection settings, Run server with resources within the workspace, and Security is enabled on this server.
  11. Enter the user ID and password for the WebSphere Application Server instance of IBM Mashup Center (defined during the IBM Mashup Center installation procedure). Click Finish.

    NOTE: If you click the Next button instead of Finish, the window that displays (Add and Remove Projects) allows you to deploy any existing projects from the workspace on the new server.

    Figure 2. WebSphere Server Settings page
    WebSphere Server Settings screen
  12. When you are finished, you can start the newly defined WebSphere Application Server instance from the Servers view (right-click the newly defined instance and select Start).

Basic configuration for the iWidget project

Configuring the iWidget project requires two steps: creating the project and adding iWidget-specific files.

Create the project

To create an iWidgets project, follow these steps:

  1. From the main menu of Rational Application Developer, select File - New - Project.
  2. In the New Project window, select Dynamic Web Project from the Web folder.
  3. In the New Dynamic Web Project window, enter the project name, for example, com.ibm.basic.hello (see figure 3). For the Target Runtime, select the newly created IBM Mashup Center WebSphere Application Server runtime; in this instance, use IMC Server Runtime v6.1.

    Note that it’s not necessary to create a new Enterprise Archive (EAR) project to create IBM Mashup Center iWidgets.

  4. If a new EAR project is wanted, enable the Add project to an EAR option. You can create and configure the EAR project by clicking the New button; otherwise, the project’s name, which is prepopulated by Rational Application Developer, can be changed in the EAR Project Name field, and the EAR project is created with the default or the recommended settings.

    Figure 3. New Dynamic Web Project window
    New Dynamic Web Project window
  5. Click Finish; the project (the project and its EAR) are created and displayed in Rational Application Developer.

    NOTE: The project’s main folder is referred to as <project_root>, and the EAR project’s main folder is referred to as <ear_project_root>.

Add iWidget-specific files

To create each of the files listed below, right-click its parent folder and select New - File:

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

    This properties file (see listing 1) should contain two key value pairs, contextRoot and componentName. The contextRoot property defines the context root for the WebSphere Archive (WAR) project. The componentName property is used by the server during the deployment process.

Listing 1. mashup.properties file
contextRoot=basic/hello
componentName=com.ibm.basic.helo
  • catalog.xml. Create this file under the <project_root>/WebContent/WEB-INF folder.

    This XML file contains the iWidget’s description (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 thus contain widget-specific tags such as title, description, definition, and icon.

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>

      <definition>HelloWidget.xml</definition>
      <content>http://www.ibm.com</content>
      <preview>http://www.ibm.com</preview>
      <icon>hello_widget_icon.gif</icon>
    </entry>
  </category>
</catalog>

Note that 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.

Customize iWidget’s content

There are two key files involved when creating the iWidget: an XML file, which contains the iWidget’s definition, and a JavaScript™ file, which contains the iWidget’s functionality.

Definition file

To create this file, right-click the <project_root>/WebContent folder and select New - File. Enter the name of the definition file in the File name field (for example, HelloWidget.xml), and click Finish. The file should display in Rational Application Developer with an XML file extension.

Note the following:

  • 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="HelloWidget"
               xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
               iScope="HelloWidget"
               allowInstanceContent="true"
               supportedModes="view edit"
               mode="view"
               lang="en">

  <iw:resource url="HelloWidget.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.

This type of iWidget does not use any other files as resources, so in this situation the <iw:resource> tag can be omitted. The value inside the tag refers to the iWidget’s main resource file, and the path is relative to the declaration file itself.

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.

Resource file

To create the resource file, right-click the <project_root>/WebContent folder and select New - File. 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 above.

Now add the iWidget’s source code, as shown in listing 4.

Listing 4. HelloWidget.js source
Dojo.declare("HelloWidget", null, {

    Id: null,

    onLoad: function() {
        this.id = "_" + this.iContext.widgetId = "_";
        alert(Hello from the iWidget with value " + this.id);
    }
}};

Note that you can write the iWidget using different implementation styles, including languages, class structure, and more. 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.

Other files

In the iWidget project, many other files can exist and can be used to customize the iWidget. For the purposes of this article, the icon for the iWidget (a GIF image) is created in an inner folder. To do this task, follow these steps:

  1. Right-click the <project_root>/WebContent folder, and select New - Folder. In the window that displays, insert the name for the new folder. Here we used images as the name.
  2. The iWidget icon must be an image file; paste or import the file inside the newly created folder.

Note the following:

  • The description of each file path should match the location of the file itself. The file path in the catalog.xml file is relative to the <project_root>/WebContent folder.
  • When a resource file is included in the definition file, the file path to the included file should be relative to the location of the definition file.
  • When a resource file is included in other resource files, the file path to the included file should be in the format:

    /widgets/<context_root>/<relative_path>

    where <context_root> is the value for contextRoot in the mashup.properties file, and <relative_path> is the file path relative to the <project_root>/WebContent folder (this detail is explained later in the article).


Deploying the iWidgets

Now let’s discuss how to deploy the iWidgets.

Create the iWidget WAR file

To create the WAR file, follow these steps:

  1. Right-click <project_root> (the project name) and select Export (see figure 14).
  2. From the window that displays, expand the Web folder, and select the WAR file item; click Next.
  3. In the window that displays next, enter the destination information and click Finish; the WAR file is created in the destination folder.

Upload the iWidget to MashupHub

To upload the iWidget to MashupHub, follow these steps:

  1. Make sure that IBM Mashup Center is started. You can start and stop the server in Rational Application Developer by using the context menu of the server instance.
  2. Open MashupHub and log in.
  3. From the Create section of the main MashupHub page, select Upload Widget (see figure 4).

    Figure 4. Create section of MashupHub
    Create section of MashupHub
  4. For the type source select the iWidget Package (.war) option, as shown in figure 5; click Next.

    Figure 5. Select the widget type source
    Select the widget type source
  5. In the next window, browse to the iWidget’s WAR file that was exported as described previously; click Next.
  6. In the next window, specify the widget-specific information (see figure 6); here we used "HelloWidget" in the Title field, "Hello iWidget demonstration" for the Description, and 1.0 for the Version.
  7. Click Finish; the iWidget is added to the catalog.

    Figure 6. Specify the widget-specific information
    Specify the widget-specific information
  8. In the What’s Next section, select View widget details.
  9. On the iWidget’s details page, select Add to Lotus Mashups.
  10. In the Add to Lotus Mashups window, specify the credentials for the IBM Mashup Center ID and click Next; on the next page, select the category (here we selected Demo) for the iWidget, and click Finish (see figure 7).

    Figure 7. Add to Lotus Mashups, second window
    Add to Lotus Mashups, second window

The iWidget is now added to the selected category in Lotus Mashups and can be dragged onto a mashup page. Note that if Lotus Mashups opened in the browser, the page must be reloaded to display the iWidget in the category’s drawer (see figure 8).

Figure 8. Using the new HelloWidget in a mashup
Using the new HelloWidget in a mashup

Note what happens in the following situations:

  • If you select the Adding the widget to Lotus Mashups option, the iWidget is deployed on IBM Mashup Center’s WebSphere Application Server.
  • If you upload an iWidget to MashupHub, each iWidget project’s file receives a unique URL and can be reached through a Web browser. This URL is composed in the following manner:

    http://<host>:<port>/widgets/<context_root>/<relative_path>

    where <host> and <port> are the values for the host and port of IBM Mashup Center’s WebSphere Application Server, and the following are true:

    • /widgets/ is added automatically by MashupHub.
    • <context_root> is the value for contextRoot in the mashup.properties file.
    • <relative_path> is the file path relative to the <project_root>/WebContent folder.

    HTTPS can also be used with the appropriate port.

  • If you add an iWidget to Lotus Mashups, an entry is added to the <imc_dir>\mm\public\cat\catalog_<username>.xml file. This entry is created with the content of the iWidget’s project catalog.xml file. Note that the values for <definition> and <icon> are rewritten to /widgets/<context_root>/<relative_path>.

Debugging or dynamically changing a widget in Rational Application Developer

If an IBM Mashup Center server is installed on the same computer as Rational Application Developer, it is possible to modify dynamically and debug iWidgets without needing to manually create WAR files and install them on the IBM Mashup Center server using MashupHub.

Uninstalling a deployed iWidget

This subsection describes how to uninstall an iWidget using the WebSphere Application Server console so that you can edit the widget’s source (as described below). To uninstall an iWidget completely, see the "Uninstalling an iWidget" section later in this article.

  1. Open the IBM Mashup Center WebSphere Application Server administrative console (Integrated Solutions Console) and select Applications - Enterprise Applications.
  2. A list of the deployed applications is shown (see figure 9). Select the application (that is, the widget) that should be uninstalled, and click the Uninstall button.

    Figure 9. Deployed applications list
    Deployed applications list
  3. Save the new server configuration.

Setting up the catalog file

When iWidgets are added to Lotus Mashups, they are placed into different drawers, which are defined in the <imc_dir>/mm/public/cat/catalog_<username>.xml file.

Each drawer is described with an XML <category> tag. To have an iWidget displayed in a Lotus Mashups drawer, a corresponding <entry> tag must be present in the file.

Note that, if the iWidget was already added to Lotus Mashups using the MashupHub, the entry was automatically inserted and does not need to be modified.

If there is no entry for the iWidget in the catalog file, it must be manually inserted, using the following steps:

  1. Copy the contents of the <category> or <entry> tag from the project's catalog.xml file and add it to the <imc_dir>/mm/public/cat/catalog_<username>.xml file, preserving the layout of the hierarchical tag structure.
  2. Edit the <definition> and <icon> tag values by appending /widgets/<context_root>/ at the beginning of the <relative_path>, as described in the last bullet point in the previous section, "Upload the iWidget to MashupHub."
  3. When the <imc_dir>/mm/public/cat/catalog_<username>.xml file is changed, you must restart IBM Mashup Center WebSphere Application Server, for the changes to take effect.

Note that there is a five-category limit in IBM Mashup Center, so when modifying the <imc_dir>/mm/public/cat/catalog_<username>.xml file, ensure that no more than five <category> tags exist in the file.

Modifying the EAR project

If an EAR project was created for the iWidget (as described earlier in the "Create the project section") it is displayed in Rational Application Developer. To modify this file, follow these steps:

  1. Open the <ear_project_root>/META_INF/application.xml file.
  2. Switch to the source view, and set the <context-root> value. The value for the iWidget module’s context root should be in this format:

    widgets/<context_root>

    where <context_root> is the value for contextRoot in the mashup.properties file.

  3. Save the file changes.

Deploy the EAR file on the local IBM Mashup Center’s WebSphere Application Server

To deploy the EAR file, follow these steps:

  1. Make sure that the server is running. The Rational Application Developer server instance indicates this detail by showing its status as either Started or Debugging.
  2. Right-click the server instance, and select Add and Remove Projects.
  3. In the Add and Remove Projects window (see figure 10), select the iWidget’s EAR project (here it’s com.ibm.basic.helloEAR), and move it into the Configured projects area by clicking the Add button.
  4. Click Finish; the project’s EAR file is deployed on IBM Mashup Center’s WebSphere Application Server.

    Figure 10. Add and Remove Projects window
    Add and Remove Projects window

The iWidget can be dragged from a Lotus Mashups drawer and dropped onto a Mashup page because an entry for the iWidget was added to the user’s catalog file.

The iWidget definition and source files are editable because they were uploaded to IBM Mashup Center’s WebSphere Application Server through the EAR project, using an appropriate value for the context root.

Runtime source modifications

The deployed definition and resources files of the iWidget can now be dynamically edited in Rational Application Developer. Each time a change is saved and the iWidget project is built, the EAR file is automatically republished on IBM Mashup Center’s WebSphere Application Server.

It is not necessary to restart the server when changes are made; the changes take effect automatically.

To see changes that were made to the iWidget in Lotus Mashups, you must refresh the Web page (clearing the browser cache is preferred). The updated widget is shown in figure 11.

Figure 11. Mashup Page with new text "Bye" displayed in the HelloWidget
Mashup Page with new text Bye displayed in the HelloWidget

Note that you can uninstall the EAR application, deployed using Rational Application Developer on IBM Mashup Center’s WebSphere Application Server, using one of the following two methods:

  • As described in the section, "Uninstalling a deployed iWidget." The application name is the value of the <display-name> tag, specified in the <ear_project_root>/META_INF/application.xml file.
  • Using the IBM Mashup Center WebSphere Application Server instance in Rational Application Developer. In the Add and Remove Projects window, remove the EAR project from the Configured projects area and click Finish.

Uninstalling an iWidget

Here we explain how to uninstall an iWidget.

Remove the widget’s application from the IBM Mashup Center WebSphere Application Server server

To remove the widget's application, follow these steps:

  • If the widget’s application was deployed on IBM Mashup Center’s WebSphere Application Server by uploading the widget using MashupHub, see the previous "Uninstalling a Deployed iWidget" subsection.
  • If the widget’s application was deployed in the Rational Application Developer server’s instance, right-click the server instance and select Add and Remove Projects. In the Add and Remove Projects window, select the iWidget’s EAR project and remove it from the Configured projects area.

Delete a widget entry from a drawer

To delete a widget entry from a drawer, follow these steps:

  1. Open Lotus Mashups, and select Go to Edit mode, to display the drawers.
  2. Find the widget in the appropriate drawer.
  3. Mouse over the widget’s entry, and click the Configuration button. From the context menu, select Remove. The widget is deleted from the drawer.

Delete a widget from MashupHub

To delete a widget from MashupHub, follow these steps:

  1. Open MashupHub and log in, using the MashupHub administrator’s ID or the ID that was used when the widget was added to Lotus Mashups.
  2. From the Catalog section, select List Widgets and select the iWidget name.
  3. On the iWidget’s details page, in the Actions section, select Delete (see figure 12). The widget is deleted from MashupHub.

    Figure 12. Widget’s details page
    Widget’s details page

Conclusion

We hope that you now know how to quickly create some custom widgets for your IBM Mashup Center mashups. You should now be able to do the following:

  • Create a simple HelloWidget that displays only text, for example, "Hello" or "Bye"
  • Deploy the new widget in a remote IBM Mashup Center instance using MashupHub
  • Deploy the new widget directly from Rational Application Developer when both Rational Application Developer and IBM Mashup Center are installed on the same system

Downloads

DescriptionNameSize
Code samplecom.ibm.basic.hello_src.zip9880B
Code samplecom.ibm.basic.hello.war4054B

Resources

Learn

Get products and technologies

Discuss

Comments

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 IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Rational, DevOps
ArticleID=437527
ArticleTitle=Setting up an IBM Rational Application Developer-based iWidget development environment
publish-date=10202009