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
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" ?>
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="http://www.w3.org/2001/XMLSchema-instance" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" supportedModes="view" mode="view" lang="en"> <iw:resource src="optional.js" id="jsId" /> <iw:content mode="view"> <![CDATA[ <div>Hello World</div> ]]> </iw:content> </iw:iwidget>
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
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
- 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
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.
- In Rational Application Developer, select File > New > Project, and begin by creating one of these projects.
- Fill in the project name and target the project to an appropriate server run time that you want.
- Next, choose any configurations that you want, or simply use the default.
- 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
- Find the iWidgets facet in the list and select the check box next to it (see Figure 2).
- Click OK to return to the project-creation wizard.
- Then click Finish to kick off the project creation process.
Figure 2. Add iWidget facet
Create an iWidget inside of your project
- Select your project in the Enterprise Explorer and right-click on any selected item.
- From the drop-down menu, select New > iWidget (Figure 3).
Figure 3. Launch the iWidget wizard
The New iWidget wizard opens, as shown in Figure 4.
Figure 4. "Create a new iWidget" view in the wizard
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.
- Event publisher iWidget: An iWidget with an event that sends out data
- Event subscriber iWidget: An iWidget with an event that receives data
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.
- 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.
- 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.
- mashup.properties 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
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
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)
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
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
All defined modes must be listed in the supportedModes attribute
- 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
- Click the Update button next to the Supported Modes field to see your new mode displayed in the list.
- 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 StockWidgetSample.zip 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.
- Click the Servers tab and go to the Servers view.
- Right-click inside of that view and select New.
- In the wizard that pops up, expand the IBM group, and choose the AJAX Test Server (ATS).
- 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
- Deploy the StockWidgetSample application to the server instance that you created in the previous step.
- Right-click on the server and select Add and Remove.
- In the wizard that pops up, add the StockWidgetSample application and click Finish.
- 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
- In Enterprise Explorer, expand the WebContent directory of the sample application.
- Right-click on the stock.xml file and select Run As > Run on Server.
- In the wizard page that opens, choose the AJAX Test Server or any other server in which you have deployed your sample.
- 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.
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
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
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
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
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
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.
- Tweak the markup in the stock.xml file or the style attributes in the style sheet.
- Wait until the server automatically synchronizes, or republish it yourself.
- 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.
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.
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.
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)
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 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
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
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.
- 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.
- Pick a time to see it in the input field.
- 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.
- 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 article||StockWidgetSample.zip||11KB|
- Explore these sites about widgets:
- Browse the Rational Application Developer for WebSphere Software page on developerWorks for links to technical articles and many related resources.
- Explore the Rational Application Developer for WebSphere Software Information Center.
- Go to the developerWorks Rational home page to learn more about other Rational software mentioned in this article.
- Learn about other applications in the IBM Rational Software Delivery Platform.
- Find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
- Explore Rational computer-based, Web-based, and instructor-led online courses.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
Get products and technologies
- Download a free trial copy of Rational Application Developer for WebSphere Software.
- Download trial versions of other IBM Rational software.
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
- Join the Development Tools forum to ask questions and participate in discussions.
- Check out developerWorks blogs.
- Get involved in the developerWorks community.