Creating and deploying a simple widget 

This topic describes how to create a widget as a WAR file, deploy it to MashupHub, and install it in Lotus Mashups.

You can create widgets using IBM Lotus Widget Factory and IBM WebSphere sMash and thendeploy them to Lotus Mashups. For information about how to create and deploy widgets using Widget Factory, see the documents that are attached to the end of this article. Also see the Widget Factory section of the IBM WebSphere Portlet Factory wiki. For information about how to create and deploy widgets using sMash, see this article from Project Zero.

NOTE: This topic assumes that you have the WebSphere Application Server (WAS)-based version of Lotus Mashups installed as well as some type of Eclipse-based development environment for creating WAR files, such as WAS Toolkit, or Rational Application Development. The steps you will follow in this mini tutorial are based on WebSphere Application Server Toolkit V6.1.1.

Lesson 1: Creating a new Eclipse project

In this lesson, you will create a new Eclipse project to contain your new widget. This step is required in order to create all the necessary artifacts that must be contained in your widget WAR file. To create the new project, do the following steps:

A. Open the WAS Toolkit.

B. Click File > New > Project.

C. In the New Project window, click Web > Dynamic Web Project, as shown here:




D. Click Next.

E. In the New Dynamic Web Project window, do the following steps:

i. In the Project name field, type mashups_tut.

ii. In the Target Runtime field, select WebSphere Application Server v6.1.

iii. In the EAR Membership section, clear the Add project to an EAR check box. This is because we only need to create a WAR file, not an EAR file.

iv. Confirm your settings, and click Next, as shown here:





F. In the next window, leave the default values, and click Finish. Now the toolkit creates the new project, including all the required artifacts, in your Eclipse workspace.

G. Now open the Project Explorer pane on the left side of the toolkit window and confirm that your new mashups_tut project created successfully, as shown here:





Lesson 2: Creating a Hello World XML file

In this lesson, you will create a WAR file and put it into the mashups_tut Eclipse project that you created in the previous lesson. To create the widget WAR file, do the following steps:

A. In the toolkit, click File > New > File.

B. In the New File window, select mashups_tut/WebContent as the parent folder, and name the new file mashups.xml, as shown here:




C. Click Finish. Now the new XML file opens in the middle pane of the toolkit.

D. Click the Source tab, and paste the following code into the window:
<iw:iwidget name="mashups" xmlns:iw="http://www.ibm.com/iWidget"

 

<iw:content

 

<![CDATA[
Hello World
]]

 

</iw:content

 

</iw:iwidget

 

E. Press Ctrl + S to save the file.



Lesson 3: Adding the image file

If your widget contains an image, do the following steps:

A. In the Package Explorer, right-click the WebContent folder, and select New > Folder.

B. In the New Folder window, select WebContent as the parent folder, type images in the Folder name field, and click Finish.

C. Drag and drop the image from your local machine into the new images folder.



Lesson 4: Creating the catalog definition file

In this lesson, you will create the XML file that defines the widgets in the WAR file. Do the following steps:

A. In the toolkit, click File > New > File.

B. In the New File window, select mashups_tut/WebContent/WEB-INF as the parent folder, and name the new file catalog.xml, as shown here:




C. Click Finish. Now the new XML file opens in the middle pane of the toolkit.

D. Click the Source tab, and paste the following code into the window:
<?xml version="1.0" encoding="UTF-8"?

 

<catalog

 

<category name="Tools"

 

<title

 

<nls-string lang="en"

 

Hello World</nls-string

 

<nls-string lang="es"

 

Hola el Mundo</nls-string

 

</title

 

<description

 

<nls-string lang="en"

 

This widget displays the string Hello World
</nls-string

 

<nls-string lang="es"

 

Este widget muestra la linea Hola el Mundo
</nls-string

 

</description

 

<entry id="helloWorld" unique-name="helloWorld"

 

<title

 

<nls-string lang="en"

 

Hello World</nls-string

 

<nls-string lang="es"

 

Hola el Mundo</nls-string

 

</title

 

<description

 

<nls-string lang="en"

 

This widget displays the string Hello World
&nbs p; &nbs
p; ; </nls-string

 

<nls-string lang="es"

 

Este widget muestra la linea Hola el Mundo
</nls-string

 

</description

 

<definition

 

mashups.xml</definition

 

<content

 

http://www.ibm.com</content

 

<preview

 

http://www.ibm.com</preview

 

<icon

 

images/generic_widget_icon.gif
</icon

 

<metadata name="widgetParam" /

 

<metadata name="onNewWire"

 

</metadata

 

</entry

 

</category

 

</catalog

 

E. Press Ctrl + S to save the file.



Lesson 5: Creating the PROPERTIES file

In this lesson, you will create the PROPERTIES file that defines the context root and component name. Do the following steps:

A. In the toolkit, click File > New > File.

B. In the New File window, select mashups_tut/WebContent/WEB-INF as the parent folder, and name the new file mashup.properties, as shown here:




C. Click Finish. Now the new file opens in the middle pane of the toolkit.

D. Click the Source tab, and paste the following code into the window:
contextRoot=mashupsshould be unique
componentName=com.ibm.mm.test.mashups



E. Press Ctrl + S to save the file.



Lesson 6: Exporting the WAR file

In this lesson, you will export the project as a WAR file. Do the following steps:

A. In the Project Explorer, right-click the project name mashups_tut, and select Export

 

Export.

B. In the Export window, select Web > WAR file, and then click Next, as shown here:




C. In the next window, browse to a location on your local machine where you want to save the WAR file. You will need to remember this location in the next lesson.

D. Click Finish.



Lesson 7: Uploading the WAR file into the catalog


A. Open the MashupHub catalog.

B. On the home page, in the Create section, click Upload Widget.

C. In the Select the widget type source page, in the Source field, select iWidgets, and then click Next.

D. In the Upload or Register a Widget page, leave the default Upload a Widget Package setting for the Widget source field.

E. In the Widget file path field, br owse to the location of the WAR file that you exported to your local machine in the previous lesson.

F. Click Next.

G. In the Specify the following information page, type Hello World as both the title and description of the widget. Leave the default values in the other fields, as shown here:




H. Click Finish. The next page informs you that the widget was saved successfully.



Lesson 8: Adding the Hello World widget to Lotus Mashups

In this lesson, you will add the Hello World widget to the Lotus Mashups toolbox. Then you will be able to drag it onto a page and use it in your mashup applications. Do the following steps:

A. Open the Lotus Mashups browser.

B. In the search field at the top, right corner, type Hello World, and then click the search icon.

C. In the Search the Catalog window, find the Hello World widget that you uploaded in the previous step, and click Add to Toolbox.

D. In the Add Widget to Toolbox window, select the drawer that you want to contain the widget, leave the other values as is, click Add and then Done, as shown here:




E. In edit mode, open the drawer that you selected in the previous step, and drag the Hello World widget onto the page. The widget should now display the string Hello World!


Next steps

Now that you know how to create and deploy a simple widget, click here to go to the Widget Programming Guide. It contains more advanced topics to help developers understand, create, and deploy widgets using the Lotus Mashups framework.