Customizing IBM Lotus Connections 2.5 with Lotus Widget Factory and Google gadgets

Create custom enterprise-ready widgets for Lotus Connections 2.5 without writing a single line of code

This article details two different approaches that you can use to accelerate and simplify the development of new widgets for IBM® Lotus® Connections.

Vincent Burckhardt, Software Engineer, IBM

Vincent Burckhardt is a Software Engineer at the IBM Dublin Software Laboratory. Vincent has been working as part of the IBM Lotus Connections development team since 2007. You can reach him at vincent.burckhardt@ie.ibm.com.



29 September 2009

Also available in Chinese Japanese

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

IBM Lotus Connections 2.0 introduced the concept of widgets as a way to extend and customize the Home page feature of the product. A widget is a small piece of code that can run within a Web application and display any custom content. Lotus Connections supports widgets written according to the IBM-defined iWidget specifications. Released in 2009, Lotus Connections 2.5 enhances the support for widgets in the Home page, Communities, and Profiles features by providing additional placement areas where the administrator can deploy widgets acquired from other developers.

Widgets can be implemented using traditional Web development practices and languages. As such, developing a widget takes time and resources and requires knowledge of Web development technologies such as HTML, CSS, and JavaScript™. This article details two different approaches that you can use to accelerate and simplify the development of new widgets for Lotus Connections.

In the first section, this article shows how you can use the Lotus Widget Factory integrated development environment (IDE) to create custom widgets for Lotus Connections. Lotus Widget Factory is a tool that allows the development of custom enterprise-ready widgets in a visual way, without your having to write code. While Lotus Widget Factory officially supports only IBM Lotus Mashups, this article demonstrates that it can also be used to develop widgets for Lotus Connections. This article takes you through the steps of creating a widget that displays a list of audio files (podcasts) from IBM developerWorks® and allows users to listen to them directly from Lotus Connections.

The second section details how to surface Google gadgets into Lotus Connections by using a wrapper. The wrapper is a standard iWidget that acts as an interface between Lotus Connections and the Google gadget. Note that the Google gadget approach was already introduced in a previous developerWorks article, "Implementing and deploying Google gadgets for the Lotus Connections home page," for the release of Lotus Connections 2.0. While the previous article focused on the development aspect of the wrapper, this section goes directly into the subject by showing the steps to deploy Google gadgets without having to write code.

The first two sections of this article are accessible to readers who have no prior programming experience, such as system administrators.

In the final section, this article deals with the programming details of the iWidget specifications. This section is targeted at developers who have a prior knowledge of Web technologies. The objective is to offer a starting point from which you can explore the possibilities of customization and to introduce the new iWidget capabilities supported in Lotus Connections 2.5.


Using Lotus Widget Factory to develop widgets for Lotus Connections

This section describes the steps you take to create a widget that displays the content of a public feed as a table and makes it available to users in Lotus Connections Home page. This section covers version 1.0.1 of Lotus Widget Factory.

The widget created in this section fetches a list of podcasts recorded by IBM developerWorks and available through a standard RSS feed. You can find more details about the podcasts at http://www.ibm.com/developerworks/podcast/.

The entries of the RSS feed are a list of MP3 podcasts recorded by developerWorks. You can create such a widget in a matter of minutes with Lotus Widget Factory and without writing a single line of code. At the end of this section, you learn how to enhance the widget with an embedded media player that allows users to play and listen to the podcasts directly from the widget interface. Figure 1 shows how the widget is going to look.

Figure 1. developerWorks podcast widget created in this section and deployed in Lotus Connections Home page
developerWorks podcast widget created in this section and deployed in Lotus Connections Home page

Lotus Widget Factory

Lotus Widget Factory is an integrated development environment (IDE) for creating dynamic custom widgets. The tool allows you to leverage existing assets such as REST services to rapidly create dynamic widgets without writing code.

A trial version of Lotus Widget Factory is available as part of the IBM Mashup Center offering. See the references at the end of the article for more details.

Lotus Widget Factory is based on the concept of models that you assemble from basic bricks called builders. The builders are generic components that encapsulate a given capability. Lotus Widget Factory comes with a large number of predefined builders ranging from user interface components, such as buttons, to components responsible for fetching data from a remote Web service. A user-friendly wizard interface is associated with each builder and lets you specify the characteristics, such as the inputs, of the builder.

Lotus Widget Factory automatically generates the source code of your widget based on the model that you put together in the tool. The source code includes the Java™ code of the server-side back-end services and the client-side code, such as the HTML views, JavaScript code, and the XML descriptor of the widget. The code and resources that make up your widget are packaged as a standard Web archive (WAR) file that can be deployed to a J2EE server, such as IBM WebSphere® Application Server.

Additional information about Lotus Widget Factory can be found in the resources listed at the end of this article.

As mentioned previously, Lotus Widget Factory is tightly related to creating widgets for the Lotus Mashups product. Because Lotus Connections and Lotus Mashups share the same underlying format of widgets (the IBM-developed iWidget specifications), it is relatively easy to reuse and deploy widgets created by this tool in Lotus Connections.

Creating a developerWorks podcast widget with Lotus Widget Factory

The first step is to create a model to generate a widget capable of fetching the RSS feed located at http://www.ibm.com/developerworks/podcast/channel-dwall.rss. This public RSS feed contains a list of recent podcasts recorded by the developerWorks team (http://www.ibm.com/developerworks/podcast/).

The widget displays information about recent developerWorks podcasts from the feed as a paginated table. Each row in the table displays the data related to a given podcast: its title, duration, description, and a link to the download of the MP3 file.

In a following subpart, the widget is enhanced with the public Yahoo MediaPlayer JavaScript library (http://mediaplayer.yahoo.com/) to allow users to listen to the podcast directly from Lotus Connections, without downloading the MP3 file manually.

First, let’s start by creating a new Lotus Widget Factory project:

  1. Start Lotus Widget Factory and select File - New - Lotus Widget Factory Project.
  2. Select a project name, for instance, developerWorksWidget. Leave the other fields blank and click Next.
  3. In the Feature Set page, keep the default options and click Next.
  4. In the Deployment Configuration option, select the WebSphere Application Server Community Edition server instance that comes with Lotus Widget Factory. As you will see, this server instance allows you to work on your widget in a stand-alone browser Web page before you deploy it to Lotus Connections.

Lotus Widget Factory now creates a new project for you. Lotus Widget Factory also prompts you to start the WebSphere Application Server Community Edition server (if it is not already started) and to deploy the project to the WebSphere Application Server Community Edition instance. Click Yes to both prompts to do so.

You are now ready to create the model for your widget. At this point, you can create a blank widget model and add different builders responsible for fetching the feed, formatting it, and displaying a data table. Lotus Widget Factory has some model wizards assisting in the creation of preconfigured models for common uses. You are going to use one of the built-in model wizards:

  1. Select File - New - Lotus Widget Factory Model.
  2. In the Choose Project form, select the project created in the preceding set of steps (it should be named developerWorksWidget).
  3. In the Select Model form, select the REST-based View & Form option (in the category “Quick Start”) to instruct Lotus Widget Factory to create a widget model preconfigured with the builders needed to fetch a feed and display it in as a table.
  4. Do not select the option, Deploy this model as widget. This option allows deploying the widget to a running Lotus Mashups instance. As mentioned previously, Lotus Widget Factory is primarily designed to create widgets for Lotus Mashups. You should not select the option now as you will deploy the widget to Lotus Connections at a later stage.
  5. In the REST Call Information form, enter the URL to the developerWorks RSS feed: http://www.ibm.com/developerworks/podcast/channel-dwall.rss. Make sure that you select GET in the HTTP Request Type option, leave the other options in the form blank, and click Next.
  6. Leave the Schema Information form blank, and then click Next.
  7. In the Final REST Service Information form, select channel/items. Each item in the RSS feed contains information about a given podcast. Therefore, in this step, you inform the REST builder to display the different items (podcasts) from this feed.
  8. In the following form, select the Paged Data Display option, which configures your model to display a pager to let users navigate through the podcast items at the bottom of the widget. Three rows per page is a good value for a widget.
  9. Select the Manage Columns option in the Column Settings form. The form lets you manage the columns to display from the feed in the table. Keep in mind that the widget has limited real estate on the page, so you should not display too many columns. Figure 2 shows an example of the settings that you can use.

    Figure 2. Column Settings form
    Column Settings form

    There is one important thing in this form: Make sure that the status field of the guid column is set to Counter Column as shown in figure 2. The guid entry in the RSS feed contains the path to the MP3 file of the podcast. By setting Counter Column, you specify to the builder to display the content of the guid column as a counter (starting at 1) rather than from the content of the field. In the following set of steps in this subpart, you will place links to the MP3 files on the counters. Click Next.

  10. Leave the Create Link to Details option cleared.
  11. Enter a name for the model, for example, developerWorksModel.

Figure 3 shows the workspace in Lotus Widget Factory after you have completed these steps. The Project Explorer panel on the left displays the resources of your developerWorksWidget model. The details of the model that you have created are displayed in the main panel. Notably, this panel shows the different builders that were preconfigured by the REST-Based View and Forms wizard and that constitute the model.

Figure 3. Lotus Widget Factory displaying the details of the widget model
Lotus Widget Factory displaying the details of the widget model

At this point, you have created a model that is already configured and ready to generate the code of a fully functional widget displaying the list of podcasts from developerWorks.

The widget can be viewed in a stand-alone browser page by selecting the model in the Project Explorer window (developerWorksModel.model as shown in figure 3) and selecting Run - Run As - Run As Active Model. This action starts an embedded instance of WebSphere Application Server Community Edition and runs the widget in a full browser page as shown in figure 4.

Figure 4. Widget running in a stand-alone page in development
Widget running in a stand-alone page in development

Finally, you add the ability to allow users to download the MP3 files from the widget. In this example, you are going to transform the counter labels in the first column of each row (the numbers in the first column in figure 4) to clickable links pointing to the MP3 file of the corresponding podcast. Remember that the first column of the table is associated with the guid field in the original RSS feed, as configured in step 9 of the instructions to create the model above (see figure 2). The guid field value in the original RSS feed is the path to the MP3 file. In this step, you use the Link builder to create the links by using the guid value:

  1. In Lotus Widget Factory, select your project and model, which you created in the previous steps.
  2. Click Add a builder call the current model as shown in figure 5.

    Figure 5. Location of the Add builder button in Lotus Widget Factory
    Location of the Add builder button in Lotus Widget Factory
  3. Select the builder Link in the category Page Elements.
  4. In this step, you configure the Link builder to create a link for each guid element in the table. Remember, the guid field in the feed contains the path to the MP3 file. Complete the builder form, as shown in figure 6, with the following information:
    • In the Name field, enter LinksGUID.
    • In the Page field, select REST_ViewPage.
    • In the Tag field, select guid.
    • In the Action Type field, select Link to a URL.
    • For the URL field, click the “…” button next to the field and select Variables - itemLoopVar - item - guid. The value generated for the field should be “${Variables/itemLoopVar/item/guid}”
    Figure 6. Settings for the Link builder
    Settings for the Link builder

That’s it! Now users have the ability to download the MP3 file of the podcast by clicking the numbers (counters) in the first column of each row. In the final subpart of this section, you can learn how to enhance the widget with an embedded media player, allowing users to listen to the podcast directly from the widget without having to manually download the MP3 file.

In this state, the widget is usable and valuable to the users. And the best part is that you haven't written a single line of code yet.

In the next section, you learn how you (as an administrator) can make the widget available to users in Lotus Connections Home page.

Deploying widgets created in Lotus Widget Factory into Lotus Connections Home page

As mentioned previously, Lotus Widget Factory 1.0.1 officially supports only Lotus Mashups. As such, it is not possible to deploy widgets directly into Lotus Connections from the IDE. For this reason, you have to go through a couple of manual, yet straightforward, steps to make your widget available in Lotus Connections.

For this example, you register the widget in the Home page feature of Lotus Connections. You can find more details for the registration steps required for the Communities and Profiles features in the IBM Lotus Connections 2.5 Information Center documentation referenced at the end of this article.

This section guides you through the two following steps:

  • Extracting the widget code and resources from Lotus Widget Factory as a standard Web Archive (WAR) file and deploying the WAR file into a WebSphere Application Server instance as a Web application.
  • Registering the deployed widget in the Lotus Connections Home page. Note that only persons in the administrator role can make new widgets available to users.

First, you export the code and resources of the widget from Lotus Widget Factory as a standard WAR file and deploy it to a WebSphere instance:

  1. In Lotus Widget Factory, right-click your widget project in the Project Explorer panel (developerWorksWidget).
  2. Select Export - WAR file.
  3. Select a location on your disk for the WAR file.
  4. Deploy the WAR file to a WebSphere Application Server instance. The suggested way to proceed is to use the same WebSphere Application Server instance as the one running Lotus Connections. Deploying a WAR file is a standard step; see the IBM WebSphere Application Server 6.1 Information Center documentation for more details.

    Make a note of the context root that you pick during deployment (for example, devWorksApp).

  5. Start the Web application after deployment from the WebSphere administration console.

Second, you register the widget in Lotus Connections Home page. Any iWidget is described by a XML descriptor. The WAR file created by Lotus Widget Factory for your widget contains a service that generates and returns the XML descriptor automatically. In the case of the deployed WAR file, the service is located at:

http://<hostname>:<port>/<contextRoot>/webengine/factory/widget/Dispatcher?_widgetID=<pathToWidgetModel>

where <pathToWidgetModel> is the path to the model relative to the model directory in Lotus Widget Factory (see figure 7) without the file extension .model. In the case of the developerWorks model, pathToWidgetModel would be developerWorksModel.

Figure 7. Path to developerWorkModel.model in Lotus Widget Factory
Path to developerWorkModel.model in Lotus Widget Factory

Here is an example of the URL to the XML descriptor:

http://homedev2.dyn.webahead.ibm.com:9080/devWorksApp/webengine/factory/widget/ Dispatcher?_widgetID=developerWorksModel

where:

  • homedev2.dyn.webahead.ibm.com is the host name of the server
  • 9080 is the port
  • devWorksApp is the context root under which the WAR file was deployed to WebSphere Application Server

You can check whether the URL is correct by trying to access it with a Web browser. You should see the XML descriptor of the widget generated by Lotus Widget Factory as shown in figure 8.

Figure 8. XML descriptor of the widget generated by Lotus Widget Factory
XML descriptor of the widget generated by Lotus Widget Factory

NOTE: The application generated by Lotus Widget Factory uses classes loaded dynamically, a process that has some limitations when the Java Security setting is turned on in WebSphere Application Server. You might get the message "SRVE0207E: Uncaught initialization exception thrown by servlet" when accessing the XML descriptor above. You can turn off the Java Security option in the WebSphere Administration Console under Security - Secure Administration, Application and infrastructure - Java 2 Security.

Alternatively, if you do not wish to turn off Java 2 Security, you can create a file was.policy under WebConfig/META-INF to define specific resources to access. Refer to the IBM WebSphere Application Server 6.1 Information Center for more details on was.policy.

Now, you register the link to the XML widget descriptor in the Home page administration interface by following these steps:

  1. Log in with an administrator account to the Home page.
  2. Select the Administration tab in the Home page as shown in figure 9.

    Figure 9. Administration tab in Lotus Connections Home page
    Administration tab in Lotus Connections Home page
  3. Select the option Add another widget at the bottom right of the page.
  4. A form displays in which you can register the widget. Enter the widget title and the URL of the XML descriptor of the iWidget (see figure 10).

    Figure 10. Administration form to register a new widget in Lotus Connections Home page
    Administration form to register a new widget in Lotus Connections Home page
  5. Select the Display on the My Page tab.
  6. You can keep the default values for the other options in the form. Additional information about these options can be found in the Lotus Connections 2.5 Information Center documentation.
  7. Click Save. You are brought back to the Administrator’s Home page; in that page, enable the developerWorks widget.

After you enable the widget, users can add the developerWorks widget to the My Page tab in the Home page through the widget palette (see figure 11). You can open the widget palette by clicking the Customize button on the top right part of the interface.

Figure 11. developerWorks podcast widget made available to users through the widget palette in Home page
developerWorks podcast widget made available to users through the widget palette in Home page

Figure 12 shows the widget rendered in Home page after being added from the palette (MyPage tab).

Figure 12. Widget in Home page after adding it from the palette
Widget in Home page after adding it from the palette

NOTE: Lotus Widget Factory generates fixed-height widgets that might result in a vertical scroll bar on your deployment. You can eliminate the scroll bar by editing the file widget_definition.xml, located in WebContent/WEB-INF/factory/xml_templates/widget/ in the IDE. Modify the value min-height on the iframe element to increase the height of the widget and eliminate the vertical scroll bar. In figure 12, the min-height attribute was increased from 200 px to 300 px.

Enhancing the podcast widget with the Yahoo! media player library

In the previous sections, you created a widget capable of displaying a list of podcasts from an RSS feed. At the moment, the list contains only links to MP3 files, which requires users to download the file and open a desktop media player such as Microsoft® Windows® Media Player, to listen to the podcast.

An interesting enhancement could be to allow users to listen to the MP3 podcast directly from the widget interface without having to take the extra steps of downloading and opening the MP3 file manually.

To enable this capability, you will use the Yahoo! Media Player library (http://mediaplayer.yahoo.com/) with Lotus Widget Factory to generate a widget with an embedded media player. After you complete these steps, each row in the table contains a Play button that allows users to listen to the podcast directly from the widget, as shown figure 13.

Figure 13. Play buttons in the podcast widget
Play buttons in the podcast widget

Yahoo! Media Player comes in the form of a JavaScript library, which loads a lightweight Flash module responsible for playing an audio file. The JavaScript library parses the HTML of the page (or, more exactly, of the widget in this case) to look for links pointing to audio files, such as MP3 files.

You can find more details about the library at http://mediaplayer.yahoo.com/.

To enable this feature, you use a Lotus Widget Factory builder to include the Yahoo! Media Player JavaScript library in your widget. The Yahoo! library automatically looks for HTML link elements (pointing to media files, such as MP3 files) on the page (for example, First link) and places Play buttons next to them.

Let’s include the Yahoo! Media Player JavaScript library in your widget model:

  1. Select your project and model, and click the button Add a builder call the current model (same button as shown on figure 5).
  2. Select the Client JavaScript option in the category Actions And Events.
  3. Complete the form with the following values as shown in figure 14:

    • In the Name field, enter YahooMediaPlayer.
    • In the Location Type field, select the In HEAD tag option.
    • In the Page field, select REST_ViewPage.
    • In the Script Source Type field, select the option Link to file/URL.
    • In the Script URL or File Location field, enter http://mediaplayer.yahoo.com/js.
    Figure 14. Client JavaScript form
    Client JavaScript form

In brief, you are telling the builder to place a standard JavaScript tag pointing to the Yahoo! Media Player library at the top of your widget. The library is loaded from Yahoo! servers every time the widget is loaded on the page.

That’s it! Your model and builders are now configured to generate a widget with an embedded media player, allowing users to listen to developerWorks podcasts. If you already deployed and registered the widget in Home page in the previous section, you only have to update the WAR file in WebSphere Application Server to make this enhanced version of the widget available to the users.


Adding Google gadgets to Lotus Connections 2.5

You can use Google gadgets to add new and compelling content with minimal effort to Lotus Connections. With a catalog of approximately 200,000 gadgets, the possibilities of extensions are almost endless. Here are just a few examples:

  • Surfacing information from other popular social network platforms, such as Facebook and MySpace
  • Displaying videos from YouTube
  • Integrating tools through Google Docs gadgets
  • Integrating mapping capabilities, thanks to the various gadgets that reuse the Google Map API

Lotus Connections supports only widgets that follow the IBM-developed iWidget specifications. There is no ready-to-use support for other widget models, such as the Google gadgets model. The iWidget format, though, is flexible enough to allow you to display any content that can be found on a standard Web page. On the other hand, Google provides a way to surface gadgets on any Web page using an HTML script tag. The technique you follow consists using an iWidget acting as a wrapper around the script tag to display the Google gadget.

A previous developerWorks article, "Implementing and deploying Google gadgets for the Lotus Connections home page," introduced the technique you can use to display Google gadgets in Lotus Connections 2.0 from a developer's point of view. The aim of this section is to offer a summary and a skeleton that an administrator can use to deploy a new Google gadget in Lotus Connections without requiring any programming knowledge. The programming details are optional; they are presented in the final section of this article for interested readers.

Quick steps to add Google gadgets to Lotus Connections

A skeleton of iWidget wrapping a Google gadget is implemented and available in the Download section of this article. In this section, you learn how to edit the skeleton to display a Google gadget of your choice.

The skeleton comes as a standard Java Platform, Enterprise Edition (Java EE) WAR file that can be deployed to any Java EE containers, such as the WebSphere Application Server running Lotus Connections, for example. At this point, the skeleton is preconfigured to wrap a Facebook Google gadget as shown in figure 15.

Figure 15. iWidget wrapping a Facebook Google gadget and running in Lotus Connections Home page
iWidget wrapping a Facebook Google gadget and running in Lotus Connections Home page

The following steps show you how to configure the skeleton to display a Google gadget of your choice from the Google Gadget Catalog. Note that you use the IDE Eclipse 3.4 to edit the files contained in the skeleton WAR file. A WAR file is a compressed file that follows a couple of conventions. As such, you could also use any standard compression application to access and edit the files inside this archive if you want.

More details about getting and installing the Eclipse IDE can be found on the official site at www.eclipse.org. Make sure that you select the Java EE developer edition.

First, let’s create an Eclipse project with the content of the WAR file:

  1. Download the WAR file named googleWrapperSkeleton.war.
  2. In Eclipse, go to File – Import – Web – WAR file. Select Next, and browse for the downloaded WAR file on your disk. Enter the name of your choice for the project.
  3. Preserve the default values of the form Web Import: Web Libraries, and click Finish. A new Eclipse project with the files contained in the WAR file has been created.

You are now ready to edit the files of the widget. First, though, you have to get the URL to the gadget descriptor from the Google Gadget Catalog:

  1. Go to the Google Gadget Catalog . Select a gadget, and click the button Add to your webpage, which directs you to the widget description page. In the following steps, you use the BBC News gadget as an example.
  2. In the widget description page, click the button Add to your webpage to get to the customization page for the gadget shown on figure 16. You can customize some attributes of the gadget, such as its size and title, from this page. For good integration with the Lotus Connections look, it is advised that you select a blank border and no title (empty string) for the gadget in the customization form as shown in figure 16. The Lotus Connections runtime automatically builds a border and title bar around each widget.

    When you have completed the customizations, click the Get the Code button.

    Figure 16. Customization form of the Google gadget
    Customization form of the Google gadget
  3. From the text box at the bottom of the page, copy and keep note of the part of the URL following the string ?url= in the src attribute of the script tag. The copy-pasted string should end with output=js.

    For example, for the BBC gadget , the URL is as follows:

    http://shazingo.com/lig/lg/178002.xml&up_extrafeed=http%3A%2F %2Fnewsrss.bbc.co.uk%2Frss%2Fnewsonline_uk_edition%2Fhealth %2Frss.xml&up_extratitle=Health&up_subject=&up_entries=6 &up_summaries=300&up_selectedTab=&synd=open&w=320&h=360&title=&border=%23ffffff%7C3px%2C1px+solid+%23999999&output=js

Now, let’s go back to Eclipse to customize the skeleton files to display the selected Google gadget. Follow these steps:

  1. Locate and expand the project created previously from the WAR file in the Eclipse Project Explorer (you might need to switch to the Java EE view).
  2. Open the file gadgetWrapper.xml in the WebContent directory. Locate the iw:item node whose ID is gadgetUrl (see figure 17). Edit the value attribute to place the URL of the gadget you picked from the Google Gadget Catalog.

    Figure 17. Node to edit in gadgetWrapper.xml with the Google gadget link
    Node to edit in gadgetWrapper.xml with the Google gadget link

    Tip: You can also edit the height item set value to adjust the total height consumed by the widget in Lotus Connections to avoid vertical scrollbars.

  3. Right-click the project in Eclipse ( the Project Explorer panel), and select Export - WAR file. Pick a location on your disk for the file and click Finish.

As for the widget created with Lotus Widget Factory in the first section of this article, you just have to follow these steps:

  1. Deploy the WAR file in WebSphere Application Server, and start the corresponding Web application. On deployment, specify the context root of the Web application and keep it in mind for the registration step in Lotus Connections. This step is standard and does not differ from the steps in any other Java EE application. Refer to the IBM WebSphere Application Server 6.1 Information Center if you need more details.
  2. Register the new widget in the Lotus Connections Home page. The URL to the XML descriptor of the widget is located at :

    http://<server>:<port>/<contextRoot>/gadgetWrapper.xml

    where server, port, and contextRoot depend on where you deployed the WAR file.

    The steps are the same as for the widget you created with Lotus Widget Factory earlier for Home page. You can also refer to theLotus Connections 2.5 Information Center documentation for more details.

That’s it! Figure 18 shows a complete user experience with the BCC News Widget, two other Google gadgets (Facebook, Currency Convertor), the DeveloperWorks widget you created with Lotus Widget Factory, and a widget provided with Lotus Connections.

Figure 18. Lotus Connections Home page 2.5 with widgets from various locations (Google gadgets, widget created with Lotus Widget Factory, and standard Lotus Connections widget)
Lotus Connections Home page 2.5 with widgets from various locations (Google gadgets, widget created with Lotus Widget Factory, and standard Lotus Connections widget)

Learning more about iWidgets

The first two sections of this article introduced two easy ways to create widgets for Lotus Connections without your having to write code. This section is intended for readers who want to go deeper and understand what happens "under the hood." The objective of this section is to give a starting point for developers willing to implement widgets with a greater level of customization than that allowed by tools such as Lotus Widget Factory. Unlike the rest of this article, this section requires knowledge about the development of Web applications.

Note that there is a parallel between this section and the previous developerWorks article, "Implementing and deploying Google gadgets for the Lotus Connections home page," released for Lotus Connections 2.0. Rather than reintroducing the entire set of specifications, this section highlights the main features of iWidgets and points to examples in the previous article. This section also introduces the new capabilities related to iWidgets in Lotus Connections 2.5.

iWidget specifications in a nutshell

The term iWidgets refers to the IBM-developed specifications for defining widgets. Several IBM products, such as Lotus Connections and Lotus Mashups, embed a common component called the iWidget framework that is capable of rendering widgets following the iWidget specifications.

Note that the iWidget specifications define only the client-side aspects of a widget, in other words, the part running on the browser. There are no restrictions on the technologies used for the server-side code of the widget. Communication between the client-side and server-side components of a widget is usually done through standard technologies such as asynchronous requests (Ajax), for example.

At its basic level, an iWidget is defined by an XML descriptor written by the widget developer. The descriptor includes the following:

  • A way to define the markup (HTML code) of one or more views supported by the widget.
  • The capability to point to external resources such as JavaScript and CSS files used by the widget. The JavaScript files usually contain code written by the widget developer and defining the behavior and logic of the widget.
  • A couple of attributes related to encapsulation. Encapsulation is needed to allow several instances of the same widget to be open on the page without resource clashes. The main aspect of this mechanism is the iScope attribute defined in the XML descriptor. The iScope attribute points to the name of the JavaScript class defining the behavior of the widget and is implemented in one of the external JavaScript files mentioned in the previous item.

You can refer to the Hello World iWidget in the first section of the earlier article, "Implementing and deploying Google gadgets for the Lotus Connections home page," http://www.ibm.com/developerworks/lotus/library/connections-gadgets/ for a concrete example of the basic iWidget concepts.

Additionally, the iWidget specifications define a few services that can be used by the widget developers. The services provided by the iWidget framework can be used by invoking methods on an object named iContext and set automatically in the iScope class of the widget instance. Here is a quick overview of the services provided by the iWidget specifications:

  • Properties store. The iWidget framework provides the ability to manage and persist name-value pairs called itemSets. itemSets can be declared in the XML descriptor of the widgets and manipulated in the iScope JavaScript code.
  • IO module allowing the widget to fetch resources from any domain by redirecting the requests through an Ajax proxy.
  • An eventing system allowing the widgets to communicate with each other on the page by publishing and catching events. Note that this feature is specific to Lotus Mashups environments and is limited in Lotus Connections.

The second part of the article, "Implementing and deploying Google gadgets for the Lotus Connections home page," introduces the different capabilities provided by the iWidget framework through the concrete example of the implementation of the Google gadget wrapper. Moreover, the wrapper introduced in the previous article goes further by allowing users to customize the gadget from the edit view of the widget, which is not possible with the generic skeleton approach.

You can find more details about the implementation of iWidget in the Lotus Connections iWidget development guide.

You can download the complete iWidget specification v1.0 document.

iWidget specification v1.0 in Lotus Connections 2.5

Lotus Connections 2.0 was based on a pre-1.0 version of the iWidget specification.

Lotus Connections 2.5 now supports the iWidget specification written following the final version of the iWidget specifications v1.0 document. Concretely, it means the following for a developer:

  • Improved persistence mechanism. Lotus Connections 2.5 supports a predefined managed itemSet named attributes that can be used by the developer to persist name-value pairs across user sessions. The main difference between the attributes itemSet and a normal itemSet is the presence of the save() method. When this method is invoked from the widget code, the items (name-value pairs) are persisted across the user session. A reference to the attributes itemSet is returned by a call to iContext.getiWidgetAttributes().

    In the previous article, "Implementing and deploying Google gadgets for the Lotus Connections home page," http://www.ibm.com/developerworks/lotus/library/connections-gadgets/ , you can notice that Lotus Connections Home page 2.0 provided a custom persistence mechanism based on methods named _save and _load. These methods are still supported for backward compatibility in Lotus Connections 2.5, but they should not be used for new widgets. The custom persistence mechanism was used in the previous developerWorks article and in the Google Date Time example. You can find an updated version of the Date Time example using the new attributes-managed itemSet attached to this article (gadgetWrapperDateTime2_5.war).

  • Consistent way to get details about the authenticated user. You can now use the method getUserProfile() on the iContext object to get an itemSet containing information about the authenticated user. For exampke, this.iContext.getUserProfile().getItemValue(‘displayName’) returns the name of the authenticated user. You can find more details the wiki page: http://www-10.lotus.com/ldd/lcwiki.nsf/dx/common-iwidget-support-in-the-lotus-connections-features under “Obtaining information about the logged in user with UserProfile."

iWidgets in Home page, Communities, and Profiles in Lotus Connections 2.5

While this article focuses on the Home page feature of Lotus Connections, be aware that Communities and Profiles can also be extended with iWidgets in Lotus Connections 2.5. Home page, Communities, and Profiles support the same version of the iWidget specifications (v1.0), and thus, widgets that strictly follow the iWidget specifications can be rendered in those three components without any modifications. This is the case for the widgets created by Lotus Widget Factory and the Google gadget using the two first sections of this article.

Note a couple of points regarding iWidgets in Communities and Profiles:

  • In Communities, widgets can be placed by the community owner in predefined placement areas on the Community page through the widget palette. You can find the details of the predefined area in the Lotus Connections iWidget Development Guide.

    Additionally, the administrator can define mandated widgets, that is, widgets that are displayed by default on any Community page and that cannot be removed by the Community owner.

  • Profiles supports only mandated widgets; that is, the Profiles owner cannot add or remove widgets from a palette as the owner can in the Home page and Communities features.
  • The deployment of new widgets in Communities and Profiles is done by editing XML configuration files on the server rather than from a user interface as in Home page. See the IBM Lotus Connections 2.5 Information Center for more details.

Conclusion

This article introduced two ways to create widgets for Lotus Connections without having a deep knowledge of Web development. The first section introduced Lotus Widget Factory as a development tool to create complex widgets for Lotus Connections and guided you through a concrete example of a widget that displays podcasts from developerWorks.

The second section of the article outlined the steps you can take to leverage the vast Google Gadget Catalog to bring new capabilities to Lotus Connections users.

Finally, the third section was a starting point for developers wanting to learn more about the iWidget specifications and implement their own iWidgets using traditional development tools.


Acknowledgments

The author would like to thank Luis Benitez and Adrian Spender for taking the time to review this article and making helpful suggestions of improvements.


Downloads

DescriptionNameSize
Code samplegadgetWrapperDataTime2_5.war4KB
Code samplegoogleWrapperSkeleton.war4KB

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, WebSphere
ArticleID=431035
ArticleTitle=Customizing IBM Lotus Connections 2.5 with Lotus Widget Factory and Google gadgets
publish-date=09292009