Building composite applications with Notes widgets in IBM Lotus

Notes 8.0.1
Level: Intermediate Document options
Liu Jun, Software Engineer, IBM
Print this page
Hardy Groeger, Certified Senior IT Architect, IBM Corporation
25 Nov 2008
This article introduces the concept and usage of Notes® My Widgets. Through several examples, it shows you how to create Notes E-mail this
widgets from different kinds of resources in IBM® Lotus® Notes® 8.0.1. Finally, it depicts the process that you can use to build a page
sample composite application leveraging Notes widgets. Document
options requiring
JavaScript are
not displayed
Notes My Widgets is a newly introduced user interface (UI) feature in Lotus Notes 8.0.1. It offers Lotus Notes users an easy but
Discuss
effective way to leverage other existing resources, such as Web sites, Lotus Notes databases, Google gadgets, or feeds. It works as
Sample code
a stand-alone application, together with another new feature called Live Text. Widgets can be triggered using Live Text, accessed
within the MyWidgets sidebar application, or leveraged as components within composite applications. Like other composite Hey there!
application components, through the composite application editor (CAE), Notes widgets can be easily configured to interact with developerWorks is using
other composite application components. Twitter
For detailed information regarding composite applications in Lotus Notes, see the composite applications topic on the IBM Follow us
developerWorks® Lotus Web site.
Rate this page
Prerequisites
Help us improve
This article assumes that you are familiar with composite applications and how to build them using the composite application editor
this content
in Lotus Notes. To use the examples on your own computer, you also need to install Lotus Notes 8.0.1, including the CAE.

Back to top
Notes widgets overview
Notes My Widgets is a new feature first introduced in Lotus Notes 8.0.1. Notes widgets are small, specialized applications that enable users to leverage existing
services or resources based on automatically recognized Live Text in their Lotus Notes documents. A widget can be accessed through the sidebar, launching it
from Live Text or text selection, or adding it to composite applications. In contrast to ordinary Lotus Notes applications, creating a Notes widget does not require
that you write any code or script. Notes widgets configuration wizards make it easy to create and configure widgets from Lotus Notes view searches or
documents, Web pages, feeds, or even Google gadgets.
Figure 1 is an example of a popular usage of Notes widgets. From a Lotus Notes mail document, a floating window containing Google Map is launched by right-
clicking selected text and using the context menu. The input search term is the selection in the Lotus Notes mail document. The floating window here is the
Notes widget itself. It looks like a common Web page running directly in a window other than a browser. Actually, the Notes widget shown in figure 1 is created
from a Web page (Google Map), and all the content in the window is provided by the Web page (Google Map).
Figure 1. Notes widget in floating window

To use Notes widgets in Lotus Notes, you can either import created Notes widgets from the Notes widgets catalog server and XML files or create your own
customized Notes widgets. Lotus Notes 8.0.1 provides tools to perform all the related actions. Figure 2 shows you the widget toolbar and the My Widgets
sidebar. The widget toolbar is used to launch the Notes widgets configuration wizards, which can help you create your own customized widgets. The My Widgets
sidebar is used to manage all your existing Notes widgets. You can configure the trigger actions and remove Notes widgets in the sidebar.

Figure 2. Notes widgets toolbar and sidebar panel

Through administrative policies or local preference settings, you can control whether users see the Widget toolbar and the My Widgets sidebar. Unless restricted
through policy settings, users can display them by selecting the option in the Widgets preference settings as figure 3 shows. If you have a Notes widgets catalog
server, you can also import existing Notes widgets there.

Figure 3. Notes widgets preference window

In addition being shown in a floating window or a sidebar, Notes widgets can also be built into composite applications working as composite application
components interacting with other components. Figure 4 shows a sample composite application made up of a Notes view component and Notes widgets.

Figure 4. A sample composite application with Notes widgets components

To better understand the building blocks of this composite application, review the four components that make up the overall functionality:

• UserTable. A Notes view containing records of the user’s profile, including name, location, address, and zip code.
• myWeather. A Notes widget created from a Google gadget showing the weather forecast for a specific city.
• Yahoo News. A Notes widget created from a feed displaying news related to a specific topic.
• Google Maps. A Notes widget created from a Web page showing map information of a specific address.

After a user selects a record in the UserTable, the other three components immediately reflect the changes according to the selected user’s profile. myWeather
displays the weather forecast of the city where the user lives, Yahoo News displays news related to the city where the user lives, and Google Maps shows the
map information of the user’s address.
In the following sections of this article, we provide step-by-step instructions on how to create this sample composite application. We first create all the required
Notes widgets using the Notes Widgets configuration wizards. Then we create the composite application from the created components through the composite
application editor in Lotus Notes.
NOTE: This article does not cover the process of creating the Notes view component. We start directly from an existing Lotus Notes database containing the
UserTable Notes view. Download the sample Lotus Notes database.

Back to top
Creating Notes widgets in Lotus Notes 8.0.1
You can create Notes widgets from Web pages, Google gadgets, or feeds.
Creating Notes Widgets from a Web page
The following section depicts the process of creating a Google Maps widget.

1. Launch the Notes widgets configuration wizard by clicking the button in the Notes Widgets toolbar as shown in figure 5.

Figure 5. Launching the Notes widgets configuration wizard

2. Select the Web page option to create Notes widgets from a Web page.
3. Select the Web page by URL option, and then type the address of the Web page from which you are going to create the Notes widget. In this example,
enter http://www.google.com/maps. Click Next. See figure 6.

Generally, you can create Notes widgets from any Web page that can be accessed through a browser. To make the Notes widgets interactive, select Web
pages that allow you to pass parameters to change the content shown.
NOTE: You can also select the Browse the Web option here. In that case, the wizard takes you to the Lotus Notes embedded browser. There you can
first browse the Web page from which you want to create the Notes widgets, and then you can perform the following actions.
 Figure 6. Configuring a component from a Web page

4. Select the From a form on this Web page option.

 The difference between the two options here is that HTTP GET passes parameters through a URL link while HTTP POST passes parameters through a
Web form submission. Google Maps shows different maps according to the user’s address input through a Web form submission on the Web page.

5. Select the correct Web form to collect the user input address.

A Web page can contain more than one Web form, including visible and invisible ones. When you select the number, the corresponding Web form in the
Web page is highlighted as shown in figure 7. It also displays a preview of the widget that you are going to create.

Figure 7. Selecting a form and previewing the widget

6. Configure the settings for the Notes widget.

The wizard automatically recognizes all the accepted parameters of the selected Web form. As Google Maps requires only a query address to show
related maps, here you just need to check the ID, which means you only need to pass one parameter to the widget (which in turn passes the parameter
to the Web form on the Web page). You can change the label of the parameter to make it more user friendly. In this case, set the display name
address.
Because we use the Google Maps widget as a composite application component, you need to select the Just configure a component for now option. You
can select the Wire as an action or Display as a sidebar panel option if you want to configure it as a stand-alone widget integrated with Live Text or
accessible through the sidebar. We do not cover that part in this article. See figure 8.

Figure 8. Configuring a component

7. Click Finish. A Google Maps widget is added to the My Widgets sidebar as shown in figure 9.

Figure 9. Google Maps widget added to the My Widgets sidebar

Creating Notes widgets from Google gadgets
The following section details the process used to create the myWeather widget from a Google gadget.

1. Launch the Notes widgets configuration wizard by clicking the button in the Notes Widgets toolbar.
2. Select the Google Gadgets option to create Notes widgets from Google gadgets.
3. Select the Add a Google Gadget by URL option, and then type the URL of the Google gadget from which you are going to create the Notes Widget. In
this case, enter http://www.notkewl.com/myWeather/myWeather.xml.

For detailed information regarding Google gadgets, see the description on the Google gadgets Web site.

4. Configure the settings for new the Notes widget.

The wizard automatically recognizes all the accepted parameters of the selected Google gadget. Here we can see that the myWeather Google gadget
requires two parameters: one for zip code and one for the weather display unit.

Figure 10. Configuring a component

5. Click Finish, and a myWeather widget is added to the My Widgets sidebar as shown in figure 11.

Figure 11. myWeather gadget added to the My Widgets sidebar

Creating Notes widgets from a feed
The following section details the process used to create the Yahoo News Search widget from a feed. Follow these steps:

1. Launch the Notes widgets configuration wizard by clicking the button in the Notes widgets toolbar.
2. Select the feed option to create a Notes widget from a feed.
3. Select the Enter a feed URL option, and then enter the URL of the Yahoo News Search feed from which you are going to create the Notes widget. In this
case, enter http://news.search.yahoo.com/news.
4. Click Finish. A Lotus Notes embedded browser opens that displays the Yahoo Search page.
5. Type "America" and click the News Search button. The browser shows the search result.
6. Launch the Notes widgets configuration wizard by clicking the button in the Notes widgets toolbar.

NOTE: You can also launch the wizard by selecting Tools - Widgets - Configure a Widget from Current Context.
7. Select the Feed: Yahoo! News Search results for America option.
8. Click Next to open the Configure a Component window.
9. Instead of always searching for “America” we want to use the search key as a parameter on the widget. Enter "topic" in the Display name field to give it
a more meaningful name.
10. Click Finish. A Yahoo News Search widget is added to the My Widgets sidebar.
Figure 12. Yahoo News Search widget added to My Widgets sidebar
 Back to top
Building composite applications with Notes widgets
Although using widgets in Lotus Notes can already save you a lot of the time that you spend opening a browser and searching bookmarks or Web sites directly,
Notes My Widgets can also use widgets directly as components within composite applications. This approach allows you to mash up solutions built from simple
widgets that interact with each other and provide a higher value than they would separately. Let’s use your newly created widgets in the context of a composite
application.
Create a blank composite application
Follow these steps:

1. Choose File - Application - New to open the New Application window as shown in figure 13.

Figure 13. New Application window

2. Enter the Title of the new composite application, select Blank Composite Application in the Template field, and then click OK to finish creating a new
blank composite application. The warning shown in figure 14 displays.

Figure 14. Empty Content View window

Add components to the composite application
Follow these steps:

1. Choose Actions - Edit Application to open the composite application editor (CAE).
2. Add NSF components to the composite application editor component palette.

Before you can carry out the following actions, copy UserTable.nsf (you can download it from the Download section) to your Lotus Notes data directory,
for example, C:\Program Files \Notes\Data.

3. Choose Tools - Component Palette - Add Components - Add NSF Component to open the New NSF Component window as shown in figure 15.

Figure 15. Opening the New NSF Component window

NOTE: You can also add components from the context menu by right-clicking in the Component Palette and selecting Add Components - Add NSF
Component.

4. In the New NSF Component window, click Browse, and then select the view User Table from the application titled UserTable.

NOTE: You might need to navigate to the database using the folder button to the right of the Application drop-down field as shown in figure 16. Click
OK.
 Figure 16. Using the folder button

5. After locating the NSF component, append &HideNavigator to the Lotus Notes URL. This option prevents the display of the Lotus Notes navigator panel
for the component and allots the entire component display area to the Lotus Notes view pane.

Your result should look like the screen shown in figure 17.

Figure 17. New NSF Component window

6. Click OK to add this NSF component to the component palette.

A new palette has been created called My Palette, and the component that you added displays in the component palette on the right as shown in figure
18.

Figure 18. Component Palette window

Define the visual placement of components using drag and drop
Now you should be able to see four components in the My Palette component palette. In this step, you need to drag those components to the blank composite
application page and adjust the layout to meet your preferences. The layout does not affect the functionality.
Figure 19 shows a sample layout.

Figure 19. A sample layout

So far, you have aggregated components into a composite application, but none of the components can interact with one other. You still have to finish the last
step: wiring. After you finish the wiring, the Notes widgets get input from the UserTable view and show information accordingly.
Wire components in the composite application
The wiring capabilities of the composite application editor can wire components of heterogeneous technologies. The property broker feature of the Lotus Notes 8
client provides the required runtime environment to carry out action triggers based on property updates. Next, you wire the three Notes widgets that you
created to the NSF component, called User Table.
Follow these steps:

1. If you have closed the CAE before, open the sample composite application in Lotus Notes and choose Actions - Edit Application to open this application
 in CAE.
2. Choose Edit - Page - Wiring to open the Wiring Pane page.

In the Wiring Pane page, all components together with their properties and actions are listed. From the User Table component, you can see that four
properties and one action are defined. In the other three Notes widget components, you can find the names that you defined during their creation. The
last thing left to do is to wire the three Notes widgets to the User Table component. In other words, you are going to send information (property data)
from the User Table component to the predefined actions in the three Notes widgets.

3. Select the Address property in the User Table component, hold down the main mouse button and drag the property to the Address property listed in the
Google Maps component, and release the mouse button.
4. Select the ZipCode property in the User Table component, hold down the main mouse button and drag the property to the ZipCode property listed in
the myWeather component, and then release the mouse button.
5. Select the Location property in the User Table component, hold \down the main mouse button and drag the property to the topic property listed in the
Feed: Yahoo! News Search component, and then release the mouse button.

Figure 20. The Editing window

 6. Choose File - Finish Editing to confirm the changes to your composite application.

Test the wiring

After you have finished editing the composite application, the updated composite application displays automatically. See figure 21.

Figure 21. The updated composite application

To see the new property and action wirings in action, select a document in the User Table view component shown in the top left of the window. When a
document is selected, the location, address, and zip code in this document are published. Then the three Notes widget components receive information as
configured in the Wiring Pane page. You should be able to see that the myWeather widget displays weather information of the location (zip code), the Yahoo!
News Search widget displays the latest news related to the location (city), and the Google Maps widget shows the map of the address.

Back to top
Conclusion
This article introduces the concept and use of Notes widgets. Then, through some examples, it shows you how to create Notes widgets from different kinds of
resources and services in Lotus Notes 8.0.1. Finally, it depicts the process to build a sample composite application leveraging previously created Notes widgets.

Back to top
Download
Name Size Download method

UserTable.nsf 320KB HTTP

Information about download methods

Resources
 • Participate in the discussion forum.

• Read the developerWorks article, "Designing composite applications: Component design."

• Read the developerWorks article, "Designing composite applications: Design patterns."

• Read the developerWorks article, "Designing composite applications: Unit testing."

• Read the developerWorks article, "Designing composite applications: Writing an Eclipse component for IBM Lotus Notes."

• Read the developerWorks article, "Designing composite applications: IBM Lotus Notes components."

• Read the developerWorks article, "Designing composite applications: Composite application assembly, part 1."

• Read the developerWorks article, "Designing composite applications: Composite application assembly, part 2."

About the authors

Liu Jun is a software engineer from the IBM Software Services for Lotus team at the IBM China Development Lab in Beijing. His working experience includes
IBM Lotus Forms, IBM Lotus Connections, composite applications, and IBM Lotus Mashups. You can reach him at liujunsh@cn.ibm.com.
Hardy Groeger is a Certified Senior IT Architect working as a Services Solution Architect for IBM Software Services for Lotus in Europe, where he focuses on
application architecture and development based on the Lotus product portfolio. Since he joined IBM in 2001, he has held various positions in product
development and services. Before joining IBM he was a Project Manager Development at a German Lotus Business Partner and was specialized in SAP R/3 and
Lotus Domino integration. You can reach Hardy at hardy.groeger@de.ibm.com.