Lotus Domino Administrator 8.5 Help - Using widgets in Lotus iNotes

LOTUS INOTES

Using widgets in Lotus iNotes
You can define a set of widgets that are integrated into the IBM® Lotus® iNotes™ mail client, and you can specify the toolbox catalog and category names from which users can select and install their own widgets. These widgets display in the Widgets folder in the navigation pane. When a user launches a widget, it may optionally solicit some input within a dialog or from selected text on the page, and then eventually open an external Web page in a new tab or a new browser window. Users can enter any text that is required by the service (such as text to be translated by a translation service), and the application results or output is displayed.

Enabling and configuring widgets in Lotus iNotes

Enable this feature by checking these two mail policy settings on the Lotus iNotes - Configuration tab of the Mail policy settings document:

Show the Widgets folder in the Mail outline
Allow users to create widgets from XML (optional, for advanced users)

If you do not use policies or if you want to enable or disable this feature temporarily on a trial basis, you can use the NOTES.INI setting iNotes_WA_Widgets=1 to enable it server-wide, or iNotes_WA_Widgets=0 to disable it server-wide. Using this setting overrides any policy setting.

To configure this feature, edit the inotes_config.xml file (located in the Domno/Data/domino/html folder) to include the widget configuration information. If this file does not exist, you can create this file based on the example provided below. The file may include one of both of the following elements:

A <toolboxCatalog> element specifying the toolbox catalog database name and the comma delimited list of categories containing widgets. Lotus iNotes users will be able to select widgets that specify the iNotes 8.5 target platform in these categories when they select the Browse Widgets Catalog context menu item on the Widgets folder in the mail outline. Note that a local replica of the toolbox catalog must be located on the Domino Web server, and that only widgets in the specified categories that specify iNotes 8.5 in the platform field of the widget document will be displayed.
Zero or more <webcontextConfiguration> elements containing widget definitions. Widgets specified here appear in the Widgets folder of all users and cannot be removed by the user. The XML for a widget can be obtained from the extension.xml file included as an attachment in the document defining the widget in the toolbox catalog.

The following is example markup for inotes_config.xml

<?xml version="1.0" encoding="UTF-8" ?>

<inotes:extensions xmlns:inotes="urn:x-inotes:ibm.com">

<toolboxCatalog name="toolbox.nsf" categories="iNotes Widgets"/>

<webcontextConfiguration version="1.1">

...

</webcontextConfiguration>

<webcontextConfiguration version="1.1">

...

</webcontextConfiguration>

</inotes:extensions>

Differences between the Notes client and Lotus iNotes using HTTP POST

The IBM® Lotus® Notes® client and Lotus iNotes™ implement the HTTP POST form submission method of loading a Web page differently due to security restrictions imposed by the same origin server policy on browser applications. Notes first loads the form from the Web site into the embedded browser, and then inserts the required parameters into the DOM of the form and submits it by invoking the form's submit JavaScript™ method. However, since Lotus iNotes is a browser application running inside of the browser (rather than an embedded browser container like Notes), it cannot access any elements in the DOM of the Web application unless the Web application is served from the same server as Lotus iNotes. This is known as the same origin server security policy. Consequently, Lotus iNotes must create a form element with the known input fields and values, and then submit the form to the Web application server using the form's action URL, specifying that the response display in the target iframe. As a result, Lotus iNotes cannot support widgets for all Web sites that the Notes client can support. The method of form submission that Lotus iNotes uses may fail for a number of reasons, but these are the most common:

The Web application requires JavaScript code to run when the form is submitted which sets the values of hidden fields on the form.
The Web application uses a nonce (a unique string who's value is valid only for a short time) that is included in the POST as a way to guard against denial of service attacks.

Known issues

Widgets created using Lotus Notes 8.0 do not specify the action URL for the form when using form based (HTTP POST) parameter submission. In 8.5, the widget creation wizard has been enhanced to provide the action URL in the <formAction> element. This means that widgets created with Notes 8.0 that use HTTP POST form submission will likely not work with Lotus iNotes and would need to be recreated using the Notes 8.5 wizard.

Web agent design elements in the toolbox catalog database must be signed using the Domino server's credentials in order to allow these agents to run for Lotus iNotes users. If the design elements are not signed by the server, Lotus iNotes users will not be able to browse the widgets catalog. Use the Domino Administrator client to sign the design documents in the database with the server's id.

Limitations

There are a number of limitations regarding the use of widgets with Lotus iNotes compared to the Notes client. These are listed below. Catalog widgets should be tested with Lotus iNotes to make sure that they work well on that platform prior to making them available to Lotus iNotes users. Catalog widgets are made available to Lotus iNotes users by adding "iNotes 8.5" to the platform field in the catalog document for the widget, and by including them in a category, or categories, specified in inotes_config.xml. Note that filtering widget catalog entries by platform type is relatively expensive from a server performance standpoint compared to filtering by category, so to maximize server performance, avoid including widgets that cannot support iNotes in the categories used to expose widgets to iNotes users. Following is a list of widget limitations when using widgets with Lotus iNotes:

Only widget definitions (<palleteItem> elements) with providerId="com.ibm.rcp.toolbox.web.provider.WebServicesPalleteProvider" are supported at this time.
The only supported output targets for a widget is a Lotus iNotes tab panel and a new browser window. The <actionType> element in the widget XML specifies the default output target. The sidebar and floating window targets are not supported. If the <actionType> element for the widget specifies an unsupported output target, then the output will be displayed in a Lotus iNotes tab panel. Note that the user can override the default output target by selecting the desired target in the Open context menu item for the widget..
The only supported contentTypeId for <contextData> elements is content.textSelection.
It is possible for users navigating a Web site within a tab panel in Lotus iNotes to click on a link that will navigate to a different top level browser page. Due to browser architecture, there is no way for Lotus iNotes to prevent this from occurring. It is best to avoid using tab panels with Web sites that contain such links and to open these Web pages in a new browser window instead.
Lotus iNotes cannot detect selected text within a Web page that is displayed in a Lotus iNotes tab pane for the purpose of passing the selected text as an input parameter to a widget, if the Web page is served from a different server than Lotus iNotes.

Related topics

Lotus iNotes

Using an HTTP-proxy Servlet to restrict URLs to external servers

Glossary

Feedback on Help or Product Usability?

Help on Help

All Help Contents

Glossary