Using widgets in iNotes

Enable this feature by checking these two mail policy settings on the 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 file 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 following example. 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. iNotes users are 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 IBM Domino Web server, and that only widgets in the specified categories that specify iNotes 8.5 in the platform field of the widget document are 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>

The IBM Notes® client and iNotes implement the HTTP POST form submission method of loading a Web page differently due to security restrictions imposed by the same original 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 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 iNotes. This is known as the same origin server security policy. Consequently, 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, iNotes cannot support widgets for all Web sites that the Notes client can support. The method of form submission that 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.

Widgets created using Notes 8.0 do not specify the action URL for the form when using form based (HTTP POST) parameter submission. In Notes8.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 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 iNotes users. If the design elements are not signed by the server, 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.

There are a number of limitations regarding the use of widgets with iNotes compared to the Notes client. These are in the following list. Catalog widgets should be tested with iNotes to make sure that they work well on that platform prior to making them available to iNotes users. Catalog widgets are made available to 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 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 are an 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 is displayed in an 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 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 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.
• iNotes cannot detect selected text within a Web page that is displayed in an 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 iNotes.