IBM developerWorks: Wikis - IBM Composite Applications - Building NSF Components

This page describes how new NSF components can be developed via Lotus Domino Designer and how existing NSF databases can be used in composite applications.

1. What are NSF components?

A component in a composite application is basically a rectangle in the UI. A NSF component displays a Notes object like a Notes view in a rectangle. A NSF component can be configured differently for every occurrence in an application as part of the composite application via static component preferences. Additionally a NSF component defines its output properties and actions.
In summary a NSF component has:
-   a Notes URL
-   static component preferences (optional)
-   output properties and actions (optional)

The lead manager sample application [reference 6] shows how four different NSF applications can be put as NSF components in a composite application.

NSF components can be added to the palette in the CAE via "Add Components-Add NSF component". From the CAE there is a NSF component picker available to navigate to a certain Notes database and then pick the Notes object you want. Alternatively NSF components can be added to the "MyWidgets" category on the palette from the Notes client directly by opening the NSF object and then use the "Configure widget from current context" action.

The Notes URLs can be used to refer to certain Notes objects. When using a Notes view the navigator can be hidden via an URL parameter "&HideNavigator" [reference 7]. The property broker can only be used from Notes forms and Notes views.

The Notes URL can contain paths to databases or it can contain replica ids. To identify special types of databases the following special 'replica id' can be used [reference 8]:
- notes:///0000000000000E00 - this opens the current user's mail database
- notes:///0000000000000E01 - this opens the current user's contacts database
- notes:///0000000000000000 - this searches for a NSF component in the same database that has the CA XML

2. Deployment of NSF components

Composite applications are typically developed in non-production environments and test databases are used. When moving the composite applications with hardcoded links to the test databases to a production environment the links break. To avoid this, relative links can be used via @Formulas that are executed in the database containing the CA XML. The @Formulas are defined in the advanced component properties in the CAE ("com.ibm.notes.ComputedNotesURL"). In these @Formulas you can for example access fields in Notes profile documents that contain the links to the databases. The values in these profile documents can then be changed via LotusScript as part of some automated deployment. See here [reference 9] for more details.

3. Using property broker - built in properties and actions

Composite applications allow the reuse of existing NSF applications in composite applications. In many scenarios it is desirable to use NSF components without changing their designs. One reason is to avoid development work to extend existing NSF applications. Especially when building the first composite applications in PoCs very often developers don't have designer access to the deployed databases that they want to reuse.
Another reason is simply to avoid the re-deployment of the changed databases for various reasons like to avoid re-testing the databases.

Because of this, Notes has so called built in properties and actions for NSF components. These properties and actions can be used without changing the databases (e.g. no WSDL needs to be defined).

Built in property SelectedNotesDocumentURLChanged:
A typical scenario is that an action is supposed to be invoked when another view entry is selected. The built in property can be used to publish the Notes URL of the currently selected view entry. Other components can then use this URL as callback to access any field of the selected document via LotusScript or Java API. To define from which views this property is supposed to be published, the views need to be defined in the advanced component property "com.ibm.notes.publishBuiltInPropsFromView".

Built in action FilterCurrentUIViewViaCategory:
In order to filter the current UI view a built in action can be used (constrained list). These views have to have a sorted column which is used as the key for the lookup. Only view entries are then shows whose values of the first sorted column match with the input property of the action.

Built in action SearchCurrentUIView:
This action performs a full text search on the current UI view.

Built in properties and actions need to be enabled in CAE:
- on page level: "com.ibm.notes.enable.preferences=true"
- on component level: "com.ibm.notes.enableBuiltInPB=true"
See here [reference 10] for more details.

4. Using property broker - custom properties and actions

For more sophisticated scenarios there are no built in properties and actions available. For example if you want to publish a column of a view on selection change rather than the Notes URL. Another example is when you want to provide an action in a form that sets certain field values that are received from other components.Yet another sample is the publication of a value of a field in a document to other components as property.

In these cases you need to follow these steps:
1.   Define the names of your output properties and actions and their datatypes using the Property Broker Editor that is part of Domino Designer (result: WSDL)
2.   For actions:
a.   Map your Notes actions in forms and views to the (property broker) actions defined in the WSDL
b.   Implement your action with LotusScript and use the property broker APIs to retrieve the input property
3.   For output properties:
a.   Properties that are declaratively published when view selections change: Map the column to an output property in the WSDL
b.   Properties that are programmatically published: Use the property broker APIs in any events in forms and views (e.g. OnSelect) to publish any property you want

See this tutorial [reference 11] for more information. See here [reference 12] for more details on how to use the Property Broker Editor. See in the Domino Designer help for more details on the LotusScript property broker APIs (LotusScript classes: NotesPropertyBroker and NotesProperty).

All datatypes are represented as single strings when accessing them from LotusScript. You can then initiate your own LotusScript classes with whatever information these strings contain. Essentially you need to de-serialize the strings in whatever object structure you want to use. For example one string could contain a list of URLs that another component passed to a Notes action. You could then represent this list of URLs in an array of strings in LotusScript or use your own classes.

For datatypes that are more complex than just strings (e.g. lists) we recommend to use JSON to serialize and de-serialize these datatypes from and to strings. JSON is much simpler to handle than complex XML and JSON libraries are available in many other languages that other components might use.
You can either you your own JSON library or try to find one on the internet. For example SNAPPS has recently released a JSON library for LotusScript that is under the Apache license.

5. Using static component properties

Every component can be configured differently for every occurrence in a composite application. This is important when you want to provide a re-usable component that can be used in many different scenarios that you might not even have thought of when you developed the component. For example you might want to use another logo or caption to be displayed on your component dependent on the context it runs in.

In order to do this static component properties can be set in the CAE. You do this under "Advanced Component Properties" where you can define these static properties as opposed to the dynamic properties that the property broker uses.

NSF components can read the values of these properties via an LotusScript API or via an @Formula:
- NotesUIWorkspace.GetComponentViewPreference
- @GetComponentViewPreference
See here [reference 13] for more details.

The same APIs can be used to receive properties that are not set as static component properties but that are passed in via URL to open an application. Composite applications can be referenced via CAI:// URLs that contain the ids of composite applications and/or the NRPC:// URLs pointing to the actual Notes database with the CA XML.
You can append your own parameters to these URLs: e.g.
CAI://....... &CustomParam=CustomParamValue
NSF components can then receive the value of the custom parameter in the same way they read the static component preferences. These custom parameters in the URL don't have to be defined in the static component preferences. If they are however defined in the static component preferences the values are overwritten with whatever is passed in via CAI URL.
See here [reference 14] for more details.

In some scenarios you don't have to know a static component preference, but you only want to know whether your NSF component runs inside of a composite application or not (standalone as in Notes 7). When running a component inside of a composite application there is often less real estate for the component than running it standalone. In these cases you might want to hide and show certain user interface controls. For example you might want to hide certain view actions when running the view component as one of multiple components on a composite application page.

To find out the context your NSF components are running in you can use any of these APIs:
- NotesUIWorkspace.IsInCompositeApp
- @IsInCompositeApp

6. Open Notes documents on pages

Notes documents can also be put on pages in composite applications together with other components. However documents are special compared to other Notes objects like views. Composite applications can have a fixed number of static pages. When documents are opened from views however each document is opened in a new tab. In order to do this template pages can be defined in the CAE that are then cloned for each document at runtime. On this template page a placeholder component ("com.ibm.notes.isDocumentPlaceholder") is put pointing to a Notes form of the documents that are supposed to be shown.
In order for Notes to know when to open a document 'standalone' vs. on a composite application page a naming convention is used. If there is a page with the same alias ("com.ibm.rcp.alias") as the alias of the form the cloned page is used to show the document when triggered from a Notes view. See here [reference 15] for more details.

7. What are NSF widgets?

NSF widgets are essentially special types of NSF components. NSF widgets can be used in composite applications exactly like NSF components can be used. NSF widgets can be added to the "MyWidgets" category on the CAE palette from the Notes client directly by opening the NSF object and then use the "Configure widget from current context" action.

In addition to NSF components widgets provide more capabilities:
1. NSF widgets can be put in the sidebar
2. NSF widgets can be triggered from live text

In order to put a NSF widget in the sidebar LOB (line of business) users can use the "Add to sidebar" toolbar icon to add the currently opened Notes object (e.g. Notes view) to the sidebar with one click. This icon also creates the widget and adds it to the "MyWidgets" sidebar and to the "MyWidgets" category in the CAE palette. NSF widgets can also be added to the sidebar by administrators using the catalog. In both cases it can be defined whether the NSF widgets should be shown in the sidebar on client startup ("contributeToSideshelfOnStartup="false"). Please note that NSF widgets can not use the property broker to interact with other components when running in the sidebar (Notes 8.0.1).

NSF widgets can either just point to a Notes object like a Notes view or they can be used to perform a full text search for a specific live text. You can define a full text search NSF widget by opening a view that you want to query and then use the action "Configure a widget from current context". Then you can define that the NSF full text search widget should be used for a certain live text or text selection within a Notes document. The search results can be shown as any widget either in the sidebar, floating window or tab.

8. References