Basics steps: Converting an IBM Lotus Notes application to use Lotus Notes 8 Java components

Java™ views were introduced in the IBM® Lotus® Notes® client in release 8.0. Many new features were implemented using the Java views to modernize the Lotus Notes interface. This article outlines the steps that IBM Lotus Domino developers would take to convert their own Lotus Domino® (simple) applications into Java views. This document presumes that you have an installed version of Lotus Notes 8.5, IBM Lotus Domino Designer 8.5, and Lotus Notes composite application editor 8.5 and that you are familiar with working in Lotus Domino Designer.

Steve Castledine, Advisory Software Engineer, IBM

Steve Castledine is an Advisory Software Engineer with IBM. He is part of the Software Group, and currently responsible for growing the open source effort on OpenNTF.Org and demonstrating the value of Lotus Domino XPages. Previously Steve worked on projects to deliver Blog, Wiki, Notebook/Personal Journal and other PIM applications. You can reach Steve at steve.castledine@uk.ibm.com.



Margo Ezekiel, User Interface Designer, IBM

Margo Ezekiel is a User Interface Designer, working on the IBM Lotus Notes and iNotes Mail clients. She designed the Lotus Notes 8.0 Mail Client, using the Java view features outlined in this document. She worked with Steve Castledine to update the Personal Journal (aka Notebook) application in Lotus Notes 8.5.



29 June 2009 (First published 10 February 2009)

Also available in Chinese Russian 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

This article describes how to convert a Lotus Notes application to a Java application, using the Personal Journal application as an example. You can apply this technique to convert other Lotus Notes templates so that they can have the look and feel of the Lotus Notes 8 personal information management, or PIM (Mail, Calendar, Contacts), applications.

A companion article, "Advanced Java View features in IBM Lotus Notes 8.5," has been published on developerWorks® Lotus.

These instructions work only on simple applications with a navigator (outline), list view, and preview layout. Here is a list of caveats:

  1. Multilevel categories in the view might not work properly.
  2. Total columns in multilevel categorized views might not work properly.
  3. Custom twistie icons might not work for categories.
  4. Navigator does not show custom actions in the navigator pane.
  5. Navigator does not show custom actions in the navigator title bar pull-down menu.

About the conversion process

For the Lotus Notes 8 and later client to render a Lotus Notes application in Java views, the application must first be a composite application. Thus, the first step is to make a composite application using the composite application editor (CAE). Then, you modify the template in Lotus Domino Designer and make further changes using CAE.

The Personal Journal application is a starting point because it’s a simple application in the format of navigator, list view, and preview pane and because it meets the preceding criteria.

Before you begin, make sure that you have installed the Lotus Notes 8.5 client with CAE and Lotus Domino Designer 8.5. You also need a 16x16 PNG file for the page icon, to be displayed in the tab for the application.

Figure 1 shows the original Personal Journal application before you convert it, and figure 2 shows the application after you have completed the steps outlined in this article.

Figure 1. Personal Journal application as a traditional Lotus Notes application - before
Personal Journal application as a traditional Lotus Notes application
Figure 2. Updated Personal Journal application in Java Views - after
Updated Personal Journal application in Java Views

Start with a blank Personal Journal application

Follow these steps in the Lotus Notes client:

  1. Create a new Lotus Notes application, based on journal6.ntf.
  2. Make sure that you turn off the Inherit future design changes option.
  3. Open the new application.
  4. Right-click the tab to open the new application in Lotus Domino Designer.

Create a new composite application in Lotus Domino Designer

Follow these steps in Lotus Domino Designer:

  1. In the navigator, click Composite Applications and then click Applications.
  2. Click the NewCompApp button in the Design pane.
  3. Name the new application file Notes Journal Application.xml and click OK as shown in figure 3.

    Figure 3. CAE: Create a new composite application in Lotus Domino Designer
    CAE: Create a new composite application in Lotus Domino Designer
  4. Select Framesets in Lotus Domino Designer, and double-click BorderFrame to edit. See figure 4.
  5. Select File - Properties and select Frameset from the list that displays.
  6. Set Composite Application – App Name to Notes Journal Application.xml for the application name.
  7. Set Composite Application – Page Name to Blank Page for the page name.

    Figure 4. Lotus Domino Designer: Modify the frameset
    Lotus Domino Designer: Modify the frameset
  8. Select File - Save.
  9. Select File - Exit.

Build the new application based on mail components

The composite application framework uses the Lotus Notes mail components (navigator and list views) to build a composite application page. The Lotus Notes mail components are already wired to drive a list view and preview. You then reassign the mail components to the frameset of your original Journal application.

Follow these steps in the Lotus Notes client:

  1. Open the Lotus Notes client.
  2. Open Journal Example (the NSF file that you created previously).
  3. Select Action - Edit Application to open the application in the composite application.
  4. Click the right arrow to open the component palette. See figure 5.
Figure 5. CAE: Editing the application; opening the component palette
CAE: Editing the application; opening the component palette

Add components

Now, you need to add two components.

Follow these steps in the composite application editor:

  1. Select the Lotus Notes Mail View item from the PIM section of the list that displays and drag it onto the middle pane. See figure 6.

    Figure 6. CAE: Drag the mail view component
    CAE: Drag the mail view component

    The window now looks like the one shown in figure 7.

    Figure 7. CAE: After the Lotus Notes mail view has been dragged in
    CAE: After the Lotus Notes mail view has been dragged in
  2. The actions that you took in the previous step might move the focus back to your Lotus Notes client workspace. If this happens, click the Lotus Notes item in the Taskbar and reopen Editing: Blank Application. You also might need to click the right arrow to reopen the component palette.
  3. Now, drag the Lotus Notes mail navigator component to the middle pane. This step is tricky; you have to drag the view onto the left edge of the pane. When you see the black arrow display on the left of the edge and the narrow bounding rectangle, as shown in figure 8, drop the component.

    Figure 8. CAE: Dragging the mail navigator
    CAE: Dragging the mail navigator

After you drop the navigator, you should see the screen shown in figure 9.

Figure 9. CAE: Drag to the middle pane
CAE: Drag and drop to middle pane

Inherit the border frameset settings from the Personal Journal application

Now you need to replace the mail components with elements from the Personal Journal. You want to have the new application inherit the border frameset settings from the journal template.

Follow these steps:

  1. Right-click the Lotus Notes Mail Navigator component (within the left pane) and select Edit Component Properties.
  2. From the Display Settings tab, select Title Bar to display the title bar.
  3. Click the Component Settings tab.
  4. Select the field Lotus Notes URL.
  5. Replace the E with a 0; replace MailFS with BorderFrame (notes:///0000000000000000/BorderFrame?OpenFrameset) so that your window looks like the window shown in figure 10.

    Figure 10. CAE: Update the Lotus Notes URL field
    CAE: Update the Lotus Notes URL field
  6. Click OK to close the window.
  7. Right-click the Lotus Notes mail view component in the left pane, and select Edit Component Properties.
  8. Click the Component Settings tab.
  9. Select the field Notes URL.
  10. Replace the E with a 0; replace MailFS with BorderFrame: notes:///0000000000000000/BorderFrame?OpenFrameset.
  11. Click the Advanced tab.
  12. Select com.ibm.rcp.csiviews.viewpart.threadurl and click Delete.
  13. Select com.ibm.rcp.csiviews.viewpart.folderalias and click Delete.
  14. Click OK.
  15. To save the changes you have made so far, select Save and Close from the File menu.

Set the page icon and rename the application

Follow these steps in Lotus Domino Designer:

  1. You need an image of format PNG (16 X 16). For an example, see the notebook8.ntf template image tab_notebook_16.png.
  2. Open Lotus Domino Designer.
  3. Select Resources – Images.
  4. Click Import Image Resource to this image as a new image resource. Enter *.png in the file name field. See figure 11.

    Figure 11. Lotus Domino Designer: Add a page icon to the shared resources/image directory.
    Lotus Domino Designer: Add a page icon to the shared resources/image directory.
    Figure 12. Lotus Domino Designer: Setting the File name field to display PNG files
    Lotus Domino Designer: Setting the File name field to display PNG files
  5. Open the composite application editor through the Lotus Notes client.
  6. Right-click Blank Page in the navigator, and select the Edit Page Properties option.
  7. Click Select to choose the icon that you stored in the previous steps. See figure 13.

    Figure 13. CAE: Edit Page icon
    CAE: Edit Page Icon
  8. Next, you can adjust the name of your application by editing the Page Title field. See figure 14.

    Figure 14. CAE: Edit Page Title field
    CAE: Edit Page Title
  9. Click OK.
  10. Select Save and Close from the File Menu.

    You can go back to the Lotus Notes client and open your application. It should look like the window shown in figure 15. You might need to restart Lotus Notes for the tab icon to update.

    Figure 15. Lotus Notes: Updated application in the Lotus Notes client
    Lotus Notes: Updated application in the Lotus Notes client

Set the reference for the page icon

You need to set the reference for this page icon, so that you can move this application to another computer (and have the page icon reference resolved properly) and so that you can create new applications based on this template.

Follow these steps in Lotus Domino Designer:

  1. Open Applications - Notes Journal Application, which you created previously.
  2. Select the Notes Journal Application.xml file that you created previously and right-click Open.
  3. Click Source.
  4. Do a Find for <preference name=”com.ibm.portal.PageIcon”> in the text.
  5. Set the base:value value to your PNG file for your page icon. Make sure to specify the PNG file here as shown:
    <preference name=”com.ibm.portal.PageIcon”>
    <base:value value=”Notebook_view16.png” xsi:type=”base:String”/>
    </preference>
  6. Save the file and Exit.

Create split-action buttons for the action bars

Lotus Notes 8 introduced split-action buttons in the view action bars. Split-action buttons allow users to click once and get a default action or click a drop-down list to get a list of choices.

An example of a split-action button displays in the mail application inbox. When a New button is clicked, it opens a a new mail document. If you click the drop-down arrow in the New button instead, you see a list of choices as shown in figure 16.

Figure 16. New split-action button
New split-action button

To make a split-action button, you need to go into Lotus Domino Designer. Follow these steps:

  1. Open the Shared Action property window.
  2. Select the Display as Split Action property within the action or shared actions property window. See figure 17.

    Figure 17. Creating a split-action button
    Creating a split-action button

Set the bookmark type

By default, the composite application XML settings cause Lotus Notes to create Notes Remote Procedure Call (NRPC) URLs when bookmarking applications from the application tab. These URLs are slow and can produce errors when the application no longer exists. Therefore, it is prudent to switch to using Notes URLs for bookmarks. This step also also ensures that the database icon is used as the bookmark icon.

To switch to Notes URLs, you need to add a preference to the composite application XML. You can add this preference by opening the composite application editor (by selecting Actions - Edit Application) and selecting Edit Page Properties from your page element. See figure 18.

Figure 18. Edit Page Properties in the composite application editor
Edit Page Properties in the composite application editor

Then switch to Advanced in the Edit Page Properties window and click Add to add the preference com.ibm.rcp.bookmark_level with the value selection. See figure 19.

Figure 19. Add Bookmark_level preference
Add Bookmark_level preference

Disable the navigator switcher

By default, the title bar of the navigator has the Switch to Calendar switcher shown. You can disable this switcher with another composite application XML preference.

Figure 20. Calendar/To Do switcher
Calendar/To Do switcher

Follow these steps:

  1. Launch the composite application editor (select Actions - Edit Application), and edit the component properties for your navigator using the right-click actions.
  2. When the component properties window displays, click the Advanced tab. Click Add, and add the preference com.ibm.rcp.showSwitch with the value false. Save and close. See figure 21.

    Figure 21. Add show switcher preference
    Add show switcher preference

Conclusion

This article outlined individual steps that allow you to customize and modernize your applications. You should now have many of the tools available to make your custom applications look like the Lotus Notes 8 native PIM applications (Mail, Calendar, Contacts, To Dos, and Notebook). For more information, refer to the Lotus Notes composite application editor Help and the Domino Designer 8.5 Help.

Resources

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, Java technology
ArticleID=368744
ArticleTitle=Basics steps: Converting an IBM Lotus Notes application to use Lotus Notes 8 Java components
publish-date=06292009