ibm lotus symphony toolkit guide 801

Lotus® Symphony

Toolkit Guide

Version

8.0.1

SC23-8727-01

��

Note: Before using this information and the product it supports, read the information in "Notices " on page 90

2nd Edition (Dec 2007)

This edition applies to release 8.0.1 of IBM Lotus Symphony toolkit (product number L-GHUS-79BMKS) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corp. 2003, 2008. All Rights Reserved.US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

2 IBM Productivity Tools Development Guide

Contents1. Quick start ........................................................................................................... 5

1.1 Intended audience .......................................................................................................... 5 1.2 How to use this guide .................................................................................................... 5

2. Introduction ......................................................................................................... 7 2.1 Requirements ................................................................................................................. 7 2.2 Architecture introduction .............................................................................................. 7 2.3 Toolkit content ............................................................................................................... 9 2.3.1 Control API ................................................................................................................ 9 2.3.2 DOM API ................................................................................................................. 10 2.3.3 Samples .................................................................................................................... 11 2.3.4 Java document .......................................................................................................... 11 2.4 API applications and supporting ................................................................................. 11 2.4.1 Rich Client applications ........................................................................................... 11 2.4.2 Office automation applications ................................................................................ 12 2.4.3 ODF supporting ....................................................................................................... 12 2.4.4 UNO supporting ....................................................................................................... 13 2.5 Next steps .................................................................................................................... 14

3. Using IBM Lotus Productivity Tools toolkit samples ....................................... 15 3.1 Supplied samples ......................................................................................................... 15 3.2 Using samples ............................................................................................................. 16

4. Setting up development environment ................................................................ 18 5. Developing Rich Client applications ................................................................. 23

5.1 Using productivity tools as a SWT control ................................................................. 23 5.1.1 Reusing productivity tools control .......................................................................... 23 5.1.2 Reusing productivity tools RichDocument ............................................................. 23 5.1.3 Reusing productivity tools RichDocumentViewer .................................................. 24 5.1.4 Creating DOM document ........................................................................................ 25 5.1.5 Loading document to view ...................................................................................... 25 5.1.6 Adding menus in view ............................................................................................. 26 5.1.7 Adding status items to status bar ............................................................................. 26 5.2 Using productivity tools as an Eclipse ViewPart ........................................................ 27 5.2.1 Extending a new view .............................................................................................. 28 5.2.2 Executing operations on rich document view ......................................................... 28 5.2.3 Monitoring execution of operations ........................................................................ 29

6. Developing office automation applications ....................................................... 31 6.1 Traversing through the document ............................................................................... 31 6.2 Accessing and modifying contents ............................................................................. 31 6.3 Accessing and modifying attributes ............................................................................ 31 6.4 Inserting content into document ................................................................................. 32 6.5 Removing content from document ............................................................................. 32

7. Programming with UNO ................................................................................... 34 8. Sample applications ........................................................................................... 37


8.1 Rich Client applications .............................................................................................. 37 8.1.1 Creating a view plug-in ............................................................................................ 37 8.1.2 Creating a view ........................................................................................................ 40 8.1.3 Loading documents to the view ............................................................................... 43 8.1.4 Adding menus for the view and creating action class ............................................. 44 8.1.5 Add status bar for the view ...................................................................................... 52 8.1.6 Running the application ........................................................................................... 53 8.2 Office automation application ..................................................................................... 54 8.2.1 Creating a project ..................................................................................................... 54 8.2.2 Creating a view ........................................................................................................ 55 8.2.3 Creating an action class ........................................................................................... 58 8.2.4 Running the application ........................................................................................... 60 8.3 Composite application ................................................................................................. 60

9. Deploying applications ...................................................................................... 67 9.1 Packaging your code into an update site project ........................................................ 67 9.2 Deploying with an update site ..................................................................................... 71 9.3 Deploying with Lotus Notes 8 installer ...................................................................... 75 9.4 Deploying with composite application support .......................................................... 76

10 Programming with LotusScript ........................................................................ 76 10.1 Sample LotusScript code .......................................................................................... 77

11 Developing composite application ................................................................... 78 11.1 Composite Application programming model introduction ....................................... 78 11.2 Using out-of-box properties and actions ................................................................... 79

Appendix A: Supported DOM API ....................................................................... 82 Appendix B: References ........................................................................................ 89 Appendix C: Notices ............................................................................................. 90


1. Quick start

1.1 Intended audience

This guide is intended for Java developers who want to use IBM Lotus Productivity Tools and need a more in-depth understanding of the toolkit in order to create their own applications. The guide is written to provide some reference of the toolkit and related samples.

This guide does not include information about general Java programming. For more information on the Java language and Java programming, please go to website http://www.java.sun.com. This guide also does not cover the details of Lotus Productivity Tools API (Application Programming Interface) that are covered in the Java documents.

1.2 How to use this guide

This guide shows how to develop Rich Client and Office Automation applications for IBM Lotus Notes 8 using Lotus Productivity Tools API. The interfaces to manipulate productivity tools rich document are described with the help of some step-by-step examples.

This document is composed of several major sections: API introduction, setting up development environment, Rich Client application developing, office automation application developing, UNO programming and deploying applications.

Chapter 2 is the overview section, introducing general technical background of IBM Lotus Productivity Tools control, DOM, ODF, UNO, and the applications of the toolkit.

Chapter 3 introduces the samples in IBM Lotus Productivity Tools toolkit.

Chapter 4 introduces how to setup the development environment.

Chapter 5 describes the development of Rich Client applications. It includes the using for productivity tools control, rich document and view.

Chapter 6 demonstrates the development of office automation applications. It shows how to access and modify the document objects with DOM API.

Chapter 7 describes the programming with OpenOffice SDK UNO API.


http://www.java.sun.com/

Chapter 8 is the sample development guide section, which goes through the detailed steps to develop Rich Client applications, office automation and composite application examples. The Rich Client application shows the steps for creating a plug-in project and adding menu in view by two different ways. The office automation application introduces how to make a meeting notice with a DOM field template. The composite application instructs how to create a new composite application and edit it with the Notes CAE tool.

Chapter 9 shows how to deploy applications to Lotus Notes 8 product environment.

Two appendices cover additional subjects and issues: Appendix A: lists all supported DOM API Appendix B: lists more references and additional information.


2. Introduction

The following terms will be used throughout this document and are defined as follows:Term DefinitionUNO Universal Network Objects, the component technology applied in Lotus

Productivity Tools software development.DOM Document Object Model, W3C API standards for XML/HTMLODF Open Document Format, OASIS standards for office documentAPI Application Programming Interface

IBM Lotus Notes 8

IBM Lotus Notes 8 or Lotus Notes 8 refers to the Eclipse-based edition of Lotus Notes client being introduced in version 8.

Composite Application

Composite applications enable the integration of information from multiple applications, providing end users with the content they need based on their role and task.

IBM Lotus Expeditor

IBM Lotus Expeditor or Lotus Expeditor is an SOA-based server managed client platform that helps improve responsiveness and increase productivity by extending composite applications to laptops, desktops, kiosks, and mobile devices. It is the IBM open standards-based competitor to the .NET client. It is both used by and integrates with key IBM products, such as WebSphere Portal, Lotus Sametime, Workplace Forms, the next version of Lotus Domino, and also sold as a stand-alone offering.

RCP Eclipse Rich Client Platform. While the Eclipse platform is designed to serve as an open tools platform, it is architected so that its components could be used to build just about any client application. The minimal set of plug-ins needed to build a rich client application is collectively known as the Rich Client Platform.

2.1 Requirements

The IBM Lotus Productivity Tools toolkit is designed to be used with IBM Lotus Notes 8 or its later version. Be sure you have installed Lotus Notes 8 with the following components: Lotus Notes 8 (Standard Configuration) IBM Lotus Productivity Tools IBM Lotus Productivity Tools toolkit

2.2 Architecture introduction

Lotus Productivity Tools wraps productivity tools application as Eclipse components to provide rich document editor service to Lotus Notes 8. IBM Lotus Productivity Tools is a standalone office productivity suite composed of IBM Lotus Documents, IBM Lotus Spreadsheets, IBM Lotus Presentations and many other document editors.

The toolkit provides two sets of Java APIs for developer use: control API and DOM API. With these Java API interfaces, users can build business component that includes rich functionalities of


Lotus Productivity Tools. Fig.1. describes the overall architecture for Lotus Productivity Tools, it is based on IBM Lotus Expeditor, and it is also applicable for Lotus Notes 8 platform.

Fig.1. Overall architecture of Lotus Productivity Tools

The Lotus Productivity Tools control API defines a set of objects and interfaces, encapsulates Lotus Productivity Tools editor components as an Eclipse SWT control. With this API set, you can integrate the Lotus Productivity Tools within Lotus Notes 8 platform.

The Lotus Productivity Tools DOM API provides a W3C DOM based implementation to access or manipulate the rich document content and styles in a logical DOM tree, which is defined with a sub-set of ODF specification. In this release, currently it only supports parts of word processing document object types. Lotus Productivity Tools now supports the Oasis ODF specification. The ODF specification is a XML based open document format which defines a standard set of objects for representing office documents, but in this specification there is no definition of standard interface for accessing and manipulating them. While the W3C DOM specifications define a standard way for accessing and manipulating document objects, which is also a platform- and language- neutral interface that allows programs or scripts to dynamically access and update the content of a document. So it is more attractive to provide a DOM API to manipulate rich document contents.

Just as shown in Fig.1, in fact, all of these two set of APIs are fundamentally based on the native back-end Lotus Productivity Tools service which is derived from OpenOffice. The front APIs


manage to start backend Lotus Productivity Tools service process internally when it is the first time trying to access it. Then it will open a named pipe UNO connection to this backend service. All subsequent front Java API call will then get to underlying UNO API call, go through the UNO connection, and finally take actions at backend Lotus Productivity Tools service process. To get notified of events and synchronize the status between the two sides of UNO connection, the Lotus Productivity Tools front also registers many listeners to the backend service. Since Lotus Productivity Tools usually works on Lotus Expeditor platforms at the front end, the API is also responsible for Lotus Productivity Tools UI integration with Eclipse environment. All these operations are well encapsulated in these set of APIs.

Lotus Productivity Tools originally provide a set of UNO API, which can still work along with these set of APIs, although there are some limitations. You can refer to reference materials in Appendix for UNO API information. When Lotus Productivity Tools backend service is startup by calling control API, and you have got the rich document UNO component objects, you can then begin to call the original UNO API to manipulate document content objects directly. Comparing to DOM API in this API set, UNO API is a more comprehensive and complete API set to work on document content, although it may take much more time to get familiar with. Because Lotus Productivity Tools encapsulates the backend service in the specific Lotus Expeditor platform environment, some kinds of UNO API call may break its integrity, such as framework management related API and document loading APIs, it is not suggested to use them except you know what you are doing and the API call does not break the integration.

2.3 Toolkit content

Besides this guide, the toolkit also includes several other parts, such as control API, DOM API samples and Java documents.

2.3.1 Control API

The control API lets users integrate the rich functionalities of Lotus Productivity Tools into Lotus Expeditor platform as an Eclipse SWT control. For example, you can build a Rich Client application to open, view, edit and save Microsoft office documents, SmartSuite documents, OASIS ODF documents.

Lotus Productivity Tools control API defines a set of objects and interfaces: RichDocumentControl: provides the SWT wrapper for productivity tools applications RichDocument: defines I/O operations of rich documents, such as load/save/export/print RichDocumentViewer: provides a simplified way to use the control and document objects

with UI interactions


Lotus Productivity Tools control API supports the following UI items: Menu actions: developing action methods/classes from Lotus Productivity Tools action

interface Status bar items: instantiating Lotus Productivity Tools status items Main editing area: re-parenting Lotus Productivity Tools native editing window

2.3.2 DOM API

You can use the DOM API to access and manipulate the content and styles of rich documents. This API set is based on W3C standards. The structure of the document is a sub-set of ODF specification. The details of ODF support will be covered in the next chapter.

Document Object Model (DOM) is a W3C specification which defines an application programming interface for valid HTML and well-formed XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated.

As a W3C specification, one important objective for the Document Object Model is to provide a standard programming interface that can be used in a wide variety of environments and applications.

In the DOM, documents have a logical structure which is very much like a tree; to be more precise, like a "forest" or "grove", which can contain more than one tree. DOM specification describes the document as a tree-like representation, the information items in the document are arranged as a "tree", and they are reached by using "tree-walking" methods.

As an object model, the DOM identifies: The interfaces and objects used to represent and manipulate a document The semantics of these interfaces and objects - including both behaviors and attributes The relationships and collaborations among these interfaces and objects

The API toolkit provides a W3C DOM based implementation for rich documents. The referenced specification is DOM level 3 Core Specification version 1.0 (In fact, it is the content of DOM Level 1 that covers core specification). Currently the API toolkit does not implement all DOM APIs. It just provides the ability to access and manipulate document content with DOM like document structures and methods.

For more information about how many W3C DOM APIs had been supported, please refer to Appendix A.


http://www.w3.org/

http://www.w3.org/DOM/

2.3.3 Samples

Some step-by-step example fragments are mentioned in this guide. Each example can be run in proper environment. More details and samples can be found from the toolkit sample code plug-ins. For instructions for the samples, refer to Chapter 3.

2.3.4 Java document

The Java document provides API navigation and description. It lists all detail of packages, classes and interfaces. Package: Each package has a page that contains a list of its classes and interfaces, with a

summary for each. Class/Interface: Each class, interface, nested class and nested interface has its own separate

page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions

2.4 API applications and supporting

The API toolkit is designed to reuse Lotus Productivity Tools application as an Eclipse SWT control. The Lotus Productivity Tools control API provides a control, document, viewer framework for developers, which is very familiar with Eclipse developers.

The API toolkit also provides API to access and modify the document content and styles. The frequently used elements and styles are supported to be accessed and modified with DOM style methods. The programming model is friendly for most of developers. However, since the functionalities provided by current implementation are limited, the rich functionalities of UNO API are still suggested for advanced customers.

2.4.1 Rich Client applications

The toolkit provides APIs for reusing a Lotus Productivity Tools control as a customized SWT control, so it can be shared by any other components and ISV applications on Lotus Notes 8 platform. The following key features are enabled in this toolkit: Implements Eclipse viewer framework for Lotus Productivity Tools control, so

programmers can easily integrate the productivity tools control into other applications in Eclipse platform


Provides a Rich Document object as a root for document content and operation Provides functionalities to customize UI for Lotus Productivity Tools controls, such as

menu and status bar Operates rich documents silently in background

2.4.2 Office automation applications

The API toolkit provides a set of Java DOM API to operate on rich document content, so it can be easily integrated into other applications and services seamlessly. The key features for the document content model API are: DOM tree-like structure model, and tree-walking-through like accessing and

modification Represents the document with ODF information items Supports a sub-set of most frequently used ODF elements and attributes Provides specializing and adding functionalities that relate specifically to ODF elements Provides a convenient mechanism, where appropriate, for common and frequent

operations on ODF elements

2.4.3 ODF supporting

Open Document Format (ODF) is an OASIS open standard. It defines an XML schema for office applications and their semantics. The schema is suitable for office documents, including text documents, spreadsheets, charts and graphical documents like drawings or presentations, but is not restricted to these kinds of documents. The schema provides high-level information suitable for editing documents. It defines suitable XML structures for office documents.

The API toolkit provides tree-like representation for rich documents. All information items in the toolkit are referenced from ODF schema. The tree structure is very similar to ODF schema, but not exactly same. The API toolkit does not support all elements and attributes defined by ODF. Only part of most frequently used elements and attributes are supported currently. The following picture describes the overall structure for the text document. For more information, please refer to the JavaDoc.


http://www.oasis-open.org/home/index.php

Fig.2. Core structure of supported ODF elements

2.4.4 UNO supporting

UNO stands for Universal Network Objects and is the base component technology for OpenOffice.org. Users can utilize and write components that interact across languages, component technologies, computer platforms, and networks. Currently, UNO is available on Linux, Solaris, and Windows for Java, C++ and OpenOffice.org Basic. As well, UNO is available through the component technology Microsoft COM for many other languages.

UNO is used to access OpenOffice.org using its Application Programming Interface (API). The OpenOffice.org API is the comprehensive specification that describes the programmable features.

Since the Lotus Productivity Tools is derived from OpenOffice.org, the UNO APIs are still accessible. This toolkit will also provide guide about how to get access to UNO APIs.


For more information, please refer to Chapter 7.

2.5 Next steps

Users need to build, debug, run and deploy the application which they create. Depending upon the style of application, and the components that are required, the tools, components and steps used to construct the applications will differ. Please consider the following scenarios:

Read and follow the instructions in "Setting up development environment" on chapter 4.

Read and follow the instructions in "Developing Rich Client applications" on chapter 5.

Read and follow the instructions in "Developing office automation applications" on chapter 6.

Read and follow the instructions in "Programming with UNO" on chapter 7.

Read and follow the instructions in "Rich Client application" sample on section 8.1.

Read and follow the instructions in "Office automation applications" sample on section 8.2.

Read and follow the instructions in "Composite application" sample on section 8.3.

Read and follow the instructions in "Deploying applications" on chapter 9.


3. Using IBM Lotus Productivity Tools toolkit samples

This chapter first describes the toolkit samples' uses and scenarios, and then introduces the steps about how to run these samples on Lotus Notes 8 platform.

3.1 Supplied samples

Several samples for Lotus Productivity Tools are supplied in the toolkit. The given samples are designed to show the use of the Lotus Productivity Tools in Notes 8. Once you have installed or deployed the samples, they are visible in the target platform. Simple EditorThis sample demonstrates how to create a simple editor. It has two kinds of menus: "MyEditor" menu includes some simple editor functions, such as "Copy", "Paste", "Undo" and "Redo"; "MyFile" menu has "Open", "Save", and "Print" items. These menus are added in two ways. The first way adds "MyEditor1" and "MyFile1" by "actionSet" with extension points; the second way adds "MyEditor2" and "MyFile2" by "MenuSet" with control API. DOM Tree ViewerThis sample demonstrates the DOM tree view. The view shows the whole document as a tree. Each element in the text is a tree node, with its parent node, sibling nodes and descendant nodes. The detailed information of the node, such as name, type, value and attributes are displayed on the right of the view. DOM FieldThis sample demonstrates how to operate user field elements in a document. It loads a notice template which has some user fields in it, such as title, date, text, attachment, key words, collation, etc. The view uses APIs to access each user field with its name, sets the proper content in it, and a new notice is completed. There are five buttons with labels and icons on the view which perform the actions as bellow:

Insert a new date field element. Edit the user fields in the document. Remove the newly created date fields. Print the current view with printer after content setting. Save the view as another file.

DOM TableThis sample demonstrates how to operate table elements in a document. It loads a cargo transporting sheet template which has three tables. One is a cargo arrangement table; the other two are header and footer with some relational information in them. The view uses API to access each item in tables with the name of table cell, sets the proper content in the cell, and then a new cargo transporting sheet is completed. There are four buttons with label and icon on the view which perform these actions as bellow:


Edit the already existing table. Create and insert a newly created footer table. Remove the newly created footer table. Print the current view with printer after content setting.

UNO APIThis sample demonstrates how to manipulate text fields in rich documents with UNO API. The view opens an empty word processing document with three buttons in the upper-left toolbar area. "Datetime" and "User" fields will be created and inserted into this document by clicking these buttons in sequence. Auto RecognizerThis sample demonstrates how to develop C2A applications based on Lotus Productivity Tools. Two keywords are predefined in the sample recognizer: PropertyBroker and AutoRecognizer. AutoRecognizer engine will call the detector to check if there are such keywords found. When users click the context menu for recognized tags, a message box will be opened. Composite ApplicationThis sample instructs user to create a new Composite Application and edit this Composite Application with the Notes CAE tool. One feature and two plug-ins are provided by this sample and you can follow section 8.3 to use this sample step by step.

3.2 Using samples

You can get the sample plug-ins from Lotus Productivity Tools toolkit. There are two ways to use these samples. One is deploying them to Notes 8 directly, as the steps in Chapter 9. Another is for development purpose, you can import the samples into Eclipse, running in the development environment and attaching the samples to Notes 8. The steps of the second method are described as below:1. Get the Lotus Productivity Tools toolkit, and put it in some location on your disk.2. Set up the development environment as described in Chapter 4.3. Start Eclipse. In Eclipse, select menu File > Import… to import the specific samples.4. In Import dialog, select Existing Projects into Workspace in General section, and then

click Next button.5. Select root directory, click Browse… button, and browse to and select the directory where

you put the toolkit sample plug-ins in step 1.6. Select the projects you want to import into Eclipse workspace, then click Finish button.


Fig.3. Import samples in Eclipse

7. From the left panel navigator in Eclipse workspace, right click the imported sample project and click PDE TOOLS > Update Classpath.

8. On the Update Java classpath panel, check the sample project option and click Finish. Then it will begin to compile sample plug-ins automatically.

9. After building sample code successfully, you can select Run... > Run or Debug... > Debug to run the sample in Eclipse, and then attach it to Notes 8 application.


4. Setting up development environment

The development environment is based on Eclipse 3.2 and Lotus Notes 8. Users should get the relevant development resources at first. All the steps quoted below are in Windows system, and the setting processes in Linux are quite similar.1. Install Lotus Notes 8 and Eclipse 3.2

Download Eclipse 3.2 and Lotus Notes 8; Unpack eclipse 3.2 to local disk. (e.g. C:\eclipse) Install Lotus Notes 8 to local disk. (e.g. D:\Lotus\Notes);

2. Start Eclipse IDE Make sure that it is starting up in a new or freshly cleaned workspace. Work-space remnants from prior installations may cause problems, so users should create a new workspace for each installation.

3. Set target platform. Select Window > Preferences menu item; In the left tree panel select Plug-in Development > Target Platform tree item; In location field, click Browse... and select the eclipse under the Lotus Notes 8 install

root directory, such as: D:\Lotus\Notes\framework\eclipse. Click Reload button

Fig.4. Target platform


4. Create an additional Installed JRE Select Window > Preferences menu item, Select Java > Installed JREs tree item in the left tree panel and Click Add... button; For JRE name, enter a name of your choice: something like "Lotus JRE" Select the current JRE home directory. Note: the suffix of the directory name may be not

unique, so you should use the current one in local Lotus Notes 8. This guide uses "D:\Lotus\Notes\framework\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.x86_1.5.0.SR2-200701121347" for the JRE Home Directory.

Click OK

Fig.5. Installed JRE

5. Create your own project code in this Eclipse workspace. There is a sample in below chapters later.

6. Create a new runtime configuration in Eclipse IDE: Select Run >Run... Select Eclipse Application from configuration list in left panel Right click and select New from popup menu Enter a name: (i.e. Notes8) Select Clear workspace data before launching Under Program to Run, select Run a product For Run a product, select com.ibm.notes.branding.notes from the product list In the Runtime JRE, select Lotus JRE which is created in step 4.


Fig.6. Set runtime configurations

Select the Arguments tab, and setting arguments as below,Note: All path separator '/' in directory in following arguments can also be '\' on Windows, but it must be '/' on Linux platform.There is also several variables in the argument strings, which will be resolved in next step.

Setting Program arguments:-personality com.ibm.rcp.platform.personality-product com.ibm.notes.branding.notes-debug-console

Setting VM arguments:-Xshareclasses-Drcp_home=${rcp_home}-Dcom.ibm.rcp.install.id=${install_id}-Drcp.install.config=user-Dosgi.install.area=${rcp_home}/eclipse-Dcom.ibm.pvc.osgiagent.core.logfileloc=${rcp_home}/rcp-Dcom.ibm.pvc.webcontainer.port=0-Declipse.pluginCustomization=${rcp_home}/rcp/plugin_customization.ini-Declipse.registry.nulltoken=true-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www.protocol


-Dosgi.hook.configurators.exclude=org.eclipse.core.runtime.internal.adaptor.EclipseLogHook

-Dosgi.framework.extensions=com.ibm.rcp.core.logger.frameworkhook-Xbootclasspath

/a:${rcp_home}/rcp/eclipse/plugins/com.ibm.rcp.base_${rcp_version}/rcpbootcp.jar;

Fig.7. Set arguments

Setting variables for arguments: Click Variables... (Note: There are two Variables… buttons on Arguments

tab page, both are OK for this step) On the Select Variable dialog, click Edit Variables... On the Preferences dialog, click New... Enter "rcp_home" for name: Enter the path where you installed Lotus Notes 8 for the value: (i.e

D:\Lotus\Notes\framework) Click OK to finish adding this variable. Click New... again Enter "install_id" for another variable Enter the random number for the value which you can get from file

rcplauncher.properties located under $rcp_home/rcp/ directory, and find the value for key rcp.install.id. This random number is generated automatically after you install Lotus Notes 8. For example, if your Lotus Notes 8 is installed to directory D:\Lotus\Notes, you can find file


D:\Lotus\Notes\framework\rcp\rcplauncher.properties, open it in a text editor, you can find a line looks like rcp.install.id=1174538145756, then the number string 1174538145756 is the value of install_id variable.

Click OK to finish adding this variable. Click New... again. Enter "rcp_version" for another variable. Enter the current version number of com.ibm.rcp.base plugin. You can find

its exact version number from your installed Notes 8 directory. For example, if the installed plugin is located at directory "D:\Lotus\Notes\framework\rcp\eclipse\plugins\com.ibm.rcp.base_6.1.0.0-200701121347", then its version number is "6.1.0.0-200701121347".

Click OK to finish adding this variable.

Fig.8. Set variables for arguments

On Preferences dialog, click OK to finish adding variables. Click Cancel on Select Variable dialog.

Note: If you select OK on Select Variable dialog, the first variable "${build_project}" in list will be added automatically to Program arguments field, and it will cause a launching error when runs. In this case, please simply delete it from this field, and continue again.

Finally select Close button to finish creating new configuration.7. To run/debug

Select Run... > Run or Debug... > Debug.


5. Developing Rich Client applications

You can use Lotus Productivity Tools API to develop your own applications. For detailed information on this set of Java API, please see API's Java document which can also be found from this toolkit, located in file javadoc.zip under "doc" directory.

5.1 Using productivity tools as a SWT control

5.1.1 Reusing productivity tools control

Rich document control is one of the major widget class published in this set of control API. It's an Eclipse SWT composite control extended to be a rich document editor control. Generally a user can instantiate a RichDocumentControl object, and get a powerful rich document editor.

RichDocumentControl is an Eclipse SWT composite which embeds the basic native productivity tools control. It manages the communication between SWT Control and Lotus Productivity Tools UI environment; it simulates standard SWT edit control behavior, such as a focus listener; it also monitors the events and status at native productivity tools side, such as hot keys or opening productivity tools model dialogs. The below sample code reuses productivity tools control as an edit control:RichDocumentControl control = new RichDocumentControl( parent, SWT.NONE );

5.1.2 Reusing productivity tools RichDocument

RichDocument defines the basic rich document interface. It stands for the handle for a given document file or stream in memory. And it is the entry point to operate on the document object or manipulate document content. By hiding the detail difference, RichDocument can process three types of IBM Productivity Tools document types (word processing documents, spreadsheets, and presentations) in a universal way.

In fact, the RichDocument implementation class is proxy for two internal classes. They will be used in different situations and their differences are transparent to users. Explicit document displays the document content in a native control explicitly, so the productivity tools control UI is visible, users can directly operate on the document from UI. The implicit document is designed for


operating on document silently without any visual UI. Besides, RichDocument also supports synchronously and asynchronously loading documents, and keeps compatibility with original productivity tools UNO API.

However, RichDocument also has some limitations. First, the document can be loaded only once at a time; second, it can be applied to only one control one time; and it doesn't support multiple files in its object lifetime.

The below sample code reuses productivity tools rich document object:RichDocument doc = new RichDocumentProvider().createRichDocument( "c:\\test.sxw" );doc.enableAsyncLoadingMode (false,null);doc.load();...doc.dispose();

RichDocument object also supports another loading method: Loading document from input stream of an existing document file. In this way, you should call another factory method of RichDocumentProvider class. Sample code is like below:

try { FileInputStream iStream = new FileInputStream("c:/temp/tmp.sxw"); RichDocument visibleDocument = new RichDocumentProvider(). createRichDocument(iStream); viewer.setDocument(visibleDocument); iStream.close(); } catch (IOException e) { e.printStackTrace(); } catch (EmptyFileObjectException e) {

e.printStackTrace();} catch (DocumentAlreadyInitializedException e) {

e.printStackTrace();}

5.1.3 Reusing productivity tools RichDocumentViewer

A rich document viewer connects a RichDocumentControl with a RichDocument, simplifies the way to use Control and RichDocument objects, and it also provides some more advanced functions. The viewer also encapsulates the menu set and status line controlling functions. By reusing the viewer, users can easily get the plentiful menu operation functions.

In an application, RichDocumentViewer can directly load a document from an input stream of a file without associating with a RichDocument object.


The below sample code reuses productivity tools document viewer:RichDocumentViewer viewer = new RichDocumentViewer( parent, this, null );RichDocument doc = new RichDocumentProvider().createRichDocument(iStream );viewer.setDocument( doc );...viewer.dispose();

5.1.4 Creating DOM document

The sample demonstrates how to create a DOM document object with a RichDocument object loaded in a RichDocumentViewer: ......RichDocumentViewer viewer;DocumentBuilder builder = new DocumentBuilder();ODFTextDocument document = (ODFTextDocument)builder.createDocumentModel(

viewer.getDocument() );......

5.1.5 Loading document to view

Below code creates a new blank document, it will be loaded by the view:public class WriterView extends ViewPart {

private RichDocumentViewer viewer;......public void createPartControl(Composite parent) { viewer = new RichDocumentViewer(parent,true);

try { RichDocument visibleDocument = new RichDocumentProvider(). createRichDocument(RichDocument.WRITER); viewer.setDocument(visibleDocument); } catch (IOException e) { e.printStackTrace(); } catch (EmptyFileObjectException e) {

e.printStackTrace(); } catch (DocumentAlreadyInitializedException e) { e.printStackTrace();}......

}......


}

5.1.6 Adding menus in view

There are two ways to add menus in view. The first is predefining "actionSet" in the plug-in's manifest (plugin.xml) file. In this way, users can define extensions of "org.eclipse.ui.actionSets" and create new actions for adding behaviors to the Eclipse platform.

Another way to add view menu is using productivity tools control API. The control API provides a class "RichDocumentMenuSet". Users can inherit this super class and rewrite it, and then use the new class with the menu set, as well as the menu manager in the view. In this way, the menu can be added programmatically without setting in the configuration file.

Please refer to section 8.1.4 for more detailed information, and a step-by-step instruction for adding menu sample with these two methods above.

5.1.7 Adding status items to status bar

The API now supports four types of status items:l Zoom item.l Ismodify item.l Page status item.l Style item.

Users could add the listed items as they want. They could create these items with class "WriterStatusLineContributionItemFactory". Below code inserts all of these items to status bar. Insert page style and status to the beginning of the bar, other items to the end.

IStatusLineManager slm = this.getViewSite().getActionBars() .getStatusLineManager();

IContributionItem pageStyleItem = WriterStatusLineContributionItemFactory.PAGE_STYLE

.createContributionItem(viewer);slm.add(pageStyleItem);IContributionItem pageStatusItem =

WriterStatusLineContributionItemFactory.PAGE_STATUS .createContributionItem(viewer);slm.add(pageStatusItem);IContributionItem insertItem = WriterStatusLineContributionItemFactory.INSERT .createContributionItem(viewer);slm.add(insertItem);IContributionItem zoomItem = WriterStatusLineContributionItemFactory.ZOOM


.createContributionItem(viewer);slm.add(zoomItem);IContributionItem selectModeItem =

WriterStatusLineContributionItemFactory.SELECT_MODE .createContributionItem(viewer);slm.add(selectModeItem);IContributionItem hyperlinkModeItem =

WriterStatusLineContributionItemFactory.HYPERLINKS_MODE .createContributionItem(viewer);slm.add(hyperlinkModeItem);IContributionItem isModifyItem =

WriterStatusLineContributionItemFactory.IS_MODIFY .createContributionItem(viewer);slm.add(isModifyItem);IContributionItem sizeItem = WriterStatusLineContributionItemFactory.SIZE .createContributionItem(viewer);slm.add(sizeItem);

5.2 Using productivity tools as an Eclipse ViewPart

In Notes 8.0, we only support to customize Productivity Tools as a SWT control. We can not provide a full functional component, just like the views we provided for common users.( e.g. click File->New->Document from menu ).

In Notes 8.0.1, we provide the ViewPart we used for common users to API users. Customers can construct a full functional component the API set. The ViewPart have all the functions we provided for common users, such as menu, toolbar and statusbar.

The ViewPart could be reused in two key application models: Rich Client Application Model, and Composite Application Model.

In Rich Client Application Model, developers can inherit the ViewPart directly, and provide enhanced functions based on provided ViewPart.

In Composite Application Model, developers can reuse it directly with Composite Application Editor. It enables users to integrate Productivity Tools with other application into one single UI in screen. Developers could also provide a customized component based on Rich Client Application Model.


5.2.1 Extending a new view

The following code snippet demonstrates how to reuse the DefaultRichDocumentView in Eclipse/Java programming. The sample code implements a WriterView which will create a writer document in the ViewPart. The ViewPart can be integrated into an Eclipse perspective therefore, or shown by a IWorkbenchPage. Please reference Eclipse/Expeditor programming about how to use it. Or the complete sample code will also be provided in the Productivity Tools toolkit.

public class WriterView extends DefaultRichDocumentView {

/** * The constructor. */public WriterView() {

super(); }

public void createPartControl(Composite parent) {super.createPartControl(parent);createWriter();

}

private void createWriter(){

NewOperation operation = OperationFactory.createNewOperation(RichDocumentType.DOCUMENT_TYPE );

operation.execute(this);}

}

5.2.2 Executing operations on rich document view

The following code snippet demonstrates how to load a rich document with the rich document view. We assume the WriterView is created in chapter 3.1.1. There are also SaveOperation, SaveAsOperation, CloseOperation provided in the API JavaDoc. The usage is similar to LoadOperation, please reference the API JavaDoc for more details.

private void loadDocument(){


LoadOperation operation = OperationFactory.createLoadOperation("c:\\text.odt", false);

this.executeOperation(operation);}

5.2.3 Monitoring execution of operations

The following code snippet demonstrates how to detect a document is loaded into the rich document view. We assume the WriterView is created. The sample code demonstrates how to add a operation listener into the ViewPart when the viewpart is created. When a load operation is executed, the monitor will be called. The OperationListener is applicable to all default operations provided in the JavaDoc. Please reference the API JavaDoc for more details.

public class WriterView extends DefaultRichDocumentView {

/** * The constructor. */public WriterView() {

super();}

public void createPartControl(Composite parent) {super.createPartControl(parent);monitorLoading();

}

private void monitorLoading(){

OperationListener listener = new OperationListener(){

public void afterExecute(Operation operation, RichDocumentView view) {

if( operation instanceof LoadOperation ){

System.out.println( "document is loaded:"+ ( (LoadOperation)operation ).getFileName());

Object document = (( LoadOperation )operation).getUNOModel();


afterLoading( document);}

}

public void beforeExecute(Operation operation, RichDocumentView view){

if( operation instanceof LoadOperation )System.out.println( "document is about to be loaded:"

+ ( (LoadOperation)operation ).getFileName());

}

};this.addOperationListener( listener );

}}


6. Developing office automation applications

6.1 Traversing through the document

The sample demonstrates how to print out the node and all of its descendants. The method "printSingleNode" is used to print the detailed information of the current node.

void printNode( Node node , int layer){ //print out the current node printSingleNode( node ,layer ); Node iter = node.getFirstChild() ; while( iter != null ) { printNode( iter, layer + 1 ); iter = iter.getNextSibling() ; }}

6.2 Accessing and modifying contents

The sample demonstrates how to access and modify the content of a target element. Retrieve the Text node from the forth text span of the first paragraph and set the new value by the "getNodeValue" and "setNodeValue" methods.

......Document doc = loadDoc("sample.sxw");NodeList textspanList =

doc.getElementsByTagName(ODFElementTags.ATTRIBUTED_TEXT);Node spanNode = (Node)textspanList.item(4);Text textNode = (Text)spanNode.getFirstChild();String textValue = textNode.getNodeValue();textNode.setNodeValue(" This is a test.");......

6.3 Accessing and modifying attributes

The sample demonstrates how to access and modify the attributes of a paragraph element. Retrieve the first paragraph, and then fetch its AutomaticStyle element by invoking the "getAutomaticStyle" method. After that you can use the 'get' and 'set' methods of the


ParagraphProperties element, a child of the AutomaticStyle element, to retrieve and change the attribute value of this paragraph as bellow code:

......Document doc = loadDoc("/sample.odt");NodeList elementList = doc.getElementsByTagName(ODFElementTags.TEXT_P);ParagraphElement testParagraph = (ParagraphElement) elementList.item(0);// getting attributesStyleElement style= node.getAutomaticStyle();ParagraphPropertiesElement p_element= style.getParagraphProperties();String value = p_element.getBackgroundColor();System.out.println(value);// seting attribuatesp_element.setBackgroundColor("#FF00FF");......

6.4 Inserting content into document

The sample demonstrates how to insert a newly created attributed text node before the first child of the second paragraph.

......Document doc = loadDoc("resource/news.odt");NodeList paragraphList = doc.getElementsByTagName(ODFElementTags.TEXT_P);Element paragraphNode = (Element)paragraphList.item(1);int count = paragraphNode.getChildNodes().getLength();Text text = doc.createTextNode( "new span");AttributedTextElement attrText = (AttributedTextElement) doc.createElement(

ODFElementTags.ATTRIBUTED_TEXT ); attrText.insertBefore( text, null ); AttributedTextElement insertedNode = (AttributedTextElement)

paragraphNode.insertBefore(attrText,paragraphNode.getFirstChild());insertedNode.getAutomaticStyle().getTextProperties().setBackgroundColor("#12345

6");......

6.5 Removing content from document

The sample demonstrates how to remove a paragraph element.//get the list of office:text elementNodeList list = target.getElementsByTagName( "office:text" );if( list.getLength() > 0 ){


//get the first office:text elementElement officeText = ( Element )list.item( 0 );officeText.removeChild( officeText.getLastChild() );

}


7. Programming with UNO

Besides the functions provided in the control API, it also provides OpenOffice.org 1.1 SDK Java UNO API compatibility. It means that based on the control API, developers can also begin to call the OpenOffice.org 1.1 Java UNO API to access other functions that are not available in control API. In control API, there are two methods, by which users can start to invoke Java UNO API.1. class com.ibm.productivity.tools.ui.ProductivityToolsUtil

public static XConnection getUNOConnection();Method getUNOConnection() in fact does two things: it first checks if the Lotus Productivity Tools backend service is started, if not, start it. After that it will expose the bidirectional byte stream.

The most frequently used UNO FMC services are originated from XMultiServiceFactory, which can be generated by below sample code,

public static XMultiServiceFactory connect( XConnection conn ) { XBridge mBridge; try { XComponentContext _ctx = com.sun.star.comp.helper.Bootstrap .createInitialComponentContext(null); Object x = _ctx.getServiceManager() .createInstanceWithContext("com.sun.star.bridge.BridgeFactory",_ctx)

; XBridgeFactory xBridgeFactory = (XBridgeFactory) UnoRuntime .queryInterface(XBridgeFactory.class, x); // // create a nameless bridge with no instance provider // try { mBridge = xBridgeFactory

.createBridge("SODC_Bridge", "urp", conn, null); } catch(BridgeExistsException beexp) {

mBridge = xBridgeFactory.getBridge("SODC_Bridge"); }

// get the remote instance x = mBridge.getInstance("StarOffice.ServiceManager"); // // Did the remote server export this object? // if (null == x)


return null; // // Query the initial object for its main factory interface // XMultiComponentFactory xOfficeMultiComponentFactory =

(XMultiComponentFactory) UnoRuntime .queryInterface(XMultiComponentFactory.class, x); // // Retrieve the component context // Query on the XPropertySet interface. // XPropertySet xProperySet = (XPropertySet) UnoRuntime .queryInterface(XPropertySet.class, xOfficeMultiComponentFactory); // // Get the default context from the editor service. // Object oDefaultContext = null; try { oDefaultContext = xProperySet.getPropertyValue("DefaultContext"); } catch (UnknownPropertyException e) { e.printStackTrace(); } catch (WrappedTargetException e) { e.printStackTrace(); } if (oDefaultContext == null) return null; XComponentContext context = (XComponentContext) UnoRuntime

.queryInterface(XComponentContext.class, oDefaultContext); return (XMultiServiceFactory) UnoRuntime .queryInterface(XMultiServiceFactory.class,

context.getServiceManager()); } catch (Exception e) { e.printStackTrace(); }

return null;}

2. class com.ibm.productivity.tools.ui.model.RichDocument public XComponent getUNOModel() throws UnInitializedDocumentException


This method is exposed to quickly get the UNO document model object for a rich document. By this method, developers then can start to call UNO API model interfaces to access, navigate and manipulate all document objects.

Though Lotus Productivity Tools API is based on UNO API, and fulfilled by a subset of UNO API, it is tightly integrated with the outer RCP environment. While some original OpenOffice.org 1.1 UNO API may work in a different way not expected in the RCP environment, nearly all of them are Frame/Controller UNO APIs, so it is strongly suggested to avoid using UNO API directly if their corresponding functions are provided in Lotus Productivity Tools control API set.

For OpenOffice.org 1.1 SDK UNO APIs, users can refer to the online documents which are available on web site http://api.openoffice.org/SDK/index.html.


http://api.openoffice.org/SDK/index.html.

8. Sample applications

This chapter provides three step-by-step samples to demonstrate conceptual functions. The first sample demonstrates how to create a simple editor with control API, which includes menu added, document loading, .etc... The second one shows how to edit user field element in a document, and then make a notice in template with DOM API. The third sample instructs users to create a new Composite Application and edit it with the Notes CAE tool.

The development environment of these samples is Eclipse, and the target environment is Lotus Notes 8. For details, please refer to the JavaDoc and Sample plug-ins code, which will be delivered with the API package.

8.1 Rich Client applications

This sample demonstrates how to create a simple editor. It loads a document form outside, and has some simple editor functions. There are two different ways to add menus. One is adding menus by "actionSet" with extension points; the other is adding menus by "MenuSet" with control API.

You can find the whole project with all source code from productivity tools toolkit directory (where $sodc_toolkit is the home directory that the API toolkit is installed to):

$sodc_toolkit/samples/eclipse/plugins/com.ibm.productivity.tools.samples.simpleeditorThe toolkit samples are introduced in section 3.1.

8.1.1 Creating a view plug-in

Sample plug-in class is mainly used for plugin entry point and resource accessing. It extends "org.eclipse.ui.plugin.AbstractUIPlugin". Class "AbstractUIPlugin" is an abstract base class for plug-ins that integrates with the Eclipse platform UI.

The steps for creating view plug-in are:1. Set the development environment as in Chapter 4.2. Select File > New > Project menu item or click right mouse button and select New > Project

context menu.


Fig.9. Create new plug-in project

3. Select Plug-in Project in the Project Category4. Click Next button, type "com.ibm.productivity.tools.samples.simpleeditor" as Project name.

Select Next button, and then click Finish button to finish creating the new project.


Fig.10. Naming the project

5. Add dependencies: Select Dependencies tab, and click the Add… button to add required plug-ins. There are three plug-ins that need to be added to it: com.ibm.productivity.tools.core com.ibm.productivity.tools.dom com.ibm.productivity.tools.ui


Fig.11. Add the dependent plug-ins

8.1.2 Creating a view

View is a component that consists of an arrangement of several view controls intended to be presented together to users. This part illustrates how to create a view.1. Select Extensions tab, click Add… button2. Add new extensions "org.eclipse.ui.views", then click Finish button.


Fig.12. Select extension point

3. In All Extensions area, click right mouse button and select New > Generic context menu item.


Fig.13. Add new view

4. Switch to "plugin.xml" tab, and modify the tab name as view5. Add attributes for the node and set values.<view class="com.ibm.productivity.tools.samples.simpleeditor.views.WriterView" id="com.ibm.productivity.tools.samples.simpleeditor.views.WriterView" name="Writer View" />

Fig.14. Modify the view node

6. Create a view class: Select menu New>Class to create a new Java class for the view, set the class arguments as below, and then click Finish button:l Package: com.ibm.productivity.tools.samples.simpleeditor.viewsl Name: WriterViewl Superclass: org.eclipse.ui.part.ViewPart


Fig.15. Create view class dialog

8.1.3 Loading documents to the view

Import necessary classes and rewrite "createPartControl" to open a viewer in "WriterView.java", then create and load a new blank document. Below is sample code:

public class WriterView extends ViewPart {private RichDocumentViewer viewer = null;public WriterView() {

super(); }

public void createPartControl(Composite arg0) { viewer = new RichDocumentViewer(arg0,true);

try {


RichDocument visibleDocument = new RichDocumentProvider(). createRichDocument(RichDocument.WRITER); viewer.setDocument(visibleDocument); } catch (IOException e) { e.printStackTrace(); } catch (EmptyFileObjectException e) {

e.printStackTrace(); } catch (DocumentAlreadyInitializedException e) {

e.printStackTrace(); }

}

public void setFocus() {

}}

8.1.4 Adding menus for the view and creating action class

Here is an example of adding an "Undo" menu item to the "MyEditor" Menu of the view window, and the below section will demonstrate it in two ways provided by the productivity tools control separately.

8.1.4.1 Method 1: adding menu by predefining action sets

There are predefined extension points for adding behavior to the Eclipse platform. Extension point "org.eclipse.ui.actionSets" is used for adding menus, menu items and toolbar buttons to common areas in Workbench window.

The plug-in manifest file, "plugin.xml", contains descriptive information that will be used by Eclipse to integrate the plug-in into the framework. Users can use the plugin.xml to define menu items.1. Open the plugin.xml in Eclipse platform and click the Extensions tab. 2. Click Add… button to add extension point.3. Select "org.eclipse.ui.actionSets", and select the Available templates for action sets, then

click Next.


Fig.16. Add extension point "org.eclipse.ui.actionSets"

4. Set the package name and class name, click Finish. This class is used to create a new view in this sample.


Fig.17. Set the package name and class name

5. Select "Sample Action Set", set the properties of "actionSet".l id:CreateActionSetl Label: CreateView Action Setl Visible: true

Fig.18. Change "Sample Action Set"

6. Select "Sample Menu (menu)", set the properties of "menu".l Id: CreateMenul Label: SimpleEditor

Fig.19. Change "Sample Menu (menu)"

7. Select "sampleGroup (separator)", set its name for "Do"


Fig.20. Change "sampleGroup (separator)"

8. Select "Sample Action (action)", and specify the properties as below:

Fig.21. Change "Sample Menu (menu)"

l Class: A fully qualified name of a class which implements "org.eclipse.ui.IWorkbenchWindowActionDelegate". This class is the handler responsible for performing the action. The value of the class here is: "com.ibm.productivity.tools.samples.simpleeditor.actions.CreateAction".

l Id: Function ID, a unique identifier used as a reference for this action. Here the ID is "createview".

l Label: An easy-to-use name that will be displayed on UI. Select "Create View" here.l MenubarPath: A slash-delimited path ('/') used to specify the location of this action in

the menu bar. Here the sample uses "CreateMenu/Do" to indicate that this menu item belongs to the "SimpleEditor" main menu.

The class above is created in step 4, and its sample code is:public class CreateAction implements IWorkbenchWindowActionDelegate {

public void dispose() {}

public void init(IWorkbenchWindow arg0) {}

public void run(IAction arg0) {IWorkbenchWindow window = PlatformUI.getWorkbench().getActiveWorkbenchWindow();try {

IWorkbenchPage page = window.getActivePage();if( page == null ) {

window.openPage("com.ibm.rcp.ui.perspectives.emptyperspective", null);page = window.getActivePage();

}page.showView


("com.ibm.productivity.tools.samples.simpleeditor.views.WriterView" );

} catch (PartInitException e) { e.printStackTrace();

} catch (WorkbenchException e) { e.printStackTrace();

}}

public void selectionChanged(IAction arg0, ISelection arg1) {}

}

9. Add another "actionSet" by repeating step 3 to step 8. The new actionSet class name is "SimpleEditorAction" (as step 4). The properties of the new "actionSet" are (as step 5):l Id: EditorMenuActionl Label: EditorMenu Action Setl Visible: false

10. Set the properties of "menu", repeating step 6: Id: EditorMenu Label: MyEditor1

11. Set the separator name as "Do", repeating step 7.12. Specify the action properties as below:

Fig.22. Set "Undo" action

l Class: "com.ibm.productivity.tools.samples.simpleeditor.actions.SimpleEditorAction".l Id: "undo1".l Label: "Undo".l MenubarPath: "EditorMenu/Do"The class above implements the interface IWorkbenchWindowActionDelegate. When there is a response from end users, the "run (IAction action)" method is invoked. Rewrite the "run" method in "SimpleEditorAction.java" like below:public void run(IAction action) {

IWorkbenchPage page = window.getActivePage(); WriterView view = (WriterView)page.getActivePart(); if (action.getId().equals("undo1")){ if (undoAction==null) {

undoAction = WriterActionFactory.EDIT_UNDO.create(view.getViewer()); }


undoAction.run(); } }

The "getViewer" method is added in "WriterView.java" like follows: public RichDocumentViewer getViewer(){

return viewer; }

The "undoAction" is a member of the "SimpleEditorAction" class: public class UndoAction implements IWorkbenchWindowActionDelegate {

...... private IAction undoAction = null;

...... }

13. Associate the menu with created view.Add an "org.eclipse.ui.actionSetPartAssociations" extension to associate the newly created actionSet with the newly created view above.

Fig.23. Add extension point "org.eclipse.ui.actionSetPartAssociations"

14. Edit the "plugin.xml" in source view by clicking the "plugin.xml" tab, then add


actionSetPartAssociation under extension points and set its targeteID and part id as follows:<extension

point="org.eclipse.ui.actionSetPartAssociations"> <actionSetPartAssociation targetID = "CreateAction" > <part id = "com.ibm.productivity.tools.samples.simpleeditor.views.WriterView"

/></actionSetPartAssociation>

</extension>

Fig.24. "plugin.xml" after adding actionSetPartAssociation

15. Add the code below in "createPartControl" in "WriteView.java". They are used to control to show/hide the "undo" menu in the view.

public void createPartControl(Composite arg0) {......

viewer.setActionSetNames(new String[] {"EditorMenuAction",null,null,null});

WorkbenchWindow window = (WorkbenchWindow)PlatformUI.getWorkbench().getActiveWorkbenchWindow();

......}

8.1.4.2 Method 2: adding menu by menu API

Besides predefining action sets in the configuration file, users can also use control APIs which are provided by Lotus Productivity Tools to add view menus:1. Create a new "WriterDocumentMenuSet" class, set its package and superclass as:

Package: com.ibm.productivity.tools.samples.simpleeditor.menus


Superclass: com.ibm.productivity.tools.ui.actionfactory.RichDocumentMenuSet

Fig.25. Create WriterDocumentMenuSet class

2. Add a constructor method to the new class, in which WriterActionFactory class is used to create an "Undo" action and then insert it to "Editor" menu as a menu item.

public WriterDocumentMenuSet(RichDocumentViewer viewer, IMenuManager rootMenuManager) { IMenuManager editMM = new MenuManager("MyEditor2", "MyEditor2ID"); rootMenuManager.add(editMM); Separator doSep = new Separator("Do"); editMM.add( doSep ); IAction action = WriterActionFactory.EDIT_UNDO.create(viewer); action.setText("Undo"); editMM.prependToGroup(doSep.getGroupName(), action); addMenu(editMM); }


3. In createPartControl() method of "WriterView.java", associate this menu set to the view public class WriterView extends ViewPart {

private RichDocumentViewer viewer; viewer.setActionSetNames(new String[] { "Set Action Set Names0210", null, null, null,}); WorkbenchWindow window =

(WorkbenchWindow)PlatformUI.getWorkbench().getActiveWorkbenchWindow(); ...... public void createPartControl(Composite parent) {

...... // add menus for this view

IMenuManager rootMenuManager = window.getMenuManager(); WriterDocumentMenuSet writerMenuSet = new

WriterDocumentMenuSet(viewer, rootMenuManager);

viewer.setMenuSetArray(new RichDocumentMenuSet[]{writerMenuSet,null,null,null,null});

viewer.showMenuSet(RichDocumentViewer.WRITER_CONTRIBUTIONSET); } ......

}

8.1.5 Add status bar for the view

Add the below code in "createPartControl" in "WriterView" to add status bar to the view:IStatusLineManager slm =

this.getViewSite().getActionBars().getStatusLineManager();IContributionItem pageStyleItem =

WriterStatusLineContributionItemFactory.PAGE_STYLE .createContributionItem(viewer);slm.add(pageStyleItem);IContributionItem pageStatusItem =

WriterStatusLineContributionItemFactory.PAGE_STATUS .createContributionItem(viewer);slm.add(pageStatusItem);IContributionItem insertItem = WriterStatusLineContributionItemFactory.INSERT .createContributionItem(viewer);


slm.add(insertItem);IContributionItem zoomItem = WriterStatusLineContributionItemFactory.ZOOM .createContributionItem(viewer);slm.add(zoomItem);IContributionItem selectModeItem =

WriterStatusLineContributionItemFactory.SELECT_MODE .createContributionItem(viewer);slm.add(selectModeItem);IContributionItem hyperlinkModeItem =

WriterStatusLineContributionItemFactory.HYPERLINKS_MODE .createContributionItem(viewer);slm.add(hyperlinkModeItem);IContributionItem isModifyItem =

WriterStatusLineContributionItemFactory.IS_MODIFY .createContributionItem(viewer);slm.add(isModifyItem);IContributionItem sizeItem = WriterStatusLineContributionItemFactory.SIZE .createContributionItem(viewer);slm.add(sizeItem);

8.1.6 Running the application

1. Select Run... >Run, Click menu SimpleEditor>Create View.


Fig.26. Run the application

2. Input some text in the new editor, and select the MyEditor1 > Undo or MyEditor2 > Undo item, and then the text is undone. The menu "MyMenu1" is added by method 1 in section 8.1.4.1, and the "MyMenu2" is added by method 2 in section 8.1.4.2.

Fig.27. the undo action

8.2 Office automation application

This sample demonstrates how to operate user field elements in a document. It loads a notice template which contains some user fields, such as notice title, destination, text, attachment, etc. The view uses APIs to access each user field with its name, sets the proper content in it, and then a new notice is completed.

You can find the whole project with all source code from productivity tools toolkit directory (where $sodc_toolkit is the home directory that the API toolkit is installed to):

$sodc_toolkit/samples/eclipse/plugins/com.ibm.productivity.tools.samples.field The toolkit samples are introduced in section 3.1.

8.2.1 Creating a project

The sample is provided as a plug-in project. The main steps for creating a project are as below:1. Set the development environment by referring to Chapter 4 2. Select File > New > Project > Plug- in Project.


3. Enter a project name "com.ibm.productivity.tools.samples.field", click next and finish the creating.

4. Add required plug-ins to the dependencies by the following step 5 in section 8.1.1. These plug-ins are:l com.ibm.productivity.tools.corel com.ibm.productivity.tools.doml com.ibm.productivity.tools.ui

5. Add a document template: Create a new folder "resource" under project folder. Open "$sodc_toolkit/samples/eclipse/plugins/com.ibm.productivity.tools.samples.field/resource", copy the template file "fields.sxw", and then add it into the "resource" folder in current project. Note: the "$sodc_toolkit" is the directory which productivity tools API toolkit is installed to.

Fig.28. the document template

8.2.2 Creating a view

1. Create a new class "FieldView", set its package and superclass as: Package: com.ibm.productivity.tools.samples.field.view Superclass: org.eclipse.ui.part.ViewPart

2. Add a new extension point "org.eclipse.ui.views" in extension tab by following steps in section 8.1.2. Add the attributes for the node and set its value in "plugin.xml".


<view class="com.ibm.productivity.tools.samples.field.view.FieldView" id="com.ibm.productivity.tools.samples.field.view.FieldView" name="Field View" />

Fig.29. Set view attributes

3. Add some members in the new class and rewrite "createPartControl" method as follows:public class FieldView extends ViewPart {

protected RichDocumentViewer viewer;private RichDocument visibleDocument;protected int documentType = RichDocument.WRITER; public FieldView() { }

public void createPartControl(Composite arg0) { // Creates one or more controls within the parent viewer = new RichDocumentViewer(arg0, true ); // The external file String fileName = getResolvedPath( "resource/fields.sxw" ); // Loads the file and creates the document

visibleDocument = new RichDocumentProvider().createRichDocument(fileName);

// Sets the document in the viewer try {

viewer.setDocument( visibleDocument );} catch ( IOException e ) {

e.printStackTrace();} catch ( ProductivityToolsException e ) {

e.printStackTrace();}

// Sets the fields contents in the template editField();}


public void editField() { ......

}

private String getResolvedPath(String file){ ......

}

public void setFocus() {// TODO Auto-generated method stub

}}

The view loads a notice template which contains some user fields, such as title, destination, text, attachment, etc. This method "editField" uses APIs to access each user field with its name, sets the proper content in it, and then a new notice is completed. The sample code demonstrates how to access the user field by its name, and then set the new value.public void editField() {

DocumentBuilder builder = new DocumentBuilder(); // Gets the document

ODFTextDocument document = (ODFTextDocument)builder.createDocumentModel( viewer.getDocument() );

// Gets all user field declarations in the document ODFCollection userFieldDecls = document.getUserFieldDeclarations(); // Sets the value of declarations UserFieldDeclarationElement curDeclaration =

(UserFieldDeclarationElement) userFieldDecls.namedItem("secret"); curDeclaration.setStringValue("Normal"); curDeclaration = (UserFieldDeclarationElement) userFieldDecls.namedItem("year"); curDeclaration.setStringValue("2007"); curDeclaration =

(UserFieldDeclarationElement) userFieldDecls.namedItem("number"); curDeclaration.setStringValue("01"); curDeclaration = (UserFieldDeclarationElement) userFieldDecls.namedItem("title"); curDeclaration.setStringValue("Sports Day"); curDeclaration = (UserFieldDeclarationElement) userFieldDecls.namedItem("desc"); curDeclaration.setStringValue("All Departments"); curDeclaration =

(UserFieldDeclarationElement) userFieldDecls.namedItem("textBody"); curDeclaration.setStringValue("The Sports Day 2007 is coming. Welcome!"); curDeclaration =


(UserFieldDeclarationElement) userFieldDecls.namedItem("attachment"); curDeclaration.setStringValue("Sports Calendar"); curDeclaration = (UserFieldDeclarationElement) userFieldDecls.namedItem("key"); curDeclaration.setStringValue("Sports Day, Agenda"); curDeclaration = (UserFieldDeclarationElement) userFieldDecls.namedItem("cc"); curDeclaration.setStringValue("Company Club"); curDeclaration =

(UserFieldDeclarationElement) userFieldDecls.namedItem("collate"); curDeclaration.setStringValue("Tom"); curDeclaration =

(UserFieldDeclarationElement) userFieldDecls.namedItem("typist"); curDeclaration.setStringValue("Mary"); curDeclaration =

(UserFieldDeclarationElement) userFieldDecls.namedItem("copyNum"); curDeclaration.setStringValue("100");}

The method "getResolvedPath" is used to load the template file. Sample code is like below:private String getResolvedPath(String file){ String resolvedPath = null;

Bundle bundle = Platform.getBundle( "com.ibm.productivity.tools.samples.field" );

if (bundle != null) { java.net.URL bundleURL = bundle.getEntry( "/" ); if (bundleURL != null) { try { resolvedPath =FileLocator.resolve( bundleURL ).getFile(); } catch (IOException e) { e.printStackTrace(); } } } return resolvedPath+file;}

8.2.3 Creating an action class

1. Create a new package "com.ibm.productivity.tools.samples.field.actions", and then create a new class "FieldViewAction" in it. This new class implements the interface "org.eclipse.ui.IWorkbenchWindowActionDelegate".

2. Rewrite the new class. The sample code is like below: public class FieldViewAction implements IWorkbenchWindowActionDelegate {


public void dispose() {}

public void init(IWorkbenchWindow arg0) {}

public void run(IAction arg0) { IWorkbenchWindow window =

PlatformUI.getWorkbench().getActiveWorkbenchWindow(); try { IWorkbenchPage page = window.getActivePage(); if( page == null ) {

window.openPage("com.ibm.rcp.ui.perspectives.emptyperspective", null);

page = window.getActivePage(); }

page.showView("com.ibm.productivity.tools.samples.field.view.FieldView"); } catch (PartInitException e) {

e.printStackTrace(); } catch (WorkbenchException e) {

e.printStackTrace(); }

}

public void selectionChanged(IAction arg0, ISelection arg1) {}

}

3. Add a actionSet definition in "plugin.xml":<extension point="org.eclipse.ui.actionSets"> <actionSet label="MySample2" visible="true" id="DOMSamples.actionSet2"> <menu label="MySample" id="com.ibm.sample.menu"> <separator name="sampleGroup"/> </menu> <action label="TextField DOM Sample"


class="com.ibm.productivity.tools.samples.field.actions.FieldViewAction" menubarPath="com.ibm.sample.menu/sampleGroup" id="com.ibm.productivity.tools.samples.field.actions.FieldViewAction"/> </actionSet></extension>

8.2.4 Running the application

The process of running is also similar with Rich Client application.1. Select Run... > Run, Click menu MySample > TextField DOM Sample.2. Select the "Sample View" to open the new notice.

Fig.30. a new document is created based on the template

8.3 Composite application

This sample instructs how to create a new Composite Application and edit it with the Lotus Notes CAE tool. The main steps are:1. Setup Eclipse development environment. To do this, please refer to Chapter 4.2. Import the related features and plugins into your workspace. The following are the features

and plugins list which can be retrieved in toolkit code: com.ibm.productivity.tools.SampleCAFeature com.ibm.productivity.tools.samples.TemplateComponent com.ibm.productivity.tools.samples.WriterComponent


3. Create a new updatesite in Eclipse workspace such as "SampleUpdateSites", and add the feature "com.ibm.productivity.tools.SampleCAFeature" to this updatesite.

4. Build and export this updatesite: right click this updatesite in the current workspace, select Export… context menu and the "Export" dialog allows you to export this updatesite to your local file system such as "c:\temp".

Fig.31. Build and export this update site

5. Open Lotus Notes 8 to create a new composite application: click File > Application>New menu, the New Application dialog pops up, fill the application title and name such as CASample, select the Blank Composite Application as the template and then confirm this dialog, finally a blank page for this newly created application will be shown in the Notes8 platform.


Fig.32. Create new composite application

6. Open the CAE to edit this new composite application: In Lotus Notes 8 window click Actions > Edit Application to open CAE.

Fig.33. Edit the new composite application

7. Add the components from local update site which is created in step 4: In the right Component Palette view of the CAE window, right click to select the Add Components >


Add Eclipse View From Update Site context menu to add eclipse components.

Fig.34. Add exported plugins

The bellow is the "Update Site Details" dialog which allows you to import plugins application contained in the local updatesite exported in step 4.

Fig.35. "Update Site Details" dialog

8. Add the imported two components to the new application: Use mouse select these two imported components drag them from the Component Palette area to the center area of the CAE .


Fig.36. Add the imported components to the new application

9. Edit this composite application: right click the application in the application palette view, select the Wiring context menu, and start wiring.

Fig.37. Edit composite application

Wire the application as the following dialog to build a new relationship between these two. com-ponents, click OK button to save this relationship.


Fig.38. Build a new relationship with one component

10. Finish editing this composite application: The following window is CAE where two components are shown in the right panel view. While clicking a document node in the left "Customer Template" component, the corresponding document will be opened in the view of the right "Writer Template" component.

Fig.39. Finish editing composite application

Select File > Finished Editing menu in the CAE and confirm the reminding dialog the CAE window is closed now you can see the edited composite application in the bellow Lotus Notes 8:


Fig.40. Edited composite application in Lotus Notes 8


9. Deploying applications

After you have completed code development, you ought to run your code in real installed Lotus Notes 8 product environment, or distribute your code to customer Lotus Notes 8 client environment. To achieve it your application needs to be packaged and deployed.

There are three methods to deploy our applications to the target environment, which applies to different situations. Deploying with an update site. The first option is exposed to customers to deploy on an

existing Notes 8 client, which deploys your applications one client at a time. Deploying with Lotus Notes 8 installer. The second way is an admin preference which

distributes your applications with Notes installation, so it can deploy in a batch mode. When your IBM productivity tools applications are integrated with other notes applications

with Composite Application support, they can also be deployed via Composite Application Editor. In this way, please make sure you have installed the Composite Application Editor when installing Lotus Notes 8.

The content below in this chapter illustrates how to package and deploy an application to Lotus Notes 8 based on the samples which can be found from IBM Lotus Productivity Tools toolkit.

9.1 Packaging your code into an update site project

An update site is the key mechanism to enable installation of the application, which includes the features and plug-ins to be deployed. For more information on update sites, including how to create one, please see the Getting Started > Update Sites section of the PDE Guide.

The steps of creating an update site are:1. Start Eclipse, create an empty workspace, and then import the sample features and plug-ins

from Lotus Productivity Tools toolkit directory, say "D:\prodtools_toolkit" on Win32 platform. If the imported projects have any building errors, please set the development environment as described in Chapter 4.


Fig.41. Import the sample features and plug-ins

2. Create a new project with "Update Site Project", and then name it as "sample".


Fig.42. Create a new update site project

3. Open file "site.xml", in the "Site Map" view, click the Add feature button, add the "com.ibm.productivity.tools.sample.feature" into the update site

4. Click the Build button to build the update site.5. Export the "sample" update site project to file system, e.g. F:\deploy\PT_sample


Fig.43. Export the update site project to file system


Fig.44. Export the update site project to special directory

9.2 Deploying with an update site

In this option, customers can deploy applications to an existing Lotus Notes 8 client in a standard update site installation.1. By default, Lotus Notes 8 client doesn't have the ability to install extra applications, as the

Expeditor platform install menu entry is hidden from users. To expose it, you need to enable it beforehand. Open $notes_home/framework/rcp/plugin_customization.ini (where $notes_home is the directory where Lotus Notes 8 is installed to), and add the following line: com.ibm.notes.branding/enable.update.ui=true

2. Launch Lotus Notes 8 and choose the File > Applications > Install menu item.3. Select "Search for new features to install" and next.4. Click "Add Folder Location" and select the update site project which is created in section

9.1 in local file system, then click Finish button.


Fig.45. Install update site project

5. In "Updates" dialog, select the update site, then click Next.


Fig.46. Update the project

6. Accept the terms in the license agreements in Install dialog, click Next, and Finish in next dialog


Fig.47. Accept the terms in the license agreements

7. Select "Install this plug-in" and click "OK" in each plug-in

Fig.48. Select "Install this plug-in" in each plug-in

After the mentioned steps, there is a new menu appearing in menu bar which shows you have successful installed your applications.


9.3 Deploying with Lotus Notes 8 installer

The previous deploying method in section 9.2 is exposed to customers, which can only be used to deploy applications client by client. There is another way to administrate preferences before Lotus Notes 8 installation. In this way, administrators can integrate your applications with Lotus Notes 8 installation files, so it can be installed with Lotus Notes 8 installation automatically. The main steps of this method are as follows:1. Create an update site project as section 9.1.2. Copy the features and plug-ins from "features" and "plugins" directory in the created update

site, and then add them into the same location in directory $notes_home/updateSite/, where $notes_home is the directory where Lotus Notes 8 is installed to.

3. Open file $notes_home/deploy/install.xml, find the special install feature whose name is "Lotus Productivity Tools". Add a new feature in the requirements as follows:<feature deferredEnable="false" id="feature_id" match="perfect"

size="feature_size" url="${installer.root}/updateSite" version="feature_version"/>

The correct parameters "feature_id" and "feature_version" can be found in "site.xml" in the update site created in step 1. Here is an example: <feature deferredEnable="false" id="com.ibm.productivity.tools.samples.feature"

match="perfect" size="1024" url="${installer.root}/updateSite" version="3.0.0.20070112-2113"/>

Fig.49. Add new feature information in "install.xml"4. Open file $notes_home/updateSite/site.xml, add a new feature at the end of the features

whose ids are begin with "com.ibm.productivity.tools". The format is:<feature id=" feature_id" patch="false" url="features_url" version="

feature_version"><category name="WCT"></category>

</feature>

The correct parameters "feature_id" and "feature_version" are as same as above. Here is an example: <feature id="com.ibm.productivity.tools.samples.feature" patch="false"

url="features/com.ibm.productivity.tools.samples.feature_3.0.0.20070112-2113.jar" version="3.0.0.20070112-2113">

<category name="WCT"></category></feature>


Fig.50. Add new feature information in "site.xml"5. Open the file $notes_home/deploy/plugin_customization.ini, then change the policy to

com.ibm.rcp.security.update/UNSIGNED_PLUGIN_POLICY=ALLOW. Doing this will allow your unsigned plug-ins to be installed.

6. Then you can begin to install Lotus Notes 8. While installing, please do select "IBM Productivity Tools" install option. So the features and plug-ins of your applications will be installed with Notes 8 automatically.

9.4 Deploying with composite application support

When your applications are designed to be integrated with other Notes views within Composite Application Editor, you needn't consider the deployment method of your application separately. Composite Application Editor provides its own way to deploy all integrated applications. It is also based on update sites, so you still need to package your applications into update sites as shown in section 9.1. Please refer to "Composite Applications Toolkit User's Guide" from "Composite Applications Toolkit" for more details on Composite Application and the way to deploy applications.

10 Programming with LotusScript

Lotus Notes is great for collaboration and workflow. Productivity Tools is a full-functional office tools based on OpenOffice and ODF, open standards around file formats. There had been a long history for Notes and Office integration. A lot of commercial products and solutions are designed for this purpose. Typically, they are based on Lotus Notes and Microsoft Office or OpenOffice before. Both Notes and Office (Microsoft Office or OpenOffice) are exposed as COM objects in Windows platform. So it is possible for scripting programmer to call each other inside its own application. The integration aggregates mutual benefits of each application, and improves operational efficiency and productivity for end users.

Lotus Notes 8 client provides both Notes client and Productivity Tools in one application. It offers great opportunity for ISVs and IBM to provide better Notes-Office integration experience.


Although there are several ways to integrate Notes and Productivity Tools in Notes 8, scripting programming is still a key aspect to achieve it for the following reasons.

LotusScript is the most important programming language in Notes. As the success of Domino/Notes, LotusScript had been widely used by Notes developers.

Productivity Tools supports scripting programming through StarBasic. StarBasic is the supported scripting language from OpenOffice1.1, it is widely used in OpenOffice community. With StarBasic, it is almost possible to access all functions provided by Productivity Tools.

StarBasic code can be executed in LotusScript environment directly. Since LotusScript can access COM objects, Productivity Tools had bridged the UNO objects into COM objects, so StarBasic code can be executed in LotusScript environment without change.

Note: The feature is applicable to Windows platform since Notes 8.0.1.

10.1 Sample LotusScript code

Specifically, the following scripting code should be executed successfully in LotusScript environment. You can copy the source code into LotusScript environment, and run it directly.

Sub Initialize

Dim objservicemanager As Variant

Dim objText As Variant

Dim args()

Set objServiceManager = CreateObject("com.sun.star.ServiceManager")

Set objCoreReflection= objServiceManager.createInstance("com.sun.star.reflection.CoreReflection")

Set objDesktop = objServiceManager.createInstance("com.sun.star.frame.Desktop")

‘the sample create a blank document, it is also possible to load from URL

Set objDocument = objDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, args)

Set objText = objDocument.getText()

Set objCursor = objText.createTextCursor()

objText.insertString objCursor, "JMP204", False

'more other calls to operate on the document model

‘dispose the document

‘objDocument.dispose

End Sub

The result of the execution will be as the following. A new document is created in Notes client, and some text is inserted.


11 Developing composite application

Productivity Tools supports composite application programming model in Lotus Notes 8. Basically, developer can build a customized Eclipse component with Productivity Tools APIs based on Productivity Tools toolkit, the component can be integrated into composite application by end user or developer. Developer or end user can also use a out-of-box Productivity Tools component, which is provided since Notes 8.0.1.

11.1 Composite Application programming model

introduction

Composite applications, which are experienced at the front end of a service oriented architecture (SOA), aggregate components on the screen to present content from multiple systems in single


context for the end user. Composite applications are an assembly of components - end-user-facing programs - that provide specific functions and access to information from multiple sources, for example, a Lotus Notes database, a Java application, the Web or a customer relationship management application. These reusable components can be mixed and matched in multiple composite applications, allowing developers to create a wide variety of applications with a small set of services—and without writing code. The various components can also send information to one another, so that when views are changed or data is entered or edited in one application, the corresponding views and information in the other applications also change.

Composite Applications are generally a collection of loosely coupled components that define particular business logic. These components could be a mix of Notes components and Eclipse based components in Notes 8 client. In Notes terminology a component is a Notes database or to be more specific, any of the different elements from a Notes Databases, e.g. Views, Forms, and Documents. These components are associated with 'properties' and 'actions' that are the basic elements of information needed for brokering. Notes property broker projects the Lotus Expeditor property broker functionality.

Property is an exchangeable data item that a component can produce or consume. Each property has at least two attributes - a type name and a namespace. Properties are part of a component. The properties are provided by developer of the component.

Action is the logic that defines how one or more properties are to be processed. Action is also considered as input property of a component. The actions are provided by developer of the component.

Wire defines the connection between specific source components to a specific target compo-nent. They are used to establish relation between a property and an action. Wires are not part of any component, they just define the association. Wires are established using Composite Application Editor when the components are deployed and a composite application is creat-ed.

Notes:For more details about composite application in Notes 8, please reference to composite application blog: http://www-03.ibm.com/developerworks/blogs/page/CompApps.

11.2 Using out-of-box properties and actions

In Notes 8.0.1, we provide an out-of-box Productivity Tools component named as “DefaultRichDocumentView”. You can add it directly into your composite application with Composite Application Editor in Notes client. The component is provided as locally installed component. For instruction and tutorial about how to use Composite Application Editor, please reference to composite application blog.


The following table describes the general information about pre-defined properties and actions. Detailed functions of property and action are provided in later chapter. Properties:

Property DataType namespace DescriptionSelectionChanged

xsd:string http://www.w3.org/2001/XMLSchema

String content of current selection, fired when selection changed in Productivity Tools

FileSaved idt:url http://www.ibm.com/xmlns/prod/datatype

URL of saved document, fired when save or saveas occurred. E.g. “file:///c:/temp/1.odt”

Actions:Action DataType namespace Description

LoadFile idt:url http://www.ibm.com/

xmlns/prod/datatype

Load a file by specifying URL. e.g. “file:///c:/temp/1.odt”

Insert xsd:string http://www.w3.org/2001/XMLSchema

Insert content at current cursor position

Generally speaking, those properties and actions are supported in all three applications: writer, spreadsheet and presentation. However there are some differences for these applications. LoadFile action and FileSaved properties are common to all three applications.

Property/Action Description ExampleLoadFile Load document into Productivity Tools

component for all supported document types“file:///c:/temp/1.odt”

FileSaved Fired when the document is saved in Productivity Tools component

file:///c:/1.odt

For Insert and SelectionChanged, the function and scope are different in three applications.

For writer application Property/Action Scope DescriptionInsert Body

TextFrameTableCellHeaderFooter

Insert string when current cursor is located within supported objects.

SelectionChanged BodyTextFrameTableCellHeaderFooterTextField

Fire property change event when cursor selection changed in supported objects

For spreadsheet application


Property/Action Scope DescriptionInsert Cell

DrawingObjectGraphics

Replace all content for selected objects, not just selected characters in the objects

SelectionChanged

CellDrawingObjectGraphics

Fire property change event when cursor select or enter supported objects. The content would be the whole content for selected object, not just selected characters

For presentation application:Property/Action Scope DescriptionInsert TextBox

DrawingObjectGraphics

Replace all content for selected objects, not just selected characters in the objects

SelectionChanged

TextBoxDrawingObjectGraphics

Fire property change event when cursor select or enter supported objects. The content would be the whole content for selected object, not just selected characters


Appendix A: Supported DOM API

The API or interface marked by green means that it has been implemented. org/w3c/dom/DOMException.java:

package org.w3c.dom;public class DOMException extends RuntimeException { public DOMException(short code, String message) { super(message); this.code = code; } public short code; // ExceptionCode public static final short INDEX_SIZE_ERR = 1; public static final short DOMSTRING_SIZE_ERR = 2; public static final short HIERARCHY_REQUEST_ERR = 3; public static final short WRONG_DOCUMENT_ERR = 4; public static final short INVALID_CHARACTER_ERR = 5; public static final short NO_DATA_ALLOWED_ERR = 6; public static final short NO_MODIFICATION_ALLOWED_ERR = 7; public static final short NOT_FOUND_ERR = 8; public static final short NOT_SUPPORTED_ERR = 9; public static final short INUSE_ATTRIBUTE_ERR = 10; public static final short INVALID_STATE_ERR = 11; public static final short SYNTAX_ERR = 12; public static final short INVALID_MODIFICATION_ERR = 13; public static final short NAMESPACE_ERR = 14; public static final short INVALID_ACCESS_ERR = 15;}

org/w3c/dom/DOMImplementation.java:package org.w3c.dom;

public interface DOMImplementation { public boolean hasFeature(String feature, String version); public DocumentType createDocumentType(String qualifiedName, String publicId, String systemId) throws DOMException; public Document createDocument(String namespaceURI, String qualifiedName,


DocumentType doctype) throws DOMException;}

org/w3c/dom/DocumentFragment.java:package org.w3c.dom;

public interface DocumentFragment extends Node {}

org/w3c/dom/Document.java:package org.w3c.dom;

public interface Document extends Node { public DocumentType getDoctype(); public DOMImplementation getImplementation(); public Element getDocumentElement(); public Element createElement(String tagName) throws DOMException; public DocumentFragment createDocumentFragment(); public Text createTextNode(String data); public Comment createComment(String data); public CDATASection createCDATASection(String data) throws DOMException; public ProcessingInstruction createProcessingInstruction

(String target, String

data) throws

DOMException; public Attr createAttribute(String name) throws DOMException; public EntityReference createEntityReference(String name) throws DOMException; public NodeList getElementsByTagName(String tagname); public Node importNode(Node importedNode, boolean deep) throws DOMException; public Element createElementNS(String namespaceURI, String qualifiedName) throws DOMException; public Attr createAttributeNS(String namespaceURI, String qualifiedName) throws DOMException; public NodeList getElementsByTagNameNS(String namespaceURI, String localName); public Element getElementById(String elementId);


}

org/w3c/dom/Node.java:package org.w3c.dom;

public interface Node { // NodeType public static final short ELEMENT_NODE = 1; public static final short ATTRIBUTE_NODE = 2; public static final short TEXT_NODE = 3; public static final short CDATA_SECTION_NODE = 4; public static final short ENTITY_REFERENCE_NODE = 5; public static final short ENTITY_NODE = 6; public static final short PROCESSING_INSTRUCTION_NODE = 7; public static final short COMMENT_NODE = 8; public static final short DOCUMENT_NODE = 9; public static final short DOCUMENT_TYPE_NODE = 10; public static final short DOCUMENT_FRAGMENT_NODE = 11; public static final short NOTATION_NODE = 12;

public String getNodeName(); public String getNodeValue() throws DOMException; public void setNodeValue(String nodeValue) throws DOMException; public short getNodeType(); public Node getParentNode(); public NodeList getChildNodes(); public Node getFirstChild(); public Node getLastChild(); public Node getPreviousSibling(); public Node getNextSibling(); public NamedNodeMap getAttributes(); public Document getOwnerDocument(); public Node insertBefore(Node newChild, Node refChild) throws DOMException; public Node replaceChild(Node newChild, Node oldChild) throws DOMException; public Node removeChild(Node oldChild) throws DOMException; public Node appendChild(Node newChild) throws DOMException; public boolean hasChildNodes(); public Node cloneNode(boolean deep);


public void normalize(); public boolean isSupported(String feature, String version); public String getNamespaceURI(); public String getPrefix(); public void setPrefix(String prefix) throws DOMException; public String getLocalName(); public boolean hasAttributes();}

org/w3c/dom/NodeList.java:package org.w3c.dom;

public interface NodeList { public Node item(int index); public int getLength();}

org/w3c/dom/NamedNodeMap.java:package org.w3c.dom;

public interface NamedNodeMap { public Node getNamedItem(String name); public Node setNamedItem(Node arg) throws DOMException; public Node removeNamedItem(String name) throws DOMException; public Node item(int index); public int getLength(); public Node getNamedItemNS(String namespaceURI, String localName); public Node setNamedItemNS(Node arg) throws DOMException; public Node removeNamedItemNS(String namespaceURI, String localName) throws DOMException;}

org/w3c/dom/CharacterData.java:package org.w3c.dom;

public interface CharacterData extends Node { public String getData() throws DOMException; public void setData(String data) throws DOMException; public int getLength(); public String substringData(int offset, int count)


throws DOMException; public void appendData(String arg) throws DOMException; public void insertData(int offset, String arg) throws DOMException; public void deleteData(int offset, int count) throws DOMException; public void replaceData(int offset, int count, String arg) throws DOMException;}

org/w3c/dom/Attr.java:package org.w3c.dom;

public interface Attr extends Node { public String getName(); public boolean getSpecified(); public String getValue(); public void setValue(String value) throws DOMException; public Element getOwnerElement();}

org/w3c/dom/Element.java:package org.w3c.dom;

public interface Element extends Node { public String getTagName(); public String getAttribute(String name); public void setAttribute(String name, String value) throws DOMException; public void removeAttribute(String name) throws DOMException; public Attr getAttributeNode(String name); public Attr setAttributeNode(Attr newAttr) throws DOMException; public Attr removeAttributeNode(Attr oldAttr) throws DOMException; public NodeList getElementsByTagName(String name); public String getAttributeNS(String namespaceURI, String localName); public void setAttributeNS(String namespaceURI, String qualifiedName,


String value) throws DOMException; public void removeAttributeNS(String namespaceURI, String localName) throws DOMException; public Attr getAttributeNodeNS(String namespaceURI, String localName); public Attr setAttributeNodeNS(Attr newAttr) throws DOMException; public NodeList getElementsByTagNameNS(String namespaceURI, String localName); public boolean hasAttribute(String name); public boolean hasAttributeNS(String namespaceURI, String localName);}

org/w3c/dom/Text.java:package org.w3c.dom;

public interface Text extends CharacterData { public Text splitText(int offset) throws DOMException;}

org/w3c/dom/Comment.java:package org.w3c.dom;

public interface Comment extends CharacterData {}

org/w3c/dom/CDATASection.java:package org.w3c.dom;

public interface CDATASection extends Text {}

org/w3c/dom/DocumentType.java:package org.w3c.dom;

public interface DocumentType extends Node { public String getName(); public NamedNodeMap getEntities(); public NamedNodeMap getNotations(); public String getPublicId(); public String getSystemId(); public String getInternalSubset();}

org/w3c/dom/Notation.java:package org.w3c.dom;

public interface Notation extends Node { public String getPublicId(); public String getSystemId();


}

org/w3c/dom/Entity.java:package org.w3c.dom;

public interface Entity extends Node { public String getPublicId(); public String getSystemId(); public String getNotationName();}

org/w3c/dom/EntityReference.java:package org.w3c.dom;

public interface EntityReference extends Node {}

org/w3c/dom/ProcessingInstruction.java:package org.w3c.dom;

public interface ProcessingInstruction extends Node { public String getTarget(); public String getData(); public void setData(String data) throws DOMException;}


Appendix B: References

1. OpenOffice SDK 2. Document Object Model (DOM) Level 2 Core Specification 3. DOM Level 2 Java Language Binding 4. OpenOffice 1.0 Developer's Guide 5. Open Document Format for OfficeApplications (OpenDocument) v1.0


http://docs.oasis-open.org/office/v1.0/OpenDocument-v1.0-os.pdf

http://www.openoffice.org/index.html

http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/java-binding.zip

http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/

http://www.openoffice.org/index.html

Appendix C: Notices

NoticesThe information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the infor-mation contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM's current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

CopyrightUnder the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or ma-chine-readable form, in whole or in part, without the prior written consent of IBM Cor-poration, except in the manner described in the documentation or the applicable li-censing agreement governing the use of the software.

Licensed Materials - Property of IBM

© Copyright IBM Corporation 1985, 2008

Lotus SoftwareIBM Software GroupOne Rogers StreetCambridge, MA 02142

All rights reserved. Printed in the United States.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GS ADP Schedule Contract with IBM Corp.

Revision History: Original material produced for IBM Lotus Notes and IBM Lotus Domino Release 8.0.1.

List of Trademarks


IBM, the IBM logo, AIX, DB2, Domino, iSeries, i5/OS, Lotus, Lotus Notes, LotusS-cript, Notes, Quickplace, Sametime, WebSphere, Workplace, z/OS, and zSeries are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both.

Additional IBM copyright information can be found at: http://www.ibm.com/legal/copy-trade.shtml

This information also refers to products built on EclipseTM (http://www.eclipse.org)

Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Intel and Pentium are trademarks of Intel Corporation in the United States, other countries, or both.

The Graphics Interchange Format© is the Copyright property of CompuServe Incor-porated. GIF(sm) is a Service Mark property of CompuServe Incorporated.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product and service names may be trademarks or service marks of others.


http://www.ibm.com/legal/copytrade.shtml_

http://www.ibm.com/legal/copytrade.shtml_