ShowTable of Contents
This is the second article to demonstrate the features of the
NotesUI API.
Sample application
The sample application in this article shows how you can execute a LotusScript agent from XPages. This is useful if you have existing LotusScript code that you would like to leverage in an XPages application.
Note that using the standard Notes APIs, it's already possible to call a
background agent from SSJS code (using
Agent.run) which also works on the web, but unfortunately this agent does not have any access to the Notes Client UI. So for example, it's not possible to open dialog boxes, picklists or simply let the user answer a simple yes/no question from the LotusScript agent.
By using the XPages2Eclipse agent execution function, you can do anything you like in the Client UI and in addition, it's possible to pass data back and forth between XPages and classic LotusScript code.
Our sample contains a simple XPage with a multiline textbox. By clicking a button, an agent gets executed that opens the same text in a classic dialog box. When you are done editing the text, the changes get transferred back to the underlying XPage:
Here is the code that is calling the UI agent:
var oldTxt=getComponent("xContent").getValue();
var conn=X2E.createConnection();
var notesTools=com.x2e.NotesUIAPI.getTools(conn);
var ws=notesTools.getNotesUIWorkspace();
//prepare the result document in which we expect the agent result
var retDbPath=notesTools.getTempDbPath();
var retDb=session.getDatabase("", retDbPath);
var retDoc=retDb.createDocument();
retDoc.save(true,false);
var retDocUnid=retDoc.getUniversalID();
retDoc.recycle();
//pass text and filepath/unid of result document to the agent
var agentParamsMap=new java.util.HashMap();
agentParamsMap.put("content", oldTxt);
agentParamsMap.put("retdbpath", retDbPath);
agentParamsMap.put("retdocunid", retDocUnid);
//execute the agent and wait for the result
ws.runAgent(database.getServer(), database.getFilePath(),
"lsDialogAgent", agentParamsMap, false, true);
//reload the result document to pull out the new text
retDoc=retDb.getDocumentByUNID(retDocUnid);
if (retDoc.hasItem("content")) {
var newTxt=retDoc.getItemValueString("content");
getComponent("xContent").setValue(newTxt);
}
//cleanup the temporary result document
retDoc.removePermanently(true);
The agent does not have to be located in the same database as the XPages application. So you can for example leave all LotusScript code in one database together with the application data and develop the new XPages based UI in a separate one.
We are using a Java Map to pass three string values to the agent: one with the current textbox content and two other values with the location of a temporary document in which we expect the agent's result.
When the agent execution is done, we reload the result document (retDoc), grab the new content for the textbox and update the XPages UI.
The agent parameters are passed to the agent via the DocumentContext document. The agent displays the Form "dialogBox" as a dialog box by using the method NotesUIWorkspace.Dialogbox and writes the edited text back into the result document.
Option Public
Option Declare
Sub Initialize
On Error GoTo errHandler
Dim session As New NotesSession
Dim db As NotesDatabase
Dim ctxDoc As NotesDocument
Dim ws As New NotesUIWorkspace
Dim result As Variant
Dim retdbpath As String
Dim retdocunid As String
Dim retdb As NotesDatabase
Dim retdoc As NotesDocument
Set db=session.Currentdatabase
'the DocumentContext document contains parameters passed to the agent
Set ctxDoc=session.DocumentContext
'the path of the local temporary database and the unid of
'the document that should receive the new value are passed
'into this agent via the documentcontext doc:
retdbpath=ctxDoc.retdbpath(0)
retdocunid=ctxDoc.retdocunid(0)
'Display the dialog
result=ws.Dialogbox("dialogBox", true, true, false, false, false, false, "Dialog box",
ctxDoc, true, false, false)
If result=True Then
'write new text into the result document
Set retdb=session.Getdatabase("", retdbpath)
Set retdoc=retdb.Getdocumentbyunid(retdocunid)
retdoc.content=ctxdoc.content(0)
retdoc.save True, False
End If
Exit sub
errHandler:
MsgBox "lsDialogAgent: "+Error()+" in line "+CStr(Erl())
Exit sub
End Sub
The sample application can be
downloaded
here.