Lotus Symphony Documents "Hello World" in LotusScript

October 21 2009

To get started with the Lotus Symphony LotusScript API, let's write our first code sample - the ever popular "Hello World" sample.

To start, create a new button in a Rich Text field in a document. Change the code selection drop-down to "LotusScript" and enter the (Options) section. To begin, every time you want to use the Lotus Symphony LotusScript API, you need to call the LSX. You do that with the following code:

      %INCLUDE "symphonylsx.lss"

This tells LotusScript to load the Symphony LSX. It also enables LotusScript to do cool things like provide type-ahead for the custom LSX - even in buttons or in actions on a form or view.

Image:Lotus Symphony Documents "Hello World" in LotusScript

Now let's write some code. Go into the Click section of the button and enter the following:

      Dim application As SymphonyApplication    
      Set application = New SymphonyApplication

To begin, we are creating an application variable and setting it to the SymphonyApplication class. We then set that variable to a new instance of that class. So how did I know what the object model for the API is? In that Toolkit download that I talked about in my last blog, if you go into the lsxapidoc folder, open the Index.html file. Click the Document API Link.

Image:Lotus Symphony Documents "Hello World" in LotusScript

This gives you a complete roadmap for the Symphony LotusScript API for Documents. You can click on each class to get all of the properties, methods, and description of each class and some samples.

We are starting with SymphonyApplication. Think of this like the NotesSession class. You will call this class no matter which of the three Symphony applications you are using. You will not see anything on screen at this point. Symphony has loaded into memory. Next, we call the SymphonyDocuments class

      Dim documents As SymphonyDocuments
      Set documents = application.Documents  
     
We are defining and setting an instance of a class that defines the Symphony Application type. At this point, you will see Lotus Symphony load on your screen. Next, we set up a single document instance to work with:

      Dim document As SymphonyDocument
      Set document =  documents.AddDocument("",True,True)

Here, we have told Symphony to load a blank new document. The AddDocument method has the following properties:

Set
document = documents.AddDocument(Template, AsTemplate, Visible)

Since we are not using a template, we leave the first parameter blank. And since there is no template, you must set the AsTemplate property to True. The documentation will tell you that you can use True or False here when Template is blank, but trust me - use True. Otherwise you will crash Notes. I know by experience!. We are also setting Visible to true. This will display the blank new document within Lotus Symphony Documents in your Notes client. We then need to setup a range to work with:

      Dim range As SymphonyTextRange
      Set range = document.content.End

If you are not working with a named object, like a bookmark or table cell, you have to work with a range. Since this is a blank document, the easiest range to work with is the entire document. So after defining our range variable, we set the range to the entire document contents using the document.content.End property. There is nothing in the document, so this is really just getting the cursor location, but it will work for our purpose. Last, we enter some text:
     
      Call range.InsertBefore("Hello World")

Using the range.InsertBefore method, we enter our "Hello World" text. Here is the code in a copy and paste format:

%INCLUDE "symphonylsx.lss"

Dim application As SymphonyApplication    
Dim documents As SymphonyDocuments
Dim document As SymphonyDocument
Dim range As SymphonyTextRange
     
Set application = New SymphonyApplication
Set documents = application.Documents  
Set document =  documents.AddDocument("",True,True)
Set range = document.content.End
     
Call range.InsertBefore("Hello World")

Once you exit the button, save the Notes document, change to Edit mode; click the button. You should see this:

Image:Lotus Symphony Documents "Hello World" in LotusScript

You might have noticed that Symphony took a bit to load up. Leave the Symphony Document open and go back to the button. Click it again. You will notice that it is quite a bit faster. Symphony caches after the first load - and also uses a start-up procedure to speed itself up. In preference, you can set if this should load at startup. You can see that option here:

Image:Lotus Symphony Documents "Hello World" in LotusScript

If you click that, you will notice a process called soffice.exe loads at Windows startup. Here is a view of that from Windows Task Manager:

Image:Lotus Symphony Documents "Hello World" in LotusScript

If you disable that, the first time load will be significantly longer than without the startup pre-load. If you use Symphony regularly, I recommend you turn this on.

There you go - your first piece of Lotus Symphony LotusScript API code written!