.Domino Framework

LotusScript is a dialect of the BASIC programming language.  Version 1.0  of LotusScript was released in 1993 as part of a new spreadsheet product called Lotus Improv.  LotusScript 2.0 added the ability to work with Notes applications and formed part of Lotus Visual Programmer (ViP).  ViP was designed as a competitor for Visual Basic, which had been released by Microsoft in 1991.   ViP was eventually discontinued as a stand-alone product and we saw LotusScript 3.0 added to Notes 4.0 in January 1996.  At this time LotusScript required the use of the "C API" to access Notes data.  In October 1996 Microsoft launched VB4,adding the ability to define custom classes, effectively making BASIC an Object Oriented Programming language.  In December 1996 Notes 4.5 was released adding the ability to create LotusScript libraries and providing 26 product classes that allowed direct access to Notes data.  At this time both Visual Basic and LotusScript were comparable products.  As discussed  last week in Part 1 Lotus/IBM continued to provide significant enhancements to the LotusScript language as part of Notes R5 (1999) and Notes 6.0  (2002).

In April 2003 the landscape of BASIC programming changed when Microsoft introduced VB.Net as part of its .Net Framework.  A new programming language (C#) was also developed as part of the .Net framework, but Microsoft also updated its VB language to allow devoted BASIC programmers an easy way to migrate to its new development platform.  This stragey seemed to work.  In Part 2 I contrasted the approach being taken by IBM who seemed to focus its effort post 6.0 on building a competing product for Lotus Notes called IBM Workplace.  Notes 8.0 provided some extensions but Notes 8.5 now looks like being the first release of Notes in which no extensions of the LotusScript language are provided and the promised Eclipse LotusScript Editor is also missing.  This is all comes despite the fact that LotusScript remains the core programming language for most Notes development.  Java has now been added as an alternative but it is still not implemented fully and does not have the same following as LotusScript.

I blogged last month about some of the things I would like to see added to the LotusScript language.  Many of these have been posted by me and others on IdeaJam.  But whilst there is little that can be done to extend the LotusScript language, the good news is that we as Notes developers can use the LotusScript language that we already have to fill in many of the gaps that exist in the product classes such as NotesDatabase and NotesDocument.  This uses the Object Oreinted Programming capabilities of Lotuscript to extend the existing product classes allowing us to add new properties/methods and even create new classes.  The following techniques will work for Notes 4.5+.

1) LotusScript Library
Create one (or more) LotusScript Libraries to hold your code.  Options include having one LotusScript library for all the new classes, or having a separate LotusScript library for each class.  The new classes can then be introduced to your Notes application via the Use statement.
Examples:
Use "BleedYellow" or Use "BleedYellow.BleedYellowDocumentCollection"

2) Create New Classes
Create one or more new classes.  It is suggested you chose names for your new classes that are derived from the product class being "extended" (e.g. DominoDocument, NotesDocument2, SuperNotesDocument).  Because LotusScript presently does not allow us to extend product classes directly we need to create new classes from scratch that include rather than extend the base class.

Example:
The NotesDocumentCollection class could be extended as follows:-

Class BleedYellowDocument Collection

  Public Documents As NotesDocumentCollection

  Sub New(Source As NotesDocumentCollection)
    Set Documents = Source
  End Sub

End Class

Note: If LotusScript supported direct extensions of product classes the above code could effectively be replaced with:-
Class BleedYellowDocumentCollection As NotesDocumentCollection
End Class

3) Make Base Object A Property
While the example above works, OOP principals require that Properties be used instead of exposing public variables directly.  This allows you the ability to wrap additional logic around the object at any time, such as validation, without exposing any changes in the interface to consumers of the class.

Class BleedYellowDocument Collection
  Private iDocuments As NotesDocumentCollection
  Sub New(Source As NotesDocumentCollection)
    Set iDocuments = Source
  End Sub
  Property Get Documents As NotesDocumentCollection
    Set Documents = iDOcuments
  End Property
  Property Get Documents As NotesDocumentCollection
    Set iDocuments = Documents
  End Property
End Class

4) Extend The Constructor
One of the first extensions that can be applied to a class is the options for the constructor.  By always making the single parameter to a the constructor a Variant it becomes possible to pass a wide range of objects to the constructor, including arrays and lists.  In a way this overcomes one of the weaknesses of LotusScript, the inability to overload a method.  The TypeName statement can be used identify the type of object being passed.

  Sub New(Source As Variant)

    Dim Doc As NotesDocument
    Select Case TypeName(Source)
      Case "NOTESDOCUMENTCOLLECTION"
        Set iDocuments = Source
      Case "NOTESDATABASE"

        Set iDocuments = Source.GetProfileDocCollection("passingkeythatdoesnotalreadyexist" )
      Case "NOTESVIEW"

        Set iDocuments = Source.Parent.GetProfileDocCollection("passingkeythatdoesnotalreadyexist" )

        Set Doc =  Source.GetFirstDocument
        While Not Doc Is Nothing
         Call iDocumentCollection.AddDocument(Doc)
         Set Doc = Source.GetNextDocument(Doc)
       Wend
      Case "NOTESDOCUMENT"

        Set iDocuments = Source.GetProfileDocCollection("passingkeythatdoesnotalreadyexist" )
        Call iDocuments.Add(Source)
      Case "OBJECT"

        Set iDocuments = Session.CurrentDatabase.GetProfileDocCollection("passingkeythatdoesnotalreadyexist" )
    End Select
  End Sub

Applying the above code....

Set Collection = New BleedyellowDocumentCollection(Nothing)            ' Create empty document collection in current database

Set Collection = New BleedyellowDocumentCollection(DB)                     ' Create empty document collection in DB

Set Collection = New BleedyellowDocumentCollection(Doc)                    ' Create document collection with single document Doc

Set Collection = New BleedyellowDocumentCollection(DB.Document) ' Create document collection with all documents in database DB

Set Collection = New BleedyellowDocumentCollection(View)                  ' Create document collection with all documents in view View

5) Add New Properties/Methods
Build out your new class by adding additional properties/methods (Note: The OOP term Method = Sub/Function in LotusScript).  You can also rewrite the logic of the product class by adding code to the new extended class.

Example: A new Add method could be developed that provides a much wider range of options for what is added to the collection.  Passing a NotesView could add all document in that view to the collection.

Sub Add(Source As Variant)
  Select Case TypeName(Source)
    Case "NOTESVIEW"
.. code to add documents in view
  End Select
End Sub

6) Using The New Class
The properties/methods of the base class can be accessedd via the base object.  The new properties/ethods are accessed via the new class.

e.g.

Dim UIW As New NotesUIWorkspace
Dim Collection As BleedYellowDocumentCollection
Dim Favorites As NotesView

Set Collection = New BleedYellowDocumentCollection(UIW.CurrentView) ' Create collection with document selected in view
Call Collection.Document.Add(Doc) ' Adds document to collection using existing NotesDocumentCollection method
Call Collection.Add(Favourites) ' Adds all the document in the Favourites folder the the collection using the new enhanced Add method

.Domino Framework
The .Domino Framework provides a large number of examples of the above in practice.  A lot of the code is found in a LotusScript library base.Domino.Application.  This library provides 100s of new properties/methods for classes such as DominoDatabase, DominoView, DominoDocumentCollection, and DominoDocument.  You can use these classes directly or take parts of the code to build your own custom classes.  So don't just wait for IBM to take the lead, If you are not already doing so, start building your own custom classes to fill in the gaps needed by your applications.