The intention of the The Builder pattern is to abstract steps of construction of objects so that different implementations of these steps can construct different representations of objects.

Huh?

The best way to explain how builder pattern works is to look at the example. Imagine you have to build product presentation for a company that sells built PCs. For clarity’s sake, let’s pretend that they sell only two types of computers. One for basic office needs, running Linux OS and one for pro gaming needs running Windows.

Let’s go!

First, you need a product class. This class will be able to store product type, add components and display itself when needed. This allows you to build product with as many components as needed.

Class CBuilderProduct
	Private m_strProductName As String
	Private m_strLParts List As String

	Sub New (productName As String)
		m_strProductName = productName
	End Sub

	Sub Add (part As String, desc As String)
		m_strLParts (part) = desc
	End Sub

	Sub Show ()
		Dim strDisplay As String

		strDisplay = "Product: " & m_strProductName
		Forall part In m_strLParts
			strDisplay = strDisplay & Chr(13) &_
                      Listtag (part) & ": " & part
		End Forall
		Messagebox strDisplay
	End Sub
End Class

Next, you need a builder class. This is an abstract class, only specifying methods and variables used by end product classes that inherit from it.

Class CBuilder
	Private m_Product As CBuilderProduct

	Property Get Product As CBuilderProduct
		Set Product = m_Product
	End Property

	Sub AddOS()
	End Sub

	Sub AddPC()
	End Sub
End Class

Now, you are ready to create real product classes. In our case, this classes will represent Basic and Pro products.

Class CBuilderProductBasic As CBuilder
   Sub New()
      Set m_Product = New CBuilderProduct ("Basic Package")
   End Sub

   Sub AddOS()
      Call m_Product.Add ("Operating system", "Fedora Core 10")
   End Sub

   Sub AddPC()
      Call m_Product.Add ("Computer", "Basic home computer")
   End Sub
End Class

Class CBuilderProductPro As CBuilder
   Sub New()
      Set m_Product = New CBuilderProduct ("Pro Package")
   End Sub

   Sub AddOS()
      Call m_Product.Add ("Operating system", "Windows 7")
   End Sub

   Sub AddPC()
      Call m_Product.Add ("Computer", "Pro gaming computer")
   End Sub
End Class

You are almost done. But first, you need a catalogue (or shop) class. This class will actually contain algorithm for building desired products. Beware that builder parameter of Create method must be of type Variant (it should be CBuilder) or you will get an error while compiling your code that will use this design pattern!

Class CBuilderCatalog
	Sub Create (builder As Variant)
		Call builder.AddPC()
		Call builder.AddOS()
	End Sub
End Class

To test the code, I wrote a simple agent that simply outputs two message boxes. One for each product.

Sub Initialize
	Dim builder As CBuilder
	Dim shop As CBuilderCatalog

	Set shop = New CBuilderCatalog ()

	Set builder = New CBuilderProductBasic ()
	Call shop.Create (builder)
	Call builder.Product.Show()

	Set builder = New CBuilderProductPro ()
	Call shop.Create (builder)
	Call builder.Product.Show()
End Sub

First, we need to assmble list of fields user needs to add. Each field usually has a label that describes to a user what information should he enter. Then, some fields are plain text, rich text, checkboxes, etc. Also, fields can have a default value.

Keeping that in mind, a basic web form usually has a field named $$Return, that specifies what happens on document submit. Also, it would be nice, if we allowed our users to enter name of the form and some short description that will be presented in web form.

The implementation

For basic forms, we don’t need anything fancy. No rich text for short description, probably only simplest field formats (plain text, rich text, radiobutton and checkbox) and probably not more than 10 fields. Since this example is here just to prove a case, I will limit it to 5 different fields.

So, our list of fields now looks like this:

• form name
• form description
• return page
• 5x field that will hold field name
• 5x field that will be used for field type
• 5x field with value (in case of radiobutton and checkbox)
• 5x field with default value
• 5x field with label

The “finished” form is displayed in picture below.

Filled user's form

Absolutely nothing. The only connection to Lotus Notes is, when you integrate this functionality into your database. It is a simple and trivial solution. I needed to create a form that will represent one single banner. This form contains name, URL, image, sort order etc. Look-up view for obtaining sorted banner list was created and some web forms that are already in “production” had to be altered, for loading of JavaScript class etc.

Prerequisites

This functionality depends heavily on jQuery library. It can be obtained here. I recommend minified version if you plan on hosting it yourself or, you can use Google Code link to link it from Google.

Next you need to obtain the adPlayer library. It is located here. I would ask you to not link the library directly from this link, but download it to your server and link it from there.

Getting started

In order to implement this application, you will first need to make a small HTML adjustment in the place where you want banner animator to be implemented.

<ul id="adPlayer">
    <li><a href=""><img src="images/ad1.jpg" /></a></li>
    <li><a href=""><img src="images/ad2.jpg" /></a></li>
    <li><a href=""><img src="images/ad3.jpg" /></a></li>
</ul>
<div id="adPlayerNav"></div>

Obviously you should insert link of your desire. The same goes for image src and alt parameters. Also, number of li elements can vary.

Next, at the bottom of the page (where your JS libraries are loaded and on load events are set), you need to load both .js files (jQuery and AdPlayer) , if you do not already have them. Next, add following (or if you already have onload event loader, just call loadPlayer() function).

<script type="text/javascript" language="javascript">
    $(document).ready(function() {
        loadPlayer();
    });
</script>

Now add some style

It is necessary to add styling to content thus far. CSS excerpt below will give you some idea as to how you can style things. Beware that #adPlayer height property must be set to height of a banner space. Also, some tweaking to .js file will have to be done, but nothing major (this will definitely be changed in future releases).

/* layout */
#adPlayer { list-style: none; height: 220px; margin-left: 0;
margin-bottom: 0; overflow: hidden; padding: 0; }
#adPlayer li { margin: 0; padding: 0; }
#adPlayerNav { position: relative; top: -1em; right: 1em;
text-align: right; }
#adPlayerNav ul { list-style: none; margin: 0; padding: 0; }
#adPlayerNav li { display: inline; margin: 0 0 0 0.1em;
padding: 0; }
#adPlayerNav li.adPlay, #adPlayerNav li.adPause {
margin-left: 1em; }
#adPlayerNav li a { cursor: pointer; padding: 0 0.5em; }

/* typography */
#adPlayerNav li { font-size: 1.2em; }

/* color */
#adPlayerNav li { border: solid 1px rgb(213, 213, 217); }
#adPlayerNav li a { background-color: white; padding: 0.5em; }

You now have fully functional banner animator.

Optimization

Loading 3+ 50K+ images in the middle of the page can never be a good thing. Thus, adPlayer library has a dynamic mode that can be used. This mode loads images after the page is loaded, which is a good thing. However, you cannot leave your banner space empty until then. A compromise solution is to load first banner in-line and all others after the document is loaded. Your HTML file must now look somewhat like this:

...
<ul id="adPlayer">
    <li><a href=""><img src="images/ad1.jpg" /></a></li>
</ul>
<div id="adPlayerNav"></div>
...
<script type="text/javascript" language="javascript">
    $(document).ready(function() {
        loadPlayer( true );
        adplayer.add ("", "images/ad2.jpg", "");
        adplayer.add ("", "images/ad3.jpg", "");
        adplayer.generatePlayer();
    });
</script>

Loading loadPlayer method with true as parameter value will enable dynamic mode. Now you can add banners in desired sort order. First parameter is link, second image src and third image alt. After you are done, just call generatePlayer method.

Requirements

As mentioned, you will need a DXL file like the result of Part 1. Beware that, if you have altered the file and removed the DOCTYPE tag, you will not be able to import DXL and you will either need to add correct DOCTYPE tag back or export the form again.

The code

The code itself is pretty straightforward. You need to open a DXL file as a NotesStream object and then use NotesDXLImporter class to import a DXL to your database. There is a catch. You need to set DesignImportOption property of NotesDXLImporter object to create design element. These options are specified in Notes Designer Help.

Dim session As New NotesSession
Dim dbCurr As NotesDatabase
Dim docForm As NotesDocument
Dim stream As NotesStream
Dim dxlImporter As NotesDXLImporter
Dim strFile As String

Set dbCurr = session.CurrentDatabase
Set stream = session.CreateStream ()

strFile = "c:\download\templateform.xml"
If (Not stream.Open (strFile, "utf-8")) Then
   Exit Sub
End If

Set dxlImporter = session.CreateDXLImporter (stream, dbCurr)
dxlImporter.DesignImportOption =_
DXLIMPORTOPTION_REPLACE_ELSE_CREATE
Call dxlImporter.Process ()

Just in case you don’t want to check Notes help for values, here are DXL import options:

• DXLIMPORTOPTION_CREATE (1)
• DXLIMPORTOPTION_IGNORE (2)
• DXLIMPORTOPTION_REPLACE_ELSE_IGNORE (5)
• DXLIMPORTOPTION_REPLACE_ELSE_CREATE (6)
• DXLIMPORTOPTION_UPDATE_ELSE_IGNORE (9)
• DXLIMPORTOPTION_UPDATE_ELSE_CREATE (10)

How to get around…

I am positive that different developers would handle this differently. For sure, the easiest thing to do would be to add designer access to a person wishes to create a form. I would advise against it. Not only it creates severe security issue, but it also enables inexperienced user to poke about the database design.

I am positive every designer till now at least heard of DXL. Some of us even used it. I did it for exporting entire database to our internal wiki and to create atom rss for another database. However, most developers, in my experience, look at DXL as a bit of a Notes voodoo.

Let’s remove this tag!

In several parts, I will try to show how to export and import a simple HTML form that one can use on the web. Also at the very end, I will try to create a form that will enable a user with less than developer access to create a web form.

Onward, to the point – Exporting Form to DXL

It is quite simple. You create or already posses a form. For exporting it to DXL, you will need to know it’s name or you can enable for to be available in Create menu and add a shared action onto it, that will do the work for you. I decided for the later.

Form with shared action as viewed in Notes client

Figure above displays a simple form previewed in Notes client with shared action “Export form”in action bar. Upon clicking on this action, a file will be saved on your disk to path c:\download\my_form_name.xml. And below is the code that does all this.

Sub Click(Source As Button)
   Dim ws As New NotesUIWorkspace
   Dim s As New NotesSession
   Dim db As NotesDatabase
   Dim nc As NotesNoteCollection
   Dim doc As NotesDocument
   Dim docForm As NotesDocument
   Dim stream As NotesStream
   Dim dxlExporter As NotesDXLExporter
   Dim bFound As Boolean
   Dim n As Integer
   Dim strId As String
   Dim strFormName As String

   Set db = s.CurrentDatabase
   Set doc = ws.CurrentDocument.Document
   Set nc = db.CreateNoteCollection (False)
   nc.SelectForms = True
   Call nc.BuildCollection ()

   bFound = False
   strId = nc.GetFirstNoteId ()
   For n = 1 To nc.Count
      Set docForm = db.GetDocumentByID (strId)
      strFormName = docForm.GetFirstItem ("$title").values(0)
      If (doc.Form (0) = strFormName) Then
         bFound = True
         Exit For
      End If
      strId = nc.GetNextNoteId (strId)
   Next

   If (Not bFound) Then Exit Sub

   Set stream = s.CreateStream ()
   Call stream.Open("c:\download\" & strFormName & ".xml","utf-8")
   Call stream.Truncate ()

   Set dxlExporter = s.CreateDXLExporter (docForm, stream)
   Call dxlExporter.Process
   Call stream.Close ()
End Sub

1. If a code compiles and seems to work in first try, there is something terribly wrong with it.
2. Never, ever, under no circumstances, move anything in production on Friday.

I urge you not to break one of these rules, no matter how confident you feel and under no circumstances.

Let me tell you a little story. I have developed a new feature for our renewed web site. This was over two weeks ago and on test system, it was working like a charm. Everyone liked it and there was no bugs found. So, I moved my code to production system. All fine and well, as without content and proper linkage, this feature would not be visible to web users until we decided to allow it. As I said, the thing missing was a content. That wasn’t my job and I paid no heed to it. So on Friday, a co-worker assigned for content gave me a green light. Now, I was feeling overconfident and despite warnings in my head and by my fellow developers, I decided to go with it.

Big mistake. I spent next 4 hours (and some overtime as well), working feverishly to remove bugs that were result of the content. It is not that content was wrong, but rather that it was not tested enough. And for a cherry on a cake, I received a call from project manager on my way home. Apparently he wasn’t aware we are going live. Well not on Friday anyway.

Lesson learned. Never, ever, under no circumstances, move anything in production on Friday. Moving on.

The Observer pattern defines a one-to-many dependency between objects so that when one object changes state, all of its dependants are notified and updated automatically.

Fine, but what can I do with that?

We will build an above mentioned example of a stock and it’s investors. First, you will need to create an observer abstract class:

Class CObserver
	m_strName As String

	Property Get ObserverName As String
		ObserverName = Me.m_strName
	End Property

	Sub New (strName As String)
		Me.m_strName = strNAme
	End Sub

	Sub Update()
	End Sub
End Class

As you can see, it contains a name, which will be used as unique id, a constructor, where the name is set and subroutine called Update that will be called when new value of our stock will be set.

Now, that we have an observer, we can create a subject class that will be an abstract class used by our stock.

Class CObserverSubject
	m_oList List As CObserver

	Sub Attach (observer As CObserver)
	  If (Not Iselement (m_oList (observer.ObserverName))) Then
	     Set m_oList (observer.ObserverName) = observer
	  End If
	End Sub

	Sub Detach (observer As CObserver)
	  If (Iselement (m_oList (observer.ObserverName))) Then
	     Erase m_oList (observer.ObserverName)
	  End If
	End Sub

	Sub Notify ()
		Forall observer In m_oList
			Call observer.Update()
		End Forall
	End Sub
End Class

The class contains list of all investors (observers) and operations to add (Attach ()) or remove (Detach ()) them. There is also routine Notify, that will update each and every investor.

Framework is now set. Moving on to concrete classes. First, we will create a concrete subject class called ObserverStock.

Class CObserverStock As CObserverSubject
	m_strName As String
	m_dValue As Double

	Property Get StockName As String
		StockName = Me.m_strName
	End Property

	Property Get Value As Double
		Value = Me.m_dValue
	End Property

	Property Set Value As Double
		Me.m_dValue = Value
		Call Notify()
	End Property

	Sub New (strName As String, dValue As Double)
		Me.m_strName = strName
		Me.m_dValue = dValue
	End Sub
End Class

The class inherits from ObserverSubject class. Also, it has a property for obtaining stock name and properties for obtaining and setting stock value. However, when setting stock value, not only value is set, but there is also a call to Notify method, specified in ObserverSubject class. This will notify all subscribers of new value.

The only thing missing now is observer concrete class called ObserverInvestors.

Class CObserverInvestor As CObserver
	m_Stock As CObserverStock

	Property Get Stock As CObserverStock
		Set Stock = Me.m_Stock
	End Property

	Property Set Stock As CObserverStock
		Set Me.m_Stock = Stock
	End Property

	Sub New (strName As String)
	End Sub

	Sub Update()
		Messagebox Me.m_strName & ": " &_
		m_Stock.StockName & " value is " & m_Stock.Value
	End Sub
End Class

And it is simple enough. It needs a constructor with name as parameter (due to his parent class), a property that ties stock to the class and Update () function that will ideally send an e-mail to investors, but in this case just pops up a message with investor and stock info.

Usage of previous classes

To use previously stated classes, I wrote an agent that will create a stock, add three investors to it, and change value. Then, last observer will be removed from notification list and value will be updated again. When running this agent, you should first get three pop up messages and then only two.

Sub Initialize
	Dim observer As CObserverInvestor
	Dim stock As CObserverStock

	Set stock = New CObserverStock ("MyStock", 120.0)

	Set observer = New CObserverInvestor ("Investor 1")
	Set observer.Stock = stock
	Call stock.Attach (observer)

	Set observer = New CObserverInvestor ("Investor 2")
	Set observer.Stock = stock
	Call stock.Attach (observer)

	Set observer = New CObserverInvestor ("Investor 3")
	Set observer.Stock = stock
	Call stock.Attach (observer)

	stock.Value = 100.0

	Call stock.Detach (observer)
	stock.Value = 102.5
End Sub

• some sort of IDE with a compiler
• version control
• and bug tracking.

Usually you get stuck with IDE with a compiler. Everything else is up to you. But how are things in Lotus Notes?

Version control

As expected Lotus Designer doesn’t have an integrated version control software. Not yet anyway. They are planing to build subclipse to work in new 8.5 designer, but that still needs some time. Also most people are probably still stuck at R7.

Well, one of the things you could use is Teamstudio Ciao!. This is a payed software meaning that either it becomes your department policy to use it or you will never use it. I had a chance of working with Ciao and I have to say that I was less than impressed. But that is just me. I know a lot of people using it without any drawbacks and with lack of tools out there, this is probably the way to go.

Next widely used option is to use separate templates for each and every version of your application. There are two things wrong with this. One is that there is no way any developer would do a new template just for fixing one single agent. Second one is that I am yet to see a consistent template policy.

Another possibility is to copy your database locally and then import it into Subversion (SVN) or perhaps write a script that would periodically do that for you. The thing is that you won’t be able to just revert to desired version of the database without deleting the existing one. There is one other option. You could export objects (agents, views etc.) as DXL, import it into SVN and then when needed import DXL back to the database. However, DXL is not 100% representation of design elements. Thus I wouldn’t recommend it.

As mentioned there is a subclipse project that would enable subclipse in Domino Designer 8.5. Subclipse is Eclipse plug-in for Subversion. And since Domino Designer 8.5 is built on Eclipse framework, this would finally solve most of our version control issues.

Bug Tracking

Why bug tracking? Well, I am yet to see software without bugs. And the thing that helps the most is some sort of bug tracking engine. However, oddly enough, this is the part rarely seen and used. Typical bug tracking process should go like this:

• someone reports a bug
• developer is assigned to the bug
• developer fixes the bug
• third person (inside a company and related to project the bug was reported for) tests the fixed code
• bug report is completed.

Now, show of hands. How many of you have this process implemented in your development cycle? I thought so. But being a Notes developer, what are your options?

There is a great open source project at openntf.org called BugTracker. Another option is to use some commercial product like Trackersuit Help Desk Software or similar.

If you are not attached to domino apps only, there are tons of open source applications for bug tracking. Probably most known amongst them are Mantis BugTracker and Bugzilla.

The most inappropriate systems for bug tracking I have seen thus far are internal forum and wiki. These applications are not meant to be bug trackers. So, please, don’t use them as such.

The Adapter pattern converts the interface of a class into an interface the client expects. Adapter lets classes work together even if they couldn’t otherwise due to incompatible interfaces.

So how does this work in practice?

You will mostly need adapters when you will obtain code from someone else. But just for the sake of simplicity, we will look into unlikely scenario, when you will get a code that prints “Hello World!” and write an adaptor that displays “Hello adapters!” in message box using the same interface.

First you need a client class and it’s interface. As we know, interfaces are not implemented in LotusScript. Thus, an abstract class will be used instead. Then we’ll need a client class. Both are pasted below:

Class CHelloWorldInterface
	Sub printText ()
	End Sub
End Class

Class CHelloWorld As CHelloWorldInterface
	Sub printText ()
		Print "Hello World!"
	End Sub
End Class

Now, we need to create our interface that displays “Hello adapters!” in message box.

Class CHelloAdaptersInterface
	Sub msgboxText ()
	End Sub
End Class

Class CHelloAdapters As CHelloAdaptersInterface
	Sub msgboxText ()
		Messagebox "Hello Adapters!"
	End Sub
End Class

All we need now is an adapter.

Class CHelloAdpatersAdapter As CHelloWorldInterface
	m_helloAdapter As CHelloAdaptersInterface

	Sub new (helloAdapter As CHelloAdaptersInterface)
		Set Me.m_helloAdapter = helloAdapter
	End Sub

	Sub printText()
		Call m_helloAdapter.msgboxText()
	End Sub
End Class

And to bind it together, here is an agent that will output both results.

Sub Initialize
	Dim hw As CHelloWorld
	Dim ha As CHelloAdapters
	Dim haa As CHelloWorldInterface

	Set hw = New CHelloWorld ()
	Set ha = New CHelloAdapters ()
	Set haa = New CHelloAdaptersAdapter (ha)

	'test HelloAdapters
	Call ha.msgboxText()

	'test HelloWorld
	Call testHello (hw)

	'test HelloAdaptersAdapter
	Call testHello (haa)
End Sub

Sub testHello (hello As CHelloWorldInterface)
	Call hello.printText()
End Sub

Now, I didn’t want to create another form or change the existing one and there was way to complicated to do a computed value in rich text for table display. And we already had a web QOA for this type of document.So what did I do? I added following custom code to rich text field:

<$$myTable>

But how would that do you any good?

Now all I had to do is add the following code to QOA:

Dim rti As NotesRichTextItem
dim rtr As NotesRichTextRange
...
Set rti = docWeb.GetFirstItem ("Body")
Set rtr = rti.CreateRange
Call rtr.FindAndReplace ({<$$myTable>}, strHtml)
Call rti.Compact ();
...

First I obtain a Rich Text field where my identifier is. Then, I created a range and used FindAndReplace method to replace identifier with HTML (stored in strHtml variable), that will display required table.

That is all?

Yes. Mind you, there is a catch. All in-line images in Rich Text field will not display on web. Image resources will display normally.