Release 8.5.1 is for LotusScript developer everything he could ever hope for. Specially if you are into OO programming. Finally you don’t have to check your old classes what parameters they take, you can easily locate them by going to class definition and helper works. Now, you have really no excuse to start OO development in LotusScript.

On the other hand, 8.5.1 introduced some strange bugs. My colleague found an interesting bug while editing forms. For some reason, formula wasn’t saved when the document was. I think he solved it by removing formula completely and then re-pasting it back. Another funny thing is code formatting. Still not working properly. Hope to see it solved in 8.5.2.

Don’t get me wrong. I take 8.5.1 over any release any day.

Are Notes really built for Java? Because at this point it certainly fails to look so.

Not a good idea. I don’t know, when was the last time, someone at IBM took a look at their rendering engine, but this just isn’t it. Unordered lists don’t close, leading to a total mess of your layout. On numerous occasions, a div tag marked as pass through text got put to the bottom of contents and not at the spot where it was in the body field, leading to some more confusion. And what killed it for me was a sudden br tag flood in the HTML for no apparent reason. All 6 of them were gone when text was put in the same line as pass through text and appeared right after I put the text back in new line. And all of this appeared randomly, which amused me for a while.

So, I guess it is no wonder, why there are so many CMS application in Notes, where content needs to be entered as HTML. However, in my experience, you as a developer or admin of such system can be glad if a content editor knows how to use Lotus Notes.

For those of you who are still not sure weather to go or not… Go. It is not that difficult. But first learn a thing or two about Composite applications, DXL import/export and new document collection methods.

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

First step

In order to ensure that content editors could alter sidebars by itself, they had to be moved from design elements to documents. All fine and well. However, if you look at typical sidebar, it is assembled from multiple parts called widgets. This widgets can be e.g. adverts, link boxes, etc. Now, I wanted to achieve as much modularity as I could and there used to be quite a lot of sidebars, containing same widgets (not all, but some). So why force a user to create same thing multiple times? Thus, widgets came to be.

Widgets

Widget (in this case) is the smallest single component that can be displayed in a sidebar. This can be a simple image, or a complex linkbox. Widget in Notes database is a simple document containing descriptive name, short web name and a rich text field. This rich text field contains content for the widget. It can be pure notes content or it can be HTML, that CSS will change into something “edible”.

Simple, and easy. However, what you now don’t want, is for users to link multiple widgets into web content documents. For one, content of sidebars is usually content related, meaning that web pages on same topic will probably have same widgets. And it has to be user friendly if you want users to use it. So, you can’t expect users to be comfortable with a feature that gives them more work if they decide to change something. And here is where Sidebar documents come in handy.

Sidebar documents

Sidebar document is nothing else but a container of widgets. What I did was enabled user to choose widgets he wants in this sidebar and he/she can sort them however he/she sees it fit. Sidebar document also contains a rich text field that will contain content of specified widgets rich text fields.

Subform

Now, that I had sidebar documents created, there is one thing I could not avoid. I had to create a subform, which I can include on each web form there is. This subform includes a rich text item and some HTML. On the plus side, you now only need one subform for all sidebars.

What does this bring me?

Well, besides the fact that users will now be able to do their own sidebars and have an easy way to change it’s contents (which means less work for you), this organization also gives you one powerful feature. All computed values and hide formulas that you will specify in widgets will be recalculated once they are displayed as part of the document and displayed on web. Thus, you can i.e. add a computed value that computes from a field on web page form and will compute correctly when displayed on web page.

But why would I need that?

As you can see from the above examples, you can implement Java functionality to your LotusScript code. This can be good if your Java programming skills aren’t that great or you already have some code in LotusScript and you wish to add functionality. For me, it would do fine in cases where I converted documents in a database to PDF on user request, or when I needed an agent to login user to notes via web in the background, or as I mentioned, when I needed to implement some functionality from other department in my already existing code. Instead, I re-wrote several agents into Java, which in the end didn’t prove to be that bad of a decision, but about that some other day.

But how do I do that?

There is a functionality called LS2J that does exactly that for you. If you will, you can imagine it as an adaptor for LotusScript that allows you to call Java classes. I will give you a small example. It is based on my user login class, although, there is really no code there to log in the user.

First you need to create/obtain a java library that does what you want. I named that library jclass:UserLogin.

public class CUserLogin {
   String m_strUsername;
   String m_strPassword;

   public void Initialize(String strUsername, String strPassword) {
      if ((strUsername.length() == 0) ||
          (strPassword.length() == 0))
         return;

      m_strUsername = strUsername;
      m_strPassword = strPassword;
   }

   public boolean run() {
      // add code that will perform auto-login
      return true;
   }
}

Then, I strongly suggest you create a LotusScript library, containing a class that will do actual Java to LotusScript conversion. Why? So you have to do it only once.
My script library called class:UserLogin is depicted below.

Uselsx "*javacon"
Use "jclass:UserLogin"

Class CUserLogin
	loginObj As JavaObject

	Sub New (strUsername As String, strPassword As String)
		Dim js As New JAVASESSION
		Dim loginClass As JAVACLASS

		Set loginClass = js.GetClass ("CUserLogin")
		Set loginObj = loginClass.CreateObject ()

		Call loginObj.Initialize (strUsername, strPassword)
	End Sub

	Function run() As Boolean
		run = loginObj.run()
	End Function
End Class

And that is it. Now all you have to do, is use this script library in your code. Where you need it. I created a simple agent that will pop-up a window with text depicting login success.

Use "class:UserLogin"

Sub Initialize
	Dim userLogin As CUserLogin

	Set userLogin = New CUserLogin ("test", "test123")
	If (userLogin.run()) Then
		Messagebox "Login succeeded"
	Else
		Messagebox "Login failed!"
	End If
End Sub