AJAX Names Lookup on Lotus Notes

I've written a sample AJAX name lookup selection from names.nsf. It uses prototype.js for the AJAX request. Instead of using pop-up dialog, the example uses subModal. You can download the example here.

Script.aculo.us Cheat Sheet

Amy Hoy has put together a cheat sheet for Script.aculo.us

Using AJAX to generate view dynamically.

Lotus Notes view can be formatted using "$$ViewTemplate" form on the web. It can be display as normal HTML or Java Applet. Java Applet can be quite slow if users does not have good connection to the server or through Internet access. Using conventional way, every view action (collapse, expand, next, previous, etc) will refresh/reload the web view page.

Page reload can be reduced by using AJAX to retrieve view data. "ReadViewEntries" can be used to access view data in XML form. Refer to Lotus Designer Help for detail on "ReadViewEntries".

Example url to retrieve XML view data:
http://servername/db.nsf/myview?ReadViewEntries

Example XML data
<?xml version="1.0" encoding="UTF-8" ?>
<viewentries toplevelentries="2">
<viewentry position="1" unid="EF312582F4ACDD4448256EF9000BAC7D" noteid="926" siblings="4">
<entrydata columnnumber="0" name="Acronym">
<text>HSE</text>
</entrydata>
<entrydata columnnumber="1" name="Description">
<text>Health Safety and Environment</text>
</entrydata>
</viewentry>
<viewentry position="2" unid="71697069D0B0198148256F0A0014FD8A" noteid="942" siblings="4">
<entrydata columnnumber="0" name="$Acronym">
<text>CG</text>
</entrydata>
<entrydata columnnumber="1" name="Description">
<text>Consumer Goods</text>
</entrydata>
</viewentry>
</viewentries>

From the XML document, you can traverse the structure and build your view. You can get the "viewentry" and then the "entrydata" from the XML. I will go in more detail example of building simple table from the XML in later write up.

To build a view, create a HTML Form. Insert a <div> area where the view is going to be display. Create the necessary buttons for the view actions (Collapse, Expand, etc).

<div id="viewtable"></div>

On form load, make a xmlhttp call to retrieve the xml data (eg. using prototype.js - refer to this)
In the form, onLoad:
getView("http://servername/db.nsf/myview?ReadViewEntries");

In the JS Header

function getView(url){
var myAjax = new Ajax.Request(
url,
{
method: "get",
onComplete: displayView
});
}

function displayView(xmlDoc){
var viewtable = xmlDoc.responseText;
//do your processing to build the view table
var viewentry = xmlDoc.responseXML.documentElement.getElementsByTagName("viewentry");

//display the XML in the "viewtable" div (replace this with your custom design view HTML.
$("viewtable").innerHTML = viewtable;
}

Then for every view action, you can call the getView() function with the appropriate url parameters.
For example to collapse the view, create a collapse button. OnClick
getView("http://servername/db.nsf/myview?ReadViewEntries&CollapseView");

So using this way, you can dynamically get the view data and build the view onto the page without refreshing the page.

Using AJAX to run LN agent from web

Sometimes we need to run an agent to process certain field in our web form. For example, when user select a name, you want to retrieve their company information. In Lotus Notes, we can use on "Refresh fields on keyword change". This works but it will do a document refresh. If you are working on a large form, it may take sometime to reload the form.
We can avoid the page reload by using an AJAX call to the agent. Prototype.js made calling an AJAX function easier.

var myAjax = new Ajax.Request(
"http://www.server.com/db.nsf/getDetail?OpenAgent",
{method: "get",
parameters:"name=myname",
onComplete: processValue
});

function processValue(xmldoc){
alert(xmldoc.responseText);
//processing
}

This would call the Agent "getDetail" in db.nsf using "GET" method. You can pass parameters from the current website. When the AJAX call completes, it will call the function processValue(). You can process the return values (in XML or other format).

On the "getDetail" agent, you can retrieve the parameter and do your processing.

Sub Initialize
Dim session As New NotesSession
Dim doc As NotesDocument
Dim param as String

Set doc = session.DocumentContext
'get the parameters
param = doc.Request_Content(0)

Print |Content-type:text/xml|
Print |<?xml version="1.0" encoding="UTF-8"?><data>|
'Do your processing and return the value..
'eg print |<company>company name</company>|
Print |</data>|

End Sub

Your agent can return just plaing text. Or from the example above, it returns a xml document. DOM can be used to retrieve the data in the XML document. You can specify in the agent what type of content-type to return, in this case, "text/xml".w
Print |Content-type:text/xml|

There's a lot of article comparing the use JSON (JavaScript Object Notation) vs. XML. I will go into more detail use of JSON instead of XML.

$F() function

$F() returns the value of any field input control (e.g. text boxes or drop-down lists). The function $F() can take as argument either the element id or the element object itself.

In Lotus Notes, when you create a field, it will only generate the fieldname.
eg <input type="text" name="Name" value="my name"/>

When using $F("Name") to retrieve the value, it works on IE but not on Mozilla. To get it working cross browser an id need to be inserted.

At the Field Property 'HTML' tab, key in the Name of the field into the 'ID'. This would create
<input type="text" name="Name" id="Name" value="my name"/>

Prototype in Lotus Notes

Prototype have been getting a lot of headlines for web 2.0 application. I've started to used it and got hook on it. Before you start, you can take a look at this Developer Notes for prototype.js.

To use it in Lotus Notes (LN), import the prototype.js into the File Resource. Then in your Form or Page 'HTML Head Content' add the line below.

"<script src='/"+@WebDbName+"/prototype.js'></script>"

Now you are ready to use the function in Prototype.

Welcome to Lotus Notes on Web 2.0

I've been working on a Lotus Notes web application. Prototype and script.aculo.us. I will share some of my experience here in this blog so watch out for future posting.