Domino Name Picker Revisited

Jake Howlett, 26 June 2006

Category: Forms; Keywords: names picker address

Out of necessity, I recently revisited a common requirement of Domino browser-based applications — "Name Pickers".

I needed a name picker for a project I was working on. After looking through the various solutions available I couldn't find one I felt comfortable using, so I decided to write my own.

What I tried to move away from is the adopted convention that a Name Picker must, for some reason, be a popup window. I've also done away with the notion of a textarea being a suitable place to visually render the chosen list of names. It's all very well giving the user a nice to way to add names, but what about when they want to remove them? Both are equally important tasks. Do they have to carefully select the name in the field and delete it manually? Instead of a field I've used a table with a delete link. The field itself is hidden.

The Problem

Domino has always been based around its central directory. Generally speaking, this address book contains all the names of people within the organisation concerned. Most applications within the organisation need a way for users to select names from this list. In the Notes client it looks like this:

When Domino came about and Lotus ported their templates to the browsers they came up with a way of mimicking this feature in the browser. The trouble is they tried too hard to mimic it and didn's stop to think whether it really should be exactly the same. The result looked something like this:

Ugly init.

Popup=bad?

The Solution

Avoiding popups I decided to try and bring the idea uptodate with a more DHTML Web-2y look and feel. In the form below there's a names field. Next to it is a people icon. Clicking on this brings up the yellow "dialog" you can see. Typing in a name fetches matches entries from the (configured) Address Book. Clicking on a name returned adds it to the list.

Note the lack of popups and page refreshes. It's all done using Ajax. Something users are growing accustomed to. No room now for ugly time-consuming methods. Got to be fast and funky.

The Code

The actual code used isn't what we're interested in here. If you curious how it works behind the scenes you can always take a look for yourself. All I want to talk about here is how to implement this solution to your applications.

First thing you'll need is to download NamePick.nsf from this article. Now copy the following design elements in to your target database:

Element Type	Element Name
Page	css/namepick.css
Subforms	NamePicker
Script Library	js/NamePicker.js
Images	images/.
File Resource	lib/prototype.js & util/effects.js

Now open the Form you want to use a name picker in. Somewhere on it, insert the NamePicker subform. Now, in the form's HTML Head Contents add references to all the required files, so that the HTML ends up looking like this:

<script type="text/javascript" src="lib/prototype.js"></script>
<script type="text/javascript" src="util/effects.js"></script>
<style type="text/css" media="all">@import url(css/NamePick.css);</style>
<script type="text/javascript" src="js/NamePicker.js"></script>

You now have everything you need to get it working. Next step is to make configuration changes. To do this, open the NamePicker subform, which looks like this:

For most cases you can leave it the same. Making changes should be obvious.

All you need to do now is add a little icon next to your names field to call the dialog. Easiest way to see how is open the "Demo" form. Icon links look like this:

The important part is the call to NamePicker.open() in the onclick event. This could of course equally well be the onclick event of a button or any HTML element for that matter. The bit you need to worry about is the third argument, which is the name of the field you want to pass values back to. The fourth option is the type of name selection - single, multi or table, each of which you can see in action in the Demo form.

Version 1.5

Updated 6/3/07: The App is now at v1.5, which means:

Uses most up-to-date "protaculous" libraries.
List of returned names uses a list instead of a table.
Works with either XML or JSON (config option {OutputFormat:'JSON'})
Code tidy up, Use DOM builder methods instead of creating strings.
Demo points to 40,000 entries in fakenames.nsf

Enjoy. More to come...