Domino Name Picker Revisited [ROUGH CUT]

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.


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 TypeElement Name
Script Libraryjs/NamePicker.js
File Resourcelib/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...


  1. Don't forget your IFrame shim..

    Not sure if it is my non-standard Domino install, but when tested with IE, the div layer does not cover other drop down controls. The old "Iframe shim" hack can help.


      • avatar
      • Jake Howlett
      • Tue 27 Jun 2006

      Re: Don't forget your IFrame shim..

      Nothing to do with Domino Jeff. It's a bug in IE. Although setting the DominoCompleteDocType ini param might have an effect (not sure though). I'm reluctant to add hacks to my (dare I claim it) elegant solution, just to fix a bug in IE. Alternatively you could change the code to open the picker above the icon that launched it. Or open it "inline" so it doesn't float over anything. Have you got an example page where this happens?

      Show the rest of this thread

  2. Alternative to DbLookup?

    This would work as an alternative to the typical DbLookup technology...except for not being able to see the choices ahead of time.

    Any ideas on how to use this for that functionality? Obviously, seeing the choices would be critical.

  3. Error in HTML Head code

    I think in your HTML head code above, you meant to refer to util/effects.js instead of util/scriptaculous.js. When I made the switch, it worked perfectly for me.

      • avatar
      • Jake Howlett
      • Thu 6 Jul 2006

      Re: Error in HTML Head code

      Thanks Chris. Fixed now. I'll use the fact that it's a "rough cut" as my get out clause ;o)

      Show the rest of this thread

  4. R5 deployment

    Hi Jake,

    I am trying to implement this in R5. Running into some issues though! I get a javascript error that NamePicker is undefined.( I am still wading my way through javascript) Here is how I reference the files in the Head: "<script src=\"/" + DBPath + "/prototype.js\"></script>" + @NewLine+ "<script src=\"/" + DBPath + "/effects.js\"></script>" + @NewLine + "<script src=\"/" + DBPath + "/NamePicker.js\"></script>" +@NewLine+ "<link href=\"/" + DBPath + "/NamePick.css\" rel=\"stylesheet\" type=\"text/css\">"

    All fo these are now in pages and not the original R6x format. Any help welcome...



      • avatar
      • Jake Howlett
      • Tue 11 Jul 2006

      Re: R5 deployment

      Hi Jakes

      Have you made sure the pages have their content-type set to application/x-javascript ??


      Show the rest of this thread

    1. Re: R5 deployment


      Using pages to hold the javascript did not work for me either. I tried to copy all scripts to the JS Header section of the CommonField subform. And the app works in R5 smoothly.

      CSS files may be put in pages.

      However, R5 has a difficult time saving the subform with the large amount of javascript, I save the modified subform in R6 instead.

      Show the rest of this thread

    • avatar
    • Leo Dai
    • Wed 12 Jul 2006

    Scroll bar not visible


    How to adjust the IE browser so that the scroll bar for the name picker will be visible?



      • avatar
      • Jake Howlett
      • Wed 12 Jul 2006

      Re: Scroll bar not visible

      Hi Leo.

      Not sure exactly what you trying to do, but this might do it; add the following CSS to the style definition for the picker div:



      Show the rest of this thread

  5. Focus


    Great work, I'm attempting to integrate this into some code I'm working on already!

    One question though, how to I make the focus shift automatically to the "q" field in the NamePicker subform when it is displayed??

    I'd like users to be able to click on the "add user" icon, then start typing immediately, without having to click in the field first.

    Any help appreciated - thanks.

    Cheers, Paul

      • avatar
      • Jake Howlett
      • Sat 15 Jul 2006

      Re: Focus

      Hi Paul. This is on my to-do/wish list as well. There's a problem with focusing on fields that are hidden, so we need a way to call focus() only when opening has finished. There's no postopen event though ;o)

  6. Mozilla problem

    Sensational date picker Jake. Got it working perfectly in IE but in Mozilla after searching for a name, the names appear but then when you click on a name nothing happens. any ideas on how to overcome this? thanks in advance

      • avatar
      • Jake Howlett
      • Mon 17 Jul 2006

      Re: Mozilla problem

      Hi David,

      Does the unaltered db you downloaded work on your server in Mozilla? It could be that your server isn't in "standards mode" and that;s affecting the behaviour.

      Try that first and we'll take it from there.


      Show the rest of this thread

    • avatar
    • jay
    • Fri 21 Jul 2006

    NamePicker settings

    Hi Jack,

    I have a form with a "Community" and "Members" fields. Now the Community field needs to do a lookup on one view, and a certain column while the "Members" field uses a completely different set.

    I have made a few changes/additions to your NamesPicker.js so that for "Community" field I do something like:


    and similarly for the "Members" field with different parameters.

    It works fine but perhaps you can implement it elegantly in your article - i.e if not done already or if there are no 'gotchas' in this approach.


    1. Re: NamePicker settings & changing speeds


      Thanks, Jake for the script, and Jay for the suggestion of passing parameters. It works great!

      I'm curious... where can we change speeds of the opening and closing of the dialog? Is there a way we can speed it up? I've tried a couple of things in the "Effect.SlideDown" and "Effect.SlideUp", but haven't been able to do it. =8(

      Thanks & keep up the good work!


      "It hurts to be on the cutting edge."

      Show the rest of this thread

  7. Notes Client.

    I love this namepicker. I would love to use it as my standard picker interface for both Web and Notes Client apps. Just to provide a consistent look and feel. However I have not had any luck getting it to work in the Notes Client. Any ideas?

      • avatar
      • Jake Howlett
      • Thu 3 Aug 2006

      Re: Notes Client.

      Hi Anthony,

      I doubt you can use the same code in web and client. You could probably mimic the look/feel of the web widget in the client though and use different code.


      Show the rest of this thread

    • avatar
    • Srini
    • Sun 20 Aug 2006

    Name picker problem

    Let me first say that this Name picker is really cool. I am facing a problem,I designed a subform with couple of Names fields that use the name picker.The name picker subform itself is in this new subform. I put the subform I designed into a form. When I open just the form in the web,the name picker works great.

    But when I create a document using the form,save the document and then edit the document in IE, the user_add.gif does not show up,I also tried to put the Namepicker.open in a button and nothing happens when the button is clicked.

    Can you help?


      • avatar
      • Jake Howlett
      • Mon 21 Aug 2006

      Re: Name picker problem


      Sounds like the path for the image might be wrong. Make sure you have the BASE href tag in the head, like in the example.


      Show the rest of this thread

  8. I have a name picker here that works ok

    I have some examples of dialog boxes that I have been using this for about a year now:

    http://jasonhoward.dominodeveloper.net/jasonhoward/webaddressbook.nsf/dialogboxl auncher.htm

    they use the AJAX design pattern?? to talk to a java agent which in turn looks up the NAB

    It only has about 5 names (made up ) in the address book. Its a demo only and runs on a dev server. Works well on a LAN my not ideal be ideal for slower connections like the web.

    For slower connections/larger address books I would include a search button to trigger the search query.

      • avatar
      • Jason
      • Sun 27 Aug 2006

      server has been down for long time

      sorry server has been down for quite a while now here is an alternate location

      http://jasonhoward.dominohosting.biz/jasonhoward/webaddressbook.nsf/dialogboxlau ncher.htm

  9. Does not work with large Domino Directory


    looks great! I got it to work with a small address book but when I tried with a big one (about 70K docs in ($VIMPeople) view), nothing happens when I type (the rotating image shows up so it's trying to do something). The view is indexed so it's not the indexing delay.

    I may try to find the problem myself if I have time but thought I'd report it here also.



    1. Now it works on a different server

      I guess there was something wrong with the first address book or server I tried with.

  10. Use within login page

    Hi you all, This tool is great

    I wonder if I can add this feature in the login page (domcfg.nsf) so that, when a user start typing a username in the <username> field, the list shows up.

    regards Andrea

      • avatar
      • Jake Howlett
      • Tue 5 Sep 2006

      Re: Use within login page

      Hi Andrea,

      This might depend on the ACL of the address book. If it was open to public access then it will be fine. If not you would need to use an agent signed by a person with access.

      In theory though, it should work.


      Show the rest of this thread

  11. Very nice...

    I modified slightly to do lookup by last name. Works great, easy to use, modify, maintain...

    1. Thanks so much!


      You again solved a problem that one of my customers had before I knew they had it!

      Thanks again for this fantastic piece of work.


  12. LotusNotes

    I want the code to put the response documents in the folder or view by usin lotus script in the lotus domino

    • avatar
    • KV
    • Thu 15 Mar 2007

    JSON Not working


    This is really a great tool, I have some challenges. JSON is not working but when I change it to XML it works any idea where I am missing something. Thanks.

    Cheers KV

    1. Re: JSON Not working

      I think I may know the reason why it is not working. You should update your Domino to 7.0. The OutputFormat=JSON cannot use in Domino6.0 or 6.5.

    • avatar
    • TomW
    • Thu 3 May 2007

    Return value

    Hi Jake,

    Very useful article as always. I wonder if you know a way to do the lookup by last name, but return the abbreviated notes name <fname lname/ou/ou/o> to the field. From what I understand, you do the lookup on the column specified in the NamePicker.init, but you also return the value from that column. If it could be changed to return another column from that view, I would be helped - but I don't know how to do that myself.

    Any help would be appreciated!



    1. Populate additional fields...

      Your name picker works great. I'm using it to log callers to the helpdesk and would like the picker to populate other fields from other columns in the address book when the caller's name is clicked, such as from the email, phone and organization columns. Is this possible? Thanks.

      Show the rest of this thread

  13. V 1.5 not looking up names

    Hey, I tried to use your version 1.5 of this and it's not working. I put the demo on my server and changed the addressbook to '/names.nsf' so it would hit my NAB. However, all it did was sit there and spin its icon. I got version 1.0 demo working no prob. Is there something else that needs to be done here?

      • avatar
      • Jake Howlett
      • Tue 19 Jun 2007

      Re: V 1.5 not looking up names

      Nick you need to start using debug tools like Firebug for Firefox.

      Show the rest of this thread

  14. v 1.5 error in read mode

    Hey this thing is great, but I' have an issue with getting 1.5 to work. When I open an existing document (not creating a new one), I'm getting the Javascript error " 'Event' is undefined ". Also, when I try to watch 'NamePicker', it is undefined. I've run through the debugger, but I've had no luck. I've really got no idea why this is happening and I hope you don't mind giving a few pointers.

    To me it seems like Prototype and the NamePicker library are not loading before this is called. Here's the call that's generating the error (from the NamePicker subform), and I only changed the addressbook and OutputFormat parameters. <script type="text/javascript"> Event.observe(window, 'load', function() { NamePicker.init( { addressbook: '/names.nsf', viewname: '($VIMPeople)', column: 1, OutputFormat: 'XML' }); }); </script>

      • avatar
      • Jake Howlett
      • Thu 21 Jun 2007

      Re: v 1.5 error in read mode

      As before - use Firebug. Use the Net tab to see if the .js files are being loaded. Use the Dom tab see if the object exist.

      If you're going to use JS libraries on the web you've *got* to learn to use debugging tools at this level.


  15. Slight Problem with IE6

    Hi Jake,

    I tried and quite succeeded with v1.0.0. I have yet to succeed with v1.5.0.

    A slight problem I encountered with IE6 however is with the field for selection of single names. It seems that the borders of the Team Leader field become rendered like the old input fields of earlier IE's. This always happens here after the color changes after the entry is shown in the field.

    I'm still tweaking with v1.5.0 that's why I can't take a closer look. I think the tweak should go somewhere after (or within) the "new Effect.SlideDown('NamesPicker')" line in js/NamesPicker.js although I'm not sure what to do.

    • avatar
    • KV
    • Fri 6 Jul 2007

    Works fine in HTTPS mode but fails in HTTP mode

    Hey it works as charm if I it is in the HTTPS mode. And fails to work in http mode. I really couldnt identify the root cause, can somebody clarify it pls.

    Cheers KV

  16. Problem in modal dialog


    this is really great stuff but it seems that the lookup is not working when called within a modal dialog (window.showModalDialog(...)) in IE. Does anybody know a tweak to get it work?


    1. Re: Problem in modal dialog

      ok I found out what the issue is: In a normal window, the logon-popup appears when accessing the names.nsf (if anonymous access is prohibited). But in a modal dialog, the logon-popup doesn't come up at all.

      If I manually log on to the names.nsf in the same session, everything works fine in the dialog. I also tried to create a DBLookup to the names.nsf, but this doesn't seem to have any effect on the AJAX processing...

      any ideas?

  17. V1.5 not looking names

    V 1.5 not working. any one can help me.

    My server 7.0.2

      • avatar
      • John
      • Thu 22 Jan 2009

      Re: V1.5 not looking names

      I agree...this is not working for me. I tried Version 1. Its great.

  18. Use for other datasources on same form

    First off, thank you. Your website is great.

    I really like the code and want to use it for all the lookups on my forms, not just the address book lookups.

    I was able to create a new form and a new subform to look into a different database. It worked great.

    Where would you start if you were to make the code modular enough that multiple lookups could be used (different sources)?

    or would you just create a object for each lookup type (NamePicker, DataSource2, DataSource3, etc.)

    Thank you again

  19. What about Swedish language support?

    I notice some strange behaviour in names thta have the ä,å in their names. how can I solve this problem?

    1. Re: What about Swedish language support?

      I realy love this app. but it dosn't support Danish. It dosn't return anything if the name contains æ, ø, å. I'm ready to test/help if any one can code it.

      /Mads Birk

  20. IE z-index workaround?

    I also discovered that IE causes a bug with displaying the namespicker beneath other fields. does anywone know a workaround for this?

    1. Re: IE z-index workaround?

      I realize this original post was in 2007 but I am having the same issue and didn't see any other posts on it. How do we code it so the namepicker is always on top of all the other divs and input fields on the page? I can't really make everything absolute positioning which I think will then make z-index work. Thanks for any suggestions!

  21. Categorized Views?


    I need to look up users that belong to categories in a db called "registration.nsf." I pointed your wonderful picker at a flat view first and it works just fine, but I next pointed it at a categorized view and added &restricttocategory=mycategory to the url in the lookup function in js/namepicker.js just to test it (with the intention of working out a way to dynamically pass the category in later). When I open the picker and type in a letter, it returns the first ten entries regardless of what letter I typed first or subsequently.

    I know you can't troubleshoot without seeing what I have and you have work of your own to do anyway, but I was hoping that my symptoms might trigger a memory of something you had already experienced. Any idea?

    Thanks mate, Charlie

    1. Re: Categorized Views?

      It is possible, I tryed and it works. Try this: NamePicker.settings['addressbook']+'/'+NamePicker.settings['viewname']+'?readvie wentries&count=10&RestrictToCategory='+bieb, where bieb is a variable that matches the single category. Don't forget to modify the subform.

      • avatar
      • Basir
      • Wed 17 Nov 2010

      I have the same problem. And Martin's solution doesn't work.

      Show the rest of this thread

  22. Problem with both versions

    Hi Jake, Your name picker really is excellent however I have found an issue where if you start typing in a persons name that appears towards the bottom of the address book, eg. the name starts with "Y" then it will not return the list of these names unless it can return 10 names.

    Are you aware of this? Is there any plan to address this limitation? Thanks

      • avatar
      • Jake Howlett
      • Thu 15 Nov 2007

      Re: Problem with both versions

      Are you sure? I can't reproduce it.

      In the online demo type in "zoe win" and you'll see the last *two* people in the NAB. Zoe Wright is the last in the view.


      Show the rest of this thread

  23. IE7

    In first : a very good work. Itry it with IE6, no problems it works perfectly I try also with IE7 and it doesn't work. Do you know the reason ? Thanks a lot for your answer Regards

      • avatar
      • Jake Howlett
      • Thu 29 Nov 2007

      Re: IE7

      Works in IE7 for me.

      Show the rest of this thread

  24. Thanks.... Very Much.

    It's good. Thanks...

  25. Problem with Name Picker

    Hi Jake,

    We have a Domino application in which we implemented the Name Picker, Name Picker is working on Domino Server without any problem. we are accessing the same domino application (where i implemented this Name Picker) in a portlet of websphere portal then Name Picker is not working (No Results are coming in XML or JSON formats). Tried by hardcoding the Domino Server Name of names.nsf working fine in domino server but not in Portlet.

    Any Suggestions?

      • avatar
      • John
      • Thu 22 Jan 2009

      Re: Problem with Name Picker

      while hardcoding try "/names.nsf" instead of "names.nsf". It should work. great stuff.

  26. multiple directories


    The script works great. Is it possible to have this script do lookups in multiple address books? For example names.nsf and names2.nsf? And if so, what changes to the script do I have to make to make that work?

    Many thanks,


      • avatar
      • Stan
      • Thu 31 Jan 2008

      Multiple Fields

      Is it possible to have the lookup populate mulitple fields in a view (i.e., phone, emaiol, company)?

      This is great BTW!!!

  27. Move Dialog Box with Scroll or Window Resize

    Thanks so very much for this functionality Jake! It is elegant looking and works well.

    My only problem occurs if users scroll the form that the name picker is on, or resize the browser window. The "dialog" box ends up being at the bottom of the screen, or off of it entirely, with no way to get to it.

    I understand that the following code in the NamePicker.js file is the one that controls where the dialog box appears, especially the 'absolute' part, and I have tried using 'relative' and making different calculations instead of using caller as the anchor. I have also been researching onscroll and onresize and can't quite figure out if these would be of use or if I'm just going astray.

    Element.setStyle('NamesPicker', {position: 'absolute', top: this.findPosY(caller)+"px", left: this.findPosX(caller)+"px"} );

    Can you please point me in the right direction?

    1. Re: Move Dialog Box with Scroll or Window Resize

      For others who are attempting this, I used the following information, which was great!

      It doesn't seem to work if the user resizes their screen, but it works well for the scrolling concern:


    • avatar
    • Stan
    • Thu 31 Jan 2008

    Populating more than one field

    I thought I should elaborate... Is it possible to have the name lookup populate mulitple fields from a single view (i.e., phone, email, company)? I need to collect more than just the user's name when a helpdesk call comes in. Thanks!!!

    1. Re: Populating more than one field

      I'll get it right sooner or later, I just wanted to include my email address

  28. How about filtering? Groups?

    1) Is there a smart way to filter the data coming from a viewentries query by a notes formula? I don´t want all users to be available for selection and don´t want to create that many filtered views in the Domino Directory. I have a property on the person documents which should be checked if it matches a formula based on the current user´s name.

    2) The person icon seems to be static in the list of hits from readviewentries. Is there any easy way to grab this icon dynamically from the notes view instead of the css? (e.g. to support groups to be selected).

      • avatar
      • Jake Howlett
      • Tue 4 Mar 2008

      Re: How about filtering? Groups?

      Hi Thomas, Yes. Both are possible. I'd probably use an agent to churn out JSON based on the criteria you want to test entries on. It won't be a simple tweak though and not worth trying if you're not comfortable with JavaScript. If you want me to do it get in touch and I can quote for doing the work.


  29. Issue if Generate HTML field is selected


    The names selected are not saved in the document if Generate HTML field is selected for the Form. Server version is 6.5. I need to put some JavaScript to push the values from NamesList1 to anothe fields before submitting.



    • avatar
    • John
    • Thu 22 Jan 2009

    Namepicker for Multiple Fields....

    Hi JH, Thanks for the great stuff. Just wanted to clear, Is that possible to implement this for two fields or more fields? Reply plz.

    Thanks in advance;



  30. Nice solution!

    You're a brilliant man Jake!

    • avatar
    • Eko
    • Wed 21 Jul 2010


    Thanks for this topic

    that not work with my server !

    Settings of my names.nsf :

    Default Access = author, Anonymous Access = None access

    Can you help please !

    • avatar
    • Eko
    • Wed 21 Jul 2010


    I 've server Domino 6/5, Lotus Notes 6.5, Lotus Designer 8.5 and IE 6

    Thanks for help

    • avatar
    • Eko
    • Thu 22 Jul 2010

    thats work !!

  31. Hi Jake,

    I am new of this great site and learned a lot so far. I have a problem with namepicker. My Domino Server and Client versions are 8.5.1. I have done all what you said. I can see the icon next to field but cannot pop up? I guess on click event does not work. Do you have any idea or suggessions for me?

    Thanks again,


Your Comments


Navigate other articles in the category "Forms"

« Previous Article Next Article »
Drag-n-Drop Sorting of Documents   Working With Character Sets and Domino

About This Article

Author: Jake Howlett
Category: Forms
Keywords: names; picker; address;


namepick-v1.0.zip (85 Kbytes)
namepick-v1.5.zip (122 Kbytes)


View Online Demo
Print Friendly

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »