Jan 292008

Today we explore two extended form widgets I used in my Lotusphere session BP212: The Great Code Giveaway: “Beyond Cool”. The first article in this series can be found here. You can download the instructions, code and databases here.

domino.form.ComboBox & domino.form.FilteringSelect

These widgets are extended from dijit.form.ComboBox and dijit.form.FilteringSelect to accommodate for the URL syntax that a Domino view requires when doing a view search. They are modern and Ajax based. You can open both by clicking the down arrow but you can also type in the field to narrow down the choices. The important part of these widgets is in the _startSearch function.

if(key != ""){
var sLetters = "abcdefghijklmnopqrstuvwxyz**";
var lastChar = key.substring(key.length-1,key.length);
var sUntilKey = "";
var iCharNum = sLetters.indexOf(lastChar);
sUntilKey = key.substring(0,key.length-1) + sLetters.substring(iCharNum+1,iCharNum+2);
sUntilKey = key.substring(0,key.length-1) + (parseInt(lastChar)+1);
query["StartKey"] = key;
query["UntilKey"] = sUntilKey;
query["StartKey"] = null;
query["UntilKey"] = null;

What we do here is creating the URL syntax for a Domino view search that requires the &StartKey= and &UntilKey= arguments to find the document(s) the user is searching for.

From Domino Designer 8 Help:

Where string is a key to a document in sorted view. The view displays at that document. In cases where there is no match for the StartKey, the next document is returned. So, for example, if the StartKey is “A” and there are no documents that begin with “A”, StartKey returns the first document that begins with “B.”

UntilKey is only valid when used with StartKey. It allows you to display the range of view entries beginning with the document specified by StartKey until the document specified by UntilKey. For example, &StartKey=A&UntilKey=B would give you all the entries that start with A. Use the &Count keyword to further limit the number of entries returned within any given range.

How to add to them to your form

Both these widgets are very easy to add to your forms. Both require the domino.data.ViewStore discussed in the previous article so you start by adding that.

<div dojoType="domino.data.ViewStore" jsId="DominoStore" url="../sessions.nsf/sessionlookup"></div>

Here we add a div tag with dojoType of domino.data.ViewStore, we give it a jsId of DominoStore and the url is pointing to a database and view. In this case a database called sessions.nsf parallel to the current database and a view named sessionlookup.

We add a Notes field to our form and make it type Dialog list. In the HTML Attributes of the field we add the following:

"dojoType="domino.form.ComboBox" store="DominoStore" searchAttr="IDTitle" pageSize="10" autoComplete="false""

The store attribute is the same as the jsId attribute of our domino.data.ViewStore above. The pageSize attribute is the number of documents we get/show at a time and the autoComplete attribute is for making the top search value auto complete the field. Try if for yourself by setting it to true.

I left the searchAttr attribute for last because it need some explaining. As you know we are using a store to get the values for the field.

If we open up the view sessionlookup in the database sessions.nsf in Domino Designer we see that the view has two columns. If you look at the Programmatic Name for the first column you’ll see that it is IDTitle. This column is what we want values from so we set the searchAttr to IDTitle. The value saved by a domino.form.ComboBox is the same as what you see.

The difference between a domino.form.ComboBox field and a domino.form.FilteringSelect field is that the latter has an onChange attribute and that the value of the field is always the identifier of the store it is using. What is an identifier you ask? Well, all data stores has a unique identifier. In some cases that is just an incrementing number starting at zero, but in the domino.data.ViewStore I created I used the NoteID. Why not the UNID? Because a document can actually exist several times in the same view.

So in a domino.form.FilteringSelect field representing all speakers I have the following attributes.

"dojoType="domino.form.FilteringSelect" store="SpeakerStore" searchAttr="Name" pageSize="10" autoComplete="false" onChange="setMentor(arguments);""

You can see this field in the “Mentor Selection” form in the “Mentors.nsf” database. It is part of the download. We now need the setMentor function.

function setMentor(arguments){
var identityRequest = {
identity: arguments[0],
onItem: function(item){
var sEmail = SpeakerStore.getValue(item, "Email");
onError: function(){
console.error("Fetch failed.");

A version of this function can be found in the “index” page inside the “Registration.nsf” database. In this function we first create an object, identityRequest, and set the property identity to the first value in the passed in arguments array by setting identity: arguments[0]. We also have an onItem property. This is the function we call when we have retrieved a value. onError is being called if an error occurs. In the bottom of the function we do the call to the store and pass in our identityRequest object. SpeakerStore.fetchItemByIdentity(identityRequest); In this case we only alert the email address of the user we selected but if you look at the same function in the “index” page mentioned above you’ll see that we call another function to go get the profile from greenhouse.lotus.com for that email.

If you want to dig deeper in all possible attributes that a ComboBox and a FilteringSelect can change see the dijit.form.ComboBox and the dijit.form.FilteringSelect JavaScript files. Remember that in Dojo the name space is done by the periods you see in the names above. So in the folder dijit you find a folder called form where you’ll find the files ComboBox.js and FilteringSelect.js.

I hope this tutorial together with my code examples will clarify these two widgets for you. If not please comment below and I will try to explain further.

  15 Responses to “ComboBox & FilteringSelect for Domino”

  1. hej, is the presentation itself available somewhere other than the IBM Lotusphere site?


  2. Patrick,
    It will be available on the download page in a couple of days.

  3. This is great code. I have would like to use filtering select in a different manner. I would like to set the indentifier to a column in the view. I am examing the domino.data.ViewStore.js trying to make this dynamic. i.e. We have a list of Things (10k large) and we want to store the Thing Id of the selected Thing and not the Note ID.

  4. I wanted to use my own identifier based on a column. I modified domino.data.Viewstore.js so that

    identifier: ‘noteid’ became

    identifier: ‘identifierx’

    and my made the programmatic name of my view column to be

  5. Combobox works great, but I am having trouble with using this to bring in multiple values from one field and displaying them in a combo box. We use keyword values and store everything in one view. The dojo Viewstore works great for pulling everything from a specific column but is there a way to use it like a dblookup?

  6. Viktor,

    I’m trying to use the filteringSelect widget with a categorized view.

    The first column of the view is categorized. The category I want is “countries”. The second column of the view has programitic name “$7″. It contains ” | “.

    My store is:
    <div dojoType="domino.data.ViewStore" jsId="CountryStore" url="../MAXHRHelpCode.nsf/DescriptionCodeLookupbyFieldname">

    my HTML attributes for the dialoglist notes field are:

    query = “myQuery”

    myQuery = { RestrictToCategory: “countries” };

    I think this is correct, but I’m getting no data.

    Does it look right to you.

    As always, any help is greatly appreciated.

    Jeff Byrd

  7. Jeff,
    I don’t think it will work for a categorized view. The searchAttr of the $7 column is not available when you pass in RestrictToCategory. I have not tested it on a Categorized view but I have my feeling that is the problem. Could you try to make the view not categorized?

  8. Viktor,

    I did get the filtering select to work with a categorized view.

    The trick is to use pass thru html instead of placing the dojo html code in HTML Attribute of the Notes field. When you see it execute in firebug, you can the query included in the URL. Then searchAttr will return the target column. Very cool. It’s basically a dbLookup!

    I think the problem I was having has something to do with the way Domino renders the HTML. Often, when I include the dojo html in the HTML attribute of the Notes field, the dojo widget doesn’t perform as expected. If I just use pass thru HTML, the widget acts as expected.

    I’ve noticed this with Filtering Select, Combo Box, and drop down Date Input.

    I’ve taken to writing my Dojo code in straight HTML and then loading my Notes fields on Submit.

    Thanks for your reply.


  9. Guys,

    I am trying to get it working and it never shows anything from the data store..

    Can someone please give me a simple sample combo box which gets the list from the domino datastore.

    Thanks and best regards,


  10. Hello Guys,

    I figured out the problem. I was running the code on 7.0 server. It runs perfectly on 7.0.2 server.

    I have another problem.

    These fields loose the selected values when you reopen the document. I have to reassign them in forms onload event.

    please let me know if anybody else has this problem or any fix.



  11. I have a combobox which is working fine to lookup values from a view in another database, the selected value is saved to the field.
    When I then edit a document this field is cleared. How can I prevent it being cleared?

    “dojoType=”domino.form.ComboBox” store=”DominoStore” searchAttr=”OrgName” pageSize=”10″ autoComplete=”false””

  12. @Matthew
    I recommend reading 3 articles posted by David Bockes over at dojomino.com:
    FilteringSelect and Dialog Lists and Firefox
    FilteringSelect Pt 2
    FilteringSelect Pt 3

    Good luck

  13. What about use of the languages which are different from English in column values? At best I see only question-mark… What can you advise?


  14. Excellent article.

    Is there any way to filter/display data until users have entered a specific number of characters (for example 4)

  15. Hello,
    thank you for this excellent article, but, with the dojo 1.6.1 version, comboBox is no longer functionnal, so, what should I modify, to make the comboBox working?

    Best regards

 Leave a Reply



You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>