Using the namePicker from the Extension Library in #XPages

One of the things that always seemed weak to me about my Domino web implementations was the selection and display of names. Now that XPages turns our work into the creation of actual web pages, the tools available are so much better and extend the flexibility of Notes development into the 21st century.

OK, saying “21st century” doesn’t sound as cool now that we’re halfway through the second decade, but since so much of what I’d done looked like it was designed in 1995, getting out of 20th century web development is a big step for me!

There are two control types from the Extension Library that are relevant here: the Dojo Name Text Box and the Name Picker.

The Dojo Name Text Box gives us that modern, Facebook-style name display, including a little “x” to delete the name from the list:

The Name Picker is very flexible. In my code example, I wanted users to be able to select from a view in the database, from the corporate NAB or, if they’re using XPiNC, from their personal address book. One of the nice thing about the picker is that if you supply multiple dataProviders, it provides a picklist of those choices, but if you only supply one (or if only one is ‘loaded’) then it doesn’t display the picklist of address books, allowing the user to just use the one NAB you’ve set as a dataProvider. It’s nice when you don’t have to tell the control the obvious things.

When you are setting up the namePicker, you need to select your dataProvider(s). There are three types (beanNamePicker, dominoNABNamePicker and dominoViewNamePicker) and the aggregator for using multiple providers (namePickerAggregator). As you can see in the example, if you choose the aggregator, you then identify your dataProviders inside that aggregator.

The dominoNABNamePicker is likely the one that’s most used, so also has a few pre-set configuration choices. While there are six parameters you could use, you can choose just to use two: addressBookSel and nameList.

• For addressBookSel, you’re choosing between broad options: all, all-public, all-private, first, first-public, or db-name. Because our environment includes an address book for non-staff folks, I didn’t choose either all or all-public, which would have included that address book. So, I went with db-name, which allows you to specify the database name. The broader categories will work for you if you don’t have the requirement to leave out one of the address books.
• For nameList, you also get some choices that are functional and make things easy for you: people, peopleByLastName, groups, or peopleAndGroups. This overrides two of the other parameters – groups and people, who are both boolean values. Using people as the nameList value returns people by first name, which can be a little annoying if you have thousands of choices, so it’s nice that peopleByLastName has beeen added.
• The addressBookDb parameter only matters if you’ve selected db-name as the addressBookSel value. In my case, when the user is accessing our database in XPiNC on the local replica, their personal address book is names.nsf and the corporate one is minnames.nsf, so I’m doing a little trickery to give them all the options. I suppose I could have specified the corporate NAB and then used all-private to get to the personal address book, but I didn’t think of that first.
• The loaded parameter is the most powerful one here for me, since it would allow me to provide the user more or fewer choices based on a formula. In this instance, the choice is only based on which client they’re using, but I could imagine basing it on roles, on values on the document or any variety of other things.
• As mentioned above, the boolean values for groups and people are overridden by the value of nameList, so I’d avoid using them. Confusion is the likely result.

I was especially happy that using a view within the existing database in the namePicker was so simple. All I had to do was create a view that had the values I wanted in the first column, sorted ascending (I assume descending works as well, but that would be user-unfriendly). The dominoViewNamePicker is simple – really you only need to specify the databaseName and viewName. My samples view was in the same database, but you can point it elsewhere. There is a loaded parameter for your use and you can choose a label for the pick list when using multiple dataProviders.

							<xe:djextNameTextBox id="approversNameTextBox" value="#{deliverableDoc.Approvers}">
							</xe:djextNameTextBox>
							<xe:namePicker id="approversNamePicker" for="approversNameTextBox" listHeight="300px" listWidth="150px"
								pickerText="Click to select technical approver" rendered="#{javascript:deliverableDoc.isEditable();}">
								<xe:this.dataProvider>
									<xe:namePickerAggregator>
										<xe:this.dataProviders>
											<xe:dominoViewNamePicker label="Contacts" viewName="ContactsNotesName">
												<xe:this.databaseName><![CDATA[#{javascript:getDb("sharedResourcesDb",true);}]]></xe:this.databaseName>
											</xe:dominoViewNamePicker>
											<xe:dominoNABNamePicker nameList="people" addressBookSel="db-name" addressBookDb="names.nsf">
											</xe:dominoNABNamePicker>
											<xe:dominoNABNamePicker nameList="people" addressBookSel="db-name" addressBookDb="minnames.nsf">
												<xe:this.loaded><![CDATA[${javascript:@ClientType() == "Notes";}]]></xe:this.loaded>
											</xe:dominoNABNamePicker>
										</xe:this.dataProviders>
									</xe:namePickerAggregator>
								</xe:this.dataProvider>
							</xe:namePicker>

Unfortunately, I know very little about beans, so I’ll leave discussion of that to someone else, or to a future post if I can follow Russ Maher’s example and get into using Beans wherever they’re useful. The more tools you have in the box, the quicker and more flexibly you can get your work done.