The Extension Library brings a new control to the party, the Value Picker. This gives the user an image or link that spawns a dialog from which they can select one or more options and even search for options. (The Value Picker itself doesn’t differentiate whether or not multiple items can be selected. That’s handled by the component into which the selected values are stored and to which the Value Picker is bound. Logically speaking, the Value Picker is bound to a component – an Edit Box, a Dojo List Text Box etc. – which is bound to a field on a document or a property in a bean.)
The Value Picker, like the Name Picker, does not take a selectItems component as its source but rather a dataProvider. Why take a different approach? The selectItems component doesn’t permit any searching or “starts with” functionality, which is included in dataProviders. There are three dataProviders available to choose from for a Value Picker:
- dominoViewValuePicker, allowing the developer to map to a Domino view.
- simpleValuePicker, taking a String of options. Properties allow the developer to define whether searching is case insensitive, what the separator between labels and their respective values is, and what the separator between each value is.
- beanValuePicker, where you can create a Java bean where you code methods to retrieve the values and handle searching.
Sometimes you don’t want to or can’t create a specific view from which to get the options. You won’t be able to create a view if you’re picking options from a keyword document. If, for example, you have country documents with a geographic region defined and you want to restrict to a previously-selected geographic region, you won’t want to create a separate view for each geographic region and you can’t pre-select all entries based on a key.
None of these dataProviders takes a Java collection as its source, so we have to get a little more sophisticated. The option with the lowest level of complexity would appear to be the simpleValuePicker. But although this is the easiest, it’s not going to perform very well, because you need to take your ArrayList or TreeSet or other collection and convert it to a String. And what if you’re working dynamically from documents under a specific category and a lot of documents get added? What are the limits, and how do you work around them? Plus (ideally) you’re wanting to constantly build your expertise, so you want to look at the beanValuePicker.
First off, the beanValuePicker is not the easiest of beasts to understand. Also, the examples in the Extension Library demo database are rather hard-coded. The beanValuePicker there works only with states. There’s nothing that gets passed in to determine the source. There are no properties you can set to make it more generic. But if you want to pick from keywords documents, for example, that’s exactly what you want: something generic that you can pass a key to and get the options for.
Thankfully, Toby Samples pointed me in the right direction by saying the dataProvider can be computed – just like virtually everything else in XPages. So in the next article I’ll explain the key methods of a dataProvider and how to extend it to make it more flexible by passing in a collection.