Creating a Dojo Filtering Select Control in XPages

If you’d like to provide users the ability to type directly into an XPages combo box (like Dialog List field in the Notes client), you can easily convert combo boxes to dojo filtering select controls in XPages.

Combo Box

Let’s start with this straightforward combo box:

FilteringSelect_2

<xp:comboBox id="comboBox1">
  <xp:selectItem itemLabel="Acai"></xp:selectItem>
  <xp:selectItem itemLabel="Apple"></xp:selectItem>
  <xp:selectItem itemLabel="Apricot"></xp:selectItem>
  <xp:selectItem itemLabel="Artichoke"></xp:selectItem>
  <xp:selectItem itemLabel="Asparagus"></xp:selectItem>
  <xp:selectItem itemLabel="Avocado"></xp:selectItem>
</xp:comboBox>

Dojo Filtering Select

If you have the extension library, 8.5.3 with Upgrade Pack 1, or Notes 9, the Dojo Filtering Select control is available to you in the Dojo Form section of the Controls palette. When you drag it onto a page, it looks the same as the standard Combo Box on the Design tab.

FilteringSelect_1

The primary difference between the two is that you can type directly into the filtering select in order to narrow down the choices.

Easily Creating a Dojo Filtering Select

There’s also a major difference in Domino Designer when creating a filtering select — it doesn’t have the ‘Values’ subtab in its properties, so there isn’t a similar method of building the options for the list.

There are two simple ways to convert this to a dojo filtering select.

1) Manually change the xp:comboBox tag to xe:dojoFilteringSelect (along with the corresponding closing tag)
2) Drag a Dojo Filtering Select control onto the page and copy all of the xp:selectItem tags into it (then remove the combo box)

In fact, this is the best way that I know of to create a dojo filtering select easily. They can be enhanced to work with a different data store, but if your list of options is hard-coded or computed with SSJS, this is an easy way to go.

<xe:djFilteringSelect id="djFilteringSelect1">
  <xp:selectItem itemLabel="Acai"></xp:selectItem>
  <xp:selectItem itemLabel="Apple"></xp:selectItem>
  <xp:selectItem itemLabel="Apricot"></xp:selectItem>
  <xp:selectItem itemLabel="Artichoke"></xp:selectItem>
  <xp:selectItem itemLabel="Asparagus"></xp:selectItem>
  <xp:selectItem itemLabel="Avocado"></xp:selectItem>
</xe:djFilteringSelect>

UI Features

Even though it’s a combo box at its core, the filtering select control functions quite differently than the standard combo box.

1) The UI is a little different, as the filtering select picks up dojo styling. This is definitely something to keep in mind; you may need to add CSS to restyle it to keep it consistent with the rest of the page.

FilteringSelect_3

2) As you start typing, it will filter the list to only include the values that start with the characters that have been typed.

FilteringSelect_4

3) If the user types a value that is not valid in the list, an icon displays in the field and an error message pops up next to the field.
FilteringSelect_5

When this happens, no server-side code will execute, because it’s failing client-side validation that’s built into the control.

Advertisements

6 responses to “Creating a Dojo Filtering Select Control in XPages”

  1. DavidLeedy (@DavidLeedy) says :

    Do you know of a way to save or get hold of a backend key field in this type of example? Often that’s going to be different then the user facing data.

    thanks!

    • Brad Balassaitis says :

      I’m not sure I understand what you’re asking, so please let me know if I don’t answer your question.

      You can bind the field to a document data source field directly from the filtering select control (it has the same Data subtab under properties).

      If you mean using SSJS to compute a list of options for the drop-down, then you can set up the computed list for a Combo Box and then just change tag to a filtering select tag and the computed list will work the same.

  2. ADIBABU KANCHARLA says :

    Be careful when using this awesome control. If you compute options (using formula or SSJS or Java…) for it and no results are returned, this will generate client-side error ‘value is required’, when interacting with any control on the XPage.

  3. Ryan says :

    Does anyone know if there is a way to include the entire value in the search? For example, searching “123” would return the value “Test 123”.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: