Your Development & Design Resource

Simple SSJS Function for xp:selectItems

Simple SSJS Function for xp:selectItems

Getting Started

As you develop more and more applications, you'll start finding similar needs. Smarter developers look to make reusable, scalable code libraries and common structural elements.

Got a new project? Copy in your common libraries and elements and you've got a head start on your new app.

In this article, we'll cover a function that I've used in countless IBM Notes Domino XPages applications to allow me a single point of development maintenance for any xp:listBox, xp:checkBoxGroup, xp:radioGroup, xp:comboBox, or any other control that uses an Array of pipe-structured (label|value) options.

The getItemOptions() SSJS Function

While we may not initially use every available option in this function, I'll cover the basic structure and the scope so those developers new to this syntax / approach aren't immediately lost:

Try, Catch, Finally

As I've covered in my article (Using Try, Catch, Finally, Throws, and Return Objects in Client Side and Server Side JavaScript for XPages), it's good practice to error trap even the most simple functions while returning something useful for troubleshooting. You don't want to throw a stack trace if you don't have values in a conditionally-displayed xp:comboBox, and this structure will help you avoid your entire app from breaking over the slightest hiccup.

NotesXspDocument uiDoc

Speaking of conditional values, you may have a scenario where you need to base your selectItems on another value on the NotesXspDocument or on a wrapped NotesDocument passed in from a View or an external NotesDatabase NotesDocument.

For these scenarios, I'm including an optional second argument in my SSJS function using the first the global CurrentDocument object and checking for an "override" via the arugments[1] reference.

Switch'ing things up!

Lastly, I'm keying off an argument (the first argument) of my function using a switch function and various case catches to handle different selectItems options.

Using this code

Here's a simple example of how you would use our getItemOptions SSJS function for an xp:comboBox control:

-- this would return as many options as you have "Active" Templates configured in your application with an initial/default blank value.


I've purposefully kept this function and the above Using this code Use Case very simple. It should not take away from the fact, tho, that this technique is both powerful and amazingly maintainable.

I could have referenced the uiDoc in my switch, I could have called out to an external NotesDatabase, I could have called Stored Procedures on a Microsoft SQL server, or I could have evaluated keywords based on the effective user (eg., session.getEffectiveUserName()) and delivered a combination of all of these possible extended scenarios.

It's really simple, but the maintainability and ease-of-use and extension make this one a no-brainer, and it's why this function -- or rather, versions of this function -- are used in countless applications that I've built.

Hopefully you'll find it as useful as I do.

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.