dominoGuru.com
Your Development & Design Resource
Simple SSJS Function for xp:selectItems
08/09/2017 by Chris Toohey
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.
Conclusion
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.