Your Development & Design Resource
Adding a Java Script Library to the Project Build Path for SSJS and XPage Development
06/07/2010 04:15:00 PM by Chris Toohey
Calling Java Methods in SSJS allows you to take XPages from a functional technology to an enterprise-level solution. Here's a quick step-by-step tutorial showing you how you can add your own custom Java Script Library into the Project Build Path of your IBM Lotus Notes Domino NotesDatabase Design.
Step 1: Get your Java Script Library
Here is a simple CRUD API for NotesData Management. The idea here is simple:
mvc.apiPOST creates a new NotesDocument from the method-submitted NotesDocument.
mvc.apiPUT updates an existing NotesDocument from the method-submitted NotesDocument.
mvc.apiGET returns a NotesDocument from the method-submitted NotesDocument.
mvc.apiDELETE deletes the method-submitted NotesDocument. Pretty basic stuff really, and I intentionally removed any application or business logic that makes this whole thing make sense as I don't want to confuse the purpose of this tutorial and instead want to keep things as basic and vanilla as possible.
An example of why you might want to do this... let's say you have a NotesItem value that's non-UI controlled but controlled via business logic. There's no reason to compute that stuff in the UI, so you add that to the MVC Control. Calculating the totalcost NotesItem might be controlled by data collected from the UI, but there's no reason to have the UI do the math if you're submitting it to the NotesDocument.
Another example: let's say that for any
mvc.apiDELETE, you don't actually want to delete the target NotesDocument, but simply change the form NotesItem or something that removes it from your View Selection Formula criteria. Again, dump that UI-controlled stuff, put everything into your MVC-friendly Java Script Library as your controller, and evolve... but again, that's off-topic.
Once we have our Java Script Library, which you could write in Notepad if you really wanted to, you'll need to import that Java Script Library into your NotesDatabase design. In fact, here's the Java Script Library (which I actually created with Notepad...):
IBM Lotus Notes Domino NotesData API Example Java Script Library
Step 2: The XPage Build Path
... there's something you need to understand about an XPage. What you see, via the Domino Designer, is simply an editor for XPages. XPages, rather simply put, are just XML at their base level. They are XPages that are compiled through the DDE XPage compiler into Java. Once they're compiled java, they're delivered via the JSF.
When you're writing your SSJS... that is translated when compiled.
When you're writing your Expression Language... well, you get the point.
What this means is that once you understand where the XPage Build Path is, you can easily add to that Build Path, and leverage imported Java Script Library methods.
Window\Show Eclipse View\Other...
Once you have the Package Explorer open, you can move it to the desired location. I, for example, keep it along with the Outline Pane at the bottom-left of the DDE Client.
(You may want to save your perspective at this point... as PE isn't turned on by default and thus it'll disappear.)
Your NotesDatabase will appear in the Package Editor, and you will be able to browse not only the XPage Build Path, but also all NotesDatabase properties and design elements.
We'll concentrate on the XPage Build Path though, and more specifically adding our api.java Java Script Library to our NotesDatabase design.
Our first step here is to create a new folder in the
IBM Domino Designer - Package Explorer - Add New Folder
And now we'll add the new src folder to our XPages Build Path:
IBM Domino Designer - Package Explorer - Add Folder to Build Path
Once you've added the
src folder to the Build Path, it will relocate (from a sorting/organization order) in the Package Explorer, and will be available at the top of the NotesDatabase PE entry. From here, you can simply drag-and-drop your api.java Java Script Library into the
src folder... but you're not quite ready to use your Java Script Library (or the methods within) just yet.
In our Java Script Libary, we've named the package
com.dominoguru.api. When you drag-and-drop into your
src folder, you'll notice that it places your Java Script Library in the default package. This will cause errors when you compile your code (stating that the package name doesn't match... because it doesn't of course.).
To fix this, we'll need to create a new package and move the Java Script Library to that package.
Domino Designer in Eclipse - New Java Package
Once you've added the new
com.dominoguru.api Java Package, simply drag-and-drop your api.java and DDE will do the rest! The final result should look something like this:
... and now we can use it!
Step 3: Using Java Methods in SSJS
Pretty simple, huh? This is XPage markup (just some XML, remember?) which imports the
com.dominoguru.api Java Script Library (which is available since we added it to the XPage Build Path), and allows us to use the
Writing this tutorial took longer than the steps it takes to add a custom or 3rd-party Java Script Library to the XPage Build Path so library methods can be used in SSJS (and SSJS Libraries).
... because once you can do that, anything's possible!