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.

This tutorial will use a simple example Java Script Library (not a JavaScript Library...) which will house a simple Model-View-Controller architecture API for NotesData Create, Read, Update, and Delete functions. All pretty standard and intentionally simple...

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 pass-thru HTML, CSS, and JavaScript... that is translated when compiled.

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.

1. Window\Show Eclipse View\Other...

   

2. Java\Package Explorer

   

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.

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 WebContent\WEB-INF location.

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:

com.dominoguru.api Package

... 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 mvc.apiPOST and mvc.apiPUT Methods.

Conclusion

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!