I've waited a long time before trying to write anything serious in XPages. I've known about them, and even extolled the potential of them as far back as late 2007 when I wrote the very first public article about them. I said then, and continue to say that whether or not XPages really live up to their potential will depend entirely on how well they're implemented in the client. Until 8.5.3 I have not had any confidence that they were stable enough to be worth working in. Thanks in large part to the work of people in the community who have pushed it, report its problems, and created the useful documentation that IBM has opted to leave out, I decided it's time to put the effort in and see what I can create with it.

As I said four years ago, to me the primary value that XPages brings to the table is the ability to focus on the page presented to the user, rather than on the individual data notes that underlay it one at a time. Most applications require a user to work with more than one interrelated document in much the same way that a relational database handles related tables. Prior to XPages, there's been no natural mechanism to do that smoothly with Notes and Domino. This one piece of functionality SHOULD make developing applications with XPages so much easier than it has ever been before.

If only it were that simple. I'm really trying to be fair here -- I want to love XPages, regardless of my current state of disgust with some of the IBM executives responsible for the Notes client.

The Original Application

The goal is to take an existing web application and create a new web front end for it using XPages. The web application has a lot of complex embedded html and css, but under that it's actually made up of a few really simple forms. There's a primary "User" form, and then each "User" can have zero, one, or many "Objects" associated with them. There are two kinds of objects, but they both are fairly simple forms based items and each is stored in a single document. There is a one-to-many relationship of users to objects, and they're tied together based on the user id. The app has other things in it, but this simple explanation covers the majority of what it does. For scale, each kind of object is in its own database. There is a database of "User" documents, and two databases each with their own kind of "Object" documents in them.

Sounds like an absolutely ideal target for an XPages application, doesn't it?

The Goal

Since this is the first phase of the project, all I wanted to do was present on a single XPAGE a couple of editable fields on the "USER" document, then have a list of the existing "Objects" of one type below that, each editable in place, and a "New" object of that type below the list. So a primary document, a repeating, editable set of existing related object documents, and a new object document which can be submitted. I'm not in the least bit interested in what it looks like at this point. I'm going for a purely functional use case test. I believe that if I can make this use case work smoothly, I'll have about 90% of everything I want to be able to do with Notes data in an XPage figured out. I can use the design patterns I've learned there on other projects to my hearts content because really, they're all the same. Oh, there's other stuff I'll need to do -- call agents, do some obscure lookups, etc, but really I can do all that with client side javascript if need to.

Here's What I Found

First of all, yes - it can be done. Technically, the promise of working with the related documents through the repeat controls can be made to work quite nicely. In fact, the repeat control itself has become "reasonably" straightforward. The hardest part is figuring out what you can actually pass to it so it knows what to repeat, and where to plug in that value, values, list, or code result -- and in the case of a code result, what format and type it can be. You see, there is virtually no reasonable documentation provided with the product by IBM. There are resources out there to find, but almost nothing in the product itself. Personally, I suspect this is because if they include documentation within the product, they have to QA that documentation and they have to provide it translated in several languages. That means spending money on headcount. Far better to just dump it out there, then maybe get involved with a book or two or even better get other people to write their documentation.

Now, would it be SO HARD to include something on this pane that indicated what the value, values, or objects that this field will accept are, as I've done below? This isn't a new product any more. It's 4 years on the market and several software revisions down the road and we still have this problem. This complete lack of contextual assistance is one of the critical factors that makes XPages such a complete pain in the backside to learn. It's a problem that is repeated on virtually every property box that accepts a scripted result as an option. None of them actually tell you what kind of a result the field is looking for. Is this laziness, or is it because IBM is too cheap to hire someone to write and QA the translations that would be required?


That's just one example, but there are hundreds of others. Where there is mouse-over help, it is singularly not helpful. For example, mouse over the option labeled "DataContexts". It sounds promising, I wonder what that does? According to the mouse-over pop-up help it "Controls data context lists". What the hell does that mean? Where is the link that lets me explore that topic in the documentation provided? Oh, wait, there is none. No link, no documentation.

There are a bunch of tricks to doing what I wanted to do. Thanks to work done by Matt White, David Leedy, and others I was able to find the hidden secret settings you have to use make my little application do what I want. Mostly. I'm not going to document those for you here yet because frankly, I'm not that good at it yet and you're better off looking at Matt's and David's work directly. When I have a solid handle on it, I think I can add to the community by documenting things in my own way, but that needs to wait until I'm sure I'm giving out good information.

I ran into several other challenges along way:

Server Crash: If, after delving deep into the various settings, I found the option to "computewithform" when I load or save a document which I created based on that form and turned it on -- my server crashed immediately on submit of that form. When I say crash, I mean complete and total crash with no errors or warnings visible. I had to use nsd -kill to clear it from memory and restart it. The crash turned out to be because of a bad subform in use on the form that had become corrupted in a previous version of designer. Nothing else using that subform caused server to crash, however. The real issue for me with the server crash, is that I've got this massive "xpages engine" thing running on my server and I have virtually no insight as to what it's actually doing.

ComputeWithForm: It still fails to compute with form on save. It will on load, but not save. If its turned on, the document fails to save. No further error is generated anywhere. It just doesn't work. I have no idea yet why. So much for using existing functionality. I'll have to re-do any calculations at save time to make sure the document ends up saved with the right values on it. Again, the big problem here is a total lack of insight as to what's not working, why it's not working, or even the fact that it isn't working.

Re-posting data on refresh: As much as I like the idea that my interactive page can submit and refresh parts of the page during its use, if the user ever does do something silly like use their browser's "Reload" button, the results are unpredictable. Whatever the last update the user attempted was, will be repeated. That can result in blank documents, duplicate submits, replication conflicts, and a general deviation from expected behavior. So, while it looked good initially, now I've got to go and create a routine to call after submitting anything on the page, that does a "blank" post to a document that is discarded at the server rather than saved so that if the user does do a refresh that is the last thing that was posted. That's just dumb.

Overall impression:

XPages can be learned, and once learned it can be used to create good applications. I suppose we'll call that a win. If the goal was to create a new design paradigm that would attract new developers to the platform by providing an IDE that didn't require the years of background, long lists of workarounds, and a wealth of community knowledge just to build half decent applications -- then its an utter failure.

I'll probably continue to work at it, and will likely build new applications, as I need them, in XPages for as long as I stay with the Notes & Domino platform. I'm just going to have to settle in and accept that developing Notes and Domino applications is going to be just has painful and require as much or more community knowledge as it always has. The opportunity to do this in a way that could seriously attract new attention to what is still the most solid and functional back end platform available was just entirely missed when IBM insisted on using the Trilog application that most of the programming community had already rejected as the basis to do it.