There’s a difference between knowing the path and walking the path

XPages developers all know that they aren’t writing Notes apps anymore. The experienced ones know, cognitively at least, that they aren’t bound by the same rules that applied to Notes. But there’s a difference between knowing and doing.

Let’s take a really simple example: a standard Notes form with a few fields in a table. Imagine you have a simply Notes form with a table containing 6 rows and two columns. The first column contains the labels for the fields appearing in the second column, for a total of 6 pairings of static text and fields across table columns.

ContainerBasicPretty normal right? And so if you decide to make an XPages version of that by creating a control and adding the data source, then you drag the fields into your editor and get something that looks like this…

Using a standard HTML table, this sets up a label/field pairing that is nearly an exact match to the structure of the original form. This is just fine for your very first XPages application. If you delivered this to a user, chances are they would nod and say “okay” and then move on with a list of enhancements.

ContainerAdvIf you’ve been doing things a bit longer and you’re familiar with the IBM Extension Library, you might do something a bit more advanced, like this…

Now you’re getting a bit more sophisticated. Instead of using a standard Table, you’re using a Form Table component, which understands title and description information, and provides rows with a basic understanding of labels and controls that relate to each other.

In both of these patterns, you have 6 rows of components in your control to represent 6 rows in your original design. This is a completely normal and everyday practice and it can be found in dozens of XPages applications written by IBM, provided by the community at, or sold commercially by business partners.

What if I told you that this approach isn’t a best practice? What if I said that there is a far simpler way to both dramatically increase developer productivity AND future-proof your application design? Would you like to know what it is?

AbstractFormHow about simply replacing 6 rows with a single row inside a repeat control?

“It’s not that simple,” you might reply, “I don’t just need labels. The inputs have to be bound to different fields, and some of them are required while others aren’t, and they need different styles and… and… and…”

Well, try it. Just look at the screen shot I’ve attached and ask yourself how much work that really is. It took me about 23 minutes, at midnight, to write an abstract custom control that can provide reading & editing of practically any Domino document in seconds. All you need to do is decide how you want to populate the members of the PageController class in any given instance. That could be from an NSF, from some XML, from a block of JSON via a REST service, from an RDBMS or whatever other path you choose from the near infinite variety of resources open to you in the XPages context.

AbstractForm2Perhaps you think my implementation is too simple. You’d like to be able to group your inputs together into logical groups with headers. No problem, that’s just one more layer to the abstraction by adding an additional controller. It takes about another 5 minutes. I didn’t bother throwing in, say, a <xp:tabPanel> around the Form Table in this example, but I think you can see that it would require about 30 seconds to do so.

When you shift your thinking away from building XPages that contain your implementation details, and instead focus on them providing structure to implement from metadata, it opens up a new world of possibilities. You can get yourself out of the business of massaging endless pages of visual components, and start to achieve real productivity gains.

Let’s take a further example of an easy win: what if in the future, the Form Table Row is enhanced to allow for a new labelPosition value? Perhaps “placeholder”? How much code would you have to change to leverage this feature across all your applications? Doesn’t “one line” sound like a fantastic answer?

P.S: What you’re reading here, by the way, is the Red Pill Methodology for XPages applications. This is the ONLY WAY we build XPages apps. And yes, there’s a lot more to it than I’ve discussed so far. We have a rich set of supporting technology that we share with our customers, and what I think are some excellent ways to determine how to extract the metadata needed to drive the above examples. But this methodology is the core reason my colleagues can do things like mobile-enable 39 applications in a single day.

Posted in Uncategorized
6 comments on “There’s a difference between knowing the path and walking the path
  1. spanky762 says:

    Thank you for this. I’ve been feeling as of late that I was “on the outside looking in” because I’ve been thinking about developing code in this manner for a while. Thanks for prying open the door and giving me a peek of what is on the other side.

  2. Pairing this with a clean way to specify models would make for some really smooth “bootstrapping” of new databases. You can sort of do that now with forms, though their validation is, to put it mildly, limited. If what you’re writing is a standard data-centric app, there’s no reason that your data model should be defined anywhere near the page… if there’s a single “Document” XPage, it could read the list of fields from the bean and display an appropriate UI for whatever document type you want to work with.

  3. Thanks for the simple presentation of the idea. I totally agree. I am working with Sencha Touch for mobile apps – and considering the same kind of patterns for XPage applications. But just starting by keeping it simple as your example may be a better approach than trying to reinvent the wheel (and thus not using much of what is presented to you as a developer in Domino Designer).

    Hmmm…. I think I am going to test some samples of this 😉


  4. Mobile applications are a good test bed for this kind of approach because they *should* be relatively simple. Though once you’ve proved the theory, extending it to more complex apps becomes more feasible.

  5. Don McNally says:

    Nathan, I am really intrigued by this but am too much of a noob to connect all the dots. Is the PageController class entered as a Java class design element? How do I connect it to the custom control? And how do I then populate the class, say from a Notes view? If something is out there to explain that, point me at it. I think it would be helpful to Domino people who haven’t seen that part of the story yet. Thanks a lot!

    • thentf says:

      In this case, the PageController class is defined as a Java class element. The object could be in a managed bean or could use an Object data source or perhaps even be set up in a scope variable in beforePageLoad. I didn’t show the resulting methods, but once you set up a shell of a class like that in the Java editor, you can right-click inside it and select “Source – Generate getters and setters.” That will set up all the methods you need to set values in them.

      From there, you populate it from a Notes object just like you would any other Java object. So if you had a document with fields called “databaseName” and “formName,” you could populate the PageController object with PageController.setDatabaseName(doc.getItemValueString(“databaseName”)) and so on. To do it from a ViewEntry instead you could use column values or whatever other method you like.

      In all likelihood, your PageController class would end up having something like .loadFromDocument(Document doc) to just handle all that at once.

Take the red pill.

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: