Tuesday, November 12, 2013

"Configurable Buttons" Solution

In our business the ability to customize our customers' online functionality is key to driving sales and just as key to delivering successful results.  Consequently anything we make configurable on a granular level is a win for us and for customers.

Case in point: "Navigation" buttons.

Well, that's what we call them but essentially they are buttons at the bottom of an XPage that either Save data then go or just, uh, go.

Based on customer requests we determined that for maximum flexibility we needed to make all of the buttons configurable on a per-"record" basis.

Turns out this was one of the easiest and most straightforward tasks I've ever had to do with XPages because there were zero surprises.  Here's how we did it...

First we established a model where there were two "button bars" consisting of five "button slots" each.

Next we decided which properties needed to be configurable for each button:

Button Text - The text on the button
Style - CSS class(es)
Icon - Which Font Awesome Icon to include in the button before the text
Client Action - The client-side JavaScript the button may need to run
Save Action - Save as Draft, Save as Completed or None
Go Action - Next Page, Previous Page, Exit
Validate Fields - Yes/No
Full or Partial Refresh - partial or complete
Refresh Target - The target id of the partial refresh

We created a regular Notes form to hold the configuration for each slot and also included a field to name the button bar configuration (I'm not proud of this right now but we'll convert it to an XPage control eventually.)

Once we had the properties we needed to configure, we created two new Java classes.  Each class has getter methods that correspond to the properties listed above to provide the information needed by the buttons and the button bar.

1. A Button - Represents a single button
2. A Button Bar - Represents an entire set of ten buttons

When we need the button bars, we walk through all of the button bar configurations and read each of the ten button configuration areas to build that button bar.  We can have as many button bars as we need, each with a unique name and each button bar can have unique (or similar) sets of buttons.  The button bars are assigned to "records" via another configuration.

The Java classes representing the buttons and the button bars are instantiated via a session-scoped managed bean (of course the session scope is not a requirement to do this, that is just how ours works).  When we want to display the button bars we have a Custom Control that contains two repeat controls, one for the first five slots and one for the second five slots, that walk through the designated button bar's buttons to read the properties that need to be set on either the button control or the button control's event handler.

"You keep using that word. I do not think it means what you think it means."

I keep saying "button" because that is what they are in our application but the actual XPage control being used is the Link control.  Below are two screen shots showing the properties being set.

As I said earlier, this piece of work was truly one of the easiest things I have ever done with XPages because each of the properties we needed to set was able to actually be set right off.  I thought for sure I would get half way into this and there would be some sort of gotcha' but nope.  All good.

So there you go.  Not THE solution, but our (current) solution to a requirement we had.