Creating Dynamic Input Custom Controls for IBM XPages with switchFacet ExtLib Controls

09/24/2012 by Chris Toohey

The Extension Library xe:switchFacet Control is quickly becoming my favorite go-to tool for Custom Control development work... but I don't think I use them in what might be considered a traditional sense.

Those of you familiar with a JavaScript Switch will immediately understand what the xe:switchFacet Control does. For everyone else (or for those of you looking for a "how a Lotus Notes developer would understand this" explanation), here's the breakdown:

Understanding the xe:switchFacet Control

At a glance, the xe:switchFacet reads like it's nothing more than a computed Subform. So let's get started by taking a look at a typical computed Subform.

For computed Subforms, a traditional Form Design Element uses some @Formula-driven logic to resolve which Subform should load at any given time.

Example Computed Subform for a Lotus Notes Domino Form

This Subform will use the value of the SomeField NotesItem on the Form/NotesDocument, and load the name-matched Subform. For example, if SomeField is "foo", it will load the "foo" Subform.

Where a Subform is external from the Form Design Element, the xe:switchFacet control actually uses the xp:this.facets facility to have really any control you wish as a child node of the given control. It computes which child node should be displayed at any given time based off code-driven logic.

Now let's take a look at a simple xe:switchFacet control:

This xe:switchFacet uses the selectedFacet property to evaluate which "xp:key"-keyed control it should return based on the currentDocument's SomeField value.

Unlike a Subform, the xe:switchFacet allows you to define a defaultFacet, in the event there is no matching keyed control.

Now that you've seen a basic xe:switchFacet control, let's look at a JavaScript switch function example:

Get the idea? The xe:switchFacet will only return the key-matched child control.

Using the xe:switchFacet Control

I love using xe:switchFacet controls in Custom Controls. The other day, I published example XPage markup using an xp:repeat control to display a custom control for "events". Here's that markup again:

If you look at the xc:tile_event properties, take note of the configuration.type property. This custom control employs an xe:switchFacet control that checks the configuration.type property to load completely different content based on the property value. As mentioned in that article, I could just as well as set the configuration.type property to "minicard", thus changing what was returned at runtime.

Pretty basic, sure... but let's take this to another level. (And finally discuss the main topic of this article...)

Let's take a look at my xe:dynamic_input.xsp custom control:

This control allows you to completely control which input-type control is returned to the user at runtime based completely on configuration vs. hard-coding the desired input controls into the XPage.

Want a simple xp:inputText control?

How about Rich Text?

What about a RadioGroup with selectItems based on an @DbLookup?!

Using the xe:switchFacet to control exactly what is returned at runtime based on Custom Control properties, I could literally wire every native property for any control, and simply pass values through to the controls based on something like a Resource Bundle.

-- or a "configuration" set of NotesDocuments.

In fact, I have a scenario for a project that I'm working on that required a non-technical user to create "surveys", each "survey" with completely unique fields and potential values. While I'm not saying that this exact technique should replace your standard XPages development of creating xp:inputText controls when you need a simple xp:inputText control, I am saying that the xe:switchFacet gives us options. And options can be an amazing thing.

Online Demo

Want to give it a spin? Check out the online demo for this article here:

xe:switchFacet Custom Controls IBM XPages Demo

Conclusion

It's another code-writing-code article... but hopefully this explains why I'm loving the xe:switchFacet control lately. Aside from the demo, I'm using this control to create single-element custom controls to house any/all of my NotesDocument rendering needs.

Need this repeat to display HTML Unordered ListItems (type="list")? Need it to display larger-scale HTML DIV (type="minicard")? Need it to display the entire document in a stylized read-only context (type="fulldoc")?

And the beauty of this is that I can just as easily add another keyed control to the xe:switchFacet-driven Custom Control and change what is displayed not through source code manipulation of various XPages... but in that Resource Bundle that defines which of my Custom Control's facets should actually display.

So are you using xe:switchFacet controls? If you didn't know about them before this article, how do you think you'll use them in your future XPages development? Comment/Like/Collaborate below!