Using Design Definitions for XPage Custom Controls

06/26/2012 03:15:00 PM by Chris Toohey

For those IBM XPage developers using the Design pane, Custom Control Design Definitions can be an invaluable tool. Here are two examples of Design Definitions that provide Custom Control insight and functionality to the Design pane...

Visual Aid Design Definitions

I'm currently working on a customer project that I will eventually "hand off" to a customer in-house developer to maintain/enhance as needed. As such, I tend to be more verbose in my code and design.

One of the requirements for this project is to integrate Google Maps (via the Static Maps API) and display various maps of locations with custom markers, paths, and more.

While my map_static Custom Control is full of configurable goodness via various Custom Controls that "wire" the Control to be used completely "at will"... since it's really nothing more than a core xp:image Control with a computed url Property, it's very difficult to point out in the Design pane.

map_static Custom Control without a Design Definition

By adding the following Design Definition to our map_static Custom Control, we can give a much more recognizable display for our control when viewed in the Design pane:

Note that this is really nothing more than an core xp:div Control with a CSS style applied to set the height and width to the desired size. Additionally, the CSS is using an Image Resource that I've included in the NotesDatabase specifically for the Design Definition as the background image.

Once added to our Custom Control, map_static will now display like this in the Design Pane:

map_static Custom Control with a Design Definition

Functional Design Definitions

Most XPages developers eventually create their own layout Custom Controls, even if they're simply extending the Extension Library ApplicationLayout Control (xe:applicationLayout).

To simplify things, let's take a look at a rather basic Dojo borderContainer-based layout using nothing but core XPage controls:

Note that I'm using the ExpandoPane Dojo Modules as well to give my layout a flexible (and animated) sidebar.

If we take a look at this Custom Controls sans Design Definition in the Design pane, you'll get the following:

cc_layout Custom Control without a Design Definition

Functional (with the xp:callback Controls readily displayed), but not very representative of the actual layout that you get with the Dojo borderContainer "sidebar" layout.

If I add the following Design Definition -- which includes identically-named xp:callback Controls -- I can get a better visual representation of the Dojo borderContainer layout while still maintaining the callback functionality!

When viewed in the Design pane, I now have the following look for my cc_layout Custom Control:

cc_layout Custom Control with a Design Definition

Conclusion

Take the time to use Design Definitions. No excuses. If you work with a team of developers, you will immediately improve everyone's ability to pick up your code (in the case of re-assignment/vacation/hit-by-bus). If you're the only developer... imagine coming back into the project 6 months later after Google (for whatever reason) changes the Static Maps API, and you now have to look through the Display pane for the specific xp:image-looking Control that is actually your map_static Custom Control.

Sure, you can use the Outline, or the Source pane for that matter... but the point is that you can not only create living documentation from your Custom Controls using Design Definitions, but you can also make it even easier to use them.