Your Development & Design Resource
Using Custom Control Design Definitions for development documentation
12/15/2011 04:27 AM by Chris Toohey
IBM Lotus Notes and Domino XPage developers - like any developers - hate documentation. Most applications are lucky to have comments in the code, but how can we add documentation to Custom Controls? This quick article shows you one technique that might do the trick!
I rarely use the Design Pane when developing XPage apps. I just feel more at home hand-writing the XSP markup anymore. I can never seem to get the drag-and-drop working. Double-clicking often sends the control outside of the target where I could have sworn my cursor last was. And there's absolutely nothing like jumping directly into the XSP markup via the Source pane and making it do what you need it to do!
But I know a lot of XPage developers still use the Design pane, so this one is mostly for you.
I recently needed a rather simple but reusable solution that required use of an HTML IFRAME element. Being a fan of Custom Controls, I thought I'd create a rather simple one:
<?xml version="1.0" encoding="UTF-8"?>
This Custom Control (
cc_iframe.xsp) has three rather simple
|Property Name||Property Definition|
|elementSRC||Define the relative or explicit URL to the target source for the control's generated IFRAME HTML Element|
|elementID||Define a simple HTML Element ID control's generated IFRAME HTML Element|
|elementCLASS||Define one or multiple ClassName property values for the control's generated IFRAME HTML Element|
As I rarely even see the Design pane, I thought nothing of the visual my Custom Control would have for anyone using it.
In other words, I was shocked by just how plain ugly and broken-looking my simple Custom Control appeared when viewed in the Design pane:
cc_iframe.xsp - Design Pane (ugly)
Yeah, that's pretty awful.
So I thought I'd use the Design Definition of the Custom Control to make the visual more appealing.
For those of you unfamiliar with a Design Definition for a Custom Control, that's its purpose: it is an container that accepts XSP markup. Whatever markup you have within the Design Definition will change the way the Custom Control is rendered in the Design pane. It does not change the way the Custom Control is rendered when used.
If you don't have a Design Definition defined, the visual will come directly from the source XSP markup. Also, I should point out that you really only see a Design Definition-based rendering of the Custom Control when it's used in another Custom Control or XPage. If you toggle between the Source and Design panes within the actual Custom Control, it won't change regardless of the use of a Design Definition.
... so back to the
cc_iframe.xsp and it's current ugliness.
I was totally at a loss. What could I add to make it look more IFRAME-ey?! An IFRAME is a bordered-box after all... so it's kinda doing it's job Design pane-rendering wise already.
And then it hit me: why don't I use the Design Definition for documenting just what the heck the Custom Control does.
I added the following XSP markup to the Design Definition tab (in the XPage Properties section):
<?xml version="1.0" encoding="UTF-8"?>
style="padding: 4px; border: 3px solid green;">
<strong>Custom Control Information</strong>
<xp:td>Chris Toohey - dominoGuru.com</xp:td>
Custom Control Properties (see below for details) to create a
simple yet easily customizable HTML IFRAME Element.
<strong>Custom Control Properties</strong>
<xp:td>Define the relative or explicit URL to the target
source for the control's generated IFRAME HTML Element</xp:td>
<xp:td>Define a simple HTML Element ID control's generated
IFRAME HTML Element</xp:td>
<xp:td>Define one or multiple ClassName property values for
the control's generated IFRAME HTML Element</xp:td>
align="center">Feel free to contact the author at ctoohey@dominoGuru.com,
and find more IBM Lotus Notes, Domino, and XPages development
articles and resouces online at www.dominoGuru.com!</p>
This gave me a much more useful Design pane-rendering of my
cc_iframe.xsp Custom Control:
cc_iframe.xsp Custom Control with Design Definition
Now, when a developer uses my
cc_iframe.xsp -- or more
accurately, when I have to modify an application which uses this Custom Control
-- I'll know what the heck I'm in for.
Man, if more developers used this technique, I might actually use the Design pane again!