dominoGuru.com

Your Development & Design Resource

Using Custom Control Design Definitions for development documentation

12/15/2011 04:27 AM by Chris Toohey

Using Custom Control Design Definitions for development
documentation 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"?>

<xp:view

    xmlns:xp="http://www.ibm.com/xsp/core">



    <iframe

        src="#{javascript:compositeData.elementSRC}"

        id="#{javascript:compositeData.elementID}"

        class="#{javascript:compositeData.elementCLASS}">

    </iframe>



</xp:view>

This Custom Control (cc_iframe.xsp) has three rather simple properties:

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"?>

<xp:view

    xmlns:xp="http://www.ibm.com/xsp/core">



    <xp:div

        style="padding: 4px; border: 3px 
solid green;">

        <p>

            <strong>Custom Control 
Information</strong>

        </p>

        <xp:table

            style="width:100%;">

            <xp:tr>

                <xp:td>Custom 
Control</xp:td>

                <xp:td>cc_iframe</xp:td>

            </xp:tr>

            <xp:tr>

                <xp:td>Author</xp:td>

                <xp:td>Chris Toohey - 
dominoGuru.com</xp:td>

            </xp:tr>

            <xp:tr>

                <xp:td>Usage</xp:td>

                <xp:td>

                    <p>

                      
  Define the

                      
  <code>elementSRC</code>

                      
  ,

                      
  <code>elementID</code>

                      
  , and

                      
  <code>elementCLASS</code>

                      
  Custom Control Properties (see below for details) to create a

                      
  simple yet easily customizable HTML IFRAME Element.

                    </p>

                </xp:td>

            </xp:tr>

        </xp:table>

        <p>

            <strong>Custom Control 
Properties</strong>

        </p>

        <xp:table

            style="width:100%;">

            <xp:tr>

                <xp:td>elementSRC</xp:td>

                <xp:td>Define the 
relative or explicit URL to the target

                    source 
for the control's generated IFRAME HTML Element</xp:td>

            </xp:tr>

            <xp:tr>

                <xp:td>elementID</xp:td>

                <xp:td>Define a simple 
HTML Element ID control's generated

                    IFRAME 
HTML Element</xp:td>

            </xp:tr>

            <xp:tr>

                <xp:td>elementCLASS</xp:td>

                <xp:td>Define one or 
multiple ClassName property values for

                    the 
control's generated IFRAME HTML Element</xp:td>

            </xp:tr>

        </xp:table>

        <p

            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>

    </xp:div>



</xp:view>

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!

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of dominoGuru.com, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.