Workshop Controls and Extensions: Part 2 - Documenting Controls

by Emmanuel Proulx
06/06/2005

Abstract

A BEA WebLogic Workshop control should be augmented with solid documentation. In the second installment of the WebLogic Workshop Controls and Extensions series, we'll talk about what needs to be done to make your controls usable, and even be accepted by the BEA verification process. We'll take a plain-looking control and add JavaDocs, a user guide, attribute descriptions, sample applications, and the infrastructure needed to merge this to the WebLogic Workshop help system.

Introduction

So you've developed this really cool control and you'd like the world to use it. You can't just send people a ZIP file and hope they can manage. You have to deliver your control on a silver platter. An important part of this process is documentation. This article discusses the steps you need to take to document your control.

Documentation isn't just important for the end-user to be happy; it's also an important aspect of the validation process for controls. Validation means that an independent organization (for example, ComponentSource.com) evaluates your controls to make sure the controls work well in WebLogic Workshop, following a provided test plan.

Starting Point

As a base for our article, let's start with an existing control, one that doesn't have all the necessary documentation. This control is a helper component to send and receive email. We will then make this control complete by adding the necessary documentation. See the download section for pointers to this base control. If you download the code, you can work through this article, applying the techniques to this base control.

Once we're done, the final control will have:

  • API documentation
  • A user guide
  • Control attribute descriptions
  • A table of contents
  • A pair of sample applications that use the control

Finally, we will test the control documentation.

Note: Extensions can also provide documentation, but this is not as vital as for controls. The API and control attribute documentation, as well as sample applications, do not apply to extensions. You can write a user guide and table of contents for an extension using the same methodology described in this article.

Validation Process

The validation process certifies your controls and extensions against a version of BEA WebLogic Workshop, proving that they work well together.

Validation isn't mandatory. You can extend WebLogic Workshop and distribute your product directly to the users. You can also post your creation to repositories, even the ComponentSource site. Some people prefer not to validate their controls and extensions because this process is a bit pricey. But validation is a requirement to getting in BEA's Premier Component Gallery site.

Emailer Control

Let's now turn to the base control. The Emailer control facilitates sending and receiving email messages. It is provided as start.zip in the download section. Unzip this file and double-click on EmailerApp.work. Choose the default (sample) WebLogic Workshop server instance. Figure 1 shows the control in question.

Emailer Control
Figure 1. Project structure

The topic of control authoring isn't covered here. If you need more information on this topic, refer to the article Advanced Controls Development Primer, or view the online documentation.

Here we can see that the control offers three methods and a callback. Internally it uses the timer control. This control can be used to send email ( sendMail() method) and to receive email ( getMail() or calling start() and waiting for the receiveMail() method to call back).

Notes on the source code:

  • When using a callback to push events to a user class, it is important to also provide a polling mechanism. This is because callbacks cannot be used with web applications.
  • This control has a full set of JavaDocs. If your control doesn't have good JavaDocs, write them now.
  • Exceptions thrown by the controls should be inside a ControlException or subclass.

Directory Structures

We start from an application containing multiple projects, and at the end we want to produce a single installation ZIP file containing the project's controls, documentation, and samples. This ZIP file has a specific structure, which we'll discuss here.

First, the following set of documentation is needed, all in HTML format:

Application Folders and Files Contents
EmailerApp/Emailer/doc/ en
/partners/ dev2dev/...
Root of all documentation. The en means English (which indicates other languages can be supported). The dev2dev folder is used here to represent the company name. This folder also contains the table of contents files. The doc folder will be added to the destination folder help in the installation ZIP file. The installation process will ultimately put these files under C:\bea\weblogic81\workshop\help.
.../java-class/*.html Generated JavaDocs. Don't confuse this with the folder javadoc-tag (below).
.../javadoc-tag/jc/*.html Description of the Java control's attributes. For example, the Emailer control attributes will be described in the file Emailer.html in this folder. It's analogous to JavaDocs for the Emailer.xml file.
.../guide/*.html The control's user guides. Use any folder and file names you want ( guide is only a suggestion). In our case we'll make a single index.html here containing the steps for using Emailer.

The final Emailer control itself must be added from the EmailerApp/Emailer project into the /controls folder in the installation ZIP file (minus the doc folder, of course). The installation process ultimately will put these files inside each application that uses the control, in the folder APP-INF\lib.

In addition, at least one example application (sample) must be provided with the controls. It must illustrate how to use the controls. I suggest writing two samples. Here are the samples we will work on:

Application Folders and Files Contents
EmailerApp/WebappEmailerSample/* Web application sample. This is a web-based email site. It uses polling to retrieve new email.
EmailerApp/WSEmailerSample/* Web service sample. Invokes the Emailer to order t-shirts. Order confirmations are also received as emails. This illustrates pushing received emails.

They will both be copied to the destination folder /samples/partners/ dev2dev in the installation ZIP file, and the installation process will eventually put them under C:\bea\weblogic81\samples.

Note that this application folder structure is only a suggestion, but it is close to the prescribed installation ZIP structure.

Once the project is done, building it will produce an installation ZIP file with the structure shown in Figure 2.

Installation ZIP file structure
Figure 2. Installation ZIP file structure

Generating the JavaDocs

By default, WebLogic Workshop doesn't create the JavaDocs when compiling the source code. This step must be added to the build process manually. To do this, follow these instructions:

1. Create the Ant build file: Go to the menu Tools | Project Properties | Emailer. In the window that appears select the Build category and click on "Export to Ant file". Click OK to close the dialog. This creates the file EmailerApp\Emailer\exported_build.xml. To replace this non-standard name, rename the file to build.xml.

2. Elect to use the Ant script: Open the Emailer project properties again. Still in the Build category, click on "Use Ant build". This should automatically select build.xml as the Ant file, and "build" as the build target. Click OK again. Figure 3 illustrates the first two steps.

Exporting the build script
Figure 3. Exporting the build script

3. Augment the Ant script with <javadoc> : Add the following:

  <javelin ...> ... </javelin>

  <!-- Add this call right after the <javelin> tag of the

       compile target. -->

  <antcall target="javadoc"/>

  ...

  <!-- Add this target right after the compile target. -->

  <target name="javadoc">

      <javadoc author="false"

               destdir="${project.local.directory}/doc/java-class"

               version="true"

               use="true"

               windowtitle="Dev2Dev -- Documenting Controls">

        <fileset dir="${src.path}" defaultexcludes="yes">

          <include name="dev2dev/emailer/**.java" />

          <!-- Exclude any class that's not part of the visible API. -->

        </fileset>

        <doctitle><![CDATA[<h1>Dev2Dev -- Documenting Controls</h1>]]></doctitle>

        <bottom><![CDATA[Copyright notice goes here.]]></bottom>

      </javadoc>

  </target>

Now, whenever you want to regenerate the JavaDocs, execute the javadoc build project, and the resulting JavaDocs will be placed in the /doc/java-class directory.

Writing the User Guide

This is the part where you can be creative. Write one or more HTML pages that describe how to use the controls. Save this in the new folder /EmailerApp/Emailer/doc/guide. This should also contain information about the sample projects. You should refer to the WebLogic Workshop Cascading Stylesheet (CSS) and JavaScript files, as follows:

<head>

...

<link href="../../../workshop.css" rel="stylesheet" type="text/css"/>

<a href="../../core/index.html" id="index"></a> <!-- Points to the main help site -->

<script language="JavaScript" src="../../../core/topicInfo.js"></script>

<script language="JavaScript" src="../../../core/CookieClass.js"></script>

<script language="JavaScript" src="../../../core/displayContent.js"></script>

</head>

<body>

<script language="JavaScript">

<!--

    displayInFrames(); // Change the display to the standard frame layout.

//-->

</script>



... Insert the documentation here ...



<script language="JavaScript">

<!--

    writeTopicInfo(); //Insert the standard footer.

//-->

</script>

</body>

After the merging is done the end result will appear as shown in Figure 4.

User's guide
Figure 4. User's guide

A very important question to ask yourself as you write HTML files is: Where are the files located? The CSS file is located in the help root folder C:/bea/weblogic81/workshop/help/doc/en. So our HTML files will end up a certain number of levels below this. Therefore, to refer to the CSS you must always put that number of ".." in front. The JavaScript files are inside the folder core below the help root. The <a> in the header won't be displayed, but it is used by displayInFrames() to find the root of the help site. All these (CSS, JavaScript, <a> tags) must point to the files in the correct relative locations.

All hyperlinks should follow this format to be displayed properly by the frame layout. For example:

<a href="javascript:reloadTOC('../javadoc-tag/jc/emailer.html')"

   >@jc:Emailer Tag</a>

Again, always use folder paths relative to the current file.

Writing the Control Attributes Description

The control-tags XML file must be included with controls. It lists the various attributes (parameters) of a control. Take a look at the file Emailer.xml for an example. Make sure there's a good <description> of each attribute. Make sure it contains the type of attribute, as well as the default, maximum, minimum, and prescribed values for each.

Now let's write another HTML file to provide online help for our control's attributes. Create the folder EmailerApp/Emailer/doc/javadoc-tag/jc and add the file emailer.html. At a minimum it should contain one section for each attribute, with a comprehensive description. It should also point to the same CSS and JavaScript files, and have that <a> tag. Here's an example:

<html>

<head>

<title>@jc:Emailer Annotation</title>

<!-- Other header tags as required here. -->

<link href="../../../../workshop.css" rel="stylesheet" type="text/css"/>

<a href="../../../core/index.html" id="index"></a> <!-- Points to the main help site -->

<script language="JavaScript" src="../../../../core/topicInfo.js"></script>

<script language="JavaScript" src="../../../../core/CookieClass.js"></script>

<script language="JavaScript" src="../../../../core/displayContent.js"></script>

</head>

<body>

<script language="JavaScript">

<!--

    displayInFrames(); // Change the display to the standard frame layout.

//-->

</script>

<div id="topictitle">

  <h1 class="Title">@jc:Emailer Tag</h1>

</div>

<div id="topictext">

  <p>Here are the attribute descriptions for a Emailer control:</p>

  <h2>Syntax</h2>

  <p class="syntax">@jc:Emailer</p>

  <p class="syntaxindent">transport=

    "<span class="syntaxpartname">imap</span>" |

    "<span class="syntaxpartname">pop3</span>"</p>

  <p class="syntaxindent">receivehost=

    "<span class="syntaxpartname">smtpOrPop3ServerToReceiveEmails</span>"</p>

  <p class="syntaxindent">sendhost=

    "<span class="syntaxpartname">smtpServerToSendEmails</span>"</p>

  <p class="syntaxindent">username=

    "<span class="syntaxpartname">smtpOrPop3UserName</span>"</p>

  <p class="syntaxindent">password=

    "<span class="syntaxpartname">smtpOrPop3Password</span>"</p>

  <h2>Attributes</h2>

  <p class="attribute"><a name="transport"></a>transport</p>

  <p class="partdesc">Mandatory. Enter of email server (can be 'imap' or 'pop3').</p>

  <p class="attribute"><a name="receivehost"></a>receivehost</p>

  <p class="partdesc">Mandatory. POP3 or IMAP email server's address 

     (to receive emails).</p>

  <p class="attribute"><a name="sendhost"></a>sendhost</p>

  <p class="partdesc">Mandatory. SMTP email server's address (to send emails).</p>

  <p class="attribute"><a name="username"></a>username</p>

  <p class="partdesc">Mandatory. POP3 or IMAP email server user name.</p>

  <p class="attribute"><a name="sendhost"></a>sendhost</p>

  <p class="partdesc">Mandatory. POP3 or IMAP email server password.</p>

<script language="JavaScript">

<!--

  writeTopicInfo();

//-->

</script>

</body>

</html>

Figure 5 shows the resulting page.

Control attributes
Figure 5. Control attributes

Writing the Table of Contents

The next step is to list all the files we just wrote in a WebLogic Workshop-specific XML file. Create the file toc.xml in the folder EmailerApp/Emailer/doc. This file is nothing more than a hierarchical set of <toc-node> tags. Each tag represents a document or a folder in the help system's contents tree. At the top of the hierarchy there's a <toc-reference> tag indicating where to "insert" these nodes. This is somewhat like an extension point for help files. Your controls should always be inserted in the reference named "extensions" as shown here:

<?xml version="1.0" encoding="ISO-8859-1"?>

<toc-root component="other" xmlns="http://www.bea.com/help/toc.xsd">

   <toc-reference anchor="extensions">

      <toc-node label="Emailer Control" url="toc.html">

         <toc-node label="User's Guide" url="guide/index.html"/>

         <toc-node label="@jc:Emailer Tag" url="javadoc-tag/jc/emailer.html"/>

         <toc-node label="Java API Reference" 

                    url="java-class/dev2dev/emailer/package-summary.html"/>

      </toc-node>

   </toc-reference>

</toc-root>

The HTML files listed here are relative to the location of toc.xml itself. You may wonder why we're listing the file java-class/dev2dev/emailer/package-summary.html instead of the more appropriate java-class/index.html. At the time I wrote this, there seemed to be collisions in the help system when two URLs are exactly the same. By pointing to a file in the folder dev2dev the collision is avoided.

The file toc.html contains a human-readable version of this table of contents and must follow the same syntax rules as the user guide and tag reference (regarding CSS, JavaScript, <a> tag), except the files are found in the ../.. folder (one level up). Here it is:

<html>

<head>

    <link href="../../workshop.css" rel="stylesheet" type="text/css"/>

    <a href="../../core/index.html" id="index"></a> <!-- Points to the main help site -->

    <script language="JavaScript" src="../../core/topicInfo.js"></script>

    <script language="JavaScript" src="../../core/CookieClass.js"></script>

    <script language="JavaScript" src="../../core/displayContent.js"></script>

</head>

<body>

<script language="JavaScript">

<!--

    displayInFrames(); // Change the display to the standard frame layout.

//-->

</script>

<H1>Emailer Control</H1>

<p>This is the complete set of documentation for the Emailer Control:</p>

<UL>

  <li><a href="javascript:reloadTOC('guide/index.html')">User's Guide</a></li>

  <li><a href="javascript:reloadTOC('javadoc-tag/jc/emailer.html')"

     >@jc:Emailer Tag</a></li>

  <li><a href="javascript:reloadTOC

     ('java-class/java-class/dev2dev/emailer/package-summary.html')"

         >Java API Reference</a></li>

</UL>

<script language="JavaScript">

<!--

  writeTopicInfo();

//-->

</script>

</body>

</html>

Figure 6 shows the HTML representation of the table of contents:

HTML table of contents
Figure 6. HTML table of contents

These two files represent the final documentation that's required. But we're not done yet. We also have to write a couple of examples.

Developing the Samples

Although only one sample is required, I suggest developing two sample applications. One should be a web application and the other a web service. These types of applications are the most popular ones right now. These samples should be well-documented, both inline (JavaDocs) and in the user guide for the control. Since it is not the aim of this article to explain how to use the Emailer control, you can write the samples any way you choose. Create these projects in the control's application, in folders /EmailerApp/WebappEmailerSample and /EmailerApp/WSEmailerSample, respectively. The following figures (Figures 7, 8, and 9) can guide you.

Web Application Flow
Figure 7. Web application flow

Web Application Actions
Figure 8. Web application actions

Web Service
Figure 9. Web service

These applications are provided in the finished project if you don't feel like developing them. I suggest you provide small, simple applications that illustrate how to use your controls in a different scenario. Don't feel like you have to show all the different ways you can use your controls in the same example; this may confuse your users.

Packaging Up the Control

Our control is now ready to be distributed. This can be done with a single ZIP file containing all the elements we created earlier, in the right folders. In preparation, the file build.xml must be modified slightly with the following. This command produces the three folders: controls, help, and samples. These are necessary to the installation process:

  <!-- Modify these properties. I prefer to use relative paths. -->

  <property name="app.local.directory" value="
                        
EmailerApp" />

  <property name="project.local.directory" value="
                        
EmailerApp/Emailer" />

  <property name="deliverable.docs.directory" value="
                        
doc" />



  ...



  <target name="make-deliverable" depends="build">

    <zip update="false" destfile="${deliverable.output.directory}" >

      <zipfileset dir="${app.local.directory}/APP-INF/lib"

                  includes="*.jar"  
                        
excludes="doc/**" prefix="controls" />

       
                        
<zipfileset dir="${project.local.directory}/${deliverable.docs.directory}"

                  prefix="help/doc"/>

      <zipfileset dir="${app.local.directory}"

                  includes="WebappEmailerSample/**,WSEmailerSample/**"

                  prefix="samples/partners/dev2dev" />

    </zip>

  </target>

                      

To produce the ZIP file, first build the entire Emailer project. Then right-click on Emailer and select Build Control Deliverable in the menu. Verify that the ZIP file Emailer.zip is created in the /EmailerApp folder.

Verify Your Documentation

We're almost done. Copy Emailer.zip to the folder C:\bea\ext_components, which is the default folder for installed components. The last step is to make sure that the help files we wrote can merge with the help system. The merging is done the first time the control is used. So we'll need to make a dummy application, and insert our control inside it. At that point, the following folders are added: C:\bea\weblogic81\samples\partners\dev2dev containing both samples, and C:\bea\weblogic81\workshop\help\doc\en\partners\dev2dev containing our HTML files.

With a web browser, open the help file locate at C:\bea\weblogic81\workshop\help\doc\en\core\index.html. Our pages appear under the category "User-Installed Extensions". If they aren't there, make sure that the file toc.xml has valid syntax. You'll need to uninstall the control (erasing the two dev2dev folders), reinstall it, and reinsert it in a project before the fixed help files are merged again.

Another test is to go to the source view of a project, clicking in the @jc:Emailer tag, and hitting the F1 key. The context-help should come up. Similarly, you can press F1 while your cursor is in any Emailer-related API, and the JavaDocs should appear.

Conclusion

We've seen in these few pages how to write a comprehensive set of useful documentation. Was it worth it?

Imagine you don't know how to drive a car. How would you feel if someone just handed you the keys to a new car and said "good luck." Your car-driving experience would likely be catastrophic. You'd probably never want to use a car after that. On the other hand, if the car came with its manuals, a driver guide, and driving lessons, chances are you'd be successful and couldn't see yourself without your new car. The car would be handed to you on a silver platter.

In conclusion, documenting your controls is an important part of the control development process.

In the next issue we will discover document templates, a less-known way to extend WebLogic Workshop.

Additional Reading

Emmanuel Proulx is an expert in J2EE and SIP. He is a certified WebLogic Server engineer.