Do the Right Thing

I have seen a fair number of WebManager Component Bundles (WCBs) and I notice they come in all shapes and sizes. In this blog posting I will give some tips on how to build a Good WCB(tm) and Do the Right Thing.

In the beginning

Before you start typing commands, determine the DOMAIN and WCB_ID of your choice. Especially the WCB_ID will haunt you till the end of days. Refactoring a new name in can be a pain, since the WCB_ID is used in a lot of places.

Have the domain reflect your organisation or that of your customer, for example "com.mycompany".

The WCB_ID may consist only of lowercase letters. Yeah, that's right: no underscore, no numbers and no camelCase! If you are going for a public WCB, you might want to choose a unique, sexy and descriptive name because the WCB_ID will appear in the WCMexchange URL. It helps if you get the type of the WCB in there somehow. For example "xmaspresentation", "bookshopelement" or "wakeupservice".

Now that you have a solid idea of the names to use, you can start your WCB from a fresh archetype. For example:

mvn archetype:generate
  -DinteractiveMode=false
  -DarchetypeGroupId=nl.gx.webmanager.archetypes
  -DarchetypeArtifactId=webmanager-presentation-archetype
  -DarchetypeVersion=9.9.1
  -DgroupId=com.mycompany
  -DartifactId=xmaspresentation
  -Dclassprefix=XmasPresentation
  -s C:\GX\WebManager9\settings.xml

You can verify your choices in the file "src/main/java/com/mycompany/xmaspresentation/api/WCBConstants.java":

public final class WCBConstants {
    /**
     * The domain of this WCB, i.e. 'nl.gx.product'.
     * By convention the domain contains only characters
     * in the range [a-z] separated by dots.
     */
    public static final String DOMAIN = "com.mycompany";
    /**
     * The WCB ID of this WCB, i.e. 'helloworldpresentation'.
     * By convention the WCB ID contains only characters in
     * the range [a-z].
     */
    public static final String WCB_ID = "xmaspresentation";
}

While developing

Generating your WCB from an archetype should have left you with quite a nice piece of example code. It will compile right off the bat and it adheres to the WCB Guidelines. Really! Get the Guideline Audit tool and see for yourself.

You will want to stick to the guidelines, because they help you do the right thing. They are the result of years of experience in developing and maintaining code and deploying it to production servers.

For example: you should put your static files like images, css and javascript files not in "static" directory, but in a directory underneath that with the WCB_ID as name. The reason: static files are all written to the same directory on the server. You will want your files to be safe from being overwritten by other WCBs, so placing them in a directory with a unique name helps. And the WCB_ID just happens to be unique!

Hence guideline G140, which says "static files used by the presentation WCB are located in a subdirectory that equals the WCB ID."

Another example: the <name> in a descriptor XML file should be unique, or WebManager cannot distinguish between two presentations and will pick one at random. This uniqueness constraint goes for all presentations in all WCBs.

This is why there is a guideline that says "the value of the name attribute in the descriptor of a JSP is prefixed by the WCB ID" (G139)

<presentation>
    <-- G139: name attribute prefixed by the WCB ID -->
    <name>xmaspresentation page</name>
    <display-name>Christmas Page</display-name>
    <scope>Page</scope>
    ...
</presentation>

Many of the guidelines are verified by the Guideline Audit tool, which you can download for free. Be sure to run your WCB through it every now and then!

In the end

You probably noticed WebManager complaining in the logs that your WCB_ID was not registered. It is easy to fix; just go to www.wcmexchange.com, log in and select the "Register a new WCB" from the "WCB Publishers" menu.

After registering the new WCB, you can examine its data and copy the WCB key (it will look like a long string of letters and numbers). Then open the Activator.java and uncomment and complete the line with setWCBKey(), e.g.:

componentBundleDefinition
     .setWCBKey("ce552f79ec6c1d82daca14140d1aac30");

Also check to see if you updated your documentation. Your WCB was probably generated with an online help service embedded. In the directory "src/main/resources/help/en_US" you will find a file "index.html" that you can fill up with useful help for WebManager editors trying to get the maximum out of your WCB.

If you want to distribute the WCB via WCMexchange, you can upload the WCB there. You have two choices: upload the ".jar" file (WCB without source code) or the "-dist.zip" file (includes source code). Either can be used in the WCB Management Console, read: it is not necessary to compile a distribution. However, the "-dist.zip" can be unpacked on disk to get the full development source code tree.

Well, that is all for today. I hope you found a few pointers to do the right thing when developing your own WCBs!

Todays video simply has to be from Spike Lee's movie. :-)

See you next time!

Greetings,

Patrick