Tip of the Iceberg

Category xpages
Disclaimer: today's tip adds no fancy features or functionality to your applications. It does not improve the end user experience in any way. What it does, instead, is make it easier for you to see at a glance where the custom controls referenced within any XPage (or within another custom control) come from.

A recent comment on an old post reminded me just how confusing XML namespacing is. For the uninitiated, an XML namespace associates a tag prefix with a URI. Here's an example familiar to anyone working with XPages:

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

In the above example, the "xmlns:xp" attribute associates the xp prefix applied to the view tag with an ibm.com URI. This distinguishes a view tag that uses the xp prefix from a view tag with any other prefix (or none at all). It simply means that the object or concept associated with that tag is unique, different from any other type of view tag. This namespacing convention allows anything parsing the XML content to make that distinction.

I suppose you could equate this with Java's "packages", which allow one to distinguish - for example - between the Document class in the Domino Java API and the Document class in the W3C DOM API by referring to them by their entire package name: respectively, lotus.domino.Document and org.w3c.dom.Document. What makes this similar to XML namespacing is that both are intended to identify not only the category, but also the origin of the entity... presumably to make it easier to find documentation about, or perhaps even assistance with, interacting with said entity.

In the case of XML namespacing, one item that has always confused me (and perhaps others) is that the URI used to define a namespace can be entirely arbitrary - it doesn't even have to exist, much less have anything to do with the XML entities to which the namespace is applied. http://www.ibm.com/xsp/core does not take you to documentation on the XML schema for XPages. In my opinion, it should, but it doesn't... in fact, it's a 404. The only purpose of the URI in this context is to distinguish tags that use the xp prefix from those that don't in a way that gives some indication of who or what defined them.

The default namespace URI for a custom control is "http://www.ibm.com/xsp/custom"; the default prefix associated with this URI is "xc". Like the previously mentioned URI, this one also goes to an error page. It's still marginally useful, because it distinguishes "custom" controls from "core" controls, though once you've spent any amount of time on the Source tab of XPages, you grow accustomed to knowing that tags prefixed with xp are core and those with xc are custom without having to periodically glance at the view tag to remind yourself of its namespace URI. But there's a small problem: I don't know where the control came from... I just know that it's custom. Given that the whole point of custom controls is the ability to create your own - and consume those that others create - I suggest overriding the defaults on every custom control you create, especially if you plan to publish the source of the application that contains the control.

For example: although I haven't had time (yet) to work on an XPage interface for DesignCatalog, when I do, it will most likely contain a custom control called "ElementVersionHistory". If, on the main properties pane for that control, I simply change the namespace URI to "http://www.openntf.org/Projects/pmt.nsf/ProjectLookup/DesignCatalog", and the default prefix to "designCatalog", then adding that control to an empty XPage would result in source XML that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
    xmlns:designCatalog="http://www.openntf.org/Projects/pmt.nsf/ProjectLookup/DesignCatalog">
    <designCatalog:ElementVersionHistory></designCatalog:ElementVersionHistory>
</xp:view>

In case it's not immediately apparent, this has at least two benefits:

1. When digging through the source of a complicated XPage, I can immediately see where each of my custom controls came from. Maybe it's from an open source project like DesignCatalog, maybe from a control library I purchased from an ISV (I haven't seen any hit the market yet, but I'm convinced there's going to be a huge market for this within a year or two), maybe from a template our organization has developed internally for storing these reusable components... or maybe this control was just developed specifically for this application. In any case, instead of seeing an xc prefix on every custom control, I'll know at a glance that certain controls are bundled into something larger... which should make the code more maintainable.
2. At the top of every parent component (whether an XPage or a custom control that references other custom controls), I have a set of website addresses for information about each type of control that component references. To revisit the scenarios listed in the first point, the namespace might be the project page for the OpenNTF project the control comes from; it might be the product wiki for the control library we purchased; it might even be an intranet site that details the design of all of our organization's own custom-built controls. Or it might be the location of our documentation for this specific application. No matter where the control came from, you know where to find more information about it.

In short, this approach to control namespacing is an easy win, because it's a rapid way to answer your maintenance programmers' two most likely questions: Where did this come from? How do I use it?

(NOTE: if you fill in the description of the control on the same properties pane, this can answer additional questions, but only via a tooltip when hovering over the control in the palette.)

P.S. Dear IBM, might I suggest that you add a URL redirect so that http://www.ibm.com/xsp/core takes us to a javadoc page for all the core controls? Yes, I know, we can use reflection to query a list of methods each control supports and the parameters each method supports... but wouldn't it just be easier if you documented this for us? If I'm not mistaken, Eclipse will spit out the HTML for you, so it's not like this would be "tricky" (or even time-consuming) to do. Just sayin'...