By now, many (if not all) of you have heard about, and, perhaps, even already installed and begun playing with, the recently released XPages Extension Library. There are a plethora of reasons to be excited about this project, but most can be folded into two categories of awesome:

With that context established, I've been asked by several folks to share my approach to storing control definitions directly in an NSF, bypassing the plugin installation process. Since I'm so fond of lists, here are two reasons why this can be useful:

To stretch the binary nature of this post just a bit further, there are really two types of files that comprise any component's definition: Java and XML. A Java class (and any other classes it might reference) defines the control's behavior, and XML files expose the existence of these controls to Designer (and the XPages runtime). The XML files can, again, be subdivided into two types: faces-config.xml and .xsp-config files.

If you've gone spelunking in the Package Explorer, you've likely already stumbled upon both of these types of XML files, because Designer automatically creates these for you as you're developing your application. The faces-config.xml file is created in WebContent/WEB-INF, and while I've never actually seen Designer contribute any content to it, it inserts a commented section where it would place its own contributions if needed. So if you're defining managed beans, for example, this is the file where you'd store that definition... so be sure to place that definition outside of that commented section. Any .xsp-config files automatically generated by Designer will be located in the CustomControls folder. Whenever you edit an XPage, you're really editing a .xsp XML file that tells Designer what Java to automatically generate for you. When you edit a Custom Control, however, you're really editing two XML files - the corresponding .xsp file, and a .xsp-config file that tells Designer that control exists. In fact, the existence of that .xsp-config file is really the reason that the icon for the Custom Control shows up in Designer; if the Java file that corresponds to the control didn't exist, it still wouldn't show up, of course, but even if it did and Designer hadn't created the .xsp-config file, the control would exist but Designer wouldn't know that.

Hence, the easiest way to include extension controls in an NSF without properly installing a control library is to simply create a linked source folder: right-click the application's folder in the Package Explorer, then select Build Path, Link Source. Browse to the top-level source folder (typically called "src") for the control library, set a folder name that will be unique in the NSF, and click Finish. In the case of the Extension Library described above, at a minimum you'll probably want to link the core plugin ("extlib"), "extlib.domino", and "extlib.oneui", but there's some other cool stuff in there as well (for instance, "extlib.dwa" includes the iNotes Calendar view as a control... let that one sink in for a moment...).

Because both the Java classes and the corresponding XML files are contained in subfolders of your linked source folder, as soon as your application finishes rebuilding (which will take a while, especially if you're linking to several of these plugin folders), you'll see the icons for the controls show up in your palette. Be warned, however: since a lot of these controls are fairly sophisticated, actually using them without properly installing the plugin is going to be hit or miss. There's a lot of other stuff going on behind the scenes that the OSGi framework allows which you can't really take advantage of unless it's treated as a true plugin. But here's something that might help: if you locate the faces-config and xsp-config files for each of the plugins you linked to (in each case, they'll be stored in a META-INF folder inside the src folder), drag them into WebContent/WEB-INF in the NSF. This ensures that they're actually stored inside the NSF and not just in the workspace folder in your Notes installation. I've found that, for some of the controls in the Extension Library, this is perfectly sufficient. But here's another word of warning: if you do take this linked source approach - at least with the Extension Library, which contains approximately 800 Java classes - every time you make any change to any XPage, the build process is going to be sloooooow, because you've introduced an additional layer of complexity into what Designer has to do in order to determine exactly what code the application contains. So you've circumvented the admins. Great. You've also just punched your productivity in the face if you don't have an SSD.

There is good news, however: on an individual control basis, there's a much better way. Add your own src folder to WEB-INF, designate it as a src folder, and create your control classes within that folder. Then add a .xsp-config file for the control to WEB-INF and, if needed, define its renderer in the faces-config.xml that's already there in the same folder. That works like a charm.

There are additional caveats, of course. The most obvious is that this is fine for a couple controls here and there, but gets unwieldy when you're maintaining large sets of controls, since you have to copy several categories of files to every NSF where you want to use them. In other words, I'd advise against taking this approach for the entire Extension Library. If there's a specific control you want to use, and you can isolate every Java source file it uses and know that it's not also relying on images, CSS, and JavaScript libraries that are bundled with the plugin (yes, you can do that... this is some of the "other stuff going on behind the scenes" to which I referred earlier), go for it. But if you're looking to pull in something as complex as the JSON-RPC control or dozens of simpler controls... just take the blue pill and walk away.

Much less obvious caveat: if you're configuring your control this way for testing purposes - for instance, you've already got a plugin library installed, and you're just developing a new control that you want to add to it - this works fine as long as the control is an extension to a native component (UIComponent, UIInput, or one of the core controls that ship with Domino). If, however, you're extending an extension (maybe you dig IBM's Dialog implementation but want to automate the addition of OK and Cancel buttons), the Java class for the base component must be directly in the application's build path - not in the plugin dependencies - even though at runtime the classloader would be able to find it. If Designer can't find it in the build path, the icon won't show up in the palette. Yes, I learned this the hard way.