Your Development & Design Resource

XPages Resources via Themes or Custom Controls?

XPages Resources via Themes or 
Custom Controls?

I've been pondering the following question for quite a while, and wondering if anyone else has some insight into what exactly a Best Practice would be:

Should we include Dojo Modules, JavaScript Libraries, Linked Resources, Metadata, Resource Bundles, Stylesheets, and Dojo Module Path Resources via Server or in-NotesDatabase Themes, or simply via layout Custom Controls?

To give you more information before you gut-check respond "Themes!", here's what I'm getting at...

The majority of the multiple-client XPages-based applications that I write use a technique that I first saw employed by Declan, as I'm a big fan of creating client-specific user interfaces and thus client-specific user experiences. The technique uses a core xp:include Control with a computed pageName property based on the UserAgent (which itself reports the client type). Basically, if I want a Home.xsp page for a web browser and an iPhone, I'll create 3 XPages: Home.xsp (which is blank, save for the xp:include), and a Home_browser.xsp and Home_iphone.xsp which I load based on the reported UserAgent. All of the device-specific UI/UX is contained within the included XPage.

A benefit to this technique is to allow me to easily test a given XPage on a given client via a direct URL (eg., "Home_screen.xsp").

As I typically do, I'll create a layout Custom Control for my XPages application. Combining this technique, there is a layout_screen.xsp and a layout_iphone.xsp Custom Control, which are designed to be used in each "_browser" and "_iphone" XPage I need.

(Another aside, I often have a "_browserOLD" layout Custom Control and set of XPages to handle IE6/7/...8.)

Traditionally, I've used Themes (both at the Domino server level and in-NSF) to handle any Resource inclusion... but maintaining those Themes, their rendered logic, et al can be extremely tedious.

Lately, I've been including any Resources directly in my layout Custom Controls with great success. Since these controls are included in every page (specific to the device), I can better simplify the rendered logic... and quite frankly, it helps having things more easily surfaced in the layout controls when you return to update an XPages app 6 months since you've last touched it.

Themes still play a large role in my development and maintenance of these applications, mind you, but ironically not in the role that I feel most developers use them: they act more "globally", setting values on XPages (eg., createForm="false") and on individual "common" controls. And, of course, they manage styleClasses and other properties for various controls.

... I'm just not using them to include a Stylesheet anymore.

So what's your experience with including Resources? Using Themes or Custom Controls? Share in the comments below, and maybe we'll establish a true Best Practice!

About the author: Chris Toohey

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

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

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.