Your Development & Design Resource

How to use 2 CSS Rules to replace the IBM Domino XPages Extension Library Picker Icons

I'm sharing this technique more to both to highlight the technique itself as well as provide a "quick win". A future article will cover alternative and "best practice" techniques. In other words, please remember that this is a cool little quick-fix before you post a comment about Custom Render Kits or the Extensibility API...

The IBM Notes Domino XPages Extension Library (or ExtLib) controls offer a level of configurability and flexibility that addresses most XPages developers needs... but for those XPages developers looking to do something different with a control that's either beyond the scope of the original intended use or simply wasn't conceived at the time of the creation of the control, that Properties pane can look rather limiting.

Let's take a look at the Properties pane for the Value Picker ExtLib control:

ExtLib Value Picker - Properties pane ExtLib Value Picker - Properties pane

If you want to change the icon of the ExtLib Value Picker control, you need to specify an Image Resource or the path of an alternate image. No big deal.

Icon Fonts have been used more and more for browser-based applications due to their flexibility: they scale much better than their image counterparts and you can easily manipulate them via CSS (color, rotation, etc.). The scaling argument is important when you're writing cross-client web browser applications, especially with the ever-increasing device screens and resolution bumps. And do you remember how you had to have "on" and "off" state images? Yeah, you don't need those anymore...

But there's no way to set a iconFont from the Value Picker Properties!

To do that properly, you would want to create a child node HTML Element with a className that matches the icon you want to use based on the Icon Font library. For example, Glyphicon (which is used in Twitter Bootstrap) uses the glyphicon glyphicon-search classNames. If we wanted to use the "search icon", we'd create a child node HTML Element such as an italic element with a className of "glyphicon glyphicon-search":

For those of you wondering why we're using the italic HTML Element here, there are arguments all over the web with the pros and cons to this technique. You can use a SPAN HTML Element instead with role and aria-label attributes, but that's something to cover in another article.

... now before we continue, let's take a look at how exactly most Icon Fonts work, and we'll do that by looking into the CSS files for Twitter Bootstrap.

If you open bootstrap.css in the text editor of your choice, you'll see the following rules:

These rules load a new "font" named "Glyphicons Halflings", which will be enabled when you use the .glyphicon className. The second className is the specific image that you want to load. In our case, we'll be using the .glyphicon-search className, which gives us the magnifying glass icon that best matches the default Value Picker control icon.

Or we would have, if we could create a child node HTML Element inside of our View Picker control...

Since we can't simply add a child node, we'll instead see if we use CSS to manipulate the HTML that's already there.

Here's the resulting HTML markup that's sent to the browser:

Not much to work with there... or so it would seem.

Let's get a handle on the "Open Picker" image HTML Element using CSS Attribute Selection, or rather use a CSS rule selector that uses HTML Element attribute and value matches.

... and believe it or not, that works! CSS Attribute Selection is part of the CSS 2.1 specifications from W3C, and is supported in every browser except IE6!

So let's create a CSS rule that gets a handle on the Value Selector image and make it so it never loads the image in the first place:

That keeps the Value Picker default icon (/xsp/.ibmxspres/.extlib/icons/iconNamePicker.png) from loading, but we still have to set our Icon Font-based "image". To do that, we'll use the CSS Pseudo-Element Selector, which again is supported with a few minor exceptions (none of which will affect our use case here):

Yep, that's it! Let's take a look at the before and after examples:

 Value and Name Picker ExtLib controls with default icons Before: Value and Name Picker ExtLib controls with default icons

Value and Name Picker ExtLib controls with Twitter Bootstrap Glyphicons After: Value and Name Picker ExtLib controls with Twitter Bootstrap Glyphicons

And here's our final CSS, which addresses both the Value Picker and the Name Picker ExtLib Controls:


Using CSS attribute selectors we're able to gain more control over the rendered user interface and better craft the user experience of our applications... without having to write our own custom implementation of - in this particular case - a Value Picker control. Sure, it was just an icon on a picker, but it's a start.

I'm often asked by fellow developers "is [whatever they're looking to do] possible?" I think most of those developers are falling victim to perceived platform limitations, or their given education, or perhaps even their familiarity with the platforms in question.

I always liked CSS Zen Garden, as it was an excellent showcase for understanding exactly what you're doing with client-side markup with applied "outside-of-the-box" thinking. XPages allow us to control 100% of the User Interface and the overall User Experience if we dive in beyond RAD, but with enough understanding of client-side markup manipulation and exactly what HTML, CSS, and JavaScript are capable of pulling off - even the more rigid XPages Core and ExtLib controls can be bent to your will.

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.