Using the NotesDatabase Icon in your IBM Domino XPages Applications

04/01/2016 by Chris Toohey

In my experience, the vast majority of IBM Notes user still use the Workspace to launch their applications. Having a custom icon for your notesDatabase can give the user a simple yet effective way of visually finding the application they're looking for... but you should know that already. IBM Notes Domino developers have been using icons for years now - even back when we were limited to 16 colors and had to draw the 32x32 pixel icons ourselves!

And since v8.5.2, we've had the option of using 32-bit RGBA (which is a format that supports billions of colors and alpha-transparency). This means that we can use photo-quality images for our icon and not be limited to a square/tile shape since we can cut our "shape" using transparent pixels.

Mind you, we still have a 32x32 pixel size limitation for our notesDatabase Icon, but Notes developers were thrilled that we had more options for our notesDatabase applications.

The UI & UX Design Paradigm Shift... and Reshift

With the move to more web browser client use, notesDatabase icons began to play a far less important role in the application development cycle. They were often perceived as taking up valuable screen real estate and served no functional purpose, and - today - have about the same adoption rate of placing your company logo at the top of Every. Single. Application. in your organization.

... and then we started creating Mobile versions of our applications for use on smartphones and tablets.

The need for an icon for your applications changed as the icon took on a different - although actually quite similar to the IBM Notes Client - role.

The term "Web Clip" describes an application (or any HTTP/S accessible app/site/etc.) that uses a combination of HTTP Head tags and other meta data along with specifically-sized images to create a pseudo-"App" launcher for your bookmarked web apps. A "Web Clip" can be added to the Home screen, meaning that - just like with our IBM Notes applications - you can have an easily-recognizable launcher for your application.

Here's an example of one of my latest XPages applications, shown as a "Web Clip" on my Android smartphone:

'Web Clip' IBM XPages Application on Android smartphone.

-- and the reason I specifically say "my Android smartphone" as this functionality is available for Android devices as well as the Apple iOS devices where the "Web Clip" originated.

Now before we proceed further, let's quickly cover how you can do this in your own IBM XPages applications!

Creating "Web Clip"-friendly IBM Domino XPages Applications

Step 1: Find an icon for your application.

First and foremost, you need to find an application that is both a good candidate for use as an application icon and visually represents your application. Here's what I look for in an application icon:

1. Is it simple yet descriptive?

   With the heavy use of FontAwesome, GlyphIcons, and the whole "Flat UI" movement for the web, Metro UI for Windows, and Material Design for Google, the rich icons of yesterday have been replaced with almost minimalist versions of their rich, 32-bit counterparts. This change has a purpose: You'll want something that can be resized - if possible - to match the 16x16 24-bit RGB requirements for a favicon while also looking great as a 512x512 32-bit RGBA tile on a super-resolution tablet. Considering this, does your icon match the current standard while also giving the user an idea of what the application is used for? If you're lucky enough to find one that matches both of those criteria, put that on the short list of icon candidates.

2. Is it consistent with my other application icons?

   Ideally, I look for an entire iconset - the bigger, the better. Something that I can browse to find an icon that meets my first criteria. If you go with an iconset, you're going to get a consistent "feel" for your "Web Clip" applications. Considering this, does your icon candidate come in an iconset? If so, proceed...

3. How easily can I modify it?

   Does this icon come in a format that would allow me to either change the color of the icon? If it's not a full-tile icon, can I get a format where the background is transparent so I can easily change the color - or opt for the transparent version - as-needed? And what size is it? You can go with a 512x512 32-bit RGBA PNG so you can adjust the size and overall design to meet your needs. Ideally however, you'll find either an SVG-based icon or an icon where the original author cut a series of common sizes and has addressed any resize-based image degradation.

Where can you find such an icon?

Queens!

Try iconArchive.com, which has tons of licensable icons (and complete iconsets) for your choosing.

My current go-to Iconset is the Windows 8 Icons by Icons8.

The icon from this iconset that I chose for my latest IBM Domino XPages project - which tracks gratuities and other non-salary payments for various events and services - was the Finance Cash Receiving Icon.

Finance Cash Receiving Icon - Windows 8 Icons by Icon8

Step 2: Modify the icon to match your needs.

Now that you have your icon, you've got to make it your icon. For this particular icon, I didn't need to add anything to the design as I think this transparent-background "shaped" icon works great without the need of a "tile" background... but I did need my "Web Clip" size versions.

And by "versions" I mean versions, as I'll need a 60x60 "default" size as well as 76x76, 120x120, 152x152 and 180x180 (pixel) versions of my icon.

So with GIMP - a free & open source image editor - I created my icons by resizing the various stock sized versions of my original icon.

apple-touch-icon.png (60x60)

icon_76.png (76x76)

icon_120.png (120x120)

icon_152.png (152x152)

icon_180.png (180x180)

And while I'm in there, I might as well create a 32x32 version (if needed, this particular icon already had a 32x32 version) for the eventual notesDatabase Icon. For now, just set that 32x32 icon aside, as we'll talk about that later in this article.

Step 3: Set your HTML Head and meta tags

If you're using a layout-type XPages Custom Control for your XPages, you can add these Resources there or directly in your XPage:

This generates the following in the HTML Head of your XPage:

Now, you'll see a references SSJS object named basehref. In my "application.jss" SSJS library I have the following function and object declaration:

Yep, that basehref is a global variable available through my application. How's that for a quicktip! Moving on...

Wait... haven't we covered this before?

Yep: IBM XPages headTag HTTP Headers for iOS Webclip Applications Icon Sizing, originally published on May 21, 2012.

So why bring it up now? To answer that, let's talk about Twitter Bootstrap.

Using the notesDatabase Icon in Twitter Bootstrap

If you took my advice from earlier in the article, you have a 32x32 version of our "Web Clip" icon. We'll use that as the actual notesDatabase icon.

IBM Notes Domino notesDatabase Icon Settings

Now that it's set, we can access the notesDatabase icon via the following URL syntax:

http[s]://server/notesDatabase.nsf/$icon

Yep, using the $icon operator/reserved name/whatever will return the notesDatabase icon. But now that we have access to the icon, let's discuss how we can effectively use it.

The Twitter Bootstrap navbar-header

Anyone familiar with Twitter Bootstrap knows what the navbar is, and I've used sticky navbar at the "top" of my application layout, and am using a few SSJS functions to build my markup:

While this function is used to build my complete top navbar and sidebar navbar, here's an abstract of the rendered HTML that you'll want to focus on:

Bootstrap documentation suggests that - if you want to use a Brand image - you'll want to replace the text within the navbar-brand Anchor HTML element with an IMG HTML element.

If you want both, however, you're on your own as you'll need to override the core Bootstrap stylesheets to support an Image HTML element + text string inside of the navbar-brand Anchor HTML element.

So, instead of modifying my beautiful HTML or overriding the core Bootstrap CSS rules for the navbar-brand... I decided on going to create a cleaner CSS-only fix.

Now, before I show you the CSS, let's take a look at the result of my first attempt:

Raw $icon inside of the navbar-brand Anchor HTML element

Since I'm using a darker, reddish-brown color for my navbar, the notesDatabase Icon - which is a 32-bit RGBA "shaped" image using alpha transparency - just doesn't look good. It doesn't pop. In fact, it looks mismatched to the text inside of the navbar-brand, which is white/#fff.

Now that you've seen my first attempt, let's look at the complete CSS rule for my navbar-brand Anchor HTML element:

First, you'll notice that this isn't actually a CSS rule for the Anchor HTML element, but rather a rule that uses the pseudo-selector ::before on the navbar-brand Anchor HTML element. This rule, with compatible browsers, allows me to inject content before the native content of any container-type HTML element.

In other words, using this pseudo-selector I'm able to inject and style my notesDatabase Icon before the string node content of my rendered markup.

This same approach is used by most icon fonts, where they will set the content of a container-type HTML element via CSS and the ::before pseudo-selector.

Check here to see if CSS generated content for pseudo-elements is supported in your browser(s).

The last two lines of the function apply an invert filter to the image, changing the color from black to white.

CSS invert-filtered $icon inside of the navbar-brand Anchor HTML element

Conclusion

I'd say "It's all about your corporate and application theme"... but I suspect that would make people think that I'm talking about webstandard.theme, corporate.theme, application.theme, and other IBM Domino XPages Themes when I'm actually referring to the overall thematic look and feel here.

Actually, Bootstrap has given me the perfect descriptor here:

It's all about branding!

notesDatabase Icons in the IBM Notes Client Workspace

The notesDatabase Icon will be seen on the IBM Notes Client Workspace, on smartphone and tablets as an app, and in-application as part of the UI and work to establish a brand for your application.

'Web Clip' IBM XPages Applications on Android smartphone

This branding will help your users quickly identify which applications they are working in, or which app they need to launch, or which tile from the Workspace they need to double-click.

If you don't believe me, imagine that your Phone, Email, and Camera apps on your smartphone shared the same generic "app" icon. How would that affect your use?

Now hopefully you'll note the differences between the notesDatabase Icon and the "Web Clip" icons above... and that's for good reason: some of those icons require the "tile backgrounds" mentioned earlier in this article based on their design. Where the Tip Jar icon is solid, you'll see that the Transfers and Inspections icons are not "closed" line-art.

As I was not thrilled with the outcome of my "Web Clip" icons using just the raw icon, I modified them slightly by changing the color of the icon or adding a solid color background. I might very well revisit that Transfers icon and match the color scheme (black icon on white background) to match the Inspections icon... and add a white background to Tip Jar.

There's a "corporate" brand to consider with these apps. Consistency, after all, is key!