Tooltips are one of those little features which you rarely have the time to add to your website (beyond the basic title settings of your HTML elements), but do add a surprising amount of polish to your application from your user’s point of view.
In an application that I have been working on recently, we added some tooltips to convey some specific information on how to use certain features and the extra help went over really well. But how do you add them in XPages?
Well Dojo is your friend, and more specifically one of the “dijit” package of plugins called dijit.ToolTip. So in your XPage you add a computed field with the display type set to HTML. In the value of the field add the following:
“<div dojoType=\”dijit.Tooltip\”\n” +
“connectId=\”” + getClientId(“hoverlabel”) + “\” style=\”display:none;\”>\n” +
“This is a tooltip\n” +
“</div>”;
Basically what we’re doing is creating a div that will get written out to the browser, the important elements are the dojoType which tells Dojo that this is something it needs to look at when the page loads. The connectId links the div to the label which we want to add the tooltip to. So in this case, I have a label called “hoverlabel”. Set the div to be hidden using CSS so that while Dojo is processing it after the page load, it doesn’t appear and then disappear very quickly.
Finally we just need to make sure that Dojo is enabled on our XPage, so:
- Go to the All Properties of your XPage and then Basics, make sure that dojoParseOnLoad is set to true
- I also set the dojoTheme to true as well.
- Then in the resources property (still in All Properties -> Basics) click the Add button and choose xp:dojoModule)
- In the dojoModule -> basics -> name property which gets added, set the value to “dijit.Tooltip”
It’s really very simple to get going and this is what you end up with:
A really nice looking tooltip with no coding on from out point of view that will be very helpful for your users.
How does the text "Hover over me" link to the tooltip? You said, I have a label called "hoverlabel". What syntax is "lable"? Do you mean ID? Would it look like this?
<span id="hoverlable">Hover over Me</span>
This is just personal preference, but when I add tooltips, I prefer to use passthru, computing only the connectId. That allows me to include rich content inside of the tooltip instead of just text.
To add a tooltip as passthru, go to the source tab, and in the desired location, add a div tag (remember, not all source tags need an xp: prefix… we can just add straight html), setting the connectId attribute to a dynamic evaluation, for example:
connectId="#{javascript: return getClientId(‘hoverlabel’);}"
The dojoType and style attributes, then, can just be static strings with no quote escaping. And then you can put anything you want inside the div – repeat controls, view panels, rich text, etc. – and that content will display inside the tooltip.
@Rob – Exactly right, sorry should have made that clearer. I’m actually using a label tag in my example but anything with an ID can be used.
@Tim – Totally agreed. I think this is the biggest challenge with XPages, there are lots of ways of doing things and it’s a matter of feeling out what is best. I suspect your way may well work better in the long run. Declan was also talking about another way using Custom Controls and properties to pass in the id and popup message which I think is probably better again.
Matt: Thanks. Nice polish for apps. Took me a bit to get it all square, but working now. Only thing is I’m getting an error when loading the page:
Could not load ‘dijit.ToolTip’; last tried ‘/dijit/ToolTip.js’
Still works though. Just wondering if you’ve run into this error and know what I might have messed up.
@John – You’re absolutely right, I get a JS error as well. What you can do is ignore the steps 3 and 4 (that are now struck through) and it should all work OK for you.
Thanks for the bug report 🙂
@Matt / @John, that’s because the second T should be lowercase:
xp:dojoModule name="dijit.Tooltip"
When you include a dojo module – whether through a dojoModule resource or a dojo.require() statement in client-side JS – it’s not just trying to load the extra script tag, it also verifies the object that tag creates, and since JS is case-sensitive, the object verification will fail if the case doesn’t match.
@Tim – Aha good spot, I really shouldn’t blog while trying to do three other things at once is the lesson from this 🙂
I find having the tooltip as a custom control works great for me as a write once use many control. I was interested by Tim’s comment above about putting richer content into the tooltip so I tried an experiement of using an Editable Area in the tooltip custom control and it seems to work fairly well.
I will write up an example and post it soon.
@Tim / @Matt
Thanks. Found the error (capital T) in one place and fixed that before testing page, but didn’t get all them, so didn’t know that’s what was causing the problem. Working now without error, even keeping in your struckout lines (strikedout?).
OK I corrected the code so it is unstruckout (?!?) now 🙂
Great tip Matt, Thanks! Does this work for you in Internet Explorer? It works great in firefox however I get an error in IE (Line: 20 Error: Member not found) when adding the dijit.Tooltip resource. I’ve tried dijit.Tooltip.js also to no avail.
@Keith – I can’t think of any reason why it wouldn’t work with IE (apart from it being a POC). It is a technique I have used several times now and it has worked in IE6 / 7 / 8 during testing so not sure what the problem is there.
OK, I found it. Seems Lotus Domino 8.5.0 does not fully support IE 8. I found this entry over on the XPages Wiki http://www.youatnotes.de/web/youatnotes/wiki-xpages.nsf/dx/Browser_compatibility
The code listed there solved my issue, thanks for the speedy response 🙂
Keith
Just discovered that dojo Tooltips don't work for controls that have been hidden and revealed by a partial refresh, eg after a radio button option has been chosen. 🙁
Oooops – yes dojo tooltips do indeed work only if their divs are stored inside the panel or whatever is the source of the partial refresh that contains the controls to be tool-tipped.