Let’s say you’ve got a Visualforce page with some input areas and you want to give your users a bit more help than field labels can provide. First of all, good for you. Your users and your support staff will all be grateful. Pat yourself on the back for a job well done. When you’re done with that, read on.

Help Bubbles

Salesforce has small help bubbles next to many fields. You can make use of this functionality too. You’ll need a <apex:pageBlockSectionItem>.

Caveats of the help bubble:

• The pageBlockSectionItem hides the field label, so you’ll have to add another one by hand.
• The pageBlockSectionItem accepts one or two child elements, and my rudimentary testing indicates that the help bubble will only display if you use two child elements. I’m looking into this.
• You must show the header on your page so that the page uses the correct CSS. This is true even if you’re going to embed your page into another page.
• When you create a custom field on an object, you have the option of providing info bubble text at that time. I don’t know if there’s a way to reference that same text on a Visualforce page. Update: Thanks to Daniel Hoescht in the comments, who points out:
  “You can reference the help text you specify on the field in setup by using helpText=”{!$ObjectType.Account.Fields.CustomerPriority__c.inlineHelpText}”Similarly, you can reference the label text using {!$ObjectType.Account.Fields.CustomerPriority__c.label}”

Hover Text

The title attribute on <apex:inputText>, <apex:inputTextArea>, and others allows you to provide a label that appears when a user hovers over the field.

This is good for short snippets of information. However, it’s the least discoverable of all the techniques mentioned here and so I advise always using it in combination with either bubbles or inline text.

Inline Text

If you want to display more information than a sentence or two and you’ve got some screen real estate to spare, you may want to consider displaying your text directly on the page. It’s cumbersome and it probably looks ugly, but I like it for a few reasons. Firstly, I don’t like reading large blocks of text in a hover. I usually reflexively move my mouse to read it and then it disappears and then I get annoyed. Secondly, I’m hoping (although I have no proof) that users might be more likely to read it if it’s right there. Finally, from a maintenance perspective, I am more likely to update the help when making functionality changes if it’s always staring me right in the face in on the page, as opposed to hidden away in a hover somewhere. Anyway, it looks like this.

In conclusion, displaying contextual help to your users is a Very Good Thing and hopefully this post has made it easier for you to do so. Questions? Suggestions? How have you all done this? Discuss in the comments.