PDF In-Depth

Forms - Hot Help Made Easy

February 12, 2001


Anything that provides contextual help to a form user at runtime is a big win for all concerned. That's one reason so many commercial software packages have added a capability to mouse navigation such that whenever the mouse lingers over a clickable toolbar icon for more than a couple seconds, a little help box pops up with a few words of explanation. For example, in Acrobat Reader, whenever the user lets the mouse linger over the little binoculars icon in the toolbar, eventually a tiny yellow box pops up with the word Find to indicate that this is the Find Tool.

Form widgets (user-interaction items) created in Acrobat come with this capability built in. You may have noticed that every time you bring up the Field Properties dialog for a form widget, there is a text field near the top of the dialog called Short Description. Whatever you enter here will be displayed to the user as a hot-help popup if the user lets his mouse linger over the widget in question. If you enter nothing at all in the Short Description area, the user gets no hot help at all. Make sense so far?

Changing messages - An advancement

Now here's the really fun part. Did you know that you can change the hot-help message programmatically at runtime, using JavaScript? This technique is used in Scriptalyzer (our JavaScript utility), in the Argument-entry text field. When you let your mouse loiter over the Arguments field for more than a couple seconds, a hot-help box pops up, but the hot-help message is different each time, depending on the value of the preset selected in the Examples dropdown menu. The Arguments field expects different types of input at different times, and the hot help adapts accordingly. This is extremely helpful to the user, who may otherwise find things confusing.

The trick is this. To change the hot-help message for a field dynamically, at runtime, you have to attach a JavaScript action to some field in your form, and in this script you have to change the value of the userName property of the field in question. (Why Adobe chose userName as the name of the hot-help attribute is a mystery.) You can attach the script as a custom Calculation script, if need be, so that whenever any field loses focus, it will get called (along with all other Calculation scripts). You need to do two things in this script. You need to get a reference to the field object for the field that has the changing hot help. Then, you need to change the hot-help text. Let's say the field we want to have changing hot-help for is called FavoriteTVChannel. Perhaps there is another field somewhere that asks for the user's gender. Then we might do something like this:

var tvchannel = this.getField("FavoriteTVChannel");var gender = 

this.getField("Gender");if (gender.value.toLowerCase() == "female")	

tvchannel.userName = "Lifetime, Home Shopping Network, or whatever."; else if  

(gender.value.toLowerCase() == "male")	tvchannel.userName = "Playboy, Sci-Fi 

Channel, or whatever.";

Okay, that might be kind of a sexist example. But you get the point. You can examine the value of some other field, then set the hot-help text for a related field programmatically, using this technique. The result is a much more satisfying user experience, because the form seems to adapt (as if by magic) to the user's own preferences, on the fly.

Javascript and other procedural languages

Note that we use the toLowerCase() method of the String class to ensure that the gender comparison is done in lower case. Also notice that in JavaScript, strings are compared by value, not by reference. This is contrary to C/C++ and many other languages, where special string comparison methods must be used. In JavaScript, you can just compare strings using the equality or inequality operators.

PDF In-Depth Free Product Trials Ubiquitous PDF

Debenu Quick PDF Library

Get products to market faster with this amazing PDF developer SDK. Over 900 functions and an equally...

Download free demo

Five visions of a PDF Day

In the world of PDFs or as we like to say Planet (of) PDF, a year isn't a real PDF year without an intense few days of industry knowledge sharing.

May 15, 2018
Platinum Sponsor

Search Planet PDF
more searching options...
Planet PDF Newsletter
Most Popular Articles
Featured Product

Debenu PDF Aerialist

The ultimate plug-in for Adobe Acrobat. Advanced splitting, merging, stamping, bookmarking, and link control. Take Acrobat to the next level.


Adding a PDF Stamp Comment

OK, so you want to stamp your document. Maybe you need to give reviewers some advice about the document's status or sensitivity. This tip from author Ted Padova demonstrates how to add stamps with the Stamp Tool along with related comments.