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.