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.