Executive Summary:
You can use JScript to write a pop-up function to provide help information in your HTML Applications (HTAs). To create a context-sensitive Help pop-up, you have to assign each form element an ID attribute. Also, each form element that needs a context-sensitive Help pop-up has both a Case clause and a Help pop-up function. |
I always try to include some type of Help feature within each of my HTML Applications (HTAs), and until recently, I was using a very basic approach to display a Help screen within each application. The Help screen was initiated by the onhelp event from within the HTML <BODY> tag (i.e., <BODY onhelp="ShowHelp" >). In this case, ShowHelp referenced a subroutine that would run when the user pressed the F1 key. The ShowHelp subroutine that I wrote used a MsgBox function to display helpful text and instructions for the user. For some applications, I provided basic help information, but for other HTAs I provided much more detailed help text and instructions. Regardless of how much detail I put into it, the help that I provided was limited to the functionality that a message box could provide, which was basically a lot of text with a few Visual Basic (VB) carriage return/line feeds thrown in to make it look a little better. Furthermore, I could provide only one Help screen for the entire application. This method worked fairly well for most applications, although there was a good bit of reading in some applications and the user was required to close the message box by clicking OK.
In the back of my mind I always knew that this method was a bit of a kludge, and I wanted to provide a better solution. The biggest drawback to this “Help” solution, aside from everything being jammed into one big Help screen, was that it lacked a key feature that I and other users really wanted—the ability to copy some of the Help text and use it within the application. The most pointed example of this made itself known every time you had to enter a detailed query string into an application. Although the structured query strings that you could call on were visible and accessible by pressing the F1 key, there was no way to copy them from the message box and paste them directly into the application input boxes. Message boxes just don’t offer that type of functionality.
In my quest to learn more about HTML and to build better HTAs, I had seen some examples of using pop-ups within Web applications to display a variety of things. However, I couldn’t get pop-ups to work when I tried to write them using VBScript. I finally decided to try my hand at writing a pop-up function using JScript. Lo and behold it worked the first time around. JScript, as I see it, has a lot of similarities to VBScript. There are some basic structural differences but not so much that it should discourage you from giving JScript a try.
I recently used JScript in one of my NT admin HTAs and it worked beautifully. The nice thing about using a pop-up was that I could finally copy portions of the Help content and paste it right into an application input box. I was even able to write the rest of my code in VBScript because JScript and VBScript can coexist within the same application.
I’ve created a very basic HTA application (HTAPop-upHelp.hta) that demonstrates how to create not only a general application Help pop-up, but also context-sensitive Help screens. (You can download this HTA by clicking the Download the Code Here button.) Creating context-sensitive Help pop-up windows involves the following four steps:
- Identifying the form elements for which you want to have context-sensitive Help pop-ups and assigning an ID attribute to each one.
- Writing code that first determines which form element is active, then calls the corresponding function that displays the appropriate context-sensitive help.
- Creating the context-sensitive functions.
- Testing the context-sensitive Help pop-ups.
Assigning ID AttributesTo create context-sensitive help, I evaluate which form element the cursor is in when the user presses F1. One of the requirements to making a context-sensitive Help pop-up work is that you must assign an ID attribute to every form element (e.g., text boxes, drop-down boxes, radio buttons, text areas, check boxes) that you want to provide help on.
Assigning an ID attribute to a form element is easy. Simply include ID="someName" (where someName is the element's ID) within the HTML code for each element that you want to provide help on. The following is an example of one of the elements I used in the HTA that accompanies this article:
<input type="radio" id="Rad1" value="V1" name="R1">
In this command, I’m assigning one of my two radio buttons (or option buttons) the ID of "Rad1."
Determining Which Form Element Is Active and Calling the Corresponding SubroutineOnce the IDs are in place, you can determine which element is active (or where the cursor is) by evaluating the document’s active elements ID property using the command
document.activeElement.id
As callout A in Listing 1 shows, this command is used in a Select Case statement in a function named ShowHelp. The ShowHelp subroutine determines which function to call based on the value that the document.activeElement.id command returns. Depending on which Case clause is true, a call is made to the corresponding context-sensitive Help pop-up function. There’s a Case clause and a Help pop-up function for each form element that requires a context-sensitive Help pop-up.
The only other thing I’d like to mention about the code in Listing 1 pertains to the first Case statement Case "". This Case statement means that the cursor isn’t in any of the form elements; instead the user has clicked the HTA background, which has no ID associated with it. In that case, I just provide the general Help pop-up. Figure 1 shows an example of the general application pop-up window.
Creating the Context-Sensitive FunctionsWithin each function is a context-sensitive Help message comprised of plain-text and HTML formatting that gets stored in the HelpMessage variable. Listing 2 shows the function that displays the context-sensitive Help message in Figure 2. This function first writes the Help message. The function then creates the pop-up, sets the pop-up style and color, assigns the Help message to the innerHTML property, and shows the pop-up at the screen coordinates relative to your HTA window. Callout A in Listing 2 shows what the section of the function that creates and formats the pop-up looks like. The first two lines in callout A in Listing 2 set up two required pop-up objects—one for the pop-up and one for the pop-up body. The next few lines of code set the pop-up color scheme, after which the contents of the HelpMessage variable are assigned to the pop-up’s innerHTML property. Finally, the pop-up is displayed at the specified coordinates via the Show method. Figure 2 shows an example of a context-sensitive Help pop-up window.
You can set the pop-up window colors to almost any color you like. In the function in Listing 2, the first style setting sets the background color to teal, the second style setting sets the color of the text to white, and the third style setting sets the border to a layered black inset style with a thickness of 1 pixel. You can experiment with the style settings to get the look you want. Some other styles you can use include the ridge, groove, solid, and outset settings.
Testing a Help Pop-UpTo test the context-sensitive Help pop-up, simply launch it and place the cursor in any field, including the check boxes and radio buttons, and press F1. If you want to test the general Help pop-up, just click the HTA background away from any of the form elements and press F1.
Setting Up onhelp EventsAs I mentioned previously, the onhelp event is also important to making the overall Help feature work. Setting up onhelp events is straightforward. To do so, simply add the following syntax to your opening <BODY> tag:
<Body onhelp=”ShowHelp”>
When you declare the onhelp event, you’re telling the HTA to execute the ShowHelp subroutine or function when the F1 key is pressed. My application calls a subroutine, but if you call a function you must include the open and close parentheses in the <BODY> tag, as shown in the following command:
<Body onhelp=”ShowHelp()”>
Providing Users with Helpful InformationContext-sensitive Help pop-ups offer you a quick and effective means of providing immediate assistance and guidance to your HTA. In fact, you can think of Help pop-ups as a quick reference guides that users can access with just the press of a key. I hope you’ll try using JScript to create context-sensitive Help pop-up windows for your HTAs.
End of Article
Register
