Lesson 3: Linking HTML Help to Web Forms

Lesson 3: Linking HTML Help to Web Forms

In this lesson, you ll learn how to display HTML Help from within a Web form. This lesson expands on the techniques introduced in Lesson 1 by showing the different ways you can display HTML Help, describing the differences between compiled and noncompiled Help, and explaining how to make Help respond to user actions in a Web application.

After this lesson, you will be able to

• Display compiled and noncompiled HTML Help using the HTML Help Viewer

• Display HTML Help in an ordinary browser window

• Cause different Help topics to be displayed, depending on which controls in a Web form have the focus

Estimated lesson time: 10 minutes

Displaying the HTML Help Viewer

As shown in Lesson 1, HTML Help is displayed in the HTML Help Viewer using the showHelp method. How you use showHelp depends on whether your HTML Help is compiled:

• Noncompiled Help can be displayed using the address of the Help topic via the Internet, as shown here:

  <a href="#" onclick="window.showHelp('Topic1.htm')">Help!</a>

• Compiled Help must be copied locally before you can display topics using showHelp, as shown here:

  <a href="#" onclick="window.showHelp('c:\\Help\\HelpSample.chm')">Help!</a>

The HTML Help Viewer is displayed differently depending on whether the Help file is compiled, as shown in Figure 14-14.

Figure 14-14. Compiled vs. noncompiled Help

As you can see in Figure 14-14, compiled Help displays Contents, Index, and Search features, while noncompiled Help displays only the requested Help topic file. By using compiled Help, you get the full features of the HTML Help system; however, the user must first download the compiled Help file.

To download a compiled Help file to the user s machine, create a hyperlink to the compiled Help file and provide the user with instructions on where to save the Help file. For example, the following HTML creates a hyperlink that downloads the HelpSample.chm file and instructs the user to save the file to a specific folder:

<a href="HelpSample.chm">Click here</a> to download the sample Help file and then save the file to the C:\Help folder on your computer.</p>

When the user clicks the preceding hyperlink, the browser asks the user whether he or she wants to open or save the Help file. When the user saves the file to the specified directory, the showHelp method can display topics from the file.

Displaying HTML Help in the Browser

The showHelp method isn t the only way to display compiled Help files. You can also display topics in the browser using URLs from within the Help file itself. The browser can t display HTML Help s Contents, Index, or Search features, but it can open topics from the compiled file across the Internet, which is something showHelp can t do!

To display a compiled Help file in the browser, create a hyperlink using the topic file s URL within the compiled file. For example, the following hyperlink displays Topic1.htm in a new browser window:

<a href="ms-its:http://www.mycompany.com/Help/HelpSample.chm::/topic1.htm"  target="HelpWin">Show Help</a>

The preceding hyperlink uses the ms-its: pluggable protocol and the Help path syntax to display a topic file from within a compiled Help file stored on the Web. The ms-its: protocol is provided in Internet Explorer versions 4.0 and later. The HTML Help path syntax has the form compiledfile::/topicfile, where compiledfile is the URL for the compiled Help file and topicfile is the HTML topic file name within the compiled Help file.

Displaying Context-Sensitive Help

If you re displaying compiled HTML Help in the HTML Help Viewer, you can use context IDs to identify topics within the Help file and associate those topics with tasks in your Web application. This type of Help is called context-sensitive Help because the topic displayed depends on the current context (or task) within the application.

Trying to display context-sensitive Help within a Web application presents a couple of challenges:

• Although you can capture the Help key (F1) using the onkeydown event and the window.event.keyCode property, you can t cancel the default action for F1 within Internet Explorer. The default action is to display Internet Explorer Help.

• The contextID argument for the showHelp method doesn t work from within a Web form or an HTML page.

To solve these problems, you must choose a mechanism other than F1 to display Help within your Web application, and you must use the HTML Help path syntax to display the appropriate Help topic. The following HTML uses the onfocus event to display different Help topics as the user moves between controls on a Web form:

VBScript

<HTML> <HEAD> <title>Context Help</title> <script language="vbscript"> Dim LastTopic Sub ShowContextHelp(Topic) If (document.all("chkHelp").checked And LastTopic <> Topic) Then ' Display Help for this context. window.showHelp "c:\help\HelpSample.chm::/" & Topic ' Store topic name. LastTopic = Topic End If End Sub </script> </HEAD> <body onfocus="ShowContextHelp('Topic1.htm')> <form  method="post" runat="server"> <H2>Context Sensitive Help</H2> <INPUT onfocus="ShowContextHelp('Topic2.htm')" type="text"> <BR> <INPUT onfocus="ShowContextHelp('Topic3.htm')" type="button"  value="Button"> <BR> <INPUT  type="checkbox" name="chkHelp">Show user assistance. </form> </body> </HTML>

JScript

<HTML> <HEAD> <title>Context Help</title> <script language="jscript"> var LastTopic; function ShowContextHelp(Topic) { if ((document.all("chkHelp").checked) && (LastTopic != Topic)) { // Display Help for this context. window.showHelp("c:\\help\\HelpSample.chm::/" + Topic); // Store topic name. LastTopic = Topic; } } </script> </HEAD> <body onfocus="ShowContextHelp('Topic1.htm')"> <form  method="post" runat="server"> <h2>Context Sensitive Help</h2> <INPUT type="text" onfocus="ShowContextHelp('Topic2.htm')"> <br> <INPUT type="button" value="Button"  onfocus="ShowContextHelp('Topic3.htm')"> <br> <INPUT  type="checkbox">Show user assistance. </form> </body> </HTML>

The CheckBox control allows the user to turn on context-sensitive Help. At run time, the ShowContextHelp procedure displays the Help topic for each item on the page when the focus changes to a new item, as shown in Figure 14-15.

Figure 14-15. Context-sensitive Help