Lesson 1: Adding Help to Web Applications | MCAD(s)MCSD Self-Paced Training Kit(c) Developing Web Applications With Microsoft Visual Basic. Net and Microsoft V[. .. ]0-315

Lesson 1: Adding Help to Web Applications

Web applications can display help in several ways: as ToolTips for controls, as Web forms or HTML pages, or as compiled HTML Help files. In this lesson, you ll learn to use these different techniques from within Web forms.

After this lesson, you will be able to

Add ToolTips to server controls and HTML controls on a Web form
Display Help as a Web form or an HTML page in a browser window
Control the size and focus of the browser window displaying Help
Display Help using the HTML Help Viewer

Estimated lesson time: 15 minutes

Displaying ToolTips

A ToolTip is a short, descriptive message that s displayed when the user places the mouse pointer over a control and leaves it there for a couple of seconds. These messages are used throughout Microsoft Windows applications to provide helpful information about toolbar buttons and other graphical controls whose meaning might not otherwise be obvious. In a sense, ToolTips are subtitles for the icon-impaired. Figure 14-1 shows a ToolTip in action.

figure 14-1 a tooltip

Figure 14-1. A ToolTip

Most server controls include a ToolTip property that you can set to the message you want to display. At run time, Microsoft ASP.NET outputs the ToolTip property as the control s title attribute, which Microsoft Internet Explorer displays as a ToolTip. Only Internet Explorer displays the title attributes as ToolTips. Other browsers do not display ToolTips.

HTML controls do not include a ToolTip property. Instead, you can use the title attribute directly. The following HTML shows the difference between setting a ToolTip for a server control and setting one for an HTML control:

<asp:Button  runat="server" Text="OK" ToolTip="Submits purchase."></asp:Button> <INPUT type="reset" value="Cancel" title="Cancels purchase.">

Not all controls include a ToolTip property or title attribute. In particular, the DropDownList and ListBox server controls do not provide a ToolTip property or a title attribute.

Displaying Help as Web Forms or HTML

Creating your Help content as Web forms or HTML pages is probably the simplest approach to providing user assistance. The Help files can reside in either the same project folder as your Web application or in a subordinate folder.

You use hyperlinks or other controls to display the Help in the browser, just as you would any other page, with one important difference: you usually want to display Help in a new window or in a separate frame from the rest of the Web application, as shown in Figure 14-2.

figure 14-2 displaying a help browser window

Figure 14-2. Displaying a Help browser window

Displaying Help in a separate browser window preserves the user s place in the Web application and allows him or her to compare the Help to the current task being performed.

To display Help in a separate window, use the client-side window object s open method, as shown in the following hyperlink:

<a href="#" onclick="window.open('topic1.aspx', 'helpwin').focus()"> Click here for help.</a>

The preceding HTML uses the onclick event to display the Help topic in a new browser window on top of the Web application s window. Setting the href attribute to "#" simply links to the current location in the Web application, rather than directing the user to a new location. The first argument to the open method specifies the Help topic to display; the second argument names the new window so that subsequent Help topics are directed to the same window. Finally, the focus method ensures that the Help window is displayed on top of the Web application.

Other Help hyperlinks within the Web application can use the same onclick script to display different topics in the same window. If your application includes more than one Help hyperlink per Web form, it s a good idea to place the script in a procedure and call it from the onclick procedure, as shown here:

VBScript

<HTML> <HEAD> <title>WebForm1</title> <script language="vbscript"> ' Shows a Web form or HTML page in a small browser window ' and switches the focus to that window. Sub ShowHelp(topicName) Dim HelpWindow ' Display topic in named window. Set HelpWindow = window.open(topicName,  "helpwin","left=600,height=300,width=200") ' Displays the window on top. HelpWindow.focus End Sub </script> </HEAD> <body> <h2>Show Help in a New window</h2> <A onclick="ShowHelp('topic1.aspx')" href="#">Click here for help.</A> <BR> <A onclick="ShowHelp('topic2.aspx')" href="#">Click here for more help.</A> </body> </HTML>

JScript

<HTML> <HEAD> <script language=jscript> // Shows a Web form or HTML page in a small browser window // and switches the focus to that window. function ShowHelp(topicName) { var HelpWindow; // Display topic in named window. HelpWindow = window.open(topicName,  "helpwin","left=600,height=300,width=200"); // Displays the window on top. HelpWindow.focus(); } </script> </HEAD> <body> <h2>Show Help in a New window</h2> <a href="#" onclick="ShowHelp('topic1.aspx')">Click here for help.</a> <br> <a href="#" onclick="ShowHelp('topic2.aspx')">Click here for more help.</a> </body> </HTML>

Within the Help topic, you can use the window object s close method to provide a link to close the Help window within the Help topic, as shown here:

<a href="#" onclick="window.close()">Click here to close help.</a>

There are other ways to display a topic in a named window, such as using the target attribute of a hyperlink. However, those techniques make it more difficult to ensure that the Help window is displayed on top of the Web application.

Displaying HTML Help

You can use the window object s showHelp method to display HTML Help files, regular HTML files, or Web forms using the HTML Help Viewer (hh.exe). An HTML Help file consists of topic files written in HTML that have been compiled into a single, compressed file that provides additional Help features.

The showHelp method displays topics in the HTML Help Viewer, which by default is displayed on top of the Web application s browser window, as shown in Figure 14-3.

figure 14-3 the html help viewer

Figure 14-3. The HTML Help Viewer

To display a Web form or an HTML page using showHelp, specify the Web form or HTML page file name as the first argument of the method, as shown here:

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

The preceding HTML displays the Web form Topic1.aspx when the user clicks the Show Help hyperlink. The Topic1.aspx file in not a compiled Help file it is simply a Help topic written using ASP.NET. Using showHelp in this way gives you the advantage of the window always being on top of the Web application even when the Web application has the focus.

The showHelp method can also display topics from compiled Help files. These files are made up of HTML pages that are compiled into a single file (.chm) using the HTML Help Workshop. When you work with compiled Help files, showHelp identifies the topic to display using a context ID that is mapped to a topic file name during compilation.

To display a topic from a compiled HTML Help file, specify the compiled file name and topic file name as the first argument of the showHelp method, as shown here:

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

The preceding HTML displays the compiled file named HelpSample.chm. Note that the compiled Help file must be downloaded and stored on the user s machine. Using compiled Help files has the following advantages over storing and displaying Help files as separate Web forms or HTML pages:

Reduced size
Compiling Help compresses the topics so that their total size is much less than the total of the individual source topics.
Contents, Index, and Search tools
The HTML Help Workshop includes tools for creating these features and adding them to your Help system.
Embedded display
The HTML Help Microsoft ActiveX control and Java applet allow you to display your Help within the browser window rather than as a separate window.
Ease of localization
Because HTML Help maps topic file names to context IDs, it s possible to have multiple compiled Help files written in different natural languages that all use the same set of context IDs.

Compiling HTML Help has a couple of limitations that you should be aware of as well:

Source files must be in HTML format
Web forms can t be compiled into .chm files.
The entire compiled file must be downloaded to the user s machine
If you have a large Help file and your users are connected via modem, it can take a long time to load Help the first time. Once the Help file is downloaded, however, it can be accessed quickly.

The following lessons discuss creating compiled HTML Help files and using those files from Web applications in more detail.