Dr. Dobb's Journal October 1998

HTML Help in Distributed Environments

By Max I. Fomitchev

Upgrading client-server applications designed for distributed multiuser environments can be an arduous task because each workstation has to be upgraded individually. Even if you have an automated process that performs upgrades, help files and supporting documentation can change more frequently than the application itself. In such cases, it seems reasonable to have a single up-to-date copy of the help files and other documentation accessible to users. One way to do this is to place HTML help files on the corporate intranet web site or Internet server. Even if the network is slow, HTML files will be delivered quickly because each help screen is generally small. Moreover, after the first access, HTML help pages will be cached locally. This can significantly improve performance and reduce the load on the web server. Since help information is viewed relatively rarely and help pages are generally small, it doesn't take much in the way of server resources to support the feature. In fact, in tests I've conducted, it takes longer to launch the Internet Explorer (IE) browser than to display the request help page (the average help page size was 20 KB, and the total size of all help files was only 600 KB -- almost five times less than the size of the original .HLP file). It is also easier to publish HTML files than Windows standard .HLP files because most tools allow export in HTML.

HTML help files must be viewed in a browser window. Microsoft provides the IWebBrowser2 interface object (IWebBrowser and IWebBrowserApp in earlier releases of SHVDOC.DLL) to automate the IE part. For displaying the help screen, either the browser's ActiveX component or the IE frame can be used. IE can also display a variety of files such as Word documents, Excel files, and so on, provided corresponding components are installed on the client's workstation. In addition, HTML help pages can contain links to a corporate help desk and e-mail feedback to tech support.

Using the IE frame to display help information provides more flexibility, since all the functionality of the browser is available (for example, users can adjust font sizes and make bookmarks). When the WebBrowser object is used as an ActiveX control, some IE functions are inaccessible and others require coding.

To use the IE frame to display HTML help pages, the IWebBrowserApp object must be initialized. In the example presented here, the WebBrowser object is created from the IWebBrowserApp interface with the help of Visual C++ class wizard. This object launches IE by means of OLE Automation; see Listing One This operation must be done each time users request a help page since, after viewing, users might close the IE window and destroy the IWebBrowserApp dispatch handle. (It is easy to test if the handle was destroyed by calling IWebBrowserApp::GetHwnd. This call will throw an exception indicating that the dispatch handle is no longer valid.)

The IE frame must be closed when the application that requested help page terminates. Listing Two must be placed in OnExitInstance or OnClose handlers.

If users have closed the IE frame by the time the application is terminated, the dispatch handle of the IWebBrowserApp has already been released and an exception will occur (because the framework will attempt to release the handle again).

You can also map UI help IDs into the HTML help pages. At first glance, a simple integer-to-string mapping routine (like Listing Three) will do.

In the MFC application presented here, it is sufficient to overwrite the CWinApp::WinHelp() method and add some of the code in Listing Three. CWinApp::WinHelp() handles all help messages sent by UI elements and dialogs. This routine can be configured to display HTML help pages, standard HLP-files, or both; see Listing Four.