Ferrysoft Help Desk
Ferrysoft Help Desk is a web based help desk solution. The Express Edition is free of charge. Click the screen shot to learn more about Ferrysoft Help Desk.
How to develop on-line help for Windows .NET Applications
Summary
This article describes a set of tools and techniques for developing on-line help for Windows .NET applications. It is intended for developers who are approaching the task of developing a help file to accompany a Windows .NET application for the first time. It describes the Microsoft tools of Visual Studio, Visual Web Developer, HTML Help Workshop, Visual Basic Express and Visual C# Express. The consideration of various third party tools that perform similar tasks is beyond the scope of this article.
The article uses the example of the Ferrysoft Help Desk Administrator application and associated help file as illustration. Ferrysoft Help Desk Administrator is the server based component of Ferrysoft Help Desk, used to perform tasks such as creating or upgrading the Ferrysoft Help Desk database.
Tools
The tools used to develop the Ferrysoft Help Desk Administrator application are described in the following table.
| Tool | Use |
|
Visual Studio or Visual Web Developer |
Authoring the topic files in HTML format that are used to create the final help file. |
| HTML Help Workshop | Setting the properties of the help file. Preparing the help file contents. Preparing the help file index. Compiling the contents, index and individual help topics to produce the final help file. |
|
Visual Studio or Visual Basic Express or Visual C# Express |
Establishing the connection between forms and form controls of a Windows .NET application with the help file and individual help topics. |
Developing the help topics
Help files are organised into help topics. The choice of help topics is a design decision that determines how sophisticated the eventual help file will be. Probably the simplest structure of help topics is to have one help topic per application window. A more sophisticated help file could be designed with different topics for each field or button within a window. Alternatively, help topics could describe the general features of the application without being bound to a particular window.
In the Ferrysoft Help Desk Administrator case, there is one help topic for each of the forms within the application. In addition, there is a single overview help topic. Each form has a Help button so that help can be obtained either by pressing the Help button or by pressing the F1 key on any window of the application.
Each help topic is authored as a single HTML file. The set of help topics for Ferrysoft Help Desk Administrator consists of:
- CreateDatabase.htm
- Default.htm (this contains the overview help topic)
- Login.htm
- Main.htm
- SetupDatabaseConnection.htm
- UpgradeDatabase.htm
The naming convention for the topic files follows the naming convention of the corresponding forms for convenience. For example, Main.htm contains the help text that describes the Main form, contained in Main.vb within the application.
Hyperlinks can be inserted in the help topic files and these become hyperlinks that can be clicked when using help after the help topic files have been compiled into the final help file. This provides a convenient way to navigate between help topics in addition to using the Table of Contents within the help file. Below is an example of a hyperlink that could be included to link to the main window help topic contained in Main.htm.
<a href="Main.htm">Main Window Help</a>
Visual Studio and Visual Web Developer are suitable tools for developing the help topic files. Other tools for authoring HTML files could be used instead. Even a text file editor such as Notepad could be used to prepare the help topic files although this would make it more difficult to get the HTML syntax correct.
The image below shows Visual Web Developer with the help files folder open and the Main.htm help topic file open in design view.
Below is the Ferrysoft Help Desk Administrator Main.htm as an example of a complete help topic.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Ferrysoft Help Desk Administrator Window</title> <style type="text/css"> <!-- a:link{ color: blue; } a:visited{ color: blue; } table{ border-style: none; border-width: 0px; border-collapse: collapse; } td{ vertical-align: top; } .topic-table{ border-style: solid; border-width: 2px; border-color: #0080FF; } .topic-table-cell{ font-weight: normal; color: black; border-style: solid; border-width: 1px; border-color: #0080FF; background-color: white; padding: 4px; } .topic-table-hyperlink{ font-weight: normal; color: black; border-style: solid; border-width: 1px; border-color: #0080FF; background-color: white; padding: 4px; white-space: nowrap; } .topic-table-top{ font-weight: bold; color: white; border-style: solid; border-width: 1px; border-color: #0080FF; background-color: #0080FF; padding: 4px; } --> </style> </head> <body> <h2>Ferrysoft Help Desk Administrator Window</h2> <p>Use this window to select from a range of administration processes.</p> <h3>Option</h3> <p>Select the required option from the available list in the table below.</p> <p>When installing Ferrysoft Help Desk for the first time, a typical sequence of options would be Create Database and Setup Database Connection.</p> <p>When upgrading Ferrysoft Help Desk on a server already running a previous version of Ferrysoft Help Desk, typically only Upgrade Database is required.</p> <table class="topic-table"> <tr> <td class="topic-table-top"> Option </td> <td class="topic-table-top"> Description </td> </tr> <tr> <td class="topic-table-hyperlink"> <a href="CreateDatabase.htm"> Create Database </a> </td> <td class="topic-table-cell"> Use this option to create the database. This only needs to be done once at installation time. </td> </tr> <tr> <td class="topic-table-hyperlink"> <a href="UpgradeDatabase.htm"> Upgrade Database </a> </td> <td class="topic-table-cell"> Use this option to upgrade the database. This only needs to be done once at installation time if a previous version of the database already exists. </td> </tr> <tr> <td class="topic-table-hyperlink"> <a href="SetupDatabaseConnection.htm"> Setup Database Connection </a> </td> <td class="topic-table-cell"> Use this option to setup the database connection to the database. This only needs to be done initially at installation time or if the connection settings need to be changed. </td> </tr> </table> <h3>Process button</h3> <p>Click the Process button to open the selected option window. If no option has been selected then the Process button is disabled.</p> <h3>Exit button</h3> <p>Click the Exit button to exit Ferrysoft Help Desk Administrator.</p> <h3>Help button</h3> <p>Click the Help button to display this help topic. The F1 key can also be used to display this help topic.</p> </body> </html>
Developing the help file
HTML Help Workshop is the recommended tool to use for compiling the topic files into a compiled help file. HTML Help Workshop is available for download from the Microsoft web site at no charge. HTML Help Workshop stores the configuration data for the help file in a help project file, in this case Administrator.hhp which can conveniently reside in the same folder as the topic files. Administrator.hhp is simply a text file which can be edited with a text editor although it is normally only maintained via HTML Help Workshop.
Below is the sample Administrator.hhp for Ferrysoft Help Desk Administrator. Note that each window definition in the [WINDOWS] section is a single unbroken line. In the example below, the window definition for Main is shown split over two lines purely for display purposes.
[OPTIONS] Compatibility=1.1 or later Compiled file=..\Administrator.chm Contents file=Administrator.hhc Default Window=Main Default topic=default.htm Display compile progress=No Full-text search=Yes Index file=Administrator.hhk Language=0x809 English (United Kingdom) Title=Ferrysoft Help Desk Administrator Help [WINDOWS] Main=,"Administrator.hhc","Administrator.hhk", "Default.htm",,,,,,0x3520,,0x3006,,,,,,,,0 [FILES] CreateDatabase.htm Default.htm Login.htm Main.htm SetupDatabaseConnection.htm UpgradeDatabase.htm [INFOTYPES]
The image below shows HTML Help Workshop with the help project file open.
HTML Help Workshop operates on the following files to create the compiled help file, in this case Administrator.chm:
- Administrator.hhp; the project file that contains the configuration of the compiled help file, the name of the compiled help file, the names of the topic files, the name of the contents file and the name of the index file.
- Administrator.hhc; the contents file that contains the structure of the contents window of the resultant compiled help file.
- Administrator.hhk; the index file that contains the structure of the index window of the resultant compiled help file.
HTML Help Workshop Project Tab
With the Project tab visible, HTML Help Workshop has buttons to:
- Change project options; set filenames and other project-wide options.
- Add/Remove topic files; to control which help topics appear in the compiled help file.
- Add/Modify window definitions; to control which windows appear when the compiled help file is used.
- Save all files and compile; to compile the help topics into the compiled help file.
HTML Help Workshop Contents Tab
The Contents feature of HTML Help Workshop allows the setup of a structured set of help topics, organised into a Table of Contents format. This is displayed in the Contents panel of HTML Help when the compiled help file is used.
With the Contents tab visible, HTML Help Workshop has buttons to:
- Contents properties; set Table of Contents properties.
- Insert a heading; to insert a heading in the Table of Contents.
- Insert a page; to insert a help topic in the Table of Contents.
- Edit selection; to edit a heading or help topic in the Table of Contents.
- Delete selection; to delete a heading or help topic from the Table of Contents.
- Move selection up/down/right/left; to re-organise headings or help topics in the Table of Contents.
HTML Help Workshop Index Tab
The Index feature of HTML Help Workshop allows the setup of a structured set of index keywords, organised into an Index format. This is displayed in the Index panel of HTML Help when the compiled help file is used.
With the Index tab visible, HTML Help Workshop has buttons to:
- Index properties; set Index properties.
- Insert a keyword; to insert a keyword in the Index.
- Edit selection; to edit an index entry in the Index.
- Delete selection; to delete an index entry from the Index.
- Move selection up/down/right/left; to re-organise index entries in the Index.
Developing the connection between the Windows .NET application and the help file
The final stage is to establish the connection between forms and form controls of a Windows .NET application with the help file and individual help topics. This is done with Visual Studio or the Visual Studio Express products to set the appropriate properties of the forms and to connect the Help button with Visual Basic or C# code. In the case of Ferrysoft Help Desk Administrator, Visual Basic is used as the source code language.
The image below shows Visual Basic Express with the Main form open.
The Windows Forms HelpProvider component is used to associate a help file with the application. Therefore a HelpProvider needs to be added to each form as follows:
- Open the form in Design View.
- Drag a HelpProvider control from the All Windows Forms Toolbox to the form. When it is added to the form, the HelpProvider component appears in the tray at the bottom of the Windows Forms Designer.
- Set the properties of the HelpProvider in the properties window. In the case of Ferrysoft Help Desk Administrator, the only property that needs setting is HelpNamespace which is set to the name of the help file, that is Administrator.chm.
If the name of the HelpProvider has been left as HelpProvider1 then each control of the form that can provide help, including the form itself will now have these properties:
- HelpKeyword on HelpProvider1
- HelpNavigator on HelpProvider1
- HelpString on HelpProvider1
- ShowHelp on HelpProvider1
In order to connect a form to its corresponding help topic, each control of the form and the form itself must have properties set as follows:
- Set HelpKeyword on HelpProvider1 to the name of the HTML topic file, in this case Main.htm.
- Set HelpNavigator on HelpProvider1 to Topic.
- HelpString on HelpProvider1 can be left blank.
- Set ShowHelp on HelpProvider1 to True.
This is sufficient to complete the connection of the form to the help file so that when the user presses the F1 key, the help file will open at the appropriate topic.
If a Help button is required on the form to do the same thing then the following additional steps are necessary:
- Open the form in Design View.
- Drag a Button control from the All Windows Forms Toolbox to the form.
- Set the properties of the Button in the properties window, for example, Name to cmdHelp and Text to Help.
- Connect the Click action of the Button control using the code that follows.
Visual Basic
Private Sub cmdHelp_Click( _ ByVal sender As Object, _ ByVal e As System.EventArgs) _ Handles cmdHelp.Click System.Windows.Forms.Help.ShowHelp( _ Me, _ HelpProvider1.HelpNamespace, _ System.Windows.Forms.HelpNavigator.Topic, _ HelpProvider1.GetHelpKeyword(Me)) End Sub
The image below shows Ferrysoft Help Desk Administrator with the Main window open.
If the user presses the Help button or presses the F1 key while the focus is anywhere on the window then HTML Help opens and displays the help file to the user.
The image below shows HTML Help with the Main window help topic open.
Conclusion
Using HTML Help Workshop and Visual Studio or the Visual Studio Express products, it is possible to quickly develop on-line help that will enhance the usability of a Windows .NET application.
About the author
Mike Green is the founder of Ferrysoft, a software development company specialising in Help Desk software technology.