Standalone HTML (Chm) help file

On the introduction to this section, I mentioned the various methods by which help files can be shown to your customers. On this page, we will be concentrating on producing a standalone HTML help file – what do I mean by this?

You may have seen applications that display help files containing highly formatted text and media contents but do not run off web browsers. A good example of this is the help file of PageBreeze, the application which I recommend you to download in the last section.

Producing this type of help system has a number of advantages over basic HTML files:

1. Is a single file so you do not need to distribute several files/images
2. It is compressed so download will be smaller and thus quicker
3. It is easier for the user to navigate and find contents
4. Looks professional
5. Less chance of it being damaged by users if they do unnecessary exploration

It is also very easy to produce! If you read the last page on this section, you have already done half the work. Again, I will ask you to download 2 files:

1. Microsoft HTML Help Workshop – this is a tool created by Microsoft for the purposes of creating such single help files from multiple HTML pages
2. Copy of the demo project we are working through - no need to download again if you have already done so!

Install the Microsoft HTML Help Workshop but don’t open it yet because you may be totally lost. It’s poorly documented.  Also unzip the demo project and browse to the \help file folder.  In the help file folder, you will see many HTML files that were created in the previous section.  In addition, you will also see some new files.  The new files are as follows.

1. help project.chm – this is the help file produced by using the HTML Help Workshop – you can open it to see the final product!
2. TOC.hhc – contains the table of contents data used to organize the webpages
3. Help project.hhp – this can be opened using the HTML Help Workshop and contains information about the help file
4. Help.chm - the actual help file which you distribute to your users.  This is a help file generated by the HTML Help Workshop and is a standalone file.  This means that you don’t need to include any other files (e.g. the HTML files and the associated picture files) because everything is compiled into the chm file.

To start exploring, you can open Help project.hhp with Help Workshop, but better still, why not delete Help project.hhp, TOC.hhc and help project.chm and learn to create those files again from the raw HTML files?! Try the following steps:

1. Open HTML Help Workshop
2. Click File, New
3. Select ‘Project’ and OK
4. Click Next
5. Click ‘Browse’, go to the folder with all the above htm files and name your project ‘Help project.hhp’
6. Click Next
7. Tick HTML files and click Next
8. Click ‘Add’ and go to the folder with the above htm files. Select the 3 files and click ‘Open’
9. Click ‘Next’ then ‘Finish’
10. On the main window, on the left, click the ‘Contents’ tab (we will now create a table of contents)
11. On the window that appears, select ‘Create a new contents file’ and click ‘OK’
12. Browse to the folder with the above htm and name your table of contents file TOC.hhc
13. You must now add files to the table of contents. Click the ‘Insert a page’ button on the ‘Contents’ tab
14. Input ‘Welcome’ on the Entry title box (this is what appears on the table of contents) and then click ‘Welcome’ from the HTML titles box (this box contains a list of the titles on all of the HTML pages you added earlier to the project)
15. Click Ok, then Ok again
16. In the same way, add “System requirements” file.
17. Then add the “Overview” file.
18. Next, we will add a heading so that we can organise the different methods of selecting colors (RGB, Screen and System) into its own folder. Click on “Insert a heading” (the folder icon). For entry title, input ‘Color selection methods’ and click ‘Add’. Select ‘RGB colors’ from the list (this will be the default page when a user clicks on ‘Color selection methods’ folder.
19. Next we add the different method of selecting colors. First one is ‘RGB colors’. Add it in a similar way to what you did for the ‘Overview’ page. But this time, we will need to put this under the ‘Color Selection methods’ heading. To do this, select the ‘RGB colors’ page on the contents list and push it one level to the right (Click on ‘Move selection right’, the button with the right arrow) such that its under the ‘Color Selection methods’ folder.
20. Do step 18 for ‘Screen colors’ and ‘System colors’
21. Do similar for the pallet, but because it is not a method of selecting colors, we will make sure that it is not under the ‘Color Selection methods’ heading. You can use the button with the left arrow if you need to move it to a different level.
22. We repeat step 20 for ‘Buy Color Crazy Plus’, ‘Contact us’ and ‘license agreement’
23. Make sure that the order of the files is correct on the list in the ‘Contents’ tab. If not, use the black arrows to sort them. Here is how mine looks…



24. Change the name of the help file by going to Project tab -> Change project options -> Files tab -> Compiled file -> Path to file and “Help.chm”
25. Change the default title of the help file (that appears on the windows title bar) by going to Project tab -> Change project options -> General tab -> Title -> enter “Color Crazy help”
26. Click File -> Save project
27. You are ready to compile the help file now! Click on the compile button (the one left to the red glasses on the toolbar)
28. Select the location and the file name and click ‘Compile’
29. You are done! Your chm help file should be ready for you to view.

Obviously this is only the basics and there’s plenty for you to explore but when you open the help file, you will be able to see how easy it is to navigate around pages and how all the links are fully functional.

Next question, how do I link this to my software? I use the ShellExecute API command. In VB, I do this:

ShellExecute (me.hwnd, “open”, path to the chm file, vbNull, vbNull, 3)

Another question, how do I automatically open the page on ‘Overview’? Simple! Use the HtmlHelpTopic API call:

Private Const HH_DISPLAY_TOPIC = &H0

Private Declare Function HtmlHelpTopic Lib “hhctrl.ocx” Alias “HtmlHelpA” (ByVal hwnd As Long, ByVal lpHelpFile As String, ByVal wCommand As Long, ByVal dwData As String) As Long

Call HtmlHelpTopic (me.hwnd, path to the chm file, HH_DISPLAY_TOPIC, “overview.htm”)

*Note above that ‘overview.htm’ was the original filename of the Getting started page

Well!  That’s it.  All you have to do now is to do the above for your own project!