The purpose of this page is to help you get started in building your help and contents file using the newer HTML Help compiler.
____________________________________________________________________________
Lesson 2: Using the HTML Help Workshop
Microsoft Visual Studio .NET includes the HTML Help Workshop, which is
installed in a separate location on the developer's machine. Use the HTML Help
Workshop to create a compiled Help file that includes a table of contents, an
index, and full-text search capabilities.
Creating HTML Help
An HTML Help file is comprised of individual HTML pages, each representing a
single Help topic. Each Help topic can include keywords that are included in
the index and cross-references to other topics. HTML Help projects include
these types of files.
HTML Help Project Files
File type Use to
Help topic (.htm) Create content to display in Help
Project (.hhp) Define how the project is compiled and which Help
topic, contents, and index files to include
Contents (.hhc) Create a table of contents for the Help file
Index (.hhk) Create an index for the Help file
Search stop list (.stp) Exclude specific words from searches
Compiled (.chm) Deploy the completed Help
The HTML Help Workshop provides tools to organize, edit, and compile these
files. By default, Visual Studio .NET installs the HTML Help Workshop in the
Program Files\HTML Help Workshop folder during setup.
To create a new HTML Help project, follow these steps:
From the HTML Help Workshop File menu, choose New. The Workshop starts the New
Project Wizard. The wizard lets you convert an existing WinHelp project or
create a new HTML Help project. Click Next to create a new project. The wizard
displays the Destination page. Type the location and name of the Help project
file you want to create, and then click Next. The wizard displays the Existing
Files page. Select the check boxes for any contents, index, or topic files you
have already created and click Next. If you select any of these existing
files, the wizard prompts you for the location of each of the selected file
types. Otherwise, the wizard creates a new, empty Help project.
A new, empty Help project
Using HTML Help Workshop is fairly simple. You use the Project, Contents, and
Index tabs on the left pane to edit the contents of the project, contents, and
index files. The buttons at the top of the pane create new files, open
existing files, compile the project, display the compiled project, and display
HTML Workshop Help.
To add topic files to the Help project, follow these steps:
Click New at the top of the HTML Help Workshop window, select HTML File, and
then specify a title for the topic. The Workshop creates a new Help topic
file.
Creating topic files
Save the HTML file, then click Add/Remove Topic Files on the Project tab. The
Workshop displays the Topic Files dialog box. Click Add, and then select the
files to add to the project. Click OK. Click OK again to close the Topic Files
dialog box. The Workshop adds the file to the project.
The HTML Help Workshop provides only basic text-editing capabilities. In
general, you will author your Help topic files in a full-featured HTML editor,
such as Microsoft FrontPage, and then use the Workshop to create the project
file and compile the Help.
Setting Project Options
Help project options are displayed on the Project tab of the HTML Help
Workshop. These options are stored in the Help project file (.hhp) in plain
text and can be modified using the HTML Help Workshop or a text editor such as
Notepad. To set project options in HTML Help Workshop, on the Project tab,
click Project Options. The Workshop displays the Project Options dialog box.
Setting options
The project options let you specify a title for the Help project, locale
information about the project, how the contents and index files are created,
whether to support searching, and other features. These items are placed in
the OPTIONS section of the project file. For example, the following project
options create index and contents files automatically when compiling a Help
file named HelpSample.chm, which displays the title "HTML Help Sample" in
the Help window:
[OPTIONS]
Auto Index=Yes
Auto TOC=9
Compatibility=1.1 or later
Compiled file=HelpSample.chm
Contents file= Contents.hhc
Default topic=topic1.htm
Display compile progress=No
Full text search stop list file=Search.stp
Index file=Index.hhk
Language=0x409 English (United States)
Title=HTML Help Sample
The project file also includes a FILES section that lists the Help topic files
to compile. The order of the files in this section determines the order of
items in the contents file when Auto TOC is selected in the OPTIONS section.
For example, the following topic files appear in sequential order in Contents:
[FILES]
topic1.htm
topic1a.htm
topic1b.htm
topic2.htm
topic3.htm
Building Tables of Contents
When building the table of contents automatically, the HTML Help Workshop uses
the heading level of the topic and its order in the FILES section of the
project file to determine how the table of contents is organized. The Workshop
puts <h1> headings at the top level, <h2> headings under those, and so on
until a new <h1> heading is encountered. If you have multiple heading levels
within a single topic, the Workshop creates subordinate Contents items for
each of those headings�even though they all represent the same Help topic. For
this reason, it is best to use only one HTML heading element per Help topic
when generating Contents automatically.
The following FILES section includes topic files with three heading levels, as
indicated by their filenames:
[FILES]
topic1.htm
topic1a.htm
topic1b.htm
topic2.htm
topic2a.htm
topic2b.htm
topic2bi.htm
topic2bii.htm
topic3.htm
Automatic table of contents
The Workshop stores the generated table of contents in an HTML file. You can
generate an automatic table of contents, turn off Auto TOC in the project
file, and then edit the generated contents file to customize the table of
contents. To edit a contents file, click the Contents tab in the HTML Help
Workshop. The Workshop displays the Contents.
Editing the contents file
One thing you might have noticed in the automatic Contents is that the icons for top-level topics aren't consistent. For instance, may show a page icon
rather than a book icon. To change the icon displayed for a topic, follow
these steps:
Select the contents topic, click Edit Selection, and then click the Advanced
tab. The Workshop displays the Table Of Contents Entry dialog box.
Changing the Contents entry icon
Select the image to use for the entry in the Image Index list box, and then
click OK. The contents file is stored as an HTML file that uses object
elements to specify the contents items, as shown by the following HTML:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic1">
<param name="Local" value="topic1.htm">
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 1.a">
<param name="Local" value="topic1a.htm">
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 1.a.i">
<param name="Local" value="topic1ai.htm">
</OBJECT>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 1.a.ii">
<param name="Local" value="topic1aii.htm">
</OBJECT>
</UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 1.b">
<param name="Local" value="topic1b.htm">
<param name="ImageNumber" value="1">
</OBJECT>
</UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 2">
<param name="Local" value="topic2.htm">
</OBJECT>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="">
<param name="Local" value="topic2.htm">
</OBJECT>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 2.a">
<param name="Local" value="topic2a.htm">
</OBJECT>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 2.b">
<param name="Local" value="topic2b.htm">
</OBJECT>
</UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Topic 3">
<param name="Local" value="topic3.htm">
<param name="ImageNumber" value="1">
</OBJECT>
</UL>
</BODY></HTML>
The HTML list items determine the hierarchy of the items in the table of
contents. The object elements determine the title, icon, location, and other
information about the link. For example, the following contents item links to
a company's New Products page and opens the page in a new window when the user
clicks it:
<OBJECT type="text/sitemap">
<param name="Name" value="New Products">
<param name="Local" value="http://www.mycompany.com/newproducts.htm">
<param name="WindowName" value="NewWindow">
<param name="Comment" value="Sample of text/sitemap params">
<param name="New" value="1">
<param name="ImageNumber" value="7">
</OBJECT>
Adding Index Entries
The HTML Help Workshop can automatically build an index file from object
elements entered in the topic files. Within a topic file, an index entry is
created as an ActiveX object with a specific classID, as shown in the
following HTML:
<param name="Keyword" value="Index Item 1">
<param name="Keyword" value="Index Item 1, Subitem a">
<param name="Keyword" value="Index Item 1, Subitem b">
</OBJECT>
The preceding HTML creates three index entries for that link to the topic file.
Automatic index entries at run time
The HTML Help Workshop does not automatically store index entries from topic
files in the index file; however, you can add Index entries to the index file
to help organize or to supplement the automatic entries. The index file (.hhk)
and the topic index entries are added together to create the Index displayed
in the compiled Help file. For example, the following index file (.hhk) is
combined with the automatic entries.
Combined index entries
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<UL>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Index Item 1">
<param name="Name" value="Topic 1.b">
<param name="Local" value="topic1b.htm">
</OBJECT>
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="Index Item 2">
<param name="Name" value="Topic 2.a">
<param name="Local" value="topic2a.htm">
</OBJECT>
</UL>
</BODY></HTML>
Adding Cross-References
There are three ways to cross-reference Help topics within HTML Help:
Use standard HTML hyperlinks to create a link from one Help topic to another.
Hyperlinks allow one-to-one relationships. Use the Related Topics command to
create a link from one topic to a list of other specific topics files. Use
associative links (ALinks) to create links from one topic to a list of other
topics based on keywords entered in those topic files. Since you already know
how to create hyperlinks (by now you'd better), the following sections discuss
how to add Related Topics and create associative links.
Adding Related Topics
You can add related topics as a cross-reference or a hyperlink. To add a Related Topics cross-reference to a Help topic, insert an HTML Help ActiveX
control in the topic file. For example, the following object element displays
a button that lists two Related Topics as pop-up menu choices:
<OBJECT id=hhctrl type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,74,9273,0"
width=100
height=100>
<PARAM name="Command" value="Related Topics, MENU">
<PARAM name="Button" value="Text:Related Topics">
<PARAM name="Item1" value="Topic 2;Topic2.htm">
<PARAM name="Item2" value="Topic 3;Topic3.htm">
</OBJECT>
Related topics
To display related topics as a hyperlink instead of as a button control,
specify a Text parameter rather than a Button parameter in the object element.
For example, the following HTML displays the preceding Related Topics as a
hyperlink:
<OBJECT id= hhctrl type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,74,9273,0"
width=100
height=100>
<PARAM name="Command" value="Related Topics, MENU">
<PARAM name="Text" value="Text:Related Topics">
<PARAM name="Item1" value="Topic 2;Topic2.htm">
<PARAM name="Item2" value="Topic 3;Topic3.htm">
</OBJECT>
Creating Associative Links
Associative links reference keywords rather than specific filenames. For this
reason, they are useful for cross-referencing between HTML Help files�you
don't have to know how the topics within a compiled file are named, you just
need to know which keywords were used. Associative links are useful within a
single Help file as well�filenames can change during development, and it is
easier to maintain a keyword list than it is to update filenames within cross-
references.
There are two parts to an associative cross-reference:
The keywords entered in the target topic files provide the destinations that cross-references link to.
The link entered in the referencing topic file provides the source from which the cross-reference links.
To create associative link keywords, insert an object element in the target topic. For example, the following object element creates the associative link keyword "Link1":
<Object type="application/x-oleobject" classid="clsid:xx-xx-x-x-x-xx">
<param name="ALink Name" value="Link1">
</OBJECT>
Associative links are very similar to keywords used in indexing HTML Help.
However, they do not appear in the Index. The reason for this is to allow
cross-referencing and indexing to be maintained separately.
To create a link to topics with a specific keyword, insert an HTML Help
control ActiveX object in the topic file making the cross-reference. For
example, the following object element displays a list of cross-references in a
pop-up menu when the user clicks the control:
<OBJECT id=hhctrl type="application/x-oleobject"
classid="clsid:xx-xx-xx-xx-xx"
codebase="hhctrl.ocx#Version=4,74,9273,0"
width=100
height=100>
<PARAM name="Command" value="ALink, menu">
<PARAM name="Button" value="Text:See Also">
<PARAM name="Flags" value=",,1">
<PARAM name="Item1" value="">
<PARAM name="Item2" value="Link1">
</OBJECT>
At run time the preceding HTML displays a list of topic titles that contain the associative link keyword "Link1".
Associative links
To display associative links as a hyperlink rather than as a button control,
omit the Button parameter from the object element and call the object's Click
event from the hyperlink. For example, the following HTML displays the links
when the user clicks the See Also hyperlink:
<OBJECT id=hhctrl type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,74,9273,0"
width=100
height=100>
<PARAM name="Command" value="ALink, menu">
<PARAM name="Flags" value=",,1">
<PARAM name="Item1" value="">
<PARAM name="Item2" value="Link1">
</OBJECT>
<a href="#" onclick="hhctrl.Click()">See also</a>
Enabling Searches
To enable full-text searches within a Help file, select Compile Full-Text
Search Information from the Compiler tab of the Project Options dialog box.
When full-text searching is enabled, the HTML Help Workshop builds a
concordance table of all the words in your topic files and includes that table
in the compiled Help file. Because this table references all words in the
topic files, it can become quite large. To help control the size of this
table, you can omit words that are not useful for searching. For example, you
might want to omit articles, conjunctions, personal pronouns, and numbers from
full-text searching.
To omit words from full-text searching, follow these steps:
Create a text file listing the words to omit.
Click Change Project Options on the HTML Help Workshop Project tab.
On the Compiler tab of the Project Options dialog box, type the filename of
the list of words to omit in the Full Text Search Stop List text box.
When a user tries to search on a word that you include in the stop list, HTML
Help displays a message box stating that the phrase cannot be searched on.
Compiling and Previewing Help
To compile an HTML Help project, choose one of the following two steps:
On the Project tab of the HTML Help Workshop, click Save All Files And Compile.
Use the HTML Help Compiler (hhc.exe) from the command line. For example, the
following command line compiles the HelpSample.hhp Help project.
hhc.exe HelpSample.hhp
To preview a compiled HTML Help project, choose one of the following two steps:
At the top of the HTML Help Workshop window, click View Compiled File button,
and then select the filename of the compiled file.
Double-click the compiled Help file (.chm) in Windows.
Important - You cannot recompile a Help file while the compiled Help file is
open for viewing. You must close the compiled Help file before recompiling.
Linking HTML Help to Web Forms
Displaying the HTML Help Viewer
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:
Non-compiled 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 displays differently, depending on whether the Help file
is compiled.
Compiled vs. non-compiled Help
Compiled Help displays Contents, Index, and Search features, while non-
compiled 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 by Internet Explorer version 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 are 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 because the topic displayed depends upon 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 id="WebForm2" 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 id="chkHelp" 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 id="WebForm2" 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 id="chkHelp" 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.
Summary
� You can provide user assistance within Web applications by using ToolTips, Web forms or HTML pages, or HTML Help.
� HTML Help provides built-in Contents, Index, and Search capabilities.
� Use the window object's showHelp method in client-side scripts to display the HTML Help Viewer.
� Use the HTML Help Workshop to create HTML Help projects and to compile HTML Help.
� Use the HTML Help ActiveX object to add index keywords, related topic links, and associative links to Help topics.
� To display compiled Help files from a Web application, you must first download the file to the user's machine.
____________________________________________________________________________
To contact me, please (Author of this website) E-mail me at:
jep1965@gmail.com
This page last updated July 6 2008