This document provides information about Netscape's Hyper Text Markup Language (HTML) help implementation using Netscape Navigator. The intended audience is help and application developers.
NetHelp (NetHelp) is an open standard for viewing HTML-based online help. Based on the Netscape Navigator 3.0 (currently in beta release) or later client, NetHelp allows you to provide context-sensitive online help for an application---in any environment where Netscape Navigator is present. With NetHelp, you can:
To ensure that the end user would be able to access help, help developers either had to provide a help viewer with the application software, or be reasonably confident that the viewer already existed on the user's computer. WinHelp became a success, in part, because the viewer existed on all Windows-based PCs---you knew that if a computer had Windows, it had the WinHelp viewer.
Other help systems required per-viewer license fees; along with your software product, you shipped a copy of the help viewer, and you paid the help software vendor a fee for every viewer you ship. For software that sells in low volume, this cost could be recouped within the price of the software itself; an large enterprise software package could amortize the help viewer cost within the large application license fee. For software that sells in high volume, like Web browsers, even a low-cost per-user license would have been prohibitive.
For software products that work on multiple platforms, you had to provide platform-specific help solutions--often, the expense of developing and providing separate help systems, with the same or similar content, was prohibitive.
We developed NetHelp to solve these and many other problems, most notably the difficulty of providing context-sensitive online help across multiple platforms and operating systems.
NetHelp is the obvious choice when the product for which you're developing help uses Navigator as its client, or when the product ships with Navigator as its connection to the Web. Since Navigator is the most popular application for browsing the web, your users are likely to have Navigator installed already.
Here are a few examples of products that can take advantage of Netscape Help:
Netscape Navigator accompanies all Netscape products. Many use Navigator to display their HTML based user interfaces. For example, Netscape servers, with their HTML form-based UI, use Navigator as their clients. The LiveWire application manager with its HTML interface, uses NetHelp, while Site Manager, a native application for web site management, also uses NetHelp accessed from its Windows, Mac, or UNIX clients. NetHelp was designed to provide cross-platform help support for these products.
Network applications use Web technology instead of traditional client/server/middleware technology. Examples include Internet shopping malls, customer support systems like the FedEx package tracker, and Intranet applications like corporate phone lists or bug tracking systems. Such applications, especially in Intranet environments where Navigator is the default browser, often use Navigator as their client. NetHelp is a natural fit for such applications, including those produced using LiveWire and NSAPI. Even traditional web sites like web-based magazines and newspapers can use NetHelp to provide context-sensitive online help for HTML pages.
ISPs provide Internet access clients to their users, including TCP/IP stacks, mail and news readers, and Web browsers. ISPs that provide Navigator to their users, in particular, ISPs that provide customized Navigators, could make effective use of NetHelp to provide customized help content to their users. For example, an ISP could provide company-specific information like server names or support contacts within customized NetHelp.
Applications native to a specific operating system can benefit from NetHelp as well. NetHelp provides a cross-platform, single-source solution for online help--the same help files can be used on any platform. Also, the rich content that HTML and plug-ins provide increase retention and effectiveness of your online help.
NetHelp, by virtue of being based on Netscape Navigator, has a viewer that is fast becoming ubiquitous in the Web world. NetHelp also provides the following benefits:
NetHelp works on any platform that Navigator runs on, and the current uncompiled file design allows the same source files (HTML, with Java or JavaScript) to be read by any Navigator on any platform. This means that if your content permits it, you don't have to change your source files for distribution on multiple platforms. The same source files can be installed to a local hard drive or hosted at your web site.
Help users can easily obtain the latest help information in a Netscape Help system, as individual topics can be kept current without recompilation. For example, you could construct a NetHelp system with a combination of locally installed and server-hosted topics. Information that has to be kept timely and up to date can be kept on your web server--users can access that topic from the help system, with the content appearing in their help window, just like any other topic.
HTML is fast becoming a standard for network-based information display. Netscape Help therefore benefits from the new tools available for producing content in HTML. NetHelp coding can be done with HTML WYSIWYG editors such as Navigator Gold. For functionality beyond HTML, you can use JavaScript functions embedded within HTML pages, like you'd use WinHelp macros or Guide Script. The same tools and techniques used to publish information to web sites can be used to construct NetHelp systems.
Netscape's HTML extensions provide richer, more appealing content than traditional online help systems. Extensions like tables and frames allow better layout control than many help systems. The new positioning, multicolumn layout, and dynamic font extensions introduced in Netscape Navigator 3.0 take help design to a new level. The current implementation of a bare window that accepts any Netscape HTML coding allows help developers to basically design their own online help UI. Other help systems, on the contrary, do not let you alter their default button bar or other UI elements.
Plug-ins provide multimedia extensions to Navigator that by design, are propagated to the NetHelp platform. Audio and video plug-ins increase the media types that can be presented to the user. Interactive media, such as Shockwave for Director files, can be used in computer-based training or "edutainment" packages. Digital paper plug-ins, such as Adobe Amber, or Tumbleweed Envoy, let you leverage your investment in digital paper publishing within your NetHelp system. 3-D plug-ins can provide models for users to manipulate instead of flat images. None of these extensions are currently available to traditional online help systems.
NetHelp is highly customizable and allows you to design your own user interface. Click the Help button below to see a basic layout example:
You can customize the button bar, colors, backgrounds, and other layout elements. Any graphical enhancements available to Web page designers are also available to you, the help developer, constructing a help system for an application.
For example, the online help system demonstrated here includes the following elements:
Of course, the same design guidelines you've followed in designing previous help systems apply to NetHelp systems as well. For most online help systems, you'll want to use a minimalist design so your users find the information they need without much visual overhead. For tutorials and conceptual information, you can use the broad spectrum of graphical and multimedia extensions to enhance the learning environment.
NetHelp can be called in two different ways:
Though the two methods differ in how they are invoked, once the help window is displayed, their appearance is essentially the same.
This type of help is used in the Netscape Site Manager application, part of the LiveWire 1.0 product. To see an example of this type of help without installing LiveWire, run the Helpdemo application for Windows (HELPDEMO.EXE) included with this SDK. See the section about using the provided test utilities for more information.
This type of NetHelp could be used for any native application, in place of or supplemental to an operating system-specific help engine like Windows Help, Apple Guide, or UNIX manpages.
Here's an overview of the process:
The following graphic illustrates the process:
This type of help is used in Netscape server products, such as FastTrack and Enterprise. This type of help could be used for any web site or application that uses an HTML interface--including all of the web sites on the Internet or intranet.
Here's an overview of the process.
Be sure you are familiar with the overview of how NetHelp works. The following sections describe in more detail how the components work together. To speed your learning of this technology, you should examine the sample help system included with this developer's kit. Later, you can create your own help system by customizing the included files.
To help you implement NetHelp quickly and easily, we provide a number of different working examples of the various help components You are free to use them as they are, or customize them to fit your needs.
The steps you take to create your NetHelp system are mostly the same whether you're going to be calling it from an application or an HTML page. However, the step of calling NetHelp is very different between the two methods. The general steps are as follows:
Provide a way to call NetHelp from the application or HTML page.
When called from a native application, the NetHelp function is attached to a Help button or menu item within the application's user interface. When called from an HTML page, the NetHelp function is attached to an HTML form button, link, or image.
Create the help user interface, consisting of a frameset file with navigation graphics.
To call NetHelp from a native application, perform the following steps:
The basic component of application-called NetHelp is the project file, where most of the help system is defined. The help project file is a text file that specifies help system settings and all mappings of IDs to URLs. The location and name of the project file are specified in the initial call from your application to Navigator. The project file is examined by Navigator every time your application calls help. (See How it works.)
Here's an example of a small project file. A line starting with a semicolon (;) is a comment and is ignored when the file is processed by Navigator. Blank lines are also ignored. All other lines are help system specifications. The purpose and syntax of these specifications is explained in the section following the sample project file.
; SAMPLE HELP PROJECT FILE ; Last updated 9 August, 1996 by CB Window-Name="Sample Help" Window-Size="400,400" <Frame_Group src = "ref.htm" default_window="help"> <ID_MAP> ; FILE MENU 134670 = "lorem.htm": target="topic" 134671 = "topic2.htm": target="topic" 134672 = "topic3.htm": target="topic" 134673 = "topic4.htm": target="topic" ; TOOLS MENU 15000 = "topic5.htm": target="topic" 15001 = "topic6.htm": target="topic" 15002 = "topic7.htm": target="topic" 15003 = "topic8.htm": target="topic" </ID_MAP>
Syntax explanation:
; SAMPLE APPLICATION PROJECT FILE
; Last updated 9 August, 1996 by CB
As noted earlier, lines beginning with a semicolon are ignored
when processed by Navigator. As a matter of style, you might find it useful
to include a pair of identifying lines like this at the start of your project
file.
Window-Name="Sample Help"
This line specifies the window's title. It's equivalent to the
HTML tag TITLE.
Window-Size="400,400"
This line specifies the size of the help window, in pixels --
first width, then height. The measurement is of the inside of the
window, and does not include the window's title bar. This is an optional
line. If it is not included, the default window size is 400 by 500 pixels.
<Frame_Group src = "ref.htm" default_window="help">
This line specifies the location and name of the frameset file.
The location and name are relative to the project file---see Specifying
locations and filenames in the project file.
<ID_MAP>
This line marks the beginning of the ID-to-URL mapping section.
134670 = "topic2.htm": target="topic"
This line specifies the corresponding URL for an ID. Additionally,
this line specifies the target frame for the URL. The location and name
are relative to the project file---see Specifying
locations and filenames in the project file.
</ID_MAP>
This line marks the end of the ID-to-URL mapping section.
The locations and filenames in the project file must be specified relative to the location of the project file. For example, if a frameset file named window.htm is kept in the directory (or folder) framesets off of the project file's directory, the frameset line would read:
<Frame_Group src = "framesets/window.htm">
Likewise, if the topic file save.htm were located in the directory above the project files directory, an ID-mapping line would read
134670 = "../save.htm": target="topic"
Notice that the locations and filenames are specified like URLs, with a forward-slash / between each directory. This is because Navigator will parse the other URL information (protocol, machine name, and program directory) with this information before it loads any files. Note also the "dot-dot" convention for denoting the parent directory of the directory containing the file.
Although you can create whatever directory structure you want for your help file, you should consider putting your project file and all your HTML help files in the same directory or folder (for example, a directory called HELP off of your application's installation directory). That way, file references in your project file won't have to specify directories. (Whether you specify subdirectories for the graphics or other embedded files in your help content is another question.)
To call NetHelp from an HTML page, perform the following steps:
Example:
Here's the JavaScript "behind" this button:
<input type=button name="blank" value="Help" onclick="help('topic2.htm')">
Syntax explanation:
<input type="button" name="blank" value="Help"
The JavaScript defines a button object and labels it "Help".
onClick="help('topic2.htm')">
The JavaScript then uses the onClick event handler to call the help function, passing the value 'topic2.htm', when the button is clicked. When called, the help function will load the help topic in the file topic2.htm. To use this button in your HTML files, simply replace topic2.htm with the name of your help topic's HTML file.
The button you've just defined calls a "help" function. Before it can use the help function, you have to make the help function available by inserting it into your HTML page's HEAD section. When the page is loaded by Navigator, the help function is loaded into memory and is available whenever it is called by other JavaScript statements (like the Help buttons you define) on the page.
NOTE: This JavaScript help function is not the same code as the NetHelp function call used with native compiled applications (as described in Calling from an Application). Although it performs much the same, it is implemented using JavaScript, not the method (OLE, X-Event, AppleScript) native to the specific operating system.
When creating NetHelp for HTML pages, incorporate the help function in each page for which you want to provide online help. If you have many such pages, and you are using Navigator 3.0, you can use the SRC attribute of the SCRIPT tag to include the function definition in each page. For example, if you define help in a file called helpfun.js (and keep it in the doc directory below the app directory), then each page that calls help would include the following tag:
<SCRIPT SRC="doc/helpfun.js>
If users don't have Navigator 3.0, then you have to explicitly include the function definition in each page, since the SRC attribute of the SCRIPT tag is not implemented in Navigator 2.0
If you look at the source of this SDK file, you'll notice that its HEAD section contains the following function:
function help(helptopic) {
var HelpWin=window.open("examples/help.htm","HelpWin",
"toolbar=no,directories=no,menubar=no,status=no,
scrollbar=no,resizable=yes,width=400,height=500");
HelpWin.onload=new Function("this.topic.location='" + helptopic
+ "'")
//Calls to this function must pass the topic name
as relative to the frameset's defined directory.
}
You don't need to change this function. Simply include this function in the <head> section HTML pages that call NetHelp. However, if you move or customize your frameset file, you must update the pathname and filename of the frameset file--the highlighted portion of the function (examples/help.htm)--to reflect the new name or location of your altered frameset file. Also, be aware that all the topics you specify in the body of the calling HTML must be specified with locations relative to the location of the frameset file.
When the new help window is created by Navigator (either called from the JavaScript NetHelp function within your HTML page or by the NetHelp function called by your application), the help system's frameset file is the first thing loaded into the window. (The frameset file is dependent on the HTML frames syntax. For an overview of frames syntax, refer to Frames: An Introduction, at the Netscape Web site.)
Whether NetHelp is called from an application's code or from HTML in a web application, it uses a frameset file. After mastering the basics of this frameset approach, you can create help systems with as many frames as you need.
The two-frame window that appears when the above Help button is clicked is created using three separate HTML files:
To use the above files as an example, help.htm would be the frameset file. Each time your native application or HTML page calls NetHelp, Navigator loads help.htm into the help window. For native application-called NetHelp, Navigator determines the name of the frameset file from the help project file. For HTML-called NetHelp, Navigator determines the name of the frameset file from the JavaScript help function.
Here's the pertinent HTML code from a frameset file:
<frameset rows='52,*'>
<frame src="navbar.html" scrolling=no marginwidth=0 marginheight=0 name="buttons">
<frame src="about:blank" name="topic">
</frameset>
Syntax explanation:
<frameset rows='52,*'>
HTML to define two row frames in the help window, one 52 pixels high, the other taking up the rest of the window's height.
<frame src="navbar.html" scrolling=no marginwidth=0 marginheight=0 name="buttons">
HTML to load the navbar.html file into the top frame, naming the top frame "buttons," and setting the look of the frame to have no scrollbars and margin width and height of zero.
<frame src="about:blank" name="topic">
HTML to define a blank bottom frame. If you wish, instead of about:blank, you can load a contents.htm file or other help topic to be used as a default help topic for the help system. The NetHelp function used with native application-called NetHelp determines the URL to be loaded in this frame from the project file. HTML-called NetHelp determines the URL to be loaded in this frame from the help() function attached to the Help button or link.
</frameset>
HTML to define the end of the frameset.
Although the contents of the top frame (the navigation buttons) would remain constant, the contents of the bottom frame would vary with each different ID.
Both application-called and HTML-called NetHelp use the same mechanism to provide navigational tools in the help window.
The sample help called by the example button in HTML-called NetHelp uses small GIF files as navigation buttons. The file navbar.html that is loaded into the help window (as described in the discussion of the frameset files), uses these button graphics to link to the Contents topic and Index topic, and link to Back, Forward, and Exit functions. You do not need to modify this file.
If you want to change the look of the button graphics, you do not need to change any of the HTML or JavaScript functions called by navbar.html. Simply create your own GIF files to replace the ones called by navbar.html.
If you are interested in how navbar.html works, read through the following discussion. This information is provided for the curious--again, you do not need to modify navbar.html to use its navigational functions.
Here's the pertinent HTML code of navbar.html:
<table width=100%>
<tr><td align="left" valign="top">
<a HREF="contents.html" target="topic"><img
src="images/content1.gif" border=0 height=37 width=44></a>
<a HREF="index.html" target="topic"><img src="images/index1.gif"
border=0 height=37 width=44></a>
<a HREF="javascript:parent.frames[1].history.go(-1)"><img
src="images/back1.gif" border=0 height=37 width=44></a>
<a HREF="javascript:parent.frames[1].history.go(1)"><img
src="images/forward1.gif" border=0 height=37 width=44></a>
</td>
<td align="right" valign="top">
<a href="javascript:top.close()"><img src="images/exit1.gif"
border=0></a>
</td>
</tr>
</table>
Syntax explanation:
<table width=100%>
<tr><td align="left" valign="top">
HTML tags to define a table in which the graphics will be placed. This allows better control over the position of the button graphics.
<a HREF="contents.html" target="topic"><img src="images/content1.gif" border=0 height=37 width=44></a>
HTML link to the Contents topic, using the file content1.gif as the button graphic, with a border of zero pixels and a height of 37 pixels by 44 pixels wide. When this button is clicked, the file contents.html is loaded into the topic frame.
<a HREF="index.html" target="topic"><img src="images/index1.gif" border=0 height=37 width=44></a>
HTML link to the Index topic, implemented in a similar manner to the Contents button.
<a HREF="javascript:parent.frames[1].history.go(-1)"><img
src="images/back1.gif" border=0 height=37 width=44></a>
<a HREF="javascript:parent.frames[1].history.go(1)"><img
src="images/forward1.gif" border=0 height=37 width=44></a>
JavaScript calls to the history list, where clicking the Back button (using the file back1.gif as the button graphic) causes the previous topic (thus the .history.go(-1) portion of the JavaScript) to get loaded into the topic frame. In a like manner, the Forward button causes the next topic in the history list to get loaded into the topic frame.
</td>
<td align="right" valign="top">
More HTML table definition tags.
<a href="javascript:top.close()"><img src="images/exit1.gif" border=0></a>
JavaScript call to close the current window ( in this case, the help window) when the Exit button (using the file exit1.gif as the button graphic) is clicked.
</td>
</tr>
</table>
More HTML table definition tags.
You can simply add your HTML content to the topic files included in the sample help system (topic1.htm, topic2.htm, etc.) or add additional help topic files as you see fit. You'll also want to edit the contents.htm and index.htm files to reflect the actual contents of your Netscape Help system.
You can use all HTML tags supported by Netscape Navigator in your HTML source--therefore, you can provide rich content using frames, tables, multicolumn layouts, and other HTML-derived formats. You can also provide multimedia content using the <EMBED> tag, provided that the proper plug-ins are present. This HTML tag lets you embed plug-in supported files, such as Adobe Acrobat or Macromedia Shockwave files, within your HTML help content. For more information on the <EMBED> tag, see Embed Tag Syntax at the Netscape Web site.
Two Windows utilities are included with this SDK: HELPDEMO.EXE, and NAVHELP.EXE.
HELPDEMO.EXE demonstrates how a native application accesses Netscape Help. HELPDEMO.EXE is a native Windows application with a Help menu. In fact, this is simply the Help menu portion of an existing Netscape application. Help topics in the sample help system can be accessed from HELPDEMO.EXE's Help menu in the same way they would be from any other native application.
Included with this SDK is a Windows application called NAVHELP.EXE. This is a utility that allows you to test context-sensitive help files even when the application that will ultimately call your help is not available. By specifying a help ID, you can "test-drive" what will happen when a help button is clicked in your application, or F1 is pressed. This utility is only available under Windows for this release but will be available for Mac and Unix platforms in the future.
Note: The Help Search String feature is not enabled for this release.
The browser opens displaying the page referenced by the help ID you specified.
Included with this SDK is the actual code (C/C++) used in some of our products that you can use (some modifications may be necessary) to call NetHelp from your product. Although the help content is cross-platform, the code put in your application is not. That is, on Windows the help window is called via OLE; on the Macintosh, through AppleScript; on X-Windows, as an X-Event.
Each operating system's sample code is accompanied by explanatory notes.
The following are some of the topics that will be addressed in future updates to this SDK. Please stay tuned...
You are free to use and distribute the sample files that, in future, will be available here. Use them as they are, or customize them to fit your needs. (Naturally, you'll want to read our disclaimer.) In the spirit of open standards, we will continually update our Help Developers site with new graphics, framesets, JavaScript examples, and Java applets, all free for distribution.
If you would like to submit sample files to our site, contact us at htmlhelp@netscape.com. If we post your sample file on our site, we'll credit you by name and email address (if you want).