Using HelpIndex

Last modified: 21 February 1997.

This page describes how to put HelpIndex onto your web site. You may wish to consult our Getting Started guide as well.

Page Contents
Make your help index file
Write your web page
Parameters
Example
Mode parameter
Index parameters
CODEBASE
Frames


Make your help index file

Your first job is to make a help index file for your pages.

This index file contains a list of your URLs and the index entries which link to them. The index file is in a published format in case you need to know.

Most people start off by using the supplied MakeHelpIndex Java program to generate an index file from their existing web pages. This looks at your main page (eg index.html or default.htm) and follows all the appropriate links to generate the index file. Each page will usually have at least one index, ie the page's title. See MakeHelpIndex for full details of what indices are made.

Alternatively you could build you index file by hand. This is hard work. However you may wish to tweak the file produced by MakeHelpIndex (or -better- alter your HTML so that MakeHelpIndex produces the right indices automatically).

Important: If you change your index file then you will almost certainly need to stop and restart your browser, as it will have cached your previous index.

We hope to have a HelpIndex Workshop Windows program available soon. This will make buiding and editing your help index files much easier.

Make sure that you keep your help index up to date with your pages.


Write your web page

Once your help index file is set up, HelpIndex is simple to use on a web page.

You need to add an APPLET tag with various parameters, as shown here.

You must specify the applet width and height; you may need to tweak these to allow room for large fonts or small displays.

Simple usage:
On web page
<APPLET code=HelpIndex.class width=450 height=250>
<PARAM NAME=index VALUE=siteindex.hi>
<PARAM NAME=mode VALUE="applet wide">
Sorry, you need a browser that runs Java to see the Help Index.
</APPLET>
Clickable icon
<APPLET code=HelpIndex.class width=70 height=80>
<PARAM NAME=index VALUE=siteindex.hi>
<PARAM NAME=mode VALUE="icon wide">
Sorry, you need a browser that runs Java to see the Help Index.
</APPLET>
The index parameter must be supplied to define your index file. In version 2, you can specify one or more index<N> parameters, see below.

In many cases, you will want to use HelpIndex in conjunction with HTML frames - see below. You could have the help index in one frame and any found pages displayed in another. HelpIndex supports this technique using the Target parameter.

On your HelpIndex page, you might also like to have some instructions, and - if desired - some predefined links for top-rated indices.


Parameters

You can add any of the following parameters to alter how HelpIndex runs. Add the parameter between the <APPLET> and </APPLET> tags, as shown in the examples above. Remember that it is best to enclose the VALUE string in double quotes. Note that the case of the NAME does not matter.

For example, to make the background colour yellow, add

<PARAM NAME=bgcolour VALUE="yellow">
Parameter Type Description Default
BgColor
BgColour
RGB triplet or colour name The background colour (above and below the tab cards) white
Version 2 only cardbgcolor RGB triplet or colour name The background colour of the cards, ie the main background. Light gray
FgColor
FgColour
RGB triplet or colour name The foreground colour black
fieldbgcolor RGB triplet or colour name The background colour of fields. BgColor
font Font definition The font used in the form Dialog 12pt
icon string The icon URL, relative to the code base helpindex.gif
iconbgcolor RGB triplet or colour name The applet background colour in icon mode. BgColor
* index string The index file URL, relative to the document base none
Version 2 only index<N> C style string of up to five comma-separated strings. See below
index file URL
language file URL
options
initial selection
initial query
none
indexlines integer, >= 1 The number of lines in the Indices list box 4
* language string The language file URL, relative to the code base none
defaults to English
minquerylength integer, >= 0 The minimum length of the query text before lookups occur.
A bit unnecessary as lookups have a separate thread, see above.
If non-zero, please include instructions in your web page.
0
mode string One of "applet" or "icon",
and one of "wide" or "high"
Version 2 only and optionally "nocontents", "noselect" or "index".
applet wide

Version 2 onlyapplet high

pagelines integer, >= 1 The number of lines in the Pages list box 2
* query C style string The initial query none
target string The target frame
The following frame names have special meaning:
_selfcurrent frame
_parentparent frame
_toptop-most frame
_blanknew unnamed top-level window
"_self"

* These parameters should only be used in version 1. The version 2 index<N> parameters offer the same functionality.


Example

This is a complicated example, using quite of few of the parameters.
<APPLET code=HelpIndex width=100% height=90% alt="HelpIndex site index">
<param name=mode value="applet high">
<param name=index value="helpindex.hi">
<param name=index1 value="helpindex.hi">
<param name=index2 value="phd.hi">
<param name=index3 value="webdes.hi,,,index.html">
<param name=index4 value="webdesfr.hi,french2.hil">
<param name=index5 value="JDKAPI.hi,,index sort,,class java.">
<param name=index6 value="dbex.hi,dbex2.hil,index nocontents">
<param name=index7 value="helpindex.hi,french2.hil">
<param name=index8 value="helpindex.hi,german2.hil">
<param name=iconbgcolor value="#FFFFC0">
<param name=fgcolour value=blue>
<param name=bgcolour value=#FFFFC0>
<param name=fieldbgcolor value=white>
<param name=cardbgcolor value=lightgray>
<param name=pagelines value=3>
<param name=target value="Main">

Please use a Java enabled browser.
<META HTTP-EQUIV="REFRESH" CONTENT="0; URL=contents.html">

</APPLET>

Mode parameter

The mode parameter specifies
(a) whether you want HelpIndex to appear on a web page ("applet") or as an "icon", and
(b) whether you want the search form to be "high" or "wide".

In "icon" mode, the applet appears as an icon initially. The user must click anywhere on the applet space, ie on the icon, to show the help index form in a new window. The window is resized to fit the form.
Note that the default icon - helpindex.gif - is 70 by 80 pixels, so you should use these values for the applet width and height.

If the mode is "wide", then the form is arranged so that it is wider than it is high. In "high" mode the form is higher than it is wide.
If in "applet wide" mode the applet should typically be at least 450x250 pixels. If in "applet high" mode the applet should typically be at least 200x350 pixels.


Index parameters

Version 1 only
Version 1.7.1 uses the index parameter to specify the index file, the language parameter to give the language file, and the query parameters for the initial index query.

Version 2 only In version 2, you should use one or more index<N> parameters instead, eg index1, index2, etc.
NB: the index, language and query parameters are still supported.

Each index<N> parameter should have one or more of these comma-separated string fields.
index The index file URL, relative to the document base
language The language file URL, relative to the code base
options One or more of the following options:
index Select the Index tab first, not Contents.
nocontents Do not display the Contents.
sort Sort the page names in the Contents.
selection The URL to be selected initially in the Contents tree.
query The initial query in the Index.

Here are some example parameters:

<PARAM NAME=index1 VALUE=index.hi>
<PARAM NAME=index2 VALUE="indexfr.hi,french2.hil,,index.html">
<param name=index3 value="JDKAPI.hi,,index sort,,class java.">
<param name=index4 value="dbex.hi,dbex2.hil,index nocontents">
The index, language, etc. specified in index1 are used at startup. Note that the user's default language is not detected.

If index1 is not given then version 1 index, language and query parameters are used.

If there is only one index then the Select tab is not displayed.


CODEBASE

You can have the HelpIndex classes in a different directory to your web pages. Within your APPLET tag, specify the HelpIndex directory using CODEBASE, eg if HelpIndex is in the classes sub-directory use:
<APPLET code=HelpIndex.class codebase=classes width=70 height=80>

Remember that your help index file must be accessible to HelpIndex. Java security rules say that it cannot access a directory higher in the disk hierarchy. So if HelpIndex is in a classes sub-directory, then your help index file must be in classes or lower.

Important: Note carefully that the HelpIndex classes must be on the same server as the web page which calls it. If this were allowed then you would be using the resources of someone else's server.


Frames

If using frames, you may well want to use the "skip target" option when running MakeHelpIndex. See Frames and the Skip Target.

Here are three suggestions for how to use HelpIndex in framesets.

These examples assume the following frameset, ie a thin contents column and a wide main window.

<FRAMESET COLS=1*,3*>
	<FRAME SRC=contents.html NAME="Contents">
	<FRAME SRC=welcome.html NAME="Main">
</FRAMESET>

HelpIndex    PHD