Using Hi HelpIndex

Last modified: 13 October 2003.

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

Read the Getting Started guide

This page details how to put Hi HelpIndex onto your web site by hand.
First time users, please read the Getting Started guide instead.

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 keywords 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 Hi Lab Windows design tool to generate an index file from their existing web pages. This scan looks at your main page (eg index.html or default.htm) and follows all the appropriate links to generate the index file.

Alternatively, you could use the MakeHelpIndex Java program or edit your index file by hand. Both these options are hard work.

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.

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


Write your web page

Hi Lab makes writing your first Hi HelpIndex web search page easy.

However, it is also straight forward to write a suitable web page by hand, or using your favourite web page editor.

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 archive="hi210.jar" width=450 height=250>
	<PARAM NAME=index1 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 archive="hi210.jar" width=70 height=80>
	<PARAM NAME=index1 VALUE=siteindex.hi>
	<PARAM NAME=mode VALUE="icon wide">
	Sorry, you need a browser that runs Java to see the Help Index.
	</APPLET>
	
The index1 parameter must be supplied to define your index file. You can specify more index<N> parameters, see below.

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

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

Hi HelpIndex bean applet 2.3 version

If you want to use the Hi HelpIndex bean applet version on your web site, use the follow HTML:
<APPLET code=COM.phdcc.hi.HelpIndex archive="hi230.jar" width=450 height=250>
<PARAM NAME=index1 VALUE=siteindex.hi>
... other parameters ...
Sorry, you need a browser that runs Java to see the Help Index.
</APPLET>
Include all the other parameters as before.
Do not use the cabbase parameter.

If this code is seen by a browser that does not support JDK 1.1, eg Navigator 3 or Explorer 3, then the applet will not run. There is a way of checking browsers using Javascript; this can ensure that the right HTML for the user's browser is used.

Note that Navigator 4 does not read the default gif files from hi230.jar. So you will need to put these files in the same directory as hi230.jar: hi.gif, hiicons.gif and hitabs.gif.


Parameters

You can add any of the following parameters to alter how Hi 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 the tab cards) white
ButtonShape string The shape of the expand/contract folder buttons in the Contents (round or square) round
CardBgColor RGB triplet or colour name The background colour of the cards, ie the main background. #FFFFCC, ie light yellow
ContentsIcons string The Contents icons URL, relative to the code base. See below. hiicons.gif
FailOnAnyError string Set to anything to fail on any load error
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 Dialog 12pt
Icon string The icon URL, relative to the code base. See below. hi.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
index<N> C style string of up to six comma-separated strings. See below
index file URL
language file URL
options
initial selection
initial query
locale
none
IndexLines integer, >= 1 The number of lines in the Keywords list box 4
kwMaxResults integer, >= 0 The number of entries shown in the Keywords list box before "... etc" is shown. If 0, then all entries are shown. 50
kwSubstFrom String If specified, the keyword sub-field delimiter in index file type 7 field 2 (Index).
To include spaces at the start or end, put # characters at start and end, eg: #, #.
none
kwSubstTo String The string used to replace each sub-field found delimited by kwSubstFrom.
To include spaces at the start or end, put # characters at start and end.
none
* language string The language file URL, relative to the code base none
defaults to English
LookForBgColor RGB triplet or colour name The background colour of the Index panel "Look for" field. FieldBgColor
MinIconWindowSize width,height Specifies the minimum size of the icon mode floating window.
If small then the window dimension may actually be bigger
If large then the window is made the size of the user's screen, eg "0,2000" will make the window fill the left hand side of the screen.
0
MinQueryLength integer, >= 0 The minimum length of the query text before lookups occur.
A bit unnecessary as lookups have a separate thread.
If non-zero, please include instructions in your web page.
0
Mode string See below.
One of "applet" or "icon",
one of "wide" or "high"
and optionally "popup" and/or "close"
applet high
PageLines integer, >= 1 The number of lines in the Pages list box 2
* query C style string The initial query none
SelectColor RGB triplet or colour name The colour of selected entries in the Contents green
ShowTips string Indicates where to show page tips.
Set to one of "contents", "index" or "both".
both
TabIcons string The tabs icon URL, relative to the code base. See below. hitabs.gif
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"
TipBgColor RGB triplet or colour name The background colour of the pop-up page tip boxes. #EFFFFF, ie light blue

* These parameters should only be used in version 1. The version 2 index<N> parameters offer the same functionality.
And some of the other parameters were not available in version 1.

Colour Parameters Guide

Picture showing where colour parameters apply

Example

This is a complicated example, using quite of few of the parameters.
<APPLET code=HelpIndex archive="hi210.jar" width=100% height=90% alt="HelpIndex site index">
<param name=mode value="applet high">
<param name=index1 value="helpindex.hi">
<param name=index2 value="phd.hi">
<param name=index3 value="JDKAPI11.hi,,index sort,,class java.">
<param name=index4 value="dbex.hi,dbex2.hil,index nocontents">
<param name=index5 value="helpindex.hi,french2.hil,noindex">
<param name=index6 value="helpindex.hi,german2.hil">
<param name=fgcolour value=blue>
<param name=bgcolour value=#FFFFCC>
<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 Hi HelpIndex to appear on a web page ("applet") or as an "icon" (with "popup" option), 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 Hi HelpIndex in a new floating window. This window is automatically the right size; if the MinIconWindowSize parameter is given then the window is made bigger if appropriate.

Note that the default icon - hi.gif - is 70 by 80 pixels, so you should use these values for the applet width and height. You may want your icon to have a transparent background if you want IconBgColor to show through.

If in "icon" mode and "popup" is also specified in the mode parameter then the floating window pops up straight away.

If in "icon" mode and "close" is also specified in the mode parameter then the floating window closes when a page is displayed.

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 300x250 pixels. If in "applet high" mode the applet should typically be at least 250 pixel high.


Index parameters

You should specify your index and language files using one or more index<N> parameters, eg index1, index2, etc. 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.
noindex Do not display the Index.
sort Sort the page names in the Contents.
expanded The Contents folders are expanded initially.
selection The URL to be selected initially in the Contents tree.
This can optionally include the Base URL to ensure the correct initial selection where duplicate filenames are used.
query The initial query in the Index.
locale The locale code of the index and language files, ie their language and country (see locales for further details).

*   Version 2.2+ of Hi HelpIndex supports different character encodings. The index and language fields above may optionally also specify a character encoding scheme.
After the index or language URL put a semi-colon character and follow it with the character encoding name. The default character encoding is "8859_1" which corresponds to the ISO 8859-1 character set.
Note that version 2.1.5 correctly ignores any character encoding names.

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="JDKAPI11.hi,,index sort expanded,,class java.">
<param name=index4 value="dbex.hi,dbex2.hil,index nocontents">
<PARAM NAME=index5 VALUE="greek.hi;MacGreek,greek2.hil;MacGreek">
<PARAM NAME=index6 VALUE="japan.hi;Unicode,japanese.hil;Unicode,,,,ja">
<param name=index7 value="indexfr.hi,french2.hil,,,,fr">
<param name=index8 value="indexde.hi,german2.hil,,,,de">
If run from a JDK 1.1 browser, the most appropriate index/language set for the user's locale is used at startup. Otherwise the first English index/language set is used.

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

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 parameter for the initial index query.


Icon parameters

The Icon parameter is used when in icon mode. The image is displayed centrally in the area given to the applet, so the image should normally have the same dimensions as the applet area. You might want the icon image to be transparent so that it can be made to match the background specified in the IconBgColor parameter.
The default hi.gif is 70 pixels wide and 80 high.

The TabIcons parameter changes the images displayed at the top of the four tab cards. The URL should refer to a single gif image, usually 56 pixels wide by 12 high. It should have four images, each 14 pixels wide, for the Contents, Index, Select and About tabs respectively. You can make the image higher if you use a larger Font.
Try editing the default hitabs.gif hitabs.gif

The ContentsIcons parameter changes the images displayed in the Contents to the left of each entry's text. The URL should refer to a single gif image, usually 64 pixels wide by 13 high (though it can be any size). It should have four images (usually each 16 pixels wide) representing the following items respectively:

The index file URL record Icon URL field image will override these icons.
Try editing the default hiicons.gif hiicons.gif

Note that all three default images have transparent portions which allow background colours to show through.

Important: If providing your own version of one of these images then make sure it has different name from the original, otherwise the original will still be used (from the file library).


CODEBASE

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

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

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


Frames

If using frames, you may well want to set a "skip target frame" in Hi Lab's scan options page. (Or set a skip target when running MakeHelpIndex. See Frames and the Skip Target.)

Here are three suggestions for how to use Hi 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