Searchlight

Searchlight 5.0

The Internet Service Provider (ISP) that I use does not provide any facilities that allow visitors to my web site to search the pages for the information they require. I believe that this is common practice amongst ISPs so I wrote Searchlight to fill the gap. Version 1.2 of Searchlight obtained a Jars "Top 5%" Rating.

If you run a web site that does not have server side search facilities then Searchlight may be for you. If you do not run a web site or your server does have search facilities then there is no point in reading any further.

Searchlight is available free of charge but there are a few conditions that you should adhere to.

This page describes how you can install and configure Searchlight for your own site. If you want to see Searchlight in action then you should search this site or visit some user sites. I've assumed that you are experienced in site administration so you know how to:

Load files from this site to your system using a browser.
Edit text files on your system.
Load files from your system to your web site.

I've tried not to assume that you have any knowledge of Java. You do not need any additional files on your server to support Java applets. However, only browsers that support Java can use Searchlight. Some proxy configurations do not allow Java applets to read data from servers, under these conditions Searchlight will not work.

If you have any questions, then you may find the answers on the Frequently asked questions page. If you continue to have problems with these instructions or have any other comments then please let me know.

What's New

Searchlight 5.1 implements the following new features:

Compiled with a Java target 1.1. Some versions of IE6 cannot cope otherwise.

Searchlight 5.0 implements the following new features:

Compiled with a Java 2, Version 1.4.2_08 compiler. This seems to have solved the problem where Internet Explorer crashed.
The Java classes are issued in a JAR file. This makes installation of the applet easier but may prevent it running on older browsers.

Terms & Conditions

Conditions

You are free to install and use Searchlight on any Internet or intranet site free of charge for 14 consecutive days. After the 14 days have expired you can continue to use Searchlight free of charge provided that:

You do not make a charge for providing Searchlight.
You do not make a charge for use of your site.
You send us an email containing the following information:
1. The name of the site.
2. The name of the organisation or person that owns the site.
3. For Internet sites, its URL.
4. The Email address of the site administrator.
You provide an HTML link to http://www.pccl.demon.co.uk/searchlight on each page where Searchlight is used. The link should be anchored to the "Searchlight Now" image or banner

Disclaimer

Pentagon Computer Consultants Ltd., does not make any warranties with respect to the contents of the Searchlight software or documentation and disclaims any implied warranties of merchantability or fitness for any purpose.

Pentagon Computer Consultants Ltd., reserves the right to revise the software or documentation at any time without obligation to notify any person or organisation.

Copyright

Files

You will need to download these files to your own system, edit them where necessary and then upload them to your web site.

search.jar M, NE This is a Java Archive file. It contains the runtime code for the Searchlight applet.

example.idx O, E This is an example configuration file. Edit this file to describe which files should be searched on your site.

example.html O, E This is an example search page. It shows the HTML that can load the Searchlight applet. You could edit this file to reflect the style of your site.

sl1.gif O, NE This is the Searchlight image. You could use this on your pages to link to your search page.

slnow.gif M^*, NE This is the "Searchlight Now" image.

slbanner.gif M^*, NE This is the "Searchlight Now" banner.

Key

M	Mandatory, the file must be added to your web site.
O	Optional, the file may be added to your web site.
M^*	Mandatory, one of these files must be added to your web site.
NE	Not editable, the file should not be modified in any way.
E	Editable, the file may be edited to suit your requirements.

Installation & Configuration

Steps

Installation of Searchlight on your web site is described in the following steps:

Download the files listed above onto your development system.
Produce a Search page that runs the Search applet.
Produce a configuration file that describes your site.
Update your other pages to provide links to your search page.
Upload the mandatory files, search page, link pages, configuration file and selected image files to your website.

Search Page

The search page is an HTML formatted page that runs the the search applet. The layout is up to you. An example is given in example.html. The HTML for running the Search applet is:

<p> 
<applet code="uk.co.demon.pccl.applet.search.Search" archive="search.jar" width="400" height="300"> 
<param name=index value=search.idx> 
<param name=target value=tframe> 
<strong> 
Searchlight cannot run as your system does not support Java. 
<strong> 
<applet> 
<p>

The following applet parameters are optional:

bg	The background colour of the applet. Use the hexadecimal value representing the RGB colour. E.G. "FF0000" is red, "00FF00" is green and "0000FF" is blue.
fg	The foreground colour of the applet. Use the hexadecimal value representing the RGB colour. E.G. "FF0000" is red, "00FF00" is green and "0000FF" is blue.
index	his file is used instead of search.idx as the name of the configuration file. The name is relative to the page's home directory.
site	Gives a name to the data to be searched. By default, this is the host name (e.g. www.pccl.demon.co.uk). This data appears on the first line of the applet display. eg: "Search This Site For:"
target	Specifies the name of a frame that is to contain the page that is selected by the load button.

The remaining parameters can be used to change the textual data displayed by Searchlight. All buttons, labels and messages can be specified by parameters. This is intended for use on sites that do not normally use the English language. The parameters are:

searchFor1 The first part of the top line ("search" site for).

searchFor2 The second part of the top line ("search" site for).

search The label on the "Search" button.

stop The label on the "Stop" button.

loadPage The label on the "Load Page" button.

all The "All words of" choice.

any The "Any words of" choice.

phrase The "Phrase" choice.

indexState The message to display when reading the configuration file. By default, this is "Loading index file".

noDataState The message to display when no matches are found. By default, this is "No data".

noParasState The message to display when no words are input. By default, this is "No parameters".

checkParasState The message to display when checking the entered parameters By default, this is "Checking parameters".

searchState The message to display, with the current filename, when searching. By default, this is "Searching".

interruptState The message to display when the "Stop" button is pressed. By default, this is "Interrupted".

resultState The message to display when the search is complete. By default, this is "Results".

badURLstate The message to display when a bad URL is formed. By default, this is "Bad URL".

badIOstate The message to display when an IO error occurs By default, this is "IO Error".

Link Format

You will need to provide links to your search page from other pages on your site. You can use any format you wish. I use the following HTML which makes use of the Searchlight image.

<a href="search.html"><img src="sl1.gif" width="90" height="30"
alt="Searchlight"><font size="1"><br>Search this site.</font>a>

Configuration File Format

The default configuration file is called search.idx and it resides in the same directory as the search page. However, you can use any name provided that it is provided as an applet parameter on your search page. You can find an example configuration in example.idx.

The configuration file is an ASCII text file. Each line of the file is terminated by a linefeed or carriage return character or both. Empty lines, lines beginning with a # character and lines consisting of only white space are considered to be comments. All other lines are data records.

Each data record describes a file to be searched. A data record consists of a number of fields, separated by white space. From the left of a record, the fields are:

Filename

This is the name of a file on your web site that you want to be searched. The name is relative to the page's home directory. Subdirectory and filenames should be separated by a slash character (/).

File Type

The file type can be set to one of the following values:

HTML
The file to be searched is in HTML format. Searchlight will not Search the HTML parts of the file.
TEXT
The file to be searched contains only ASCII text.

Search type

This field describes how the file is to be searched. The following values can be used:

FILE
Search the file specified in the Filename field.
FIND
Whatever words are searched for, always say that they have been found in the file specified in the Filename field.
INDEX
Instead of searching the file specified in the Filename field, search the file specified in the next field.
NONE
Never find this file. This option can be used during testing.

Index File

The "index file" field is optional. It should only be used where the "Search Type" is set to INDEX. It contains the name of the file to be searched instead of the file specified in the Filename field. The name is relative to the page's home directory. Subdirectory and file names should be separated by a slash character (/).

Title

The rest of the line contains the title of the document. It is displayed to the user if a match is found.

Configuration

When Searchlight performs a search, it reads through the configuration file. For each data record it reads the specified file looking for the required match. When a match is found, it closes the file and reads the next configuration data record.

As Searchlight runs on the client system, in the browser, searching many and large files is likely to require a lot of network traffic. Careful configuration is required to keep the traffic to a minimum. Here are a few tips:

Make sure that only files containing useful information are searched. For example:
- Ihave HTML, text and WORD 6 versions of my CV on my web site but I only specify the HTML in my Searchlight configuration.
- It's unlikely that you need to search an HTML file that assists in downloading other files.
If you have a large file, consider copying the key words into an index file. This will make searching a lot quicker.
Keep files small by eliminating unnecessary white space and comments.
If you have divided your site into several sub-sites you can specify a unique configuration for each of them. This way you can avoid searching files that have nothing of interest to the visitor.

While testing your configuration you may find it useful to look at your browser's Java Console. This is where Searchlight writes its error messages.

Index Files

Index files are files that are searched instead of the file containing the data. You should consider using index files when:

You have a large data file that can be condensed into a few key words.
You have a file that cannot otherwise be searched (e.g. a GIF or JPEG file).

Index files contain only the words to be found. The words are separated by white space or line boundaries.

Images

I have include some GIF images as part of the Searchlight package. You must use at least one of these on your search page and link it back to our site.

The images on this page were written as part of the Searchlight package. Alternatively, you may like to use one of the Approved Images. These have been provided by some of the, more artistic, Searchlight users.

The Searchlight Image

The Searchlight image can be used on links to your search page.

The Searchlight image can be displayed using this bit of HTML:

<img src="sl1.gif" width="90" height="30" alt="Searchlight">

The Searchlight Now Image

The Searchlight Now image or the Searchlight Now banner must be used on your search page. It should link to our URL (http://www.pccl.demon.co.uk/searchlight). The Searchlight Now image can be displayed using this bit of HTML:

<img src="slnow.gif" width="90" height="30" alt="Searchlight Now">

The Searchlight Now Banner

The Searchlight Now banner or the Searchlight Now image must be used on your search page. It should link to our URL (http://www.pccl.demon.co.uk/searchlight). The Searchlight Now banner can be displayed using this bit of HTML:

<img src="slbanner.gif" width="400" height="40" alt="Searchlight Now">

Vote for Searchlight

You may like to add a link to the Searchlight page at Jfind. This will allow your clients to vote for Searchlight if they find it useful. The HTML that allows this is:

<a target="Target" href="http://www.jfind.com/vote.php3?id=58"
title="Vote">Vote for this applet<a>

If you have found Searchlight useful then please Vote for this applet.

Home

search.jar	M, NE	This is a Java Archive file. It contains the runtime code for the Searchlight applet.
example.idx	O, E	This is an example configuration file. Edit this file to describe which files should be searched on your site.
example.html	O, E	This is an example search page. It shows the HTML that can load the Searchlight applet. You could edit this file to reflect the style of your site.
sl1.gif	O, NE	This is the Searchlight image. You could use this on your pages to link to your search page.
slnow.gif	M^*, NE	This is the "Searchlight Now" image.
slbanner.gif	M^*, NE	This is the "Searchlight Now" banner.

searchFor1	The first part of the top line ("search" site for).
searchFor2	The second part of the top line ("search" site for).
search	The label on the "Search" button.
stop	The label on the "Stop" button.
loadPage	The label on the "Load Page" button.
all	The "All words of" choice.
any	The "Any words of" choice.
phrase	The "Phrase" choice.
indexState	The message to display when reading the configuration file. By default, this is "Loading index file".
noDataState	The message to display when no matches are found. By default, this is "No data".
noParasState	The message to display when no words are input. By default, this is "No parameters".
checkParasState	The message to display when checking the entered parameters By default, this is "Checking parameters".
searchState	The message to display, with the current filename, when searching. By default, this is "Searching".
interruptState	The message to display when the "Stop" button is pressed. By default, this is "Interrupted".
resultState	The message to display when the search is complete. By default, this is "Results".
badURLstate	The message to display when a bad URL is formed. By default, this is "Bad URL".
badIOstate	The message to display when an IO error occurs By default, this is "IO Error".