Make your own free website on Tripod.com

SearchToHTML ReadMe

August 23, 2001
Introduction
Adding SearchToHTML to your site
Changing the style of the search results
Capability, compatability, and contact info
Examples
Alternatives
Linkware

Other documentation

Parameters guide
Releases

Introduction

Top

The SearchToHTML applet provides your visitors with a simple way to search your Web site. Search results are displayed in HTML.

The SearchToHTML applet is the third in a series of client-side search applets. The first was SiteSearcher. SearchToHTML followed close after the second, AdvSiteSearcher. SiteSearcher and AdvSiteSearcher display their search results in lists within the applets.

Using HTML to display the results has made it possible to add three new features to the search results (not available before because of display space concerns): the match context (some of the words surrounding the match), the nearest HTML anchor to the match (so that the visitor doesn't have to scroll as much), and the title of the page (if it is encountered before a match). Also, using HTML to display the results gives Web designers much more control over the display of the search results.

This applet is distributed as linkware for The Gilbert Post. Each site that uses the applet must include a link to The Gilbert Post, http://www.geocities.com/gilbertnews/.

SearchToHTML was selected as JavaBoutique's Applet of the Week for the week of May 25, 2001.

Adding SearchToHTML to your site

Top

To add SearchToHTML to your site, follow these directions:

1. Upload the required files to the same directory as the HTML file that will display the applet. The required files are:
  1. SearchToHTML.class
  2. SearchDocument.class
  3. SearchSieve.class
  4. ProgressBar.class
  5. CircularStringBuffer
  6. searchresults.html

In a normal distribution of SearchToHTML, these files are contained in the "required" subdirectory. The spelling and case of the .class file names are significant. The applet will probably not even load if you change these file names, unless you massage the Java source code and recompile.

You should upload all of the class files every time you update the applet. Newer versions of the class files are not guaranteed to be compatible with older versions.

2. Paste the following code into the page where you want the applet to appear:

3. Change the pasted code to fit your needs. See the Parameters guide for more information on how to do this.

You must fill out the files or files_file parameter to let the applet know which files to search. You may also choose to set both parameters.

The files parameter's value should consist of a list of the files to be searched, each file name separated from the others by a comma, space, tab, or line ending. The file names are expected to be relative to the file displaying the applet.

For example, if the applet is displayed at http://www.geocities.com/gilbertnews/search.html and you want to the applet to search the file http://www.geocities.com/gilbertnews/index.html, you would add "index.html" to the list of files to search.

Changing the style of the search results

Top

The applet encodes the search results and sends them onto a JavaScript found in searchresults.html. If you would like to change the display of the search results, you'll need to modify searchresults.html.

If you're interested in changing the text of the search results, look under the heading "Text used in search results messages:" in the source of searchresults.html.

If you're interested in leaving out the closest anchor, document info, or context from each search result, then look under the heading "Which elements should be displayed along with the results?" in the source of searchresults.html.

If you would like only the titles of search matches to be shown, rather than both the titles and the file names, set the var preferTitleOnly of searchresults.html to true. If the title is unavailable, the file name will be shown instead, in any case.

If you would like only a link to the closest anchor to be listed, rather than both a link to the document and the closest anchor, set the var anchorTheLink of searchresults.html to true. If this is done, the closest anchors will not be listed separately.

The search results are displayed as a list of links in the HTML generated by searchresults.html. Set the var targetFrame to the frame you'd like a search result link to be opened in.

Capability, compatability, and contact info

Top

SearchToHTML uses only the APIs of JDK 1.02 so it should run under all Java-enabled browsers. Please report any compatibility errors to gilbertnews@hotmail.com.

SearchToHTML requires that your users have JavaScript enabled. JavaScript is used in displaying the search results.

SearchToHTML's source code is included with this distribution. Send your questions or comments on the source to gilbertnews@hotmail.com.

This version of SearchToHTML does not support Boolean expressions or wild card searches. (These features are under active investigation.) When a visitor enters a search phrase, the applet divides the phrase into tokens and searches for each token individually. If a match for a token is found in a document, that document is added to the list of matches (equivalent to a Boolean or search). The order of the documents in the search results is non-deterministic.

If you have a very large number of documents to search, you and your users will be much better off if you can use a server-side search engine rather than a client-side search engine (such as SearchToHTML). Client-side search engines must download portions of each file to be searched (unless they're using an index file, in which case the index file must be downloaded -- SearchToHTML does not use an index file). The client-side search engine itself must be downloaded to the user's computer. Therefore, it will probably be coded to include less features than a server-side search engine. Other advantages of server-side search engines: they can cache results between different users' searches; they have more intimate access to the files they search (applets usually face severe security restrictions); server-side search engines will almost certainly not require that your users' browsers support Java. (A few server-side search engines are listed in the Alternatives to SearchToHTML section.)

If you experience any problems with the applet or have suggestions, please e-mail gilbertnews@hotmail.com. Want a new feature? Think the documentation is lacking? Send in an e-mail. Please remember, however, that the SearchToHTML applet is distributed without warranty or guarantee. Use it at your own risk.

Contact: David Faden <gilbertnews@hotmail.com>

Examples

This distribution of SearchToHTML includes several examples of how to use the applet in the examples directory.

paramex.html
Demonstrates nearly every parameter SearchToHTML understands.

frames.html
Demonstrates using SearchToHTML with frames.

minimalist.html
Demonstrates the most minimal interface SearchToHTML can offer: a single text field.

Alternatives to SearchToHTML

Top

There are now many, client-side Java search engines in addition to SearchToHTML. Rather than trying to maintain my own list, below I have included some links to lists of links to Java search engines.

If your site has many pages, consider giving your users and your server a break -- either run a server-side search engine yourself, or use the services of a third party search provider. I have not personally used any of the products or services listed below.

Linkware agreement

Top

You will maintain a prominent link to The Gilbert Post (http://www.geocities.com/gilbertnews/) on each site that makes use of the SearchToHTML applet or a variant on its code in return for the right to use the applet on that site. (Please also leave our spiel on the search results page.) SearchToHTML is distributed without warranty of any kind. Use it at your own risk.

When I originally released an applet as "linkware," I had never seen the term "linkware" used anywhere else. However, recently I've found out that term was in use at least as early as 1996 by Todd Lehman. Lehman's Linkware Home Page is located at http://www.fibblesnork.com/linkware/.



SearchToHTML © 1999 - 2001 David Faden

The Gilbert Post is an independent student paper serving Gilbert High School of Gilbert, Iowa, and the world (hopefully). It was founded because at the time (and at present) there was no official school paper, a chasm that needed to be filled. By adding the SearchToHTML applet and a link to us to your page, you are helping The Gilbert Post. Thank you.