Creating A Glimpse Search Form
|
|
Creating A Glimpse Search Form |
A glimpse search form is a form used to search a glimpse index (You must create the index before you can search it with a search form). The search form allows the user to enter a search pattern (normally a word or words) for which they are searching.
When the user submits the search form, the server returns a result page, which contains a list of all matching files from your index (of your web site), with hotlinks for the user to go directly to a match they're interested in. Or, if their search yields no matches, the result page informs them of that fact. If your search form is configured to show matching lines in web pages as well as the "header" information (all this will be explained more fully below), then the matching word(s) in each line are shown in bold.
If you do not know what a form is, you'll want to browse through the WebCom Forms Tutorial to familiarize yourself with HTML fill-out forms concepts before attempting to create a search form. Before you can actually use your search form, you'll also need to create the glimpse index.
If you know all about forms and want to get down to the business creating your form, then simply retrieve our template form at the following URL:
ftp://ftp.webcom.com/~webcom/pub4/webcom/templates/search_form.html
This template contains every available search parameter as an input field. You will want to delete many of them and use the default options, so as not to overwhelm the user with search options (and you'll set many of them for the user with hidden fields).
Refer the documentation on the search form parameters (options) to decide how you want to tailor the form for your site.
The search parameters, explained below, allow you to control how your search form works quite easily. When somebody submits your search form, the WebCom search facility just looks at the parameters on the form and then takes care of the search for you, automatically creating a dynamic result page for each search.
Your Glimpse search form, like all other forms, must have an ACTION encoded in the FORM open tag. Specifically, the ACTION for your Glimpse search form must be set to http://webcom.com/~webcom/cgi-bin/glimpse. Here's exactly what the form open tag in your search form should look like:
<FORM METHOD=post ACTION="http://webcom.com/~webcom/cgi-bin/glimpse">
This tag informs the WebCom server to invoke the WebCom Glimpse search facility to process the form each time it's submitted (but don't worry about that if you don't understand it--just set the FORM open tag as shown).
Your Glimpse search form must have an input field for the user to enter the search terms (typically a word or words for which they're searching). This field should be a text type input field so the user can type in what they're searching for (or alternatively, you could use an option list or radio buttons to have the user select from a set of searches you've pre-defined for them). Whatever type of field you use, this search field must exist in your search form: its NAME must be "glimpse_search" and its VALUE when the form is submitted must be the search or query terms (normally a word or words). The Glimpse search engine limits the search pattern to 32 characters, so if you use a text input field to set the search pattern, you must set the LENGTH and MAXLENGTH to 32 or less.
Another required field in your Glimpse search form is your WebCom userid, which is necessary for the server to know it's your form (as opposed to another WebCom user) each time the form is submitted.
Naturally, you don't want to require the user to have to type in your userid to search your site, so the userid form should be coded as a hidden field (A hidden field allows you to pass a named value to the server without the user having to type in the field, or even see it). Here's what the hidden field for your userid will look like:
<INPUT TYPE=hidden NAME=userid VALUE=webcom>
Instead of "webcom", you'll need to set the VALUE to your WebCom userid. Like any hidden field, the location in the page is not significant as long as it's between the form open and form close tags.
If you don't already know how Glimpse indexes a directory, you'll need to read the page on choosing and specifying the directory to be indexed, which explains which files are included in a directory index.
Most WebCom users create a Glimpse index of their www tree (the 'www' sub- directory of their WebCom directory, and all its sub-directories, etc.). For this reason, unless you tell it otherwise, the Glimpse search facility will assume the search form is for your www tree, and it will expect that you've already created a glimpse index of that tree.
If your search form is for a tree other than your www tree, you'll need to include a field in your form defining the tree to be searched (the directory name). The field can be hidden, or it could be an option list or radio buttons to allow the user to select one from a list of glimpse indexes. Whatever field type you choose, the NAME of the field should be "glimpse_directory", and its VALUE when the form is submitted should be the name of the directory to be searched, relative to your home directory.
For example, suppose in your www subdirectory you have a subdirectory named "products," which contains a web page of each of your products, and suppose you've created a Glimpse index for that sub-tree. You'd need to have the glimpse_directory field in the search form for the products sub-tree set to "www/products" (indicating to the search facility that the form is intended to search the Glimpse index in the products sub-directory of your www sub-directory). In most cases, the glimpse_directory value is set as a hidden field:
<INPUT TYPE=hidden NAME=glimpse_directory VALUE=www/products>
As mentioned previously, the default value of glimpse_directory is "www."
Like all forms, your search form will need a button so the user can submit the form after filling it out. Your button will probably be labeled "Search":
<INPUT TYPE=submit VALUE=Search> </FORM>
(And of course don't forget the form close (/FORM) tag!
The above described requirements are the minimal requirements for a basic search form. In summary:
Your search form can also contain additional search parameters (which are optional). Additional parameters can control things such as whether or not the search will be case sensitive, the maximum number of matches to return, whether to allow spelling errors in the search terms, etc. All of these additional parameters default to the most commonly used options, (e.g., default is not case sensitive, unlimited matches), so you'll only need to set them if you want to override the defaults. See the documentation (in the above link for search parameters) for a complete list of the parameters, their options, and the defaults.
Any of the additional parameters for a search can either be set to a constant value with the use of hidden fields, so that the form always uses that parameter without the user having to tell it to, or they can be set by input fields, as in our template form (see above for the URL of the template). This gives the user control over that option (for instance you could have a checkbox to allow the use to select whether or not they wanted to perform a case-sensitive search). Any optional search parameter you omit from your form will be set to the default value for that parameter.
[an error occurred while processing this directive]