Creating Custom Searches

The system-wide search engine can also be limited to a subset of all pages, the result being that anyone can create a search page that will search only their pages. This is essentially done by telling the search engine to only show the pages matching the query that are in a particular folder.

The Quick Way: Using the Document Interface

The easiest way to get a custom search form on your page is to use the DI's .SEARCHFORM command. This produces a small form with a red "Go" button next to it, like the ones on the top levels of the MHC site.

In order to use this command, you should be familiar with the Document Interface.

The More Flexible Way: Creating the HTML form Yourself

A search page contains a regular HTML form, like the code below. The same page is used both to ask the user for search terms the first time around, and to present the results of the search. Some special things are added to the code at the source level:

<!-- The first example uses a normal textfield for the search terms -->
<FORM ACTION="/dir/search/search.mperl" method="GET"> 
   <H3>Search by Keywords</H3>
   <input type=hidden name="url" value="/lits/library/arch/">
   <input type=hidden name="template" value="/dir/search/arcsp.shtml">
   <!--NOEDIT--><!--Tell Pagemill not to harm this code-->
   <!--The following comment precedes the "term" variable. The ""
       gets replaced with whatever the user previously searched for-->
   <!--%%TEXT%%-->
   <INPUT TYPE="text" NAME="term" SIZE="50" value="">
   <!--End of Pagemill protection--><!--/NOEDIT-->
   <INPUT TYPE=submit VALUE="Search"> 
</FORM>
<!--The results of the search will appear here-->
<!--%%RESULTS%%-->

The <FORM> tag refers to the search engine CGI script, /dir/search/search.mperl. This must be here in order for the form to do anything. The method="GET" part tells the browser how the data is to be sent to the Web server. The other method you may sometimes see, "POST" will not work here.

Within the form code, there are several hidden parameters. The first is named url. This is the path (URL) to which the search will be limited, and should usually be set to the path of the documents to which you want to restrict the search.

Next is the hidden parameter template. This is the location of the file that the search engine will use to present the results of the search to the user. Usually, you will set this to the full path of the very same file that contains the form.

The term variable is the actual text field into which the user enters her search terms. It is preceded by the special comment <!--%%TEXT%%-->, which tells the search engine to replace the "" it contains with the text initially entered by the user when it displays the search results page. That way, the user can see what was originally typed into this field and even make changes to it.

Finishing up are the code for the Submit button, the end of the <FORM> tag, and a special <!--%%RESULTS%%--> comment, which tells the search engine where to display the results within this template page. Don't forget to include this comment, or there will never be any results displayed. You can see this sample form in action by following this link.

Important Note

Your search page must be an .shtml or .shm page! Refer to these pages for more information on the Document Interface.

Optional Parameters

perpage

Number of matches per page of results; a number >= 1; defaults to 20

pgtitle

This value, which you will usually supply in a HIDDEN field, causes a different title to appear at the top of the search results page. You might set it to something like "Search Admission", to indicate to the user that they are not searching the entire MHC site.

Specialized Forms

Some more specialized search forms can be created using popup menus. This first example shows you how to search based on a preset list of topics. It can be seen in action on this page.

<FORM ACTION="/dir/search/search.mperl">
   <input type=hidden name="url" value="/offices/library/arch/">
   <input type=hidden name="template" value="/dir/search/arcsp.shtml">
   <select NAME="term">
      <!-- Using '"quotes"' makes sure the phrases get passed to the
           CGI with "quotes" around them -->
      <option value="">Choose a Topic
      <option value='"Five College Inc"'>Five College Inc.
      <option value='"Office of the Treasurer"'>Office of the Treasurer
      <option value='"Auxiliary Services"'>Auxiliary Services
   </select>
   <INPUT TYPE=submit VALUE="Search">
</FORM>
<!--%%RESULTS%%-->

Instead of allowing the user to type text into a field, this form uses a popup list of predefined choices. The options are specified using the unusually '"quoted"' syntax, which means that the phrase will be passed to the search engine with "double-quotes" around it, causing it to be treated as an exact phrase.

Note that searching using an exact phrase can take longer than searching using simple keywords. You may want to warn the user of this fact in advance.

Popup menus can also be used to select a list of locations to search, like this version on the Advanced Search page: