Designing search.htm

How the search results page is created

The file template file search.htm consists of a number of blocks delimited by HTML comments starting with <!--comment--> and ending with <!--/comment-->.

There is a special block <!--variables ... --> which is used to put commands to. The other blocks form parts of the output.

The blocks <--top--> and <!--bottom--> are always returned to the user as the top and the bottom parts of the output page page respectively.

The three blocks <!--restop-->, <!--res--> and <!--resbot--> are displayed to the user in case when a search query produced at least one result. The blocks <!--restop--> and <!--resbot--> are displayed once, while the block <!--res--> is displayed for every found document.

Furthermore there is a serie of page navigation blocks and the blocks <!--notfound-->, <!--noquery--> and <!--error-->. The latter three blocks are returned occasionally in situations when search did not return any results.

Any HTML code that is outside the pre-defined blocks in search.htm is completely ignored.

The output of search.cgi consists of these parts, depending on the situation:

  top                 
  restop                top                 top              top
  res            or     notfound      or    error     or     noquery
  resbot                bottom              bottom           bottom
  (navigation)
  bottom

The navigation part is built in the same way, with the elements that pertain to every results page. For example, <!--navleft--> and <!--navright--> are used to link to the previous and next results pages, while <!--navXXX_nop--> is used when there are no more pages in one or either direction.

Your HTML

The default HTML template code provided in search.htm-dist is ready for use, so you may decide to use it without applying any major modifications.

Once you decide to add bells and whistles to your search, you have multiple options. One option is to keep the simple design of search.htm and make it part of a frame set. This way you can add elements such as menus etc in a frame and keep the output of search.htm in another frame.

Other option is to incorporate your entire design into search.htm. As soon as you understand the idea of the blocks described above, this should be easy to do.

For example, you might want a page in tables that looks like this:

                   ----------------------------------
                  |       top  table                 |
                  |..................................|
                  |        .                         |
                  |left    .                         |
                  |        .                         |
                  |        .         main table      |
                  |table   .                         |
                  |        .                         |
                  |        .                         |
                   ----------------------------------

If you are planning to put your results in the main table, you can put all the HTML code in the <!--top--> block of search.htm, up to and including the opening of the main table (<table><tr><td>). If you then put the closing of the main table and the closing tags of the page in the <!--bottom--> block (</table></tr></td></body></html>) and leave all other blocks unformatted, you will have the design of your choice and all your results in the right place.

In a more complicated design, where you want to format results individually, you can apply the same method as long as you keep track of the opening and closing of HTML elements. You must either open and close them in the same block, or make sure that any possible combination of blocks will result in properly opened and closed HTML tags.

What you cannot do without editing the source code, is change the order in which the blocks are parsed. Taking the above example, let's assume that you want your page to look like this:

                   ----------------------------------
                  |  logo       banner ads           |
                  |..................................|
                  |            .                     |
                  |choices     .                     |
                  |            .                     |
                  |            .    results          |
                  |search      .                     |
                  |button      .                     |
                  |            .                     |
                   ----------------------------------

To get this, you need to have everything except the results and navigation in the <!--top--> block, since that is the only block that can draw the page even if there are no results at all. In this case your search.htm would look like this:

 <!--variables-->
  [your configuration]
 <!--/variables-->

 <!--top-->
  <html>
  <body>
  <table>
    <tr colspan="2">
    <td>[logo, banner ads]</td>
    </tr>
    <tr>
    <td>[search form]</td>
    <td>
  <!--/top-->

  [all other blocks in search.htm except "bottom"]

  <!--bottom-->
    [closing elements like the mnogosearch link 
     and a link to the webmaster]
    </td>
    </tr>
  </table>
  </body>
  </html>
  <!--/bottom-->
    

The individual blocks can be formatted individually as long as that formatting is closed within each block. Thus, nothing stops you from doing things like

  <!--error-->
    <table>
    <tr><td bgcolor"red">
      <font color="#ffffff">  
      [error variables]
      </font>
    </tr><td>
    </table>
  <!--error-->

as long as such formatting is opened and closed properly within the same block.

Forms considerations

Although the modern browsers can handle forms that stretch over different tables, writing this kind of forms abuses the standards and is usually considered as bad HTML. Unless you really can't avoid it, using this style is not recommended.

For example,

  <table>
  <tr><td>
     <form>
     <input type="text" name="something">
     <input type="radio" name"button1">
     <input type="radio" name"button2">
     </form>
  </tr></td>
  </table>
      

is fine, but

  <table>
    <tr><td>
       <form>
       <input type="text" name="something">
    </tr></td>
  </table>
  <table>
    <tr><td>
       <input type="radio" name"button1">
       <input type="radio" name"button2">
       </form>
    </tr></td>
    </table>
      

is not.

Note that the input forms in search.htm can be changed at will. The default is drop-down menus, but nothing stops you from using radio buttons or hidden input or text boxes. For instance, where search.htm says

  Results per page:
  <SELECT NAME="ps">
  <OPTION VALUE="10" SELECTED="$ps">10
  <OPTION VALUE="20" SELECTED="$ps">20
  <OPTION VALUE="50" SELECTED="$ps">50
  </SELECT>
      

you can very well substitute

  <input type="radio" name"ps" value="10">
  <input type="radio" name"ps" value="20" checked>
  <input type="radio" name"ps" value="50">
      

which will result in three radio buttons instead of the drop-down menu, with 20 being the default page size.

Note that you can also use the

  <input type="hidden" name="XX" value="YY">
        

format if you want to set your own default values without allowing the user to change them.

Relative links in search.htm

It might be worth mentioning that search.htm is parsed by search.cgi which usually resides in the /cgi-bin/ directory of your Web server. When you open http://site-name/cgi-bin/search.cgi in your browser, all relative links are considered as relative to the /cgi-bin/ directory. Therefore, if you have a file system structure like

   /var/www/images/
   /var/www/html/
   /var/www/cgi-bin/

the correct relative link from search.cgi to the images in /images/ will be

<img src="../images/image.gif">

Adding a small Search form to the other pages of your site

To add a small search form to any of your pages, you can put the following code:

<FORM METHOD="GET" ACTION="/cgi-bin/search.cgi">
  <INPUT TYPE="text" NAME="q" VALUE="">
  <INPUT TYPE="submit" VALUE="Search!">
</FORM>