HTML design problems and considerations
=======================================


This document is assuming that you are using the CGI front end. 


How the results page is created
-------------------------------

The file etc/search.htm consists of a number of blocks delimited by HTML 
comments that start with <!--comment--> and end with <!--/comment-->. 

The <!--variables--> block is only used by search.cgi. The other blocks 
form part of the results output depending on the situation. 

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

There are three series of <!--restop-->, <!--res--> and <!--resbot--> 
blocks. The first series is returned to users that have requested long 
results (default), the second one to those that have requested short 
results and the third one to those that have requested results as URL 
only. All three blocks must be present in search.htm. Furthermore there 
is a series of navigation blocks and the blocks <!--notfound-->, 
<!--noquery--> and <!--error-->. The latter are returned occasionally 
instead of results.

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

Thus, the output of search.cgi will always be something like this: 

  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 each 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 simplest HTML is provided ready for use in search.htm-dist. It is 
advisable that you use this until your back-end works fine. 

Once you decide to add bells and whistles to your search, you have two 
options. One is to keep the simple design of search.htm, but 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. 

The other option is to incorporate your entire design in search.htm. If 
you fully understand the "blocks" system described above, this should 
not be too difficult. The one most important factor is to keep track 
of elements that need to be opened in one block and closed in another. 

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
--------------------

Most modern browsers can handle forms that stretch over different 
tables, but writing such forms is against all standards and is bad 
HTML. Unless you really can't avoid it, don't do it. 

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 even text boxes. For instance, where 
search.htm-dist 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 a drop-down menu, 
with "20" as the default and the exact same functionality. What you 
obviously cannot do is provide multiple-choice menus like 
<type="checkbox"> or <select multiple>. 

Note that you can also use the 

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

format if you want to set other defaults than the pre-defined and not 
allow the user to change them. 


Relative links in search.htm
----------------------------

It might be worth mentioning that search.htm is parsed from your cgi-bin 
directory. The position of this directory in relation to your document 
root is determined by the web server, independently of its actual 
position in the file system. Almost invariably is is
http://your_document_root/cgi-bin/ . Since search.cgi lives in cgi-bin, 
any links to images etc in search.htm will assume cgi-bin as the base 
directory. Therefore, if you have a file system structure like 

   home/
   home/your_document_root/
   home/your_document_root/img/
   home/cgi-bin/

the correct relative link from search.cgi to images in img/ would still 
be 

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

despite the fact that it doesn't match the file system structure.