This section is assuming that you are using the CGI front end.
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.
The simplest HTML is provided ready for use in etc/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 DataparkSearch 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.
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 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" checked="$(ps)"> <input type="radio" name="ps" value="20" checked="$(ps)"> <input type="radio" name="ps" value="50" checked="$(ps)">
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
format if you want to set other defaults than the pre-defined and not allow the user to change them.
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 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
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.
To place a search form to any of your pages, please place the following code where you would like the form to be displayed: