Since version 2.1 of UdmSearch users have an ability to customize
the search results (output of search.cgi or search.php3). You do so
by providing template file search.htm, which should be located in etc
directory of UdmSearch installation.

Template file is like a plain HTML file, which is divided into sections.
Each section begins with <!--sectionname--> and ends with <!--/sectionname-->
delimiters, which should reside on a separate line.

Each section consists of HTML formatted text with special meta symbols. Meta
symbol is one- or two-letter name with the preceding $ sign (examples: $DX,
$V). Every meta symbol is replaced by its correspondent string. You can think
of meta symbols as of variables, which will have their appropriate values while
displaying the search results.

Keep in mind that you can just open template file in your favourite browser and
get the idea how it looks like.

The following section names are defined:


top	This section is included first on every page. You should begin this
        section	with <HTML><HEAD> and so on. Also, this is a definitive place
	to provide a search form. There are two special meta symbols you
	will use in this section:
	    $A - argument for FORM ACTION tag
	    $Q - your query
	    $rN - random number (here N is a number)

	If you want to include some random banners on your pages, please use
	$rN. You should also place string like RN=xxxx in 'variables' section
	(see below), which will give you a range 0..xxxx for $rN.
	You can use up to MAXRANDOM numbers as N (defined in search.h, default is
	128). Example: $r0, $r1, $r45 etc.

	Simple top section should be look like this:

<!--top-->
<HTML>
<HEAD>
 <TITLE>UdmSearch: $Q</TITLE>
</HEAD>
<BODY>

<A HREF="http://www.yourbannersite.com/ads.pl?advert=NonSSI&page=$r0">
<IMG SRC="http://www.yourbannersite.com/ads.pl?ID=your_id&page=$r0" HEIGHT=60 WIDTH=468 BORDER=0></A>

<FORM METHOD=GET ACTION="$A">
 <INPUT TYPE="hidden" NAME="ul" VALUE="">
 <INPUT TYPE="hidden" NAME="ps" VALUE="20">
 <INPUT TYPE="hidden" NAME="np" VALUE="0">
 Search for: <INPUT TYPE="text" NAME="q" SIZE=30 VALUE="$Q">
 <INPUT TYPE="submit" VALUE="Search!"><BR>
</FORM>
<!--/top-->

You can see some variables defined in FORM.
ul is the filter for URL (so you can limit results to particular site etc.).
ps is default page size (e.g. how many documents to display per page).
np is the number of page (and should be set to zero).
q is the query itself.


bottom	This section is always included last in every page. So you should
	provide all closing tags which have their counterparts in top section.
	Although it is not obligatory to place this section at the end of
	template file, but doing so will help you to view your template as an
	ordinary html file in a browser to get the idea how it's look like.
	
	Below is an example of bottom section:
	
<!--bottom-->
<P>
<HR>
<DIV ALIGN=right><A HREF="http://search.udm.net/about/"><IMG SRC="udmsearch.gif" BORDER=0 ALT="[Powered by UdmSearch]"></A>
</BODY>
</HTML>
<!--/bottom-->


restop	This section is included just before the search results. It's not a bad
	idea to provide some common search results. You can do so by using the
	next meta symbols:
	    $f - number of First document displayed on this page
	    $l - number of Last document displayed on this page
	    $t - Total number of found documents
	    $W - information about the number of word forms found
	         (e.g. if your query was 'develop' $W can be something like
	         'develop: 10, developed:5, developing: 3')
		 and about words that was excluded from search
		 (e.g. 'if: stopword')
		 
	Below is an example of 'restop' section:

<!--restop-->
<TABLE BORDER=0 WIDTH=100%>
<TR>
<TD>Search<BR>results:</TD>
<TD><small>$W</small></TD>
</TR>
</TABLE>
<HR>                                                                            
<CENTER>Displaying documents $f-$l of total <B>$t</B> found.</CENTER>
<!--/restop-->


res	This section is used for displaying various information about every
	found document. The following meta symbols are used:
	    $DU  Document URL
	    $DT  Document Title
	    $DR  Document Rating (as calculated by UdmSearch)
	    $DX  Document teXt (the first couple of lines to give user an idea
		 of what the document is about).
	    $DC  Document Content-type (for example, text/html)
	    $DM  Document last Modified date
	    $DS  Document Size (in bytes)
	    $DN  Document Number (by order of appearance)
	    $DD  Document Description (from META DESCRIPTION tag)
	    $DK  Document Keywords (from META KEYWORDS tag)
	    $CL  Clone List (see section 'clone' for details)
	
	Here is an example of res section:

<!--res-->
<DL><DT>
<b>$DN.</b><a href="$DU" TARGET="_blank"><b>$DT</b></a> [<b>$DR</b>]<DD>
$DX...<BR>
<b>URL: </b><A HREF="$DU" TARGET="_blank">$DU</A>($DC)<BR>
$DM, $DS bytes<BR>
<b>Description: </b>$DD<br>
<b>Keywords: </b>$DK<br>
</DL>
<UL>
$CL
</UL>
<!--/res-->


clone	The contents of this section is included in result just instead of
	$CL meta symbol for every document clone found. This is used to
	provide all URLs with the same contents (like mirrors etc.).
	You can use the same $D* meta symbols here as in 'res' section. Of
	course, some information about clone, like $DS, $DR, DX will be the
	same so it is of little use to place it here.

	Below is an example of 'clone' section.

<!--clone-->
<li><A HREF="$DU" TARGET="_blank">$DU</A> ($DC) $DM
<!--/clone-->

resbot	This is included just after last 'res' section. You usually give a
	navigation bar here to allow user go to next/previous results page.
	The meta char used is:
	    $V - naVigator (links to previous/next pages)

Navigator is constructed from the following templates:

Previous page: Printed if current page>0
<!--navleft-->
<TD><A HREF="$NH"><IMG...></A><BR><A HREF="$NH">Prev</A></TD>
<!--/navleft-->

Current Page:
<!--navbar0-->
<TD><IMG 0...></A><BR>$NN</TD>
<!--navbar0-->

All other pages:
<!--navbar1-->
<TD><A HREF="$HR"><IMG 1...></A><BR><A HREF="$NH">$NN</A></TD>
<!--/navbar1-->

Next Page: Printed if there is a next page only
<!--navright-->
<TD><A HREF="$NH"><IMG...></A><BR><A HREF="$NH">Next</A></TD>
<!--navright-->

This is the sample of navigator:

<!--navigator-->
<TABLE BORDER=0><TR>$NL $NB $NR</TR></TABLE>
<!--/navigator-->

	This is an example of 'resbot' section:
	
<!--resbot-->                                                                   
<HR>                                                                            
<CENTER>$V</CENTER>
<!--/resbot-->

notfound	As its name implies, this section is displayed in case no
	documents are found. You usually give a little message saying that
	and maybe some hints how to make search less restrictive.
	
	Below is an example of notfound section:

<!--notfound-->
<CENTER>
Sorry, but search returned no results.<P>
<I>Try to produce less restrictive search query.</I>
</CENTER>
<HR>
<!--/notfound-->

error	This section is displayed in case some internal error occured while
	searching. For example, database server is not running or so. 
	You should provide next meta symbol:
	    $E - Error text

	Example of error section:

<!--error-->
<CENTER>
<FONT COLOR="#FF0000">An error occured!</FONT>
<P>
<B>$E</B>
</CENTER>
<!--/error-->


There is also a special variables section, in which you can set some values for
search. It looks like this:

<!--variables
DBHost=localhost
DBUser=foo
DBPass=bar
DBName=udmsearch
LocalCharset=iso-8851-1
R0=10000
R1=250
-->

RN is maximum random number generated if you are using $rN meta symbol. N is a
number in range from 0 to MAXRANDOM-1 (defined in search.h, default is 128).
Please provide RN=xxxx for every $rN which you use in template.

Please note that the whole section looks like one HTML comment, so it will not
be visible in the browser.

WARNING: Since the template file contains such info as password, it is
strongly recommend to give the file permissions 0600 to protect it from
reading/writing by anyone but you and search program. Otherwise your passwords
may leak!

