Using search result templates
=============================


General templates information
-----------------------------
Since version 2.1 mnoGoSearch users have an ability to customize
search results (output of search.cgi or search.php). You may do it
by providing template file search.htm, which should be located in /etc/
directory of mnoGoSearch installation.

Template file is usual HTML file, which is divided into sections.
Keep in mind that you can just open template file in your favourite browser and
get the idea of how the search results will look like.

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 it's corresponding string. You can think
of meta symbols as of variables, which will have their appropriate values while
displaying search results.


Template sections
-----------------
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
	may use in this section:
	    $A - argument for FORM ACTION tag
	    $Q - your query, escaped to be printed in HTML form.
	    $q - your query, escaped to be printed in URLs. You may
	    use it for links to find the same query in other search engines:
		<A HREF="http://www.altavista.com/cgi-bin/query?q=$q">
		Find "$Q" in AltaVista
		</A>
	    $ndocs  - total number of documents in the database
	    $cat    - current category value
	    $cat(0) - the same as $cat
	    $cat(1) - category on one level above
	    $cat(X) - category on X levels above
	    $g      - current tag value
	    $g(0)   - the same as $g
            $g(X)   - tag without X trailing characters
	    $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 like this:

<!--top-->
<HTML>
<HEAD>
 <TITLE>mnoGoSearch: $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">
 Search for: <INPUT TYPE="text" NAME="q" SIZE=30 VALUE="$Q">
 <INPUT TYPE="submit" VALUE="Search!"><BR>
</FORM>
<!--/top-->

	There are some variables defined in FORM.
	
	'ul' is the filter for URL. It allows you to limit results to
	particular site or section etc. For example, you can put the following
	in the form

Search through:
<SELECT NAME="ul">
<OPTION VALUE=""            SELECTED="$ul">Entire site
<OPTION VALUE="/manual/"    SELECTED="$ul">Manual
<OPTION VALUE="/products/"  SELECTED="$ul">Products
<OPTION VALUE="/support/"   SELECTED="$ul">Support
</SELECT>

	to limit your search to particular section.
	
	The expression `SELECTED="$ul"` in example above (and all the examples
	below) allows the selected option to be reproduced on next pages. If
	search frontend finds that expression it prints the string SELECTED
	only in the case OPTION VALUE given is equal to that variable.
	[OK, I see this description is confusing, anyway - if you want your
	selection to be "saved", use this format. --kir.]
	
	'ps' is default page size (e.g. how many documents to display per page).
	
	'q' is the query itself.

	'pn' is ps*np. This variable is not used by mnoGoSearch, but may be
	useful for example in $iurl directive if you want to include result
	produced by another search engine.
	
	
	Next variables are concerning advanced search capabilities.
	
	'm' can be used to choose default search type if your query consists of
	more than one word. In case m=any, the search will try to find at least
	one word, in case m=all, the search is more restrictive - all words
	should be in the document. If m=bool query string is considered as
	a boolean expression.

	'o' is used to specify the output format, so user can select different
	formats, such as long, short etc.
	[FIXME: how it is done? Alex please write this section]
	
	'dt' is time limiting type. There are three types supported.
	
	If 'dt' is 'back', that means you want to limit result to recent pages,
	and you should specify this "recentness" in variable 'dp' in the form
	'xxxA[yyyB[zzzC]]'. Spaces are allowed between xxx and A and yyy and
	so on).	xxx, yyy, zzz are numbers (can be negative!) A, B, C can be
	one of the following (the letters are the same as in strptime/strftime
	functions):
		s - second
		M - minute
		h - hour
		d - day
		m - month
		y - year
	Examples:
		4h30m 	  - 2 hours and 30 minutes
		1Y6M-15d  - 1 year and six month minus 15 days
		1h-60m+1s - 1 hour minus 60 minutes plus 1 second
	       
	If 'dt' is 'er' (which is short for newer/older), that means the search
	will be limited to pages newer or older than date given. Variable dx
	is newer/older flag (1 means "newer" or "after", -1 means "older" or
	"before"). Date is separated into fields as follows:
		'dm' - month (0 - January, 1 - February, .., 11 - December)
		'dy' - year (four digits, for example 1999 or 2000)
		'dd' - day (1...31)
		
	If 'dt' is 'range', that means search withing given range of dates.
	Variables 'db' and 'de' are used here and stands for beginning and end
	date. Each date is string in the form dd/mm/yyyy, there dd is day,
	mm is month and yyyy is four-digits year.
	
	This is the example of FORM part where you can choose between different
	time limiting options.

<!-- 'search with time limits' options -->
<TR><TD>
<TABLE CELLPADDING=2 CELLSPACING=0 BORDER=0>
<CAPTION>
Limit results to pages published within a specified period of time.<BR>
<FONT SIZE=-1><I>(Please select only one option)</I></FONT>
</CAPTION>
<TR> 
<TD VALIGN=center><INPUT TYPE=radio NAME="dt" VALUE="back" CHECKED></TD>
<TD><SELECT NAME="dp">
<OPTION VALUE="0" SELECTED="$dp">anytime
<OPTION VALUE="10M" SELECTED="$dp">in the last ten minutes
<OPTION VALUE="1h" SELECTED="$dp">in the last hour
<OPTION VALUE="7d" SELECTED="$dp">in the last week
<OPTION VALUE="14d" SELECTED="$dp">in the last 2 weeks
<OPTION VALUE="1m" SELECTED="$dp">in the last month
<OPTION VALUE="3m" SELECTED="$dp">in the last 3 months
<OPTION VALUE="6m" SELECTED="$dp">in the last 6 months
<OPTION VALUE="1y" SELECTED="$dp">in the last year
<OPTION VALUE="2y" SELECTED="$dp">in the last 2 years
</SELECT>
</TD>
</TR>
<TR>
<TD VALIGN=center><INPUT type=radio NAME="dt" VALUE="er">
</TD>
<TD><SELECT NAME="dx">
<OPTION VALUE="1" SELECTED="$dx">After
<OPTION VALUE="-1" SELECTED="$dx">Before
</SELECT>

or on

<SELECT NAME="dm">
<OPTION VALUE="0" SELECTED="$dm">January
<OPTION VALUE="1" SELECTED="$dm">February
<OPTION VALUE="2" SELECTED="$dm">March
<OPTION VALUE="3" SELECTED="$dm">April
<OPTION VALUE="4" SELECTED="$dm">May
<OPTION VALUE="5" SELECTED="$dm">June
<OPTION VALUE="6" SELECTED="$dm">July
<OPTION VALUE="7" SELECTED="$dm">August
<OPTION VALUE="8" SELECTED="$dm">September
<OPTION VALUE="9" SELECTED="$dm">October
<OPTION VALUE="10" SELECTED="$dm">November
<OPTION VALUE="11" SELECTED="$dm">December
</SELECT>
<INPUT TYPE=text NAME="dd" VALUE="$dd" SIZE=2 maxlength=2>
,
<SELECT NAME="dy" >
<OPTION VALUE="1990" SELECTED="$dy">1990
<OPTION VALUE="1991" SELECTED="$dy">1991
<OPTION VALUE="1992" SELECTED="$dy">1992
<OPTION VALUE="1993" SELECTED="$dy">1993
<OPTION VALUE="1994" SELECTED="$dy">1994
<OPTION VALUE="1995" SELECTED="$dy">1995
<OPTION VALUE="1996" SELECTED="$dy">1996
<OPTION VALUE="1997" SELECTED="$dy">1997
<OPTION VALUE="1998" SELECTED="$dy">1998
<OPTION VALUE="1999" SELECTED="$dy">1999
<OPTION VALUE="2000" SELECTED="$dy">2000
<OPTION VALUE="2001" SELECTED="$dy">2001
</SELECT>
</TD>
</TR>
<TR>
<TD VALIGN=center><INPUT TYPE=radio NAME="dt" VALUE="range">
</TD>
<TD>
Between
<INPUT TYPE=text NAME="db" VALUE="$db" SIZE=11 MAXLENGTH=11>
and
<INPUT TYPE=text NAME="de" VALUE="$de" SIZE=11 MAXLENGTH=11>
</TD>
</TR>
</TABLE>

</TD></TR>
<!-- end of stl options -->



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://www.mnogosearch.org/"><IMG SRC="mnoGoSearch.gif" BORDER=0 ALT="[Powered by mnoGoSearch]"></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 'html template' $W can be something like
	         'html: 10  template: 20')
		 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 mnoGoSearch)
	    $DX  Document teXt (the first couple of lines to give 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 (in order of appearance)
	    $DD  Document Description (from META DESCRIPTION tag)
	    $DE  if non empty $DD then $DD else $DX
	    $DK  Document Keywords (from META KEYWORDS tag)
	    $DY  Document category with links,
		 i.e. /home/computers/software/www/
	    $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 a complex thing and therefore is constructed from the following
template sections:

navleft, navleft_nop	
	
	These are used for printing the link to the previous page. If that
page exists, <!--navleft--> is used, and on the first page there is no
previous page, so <!--navleft_nop--> is used.

<!--navleft-->
<TD><A HREF="$NH"><IMG...></A><BR><A HREF="$NH">Prev</A></TD>
<!--/navleft-->

<!--navleft_nop-->
<TD><IMG...><BR><FONT COLOR=gray>Prev</FONT></TD>
<!--/navleft_nop-->

navbar0
	This is used for printing the current page in the page list.

<!--navbar0-->
<TD><IMG...><BR>$NN</TD>
<!--navbar0-->

navright, navright_nop

	These are used for printing the link to the next page. If that page
exists, <!--navright--> is used, and on the last page <!--navright_nop-->
is used instead.

<!--navright-->
<TD><A HREF="$NH"><IMG...></A><BR><A HREF="$NH">Next</A></TD>
<!--navright-->

<!--navright_nop-->
<TD><IMG...><BR><FONT COLOR=gray>Next</FONT></TD>
<!--navright_nop-->


navbar1

	This is used for printing the links to the other pages in the page
list.

<!--navbar1-->
<TD><A HREF="$HR"><IMG...></A><BR><A HREF="$NH">$NN</A></TD>
<!--/navbar1-->


Below 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 when
	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 hasn't returned results.<P>
<I>Try to compose less restrictive search query or check spelling.</I>
</CENTER>
<HR>
<!--/notfound-->

noquery
	This section is displayed in case when user gived an empty query.

	Below is an example of noquery section:

<!--noquery-->
<CENTER>
You haven't typed any word(s) to search for.
</CENTER>
<HR>
<!--/noquery-->


error	This section is displayed in case some internal error occured while
	searching. For example, database server is not running or so.
	You may 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 up 
some values for search. Note that database options work only for SQL
backend and do not matter for built-in text files support.

Like in indexer.conf, DBHost takes affect for
natively supported databases only and does not matter for ODBC databases.
In case of ODBC use DBName to specify ODBC DSN.
Special variables section usually looks like this:

<!--variables
DBHost		localhost
DBUser		foo
DBPass		bar
DBName		mnoGoSearch
TrackQuery	yes
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.


Include in templates
--------------------
$if
	You can use $if(another_template_file_name) meta symbol to include
	another file into being proccessed one in any part of template.
	For example, this will use top.htm as "top" section of search results:

        <!--top-->
	$if(top.htm)
	<!--/top-->

$iurl
	You can use $iurl(http://myhostname/my_path?arguments) meta symbol
	to include result of processing this URL. If search.cgi is compiled
	with threads support, URL processing will be done in parallel with
	search process.

	WARNING: You can use $iurl ONLY in the following template sections:
	<!--top-->, <!--bottom-->, <!--restop-->, <!--resbot-->,
	<!--notfound-->, <!--error-->.

	This is an example of $iurl usage:

        <!--top-->
        $iurl(http://my.search.com/findit?query=$q&from=$pn)
        <!--/top-->


Using several formats with one template
---------------------------------------
Since version 3.0.10 mnoGoSearch allows to define several (up to 100)
descriptions for the same template section. It is often reasonable, for
example, to have both "Long" and "Short" search results format. To implement
this just write two separate "res" template sections for "Long" and "Short"
result output formats one by one. The sample of different formats usage is
given in search.htm-dist. Note that "res" is not the only section - every
template section may be given several times. So, it is easy for example to
prepare multi-language templates.



Security issues
---------------
WARNING: Since the template file contains such info as password, it is
highly recommended to give the file proper permissions to protect it from
reading by anyone but you and search program. Otherwise your passwords may 
leak. 
