Using search result templates ============================= General templates information ----------------------------- Since version 2.1 UdmSearch users have an ability to customize the 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 UdmSearch 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 and ends with 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 the 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 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 $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: UdmSearch: $Q
Search for:
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). q is the query itself. Variable $ul is also available. So, you can is like in the form to display previously submited value: 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:


[Powered by UdmSearch] 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:
Search
results:
$W

Displaying documents $f-$l of total $t found.
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 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) $DK Document Keywords (from META KEYWORDS tag) $CL Clone List (see section 'clone' for details) Here is an example of res section:
$DN.$DT [$DR]
$DX...
URL: $DU($DC)
$DM, $DS bytes
Description: $DD
Keywords: $DK
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.
  • $DU ($DC) $DM 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
    Prev Current Page:
    $NN Next Page: Printed if there is a next page only
    Next Middle pages in navigation bar:
    $NN This is the sample of navigator: $NL $NB $NR
    This is an example of 'resbot' section:
    $V
    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:
    Sorry, but search hasn't returned results.

    Try to produce less restrictive search query or check words spelling


    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:
    An error occured!

    $E

    There is also a special variables section, in which you can set up some values for search. Note that database options works 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 the case of ODBC use DBName to specify ODBC DSN. Special variables section usually looks like this: 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 -------------------- You may also use special $if(enother_template_file_name) meta symbol to include enother template file into being proccessed one in any part of template. For example, this will use top.htm as "top" section of search results: $if(top.htm) Using several formats with one template --------------------------------------- Since version 3.0.10 UdmSearch allows to define several (up to 100 ) descriptions for the same template part. It is often reasonable, for example, to describe "Long" and "Short" search results format. To implement this just write two separate "res" template sections for "Long" and "Short" results output formats one ofter enother. The sample of different formats usage is given in search.htm-dist. Note that "res" is not the only part which may be described twice or more. All template parts 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 recommend to give the file proper permissions to protect it from reading by anyone but you and search program. Otherwise your passwords may leak.