mnoGoSearch 3.3.9 reference manual: Full-featured search engine software
Prev | Chapter 10. Searching documents | Next

# How to write search result templates

mnoGoSearch users can fully customize the search results look and feel. You can do it by editing the template file `search.htm` which resides in the `/etc/` directory of your mnoGoSearch installation.

## Template file structure

The template file is a usual HTML file divided into blocks (sections). Keep in mind that you can just open the template file in your Web browser and get the idea of how the search results will look like.

> Note: Lines in the template file should not exceed `1024` bytes.

Every section starts and ends with special section delimiters which look like `<!--sectionname-->` and `<!--/sectionname-->` correspondingly. The section delimiters should reside on separate lines.

Every section consists of a HTML formatted text with variable references. A variable reference is replaced by its value when search.cgi is running.

## Template variable formats

Template variables can be printed using a number of different formats:

`$(x)` - a plain text value.
`$&(x)` - a HTML-escaped value with search words highlighted.
`$%(x)` - a value escaped for use in URLs
`$^(x)` - a HTML-escaped value with search words highlighted.

It is possible to specify the maximum number of characters printed by a variable. For example, `$(URL)` can return a very long URL and break the search results layout. To limit the maximum length printed by a variable, use the `$(URL:xx)` syntax, where `xx` is the maximum number of characters to display.

`$(URL:40)` will print the URL variable value. In case when it is longer than `40` characters, only `40` characters will be displayed including the trailing dots:

`http://very.long.url/path/veery/long/...`

Starting from the version `3.3.1`, it is also possible to display the rightmost characters:

`$(URL:-40)`

## Template sections

mnoGoSearch supports the following sections:

### The TOP section

This section is printed in the very beginning of search.cgi output and should usually start with `<HTML><HEAD>` and so on. Also, this is the proper place to put a search form to.

A number of variables is available in the top section:

    $(self)  - the argument for the FORM ACTION tag
    $(q)     - the search query
    $(cat)   - the current category value
    $(tag)   - the current tag value
    $(rN)    - a random number (here N is a number between 0 and 9)

> Note: If you want to print some random banners or random links in your search results, you can use the `$(r0)`..`$(r9)` variables. For example:

>     <A HREF="http://www.sitename.com/redirect.php?targetID=$(r0)">
>     Go to a random page of the site
>     </A>

> You can also initialize the `$(rX)` variables to a desired number range using the R0 - R9 commands.

A example of the top section can look like this:

    <!--top-->
    <HTML>
    <HEAD>
     <TITLE>mnoGoSearch: $&(q)</TITLE>
    </HEAD>
    <BODY>

    Search in the manual:
    <FORM METHOD=GET ACTION="$&(self)">
     <INPUT TYPE="text" NAME="q" SIZE="30" VALUE="$&(q)">
     <INPUT TYPE="hidden" NAME="ul" VALUE="/manual/">
     <INPUT TYPE="hidden" NAME="ps" VALUE="20">
     <INPUT TYPE="submit" VALUE="Search!">
    </FORM>
    <!--/top-->

The example above includes some search parameters, described in details in the Section called Search parameters :

The `ul` form variable is an URL filter. It allows to limit results to a particular site or a site directory. For example, you can put the following code into your template:

    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 a particular site directory.

> Note: The attribute `SELECTED="$(ul)"` in the above example (and in the other examples below) allows the selected option to be selected again by default on the next page displayed after pressing the `Search!` button. The attribute is replaced to either the `SELECTED` keyword, or to empty string, according to the current `$(ul)` value.

`ps` is the default page size (e.g. how many documents are displayed per page).

`q` is the search query.

### The BOTTOM section

This section is always displayed in the end of search.cgi output and typically contains all closing tags which have their counterparts in the top section.

> Note: The position of the bottom section in the search template file does not matter. It is always displayed in the very end of output. Putting the bottom section in the end of the template file is recommended solely for convenience reasons, to be able to view the template as an ordinary HTML file in your Web browser.

An example of the bottom section can look like this:

    <!--bottom-->
    <P>
    <HR>
    <DIV ALIGN=right>
    <A HREF="http://search.mnogo.ru/">
    <IMG SRC="mnogosearch.gif" BORDER=0 ALT="[Powered by mnoGoSearch]">
    </A>
    </BODY>
    </HTML>
    <!--/bottom-->

### The RESTOP section

This section is included just before the search results. It's a good idea to use this section to put some statistics about the query just executed, with help of the following variables:

- `$(first)` - the offset of the first document displayed on this page.

- `$(last)` - the offset of the last document displayed on this page.

- `$(total)` - the total number of the documents found.

- `$(W)` - short word statistics with information about the number of the exact and the fuzzy query word forms, delimited by the `/` sign for every query word. For example, if the `$(W)` value is `test: 25/73`, it means that mnoGoSearch found `25` exact word forms `test`, and `73` fuzzy forms like `tested`, `tests`, `testing`, etc.

- `$(WE)` - extended word statistics including information about every exact and fuzzy word form found.

- `$(SearchTime)` - search query execution time.

- `$(CurrentTimestamp)` - current time, in seconds since `00:00:00 UTC, January 1, 1970`.

- `$(ndocs)` - the total number of documents in the database.

This is an example of the restop section:

    <!--restop-->
    <TABLE BORDER=0 WIDTH=100%>
      <TR>
      <TD>Search<BR>results:</TD>
      <TD><small>$(WE)</small></TD>
      <TD><small>$(W)</small></TD>
      </TR>
    </TABLE>
    <HR>
    <CENTER>
      Displaying documents $(first)-$(last) of total <B>$(total)</B> found.
      Search took <b>$(SearchTime)</b> seconds
    </CENTER>
    <!--/restop-->

### The RES section

This section is displayed for every document from the current result page (`10` documents per page by default).

The following variables are available in the RES section:

- `$(URL)` - the URL

- `$(Title)` - the Title

- `$(Score)` - the score (as calculated by mnoGoSearch)

- `$(Body)` - a piece of text, to give an idea of what the document is about:

  - a smart excerpt with the query words in their context if CachedCopy is available,

  - otherwise, the first couple of lines from the document body.

- `$(Content-Type)` - the Content-type (for example, `text/html`)

- `$(Last-Modified)` - the modification date, using DateFormat.

- `$(Last-Modified-Timestamp)` - the modification date as a number of seconds since `00:00:00 UTC, January 1, 1970`.

- `$(Content-Length)` - the document Size (in bytes)

- `$(Content-Length-K)` - the document Size (in kilobytes)

- `$(Order)` - the document Number in the order of its appearance in the search results, starting from `1`.

- `$(DBOrder)` - the Original Database Document Order - the original order of the document in its database result set, before multiple DBAddr search results were merged into the final result. It is equal to `$(Order)` if only a single DBAddr command is given in `search.htm`. This variable is mostly for debugging purposes.

- `$(DBNum)` - the Source Database Number - the number of the database generated this document, in the order of appearance of the DBAddr commands, starting from `0`. That is `0` means that the document was found in the database corresponding to the first DBAddr command, `1` - to the second DBAddr command, and so on. `$(DBNum)` is always `0` `search.htm` uses only a single DBAddr command. This variable is mostly for debugging purposes.

- `$(meta.description)` - the description meta tag value.

- `$(meta.keywords)` - the keywords meta tag value.

- `$(DY)` - the document category with links, i.e. `/home/computers/software/www/`

- `$(CloneN.URL)` - the URL of the `N-th` clone, where `N` is a number starting from `0`. The `$(CloneN)` variables appeared in mnoGoSearch `3.3.0`.

- `$(PerSite)` - the total number of documents found on the same site when GroupBySite is enabled, or `0` otherwise.

Here is an example of the res section:

    <!--res-->
    <DL><DT>
    <b>$(Order).</b><a href="$(URL)" TARGET="_blank">
    <b>$(Title)</b></a> [<b>$(Score)</b>]<DD>
    $(Body)...<BR>
    <b>URL: </b>
    <A HREF="$(URL)" TARGET="_blank">$(URL)</A>($(Content-Type))<BR>
    $(Last-Modified), $(Content-Length) bytes<BR>
    <b>Description: </b>$(meta.description)<br>
    <b>Keywords: </b>$(meta.keywords)<br>
    </DL>
    <UL>
    $(CL)
    </UL>
    <!--/res-->

### The CLONE section

This section was supported in mnoGoSearch versions prior to `3.3.0` and was removed in the later versions. Use the `$(CloneN.URL)` variables instead.

### The RESBOT section

This section is included just after the last document. You can usually print the page navigation bar here, which includes links to move to the next and the previous result pages.

This is an example of the resbot section:

    <!--resbot-->
    <HR>
    <CENTER>
    Result pages: $(NL)$(NB)$(NR)
    </CENTER>
    <!--/resbot-->

The page navigator is constructed from the following template sections:

### The navleft, navleft_nop sections

These sections are used to print the links to the previous result page. If the previous page exists, the code in `<!--navleft-->` is used. The very first page does not have previous pages, so `<!--navleft_nop-->` is used instead.

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

### The navbar0 section

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

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

### The navright, navright_nop sections

These two sections are used to print the link to the next page. If the next page exists, the `<!--navright-->` section is used. On the last page the `<!--navright_nop-->` section 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-->

### The navbar1 section

This template section is used to print 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-->

### The notfound section

As the section name implies, the notfound section is displayed in case when no documents were found and usually consists of a message with hints how to make the search condition less restrictive.

This is an example of the notfound section:

    <!--notfound-->
    <CENTER>
    Sorry, search did not find any results.<P>
    <I>Try to compose a less restrictive search query or check spelling.</I>
    </CENTER>
    <HR>
    <!--/notfound-->

### The noquery section

This section is displayed in case when the user gives an empty search query. For example:

    <!--noquery-->
    <CENTER>
    You didn't type any words to search for.
    </CENTER>
    <HR>
    <!--/noquery-->

### The error section

This section is displayed in case when some internal error occurred while searching. For example, when the database server is not available. You can use the `$(E)` variable to print the error text:

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

### The variables section

This is a special section were you put configuration commands.

The variables section can look like this:

    <!--variables
    DBAddr mysql://foo:bar@localhost/search/?DBMode=blob
    LocalCharset    iso-8859-1
    BrowserCharset  iso-8859-1
    TrackQuery  yes
    DetectClones  yes
    HlBeg <font color="blue"><b><i>
    HlEnd </i></b>
    R1    100
    Synonym synonym/english.syn
    -->

The typical configuration commands are: DBAddr, LocalCharset, BrowserCharset, DetectClones, GroupBySite, HlBeg, HlEnd, DateFormat. See Reference I, mnoGoSearch command reference for the description of all available commands.

### Using the variables section with operators

You can also use another variables section in combination with all operators supported by the mnoGoSearch template language. You can set some variable values which will be used during search, for example search limits.

Examples:

    <!--variables-->
    <!SET NAME="ul" CONTENT="/path/">
    <!--/variable-->

## Includes in templates

You can use the `<!INCLUDE Content="http://hostname/path">` operator to include content of an external document into search results.

WARNING: `<!INCLUDE>` works only in the following template sections:

`<!--top-->`
`<!--bottom-->`
`<!--restop-->`
`<!--resbot-->`
`<!--notfound-->`
`<!--error-->`

Example:

    <!--top-->
    ....
    <!INCLUDE CONTENT="http://hostname/banner?query=$&(q)">
    ...
    <!--/top-->

## Security issues

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

Prev | Home | Next
Searching documents | Up | Designing `search.htm`