htsearch

ht://Dig Copyright © 1995-2004 The ht://Dig Group
Please see the file COPYING for license information.

Output Templates

The htsearch program will normally produce HTML output. In this process it makes extensive use of template in which variables will be substituted. The templates are specified in the configuration file. The configuration file attributes defining these templates are:

• search_results_header
• search_results_footer
• search_results_wrapper
• nothing_found_file
• syntax_error_file

In addition to these files, the search results are also produced with the use of templates. The result templates are a bit more complicated because they can be specified at runtime using an HTML menu. They are specified using the template_map configuration file attribute. This attribute contains a list of strings triplets. For each triplet of strings, the elements have the following meaning:

1. the name that will appear in the FORMAT menu (see below)
2. the internal name used by htsearch for this result template
3. the base filename for the template.

There are two predefined templates that are used by default. They have the internal names builtin-long and builtin-short. As such, the default value for the template_map attribute is as follows:

Long builtin-long builtin-long \
Short builtin-short builtin-short

Which means that there will be two ways to display the search results: a "Long" and a "Short" way. The first template listed will always be the default one for the first search. Thereafter, the default will be whatever was selected for the previous search.

Result template files

When a custom template is required, one or more template files need to be created and referenced in the template_map attribute. These templates are user-selectable from the search form. It is also possible to select result templates based on URL patterns of the search matches, using the template_patterns attribute. This allows distinct visual styles to be used for matches on different web sites.

There are many variables that can be substituted into these templates. Not all of them make sense for each file, so not all of them will be substituted for every file, as noted below. In addition, all of the standard CGI environment variables are available, and listed in the cgi specification. Variables will be substituted normally with the format $(VAR), escaped for use in a URL with the format $%(VAR), URL-encoding decoded with the format $=(VAR), and HTML-escaped with the format $&(VAR). The variables are:

ANCHOR (Only in matchTemplate)

Expands to the named anchor found just before the first match; it includes "#" at the start so it can be directly appended to the URL variable. If no anchor was found, ANCHOR is empty.

BACKLINKS (Only in matchTemplate)

The number of links to the current match.

CGI

Unless the configuration file sets a different value, this expands to whatever the SCRIPT_NAME environment variable is. See the script_name configuration file attribute for more information.

CONFIG

The configuration file.

CURRENT (Only in matchTemplate)

The number of the current match.

DESCRIPTION (Only in matchTemplate)

The first URL description for the matched document. See below.

DESCRIPTIONS (Only in matchTemplate)

A list of URL text descriptions for the matched document. The entries in the list are separated by <br>. These are the text used between the <a href...> and </a>tags. These are controlled by the max_descriptions and max_description_length configuration attributes.

DOCID (Only in matchTemplate)

The internal ID for the document for the current match.

EXCERPT (Only in matchTemplate)

The relevant excerpt for the current match.

EXCLUDE

A list of words excluded from the search, separated by '|'.

FIRSTDISPLAYED

The index of the first match on this page.

FORMAT

Expands to an HTML menu of all the available formats. The current format will be the default one. The menu is composed of choices itemized in the template_map attribute. The expansion of this template variable is described in more detail in the select list documentation.

HOPCOUNT (Only in matchTemplate)

The distance of this match away from the starting document(s).

KEYWORDS

A string of the search keywords with spaces in between, as specified in the keywords input parameter.

LASTDISPLAYED

The index of the last match on this page.

LOGICAL_WORDS

A string of the search words with "and", "or" or "not" between the words, depending on the type of search. (These values are overridden by the boolean_keywords attribute.)

MATCH_MESSAGE

This is either all or any depending on the match method used. (These values are overridden by the method_names attribute.)

MATCHES

The total number of matches that were found.

MATCHES_PER_PAGE

The configured maximum number of matches on this page.

MAX_STARS

The configured maximum number of stars to display in matches.

METADESCRIPTION (Only in matchTemplate)

The meta description text (if any) for the matched document.

METHOD

Expands to an HTML menu of all the available matching methods. The current method will be the default one. The menu is composed of choices itemized in the method_names attribute. The expansion of this template variable is described in more detail in the select list documentation.

MODIFIED (Only in matchTemplate)

The date and time the document was last modified

NEXTPAGE

This expands to the value of the next_page_text or no_next_page_text attributes depending on whether there is a next page or not. If there is only one page of output, this is empty, regardless of the setting of no_next_page_text.

NSTARS

The number of stars calculated for this document as an integer, up to a maximum specified by the max_stars attribute.

PAGE

The current page number. Equal to the page CGI argument, or 1 by default.

PAGEHEADER

This expands to either the value of the page_list_header or no_page_list_header attributes depending on how many pages there are.

PAGELIST

This expands to a list of hyperlinks using the page_number_text and no_page_number_text attributes. For the current page, it displays no_page_number_text without a hyperlink. Other pages have a hyperlink, and use page_number_text.

PAGES

The total number of pages.

PERCENT (Only in matchTemplate)

The match score as a percentage. Its range is 1 to 100, without a percent sign. The minimum is always 1 so the variable can be used as the value for an HTML WIDTH attribute.

PLURAL_MATCHES

If the MATCHES variable is other than 1, this will be a single 's'. (This value is overridden by the plural_suffix attribute.)

PREVPAGE

This expands to the value of the prev_page_text or no_prev_page_text attributes depending on whether there is a previous page or not. If there is only one page of output, this is empty, regardless of the setting of no_prev_page_text.

RESTRICT

The list of patterns which must be matched by the returned URLs, separated by '|'.

SCORE (Only in matchTemplate)

The score of the current match

SELECTED_FORMAT

The currently selected format.

SELECTED_METHOD

The currently selected matching method.

SELECTED_SORT

The currently selected sorting method.

SIZE (Only in matchTemplate)

The size of the document for the current match

SIZEK (Only in matchTemplate)

The size in kilobytes of the document for the current match

SORT

Expands to an HTML menu of all the available sorting methods. The current method will be the default one. The menu is composed of choices itemized in the sort_names attribute. The expansion of this template variable is described in more detail in the select list documentation.

STARSLEFT (Only in matchTemplate)

A set of HTML <img> tags with the stars aligned on the left.

STARSRIGHT (Only in matchTemplate)

A set of HTML <img> tags with the stars stars aligned on the right.

STARTYEAR, STARTMONTH, STARTDAY, ENDYEAR, ENDMONTH, ENDDAY

The currently specified date range for restricting search results.

SYNTAXERROR (Only in syntax_error_file)

Is the text of the boolean expression syntax error.

TITLE (Only in matchTemplate)

The title of the document for the current match

URL (Only in matchTemplate)

The URL to the document for the current match

VERSION

The ht://Dig version number.

WORDS

A string of the search words with spaces in between.