htsearch
	
	
	  ht://Dig Copyright © 1995-2002 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:
	
	
	
	  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:
	
	
	  - 
		the name that will appear in the FORMAT menu (see below)
	  
- 
		the internal name used by htsearch for this result template
	  
- 
		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. 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
	  
- 
		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.
	  
- 
		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.
	  
- 
		CURRENT
	  
- 
		The number of the current match.
	  
- 
		DESCRIPTION
	  
- 
		The first URL description for the matched document.
	  
- 
		DESCRIPTIONS
	  
- 
		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.
	  
- 
		DOCID
	  
- 
		The internal ID for the document for the current match.
	  
- 
		EXCERPT
	  
- 
		The relevant excerpt for the current match
	  
- 
		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
	  
- 
		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 either "and" or "or"
		between the words, depending on the type of search.
	  
- 
		MATCH_MESSAGE
	  
- 
		This is either allorsomedepending on
		the match method used.
- 
		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
	  
- 
		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
	  
- 
		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.
	  
- 
	        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.
	  
- 
		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.
	  
- 
		PAGES
	  
- 
		The total number of pages.
	  
- 
		PERCENT
	  
- 
		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'.
	  
- 
		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.
	  
- 
		SCORE
	  
- 
		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
	  
- 
		The size of the document for the current match
	  
- 
		SIZEK
	  
- 
		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
	  
- 
		A set of HTML <img> tags with the stars aligned on
		the left.
	  
- 
		STARSRIGHT
	  
- 
		A set of HTML <img> tags with the stars aligned on
		the right.
	  
- 
		STARTYEAR, STARTMONTH, STARTDAY,
		ENDYEAR, ENDMONTH, ENDDAY
	  
- 
		The currently specified date range for restricting search
		results.
	  
- 
		SYNTAXERROR
	  
- 
		Is the text of the boolean expression syntax error.
	  
- 
		TITLE
	  
- 
		The title of the document for the current match
	  
- 
		URL
	  
- 
		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.
	  
	Last modified: $Date: 2002/01/27 05:33:20 $