  
	
  
  
	
	  htsearch
	
	
	  ht://Dig Copyright © 1995-2004 
THANKS.htmlThe ht://Dig Group 	  Please see the file 
COPYINGCOPYING  for
	  license information.
	
	
	
	  Input parameter select lists
	
	
	  The primary interface to htsearch is through an HTML
	  
hts_form.htmlform .
	  The input fields in this form can be defined as any type that
	  HTML allows, but some of these are best handled through HTML
	  
select lists.
	
	
	  
	  Pre-defined template select lists
	
	
	  In order to propagate these select lists to the search form
	  in the results template, so that the default 
selected	  value will be the one the user last selected, htsearch defines
	  a few of these select lists as
	  
hts_templates.htmltemplate variables .
	  These variables are:
	
	
	  
		
FORMAT, which selects the format input parameter
		for follow-up searches, with the current value being the
		default. The current value is taken from the 
format		input parameter, if one was provided, or from the
		
attrs.html#template_nametemplate_name 		attribute otherwise, and this value will also be given in
		the 
SELECTED_FORMAT template variable.
		The various parameter values, and their corresponding
		labels for the select list, are taken from the
		
attrs.html#template_maptemplate_map 		attribute.
	  
	  
		
METHOD, which selects the method input parameter
		for follow-up searches, with the current value being the
		default. The current value is taken from the 
method		input parameter, if one was provided, or from the
		
attrs.html#match_methodmatch_method 		attribute otherwise, and this value will also be given in
		the 
SELECTED_METHOD template variable.
		The various parameter values, and their corresponding
		labels for the select list, are taken from the
		
attrs.html#method_namesmethod_names 		attribute.
	  
	  
		
SORT, which selects the sort input parameter
		for follow-up searches, with the current value being the
		default. The current value is taken from the 
sort		input parameter, if one was provided, or from the
		
attrs.html#sortsort 		attribute otherwise, and this value will also be given in
		the 
SELECTED_SORT template variable.
		The various parameter values, and their corresponding
		labels for the select list, are taken from the
		
attrs.html#sort_namessort_names 		attribute.
	  
	
	
	  In addition to these template variables, htsearch makes
	  use of a number of other input parameters, all of which
	  have corresponding template variables and configuration
	  attributes.  It's also possible, within htsearch, to make an
	  input parameter out of any 
attrs.htmlconfiguration
	  attribute
 that's not already automatically handled by an
	  input parameter. This is accomplished by means of the
	  
attrs.html#allow_in_formallow_in_form  attribute.
	  The attributes listed in the allow_in_form list will be settable
	  in the search form using input parameters of the same name,
	  and will be propagated to the follow-up search form in the
	  results template using template variables of the same name
	  in upper-case.
	
	
	  
	  Custom template select lists
	
	
	  This gives you a great deal of flexibility in configuring
	  htsearch, but all of these template variables still contain
	  only the parameter value, and not a select list to choose
	  the value. In order to use any input parameters as select
	  lists, other than the three pre-defined variables above, one
	  must either statically define a select list in the results
	  template follow-up form, just as in the initial search form
	  or instruct htsearch to build one as a template variable.
	  Statically defining new select lists is easier, as you have
	  to do it for the initial search form anyway, but this has the
	  drawback that the user's selection from the initial form does
	  not appear as the default selection in the follow-up form,
	  because the default is static.
	
	
	  To overcome this drawback, you must use the
	  
attrs.html#build_select_listsbuild_select_lists 	  configuration attribute. Its usage is a bit complicated, but
	  it's extremely flexible, allowing you do define any htsearch
	  input parameter as a select list for use in templates, provided
	  you also define the corresponding name list attribute which
	  enumerates all the choices to put in the list. It can be used
	  for existing input parameters, as well as any you define using
	  the allow_in_form attribute.
	
	
	  The entries in this list each consist of an 
octuple, a
	  set of eight strings defining the variables and how they are to
	  be used to build a select list. The attribute can contain many
	  of these octuples. The strings in the string list are merely
	  taken eight at a time. For each octuple of strings specified in
	  build_select_lists, the elements have the following meaning:
	
	
	  
		the name of the template variable to be defined as a list,
		optionally followed by a comma and the type of list, and
		optional formatting codes
	  
	  
		the input parameter name that the select list will set
	  
	  
		the name of the user-defined attribute containing the
		
name list, that is the list of values and labels
		for the select list items, much like the template_map,
		method_name and sort_name attributes
	  
	  
		the 
tuple size used in the name list above
	  
	  
		the index into a name list tuple for the value
	  
	  
		the index for the corresponding label to be displayed on
		the selector
	  
	  
		the configuration attribute where the default value for
		this input parameter is defined, which may or may not be
		the same name as the input parameter
	  
	  
		the default label, if not an empty string, which will be
		used as the label for an additional list item for the
		current input parameter value if it doesn't match any value
		in the given list
	  
	
	
	  The first element in an entry is actually a comma separated
	  list. The first item within this list is the name of the
	  template variable to be created. The next item, if specified,
	  is the type of select list or input list to be created in this
	  template variable. Choices are 
select,
	  
multiple, radio,
	  and 
checkbox, with the default being
	  
select. The word multiple	  refers to a <select multiple> type of select list,
	  where more than one option can be selected. The choices
	  
radio and checkbox will build
	  lists of <input> tags of these types, rather than a select
	  list with <option> tags. The optional third and fourth
	  items in this comma separated list are text or formatting tags
	  that will be prepended and appended, respectively, to each item
	  in the built list, before the <option> or <input>
	  tag and after the label for that tag. This first element is
	  parsed as a quoted string list within a quoted string list,
	  so you can embed quotes and commas within elements of this
	  inner list if you use correct quoting. See examples below.
	
	
	  The name list that you define will most commonly consist
	  of pairs of values, and therefore you'd use a tuple size of
	  2. The method_names and sort_names attributes are samples of
	  such name lists. You can give any name you'd like to the name
	  list attributes you define yourself, but you should try to
	  avoid using any of the names of 
attrs.htmlexisting
	  attributes
. The value and label for the pairs in lists you
	  define yourself can appear in either order, depending on the
	  index you specify for each. In the case where you'd want the
	  labels on the selector to be the same as the actual parameter
	  values used, which would make sense for lists of numbers,
	  you can use a tuple size of 1, and indexes of 1, to avoid
	  having to duplicate all the numbers in the list.
	
	
	  Any of the strings in an octuple may be quoted, and should be if
	  you want to include spaces or define an empty string.  If the
	  default label, the eight element in an entry, is an empty
	  string, the select list will not have a 
selected item
	  if the current input parameter value doesn't match any value
	  in the name list. If a default label is given, an additional
	  list item will be added to the list using this label, if the
	  current input parameter value doesn't match.
	
	
	  If the seventh element, the configuration attribute name, is
	  an empty string, the default value will be taken from from
	  the input parameter, the second element, instead. This is
	  especially useful for input parameters that don't get mapped
	  to a configuration attribute, or for checkboxes or multiple
	  selects, where the separation between individual choices may
	  get lost when the input parameter is mapped to an attribute.
	
	
	  Here is an example of its usage, which illustrates different
	  tuple sizes and orders:
	
	
build_select_lists:     MATCH_LIST,radio matchesperpage matches_per_page_list \
                                1 1 1 matches_per_page "Previous Amount" \
                RESTRICT_LIST,multiple restrict restrict_names 2 1 2 restrict "" \
                FORMAT_LIST format template_map 3 2 1 template_name ""
matches_per_page_list:  1 5 10 20 100 500
restrict_names: "http://www.myschool.edu/Admin/" "Admin Web Pages" \
                "http://www.myschool.edu/Faculty/" "Faculty Web Pages" \
                "http://www.myschool.edu/Student/" "Student Web Pages" \
                "" "Whole Web Site"
	
	
	  The FORMAT_LIST example should give something equivalent to the FORMAT
	  template variable, which is already set by htsearch.  It is included as
	  an additional example of how to specify the tuple size and indices of
	  values and labels in a tuple.
	
	
	  Here is an example which illustrates additional formatting tags,
	  and the quoting that may be required:
	
	
build_select_lists:     "RESTRICT_LIST,checkbox,'<font face=\\"Arial,Helvetica\\" size=\\"+2\\">',</font><br>" \
                                restrict restrict_names 2 1 2 restrict ""
	
	
	  In this example, the font tag will be inserted before each
	  checkbox input tag, and the closing font tag and line break will
	  be appended after each label that follows the input tag. Because
	  the font tag has an embeded comma, which is also the separator
	  for the list in the first element, the whole tag (i.e. the whole
	  third item in the comma separated list) is quoted, and it's
	  quoted with single quotes so as not to conflict with the double
	  quotes enclosing the whole element. Finally, to embed a double
	  quote in the font tag, it must be escaped with two backslashes -
	  the first of these is absorbed by the variable expansion phase
	  that all attribute values go through, and the second is used
	  to embed the double quote within a double quoted string.
	
	
	  
	  Combining the format select list with template_patterns
	
	
	  The addition of the 
attrs.html#template_patterns	  template_patterns
 attribute has added a new wrinkle to
	  the pre-defined select list for the 
format parameter.
	  If a document URL matches an entry in template_patterns, its
	  corresponding result template will override any template the
	  user selected with the format parameter. The problem stems
	  from the fact that the two were not originally intended to
	  be used together in the same htsearch configuration. When
	  configuring htsearch, you'd normally set it up to use one
	  mechanism or the other, but not a combination of the two.
	
	
	  However, the following example would allow user-selected
	  templates to work together with template_patterns:
	
	
template_map:      Long long ${common_dir}/long.html \
                   Short short ${common_dir}/short.html
template_name:     long
template_patterns: .pdf ${common_dir}/${template_name}-pdffile.html \
                   .ps  ${common_dir}/${template_name}-psfile.html \
                   .doc ${common_dir}/${template_name}-docfile.html
	
	
	  This works because the template_name attribute gets set
	  internally in htsearch, to the user-selected value of the
	  
format input parameter, before the variable expansion
	  in template_patterns takes place. As long as you stick to
	  a template file naming convention that uses the internal
	  name element of template_map (second element in a triple) as
	  part of the file name, this should work like a charm. Your
	  common directory would have to contain the template files
	  long-pdffile.html, long-psfile.html, long-docfile.html,
	  short-pdffile.html, short-psfile.html, and short-docfile.html,
	  for the example above to work, in addition to the long.html
	  and short.html files, which will be used for URLs that don't
	  match any of the patterns. Of course, these patterns can be
	  any URL parts, and not just suffixes. Be sure to also change
	  the values for format in your initial search form, search.html,
	  to use your chosen internal names.
	
	
	Last modified: $Date: 2004/05/28 13:15:18 $
  
