j  � ht://Dig: htsearch� �  

htsearch



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




 Input parameter select lists



7 The primary interface to htsearch is through an HTML$ form.@ 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 selectedA value will be the one the user last selected, htsearch defines! a few of these select lists as7 template variables. These variables are:

 

: 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 configuration? attribute that's not already automatically handled by an8 input parameter. This is accomplished by means of theB allow_in_form attribute.C 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 theA build_select_lists? configuration attribute. Its usage is a bit complicated, but? it's extremely flexible, allowing you do define any htsearchB 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 usedA 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, aB set of eight strings defining the variables and how they are toA be used to build a select list. The attribute can contain many? of these octuples. The strings in the string list are merelyB taken eight at a time. For each octuple of strings specified in? build_select_lists, the elements have the following meaning:


    
  1. ; the name of the template variable to be defined as a list
  2. 
  3. 8 the input parameter name that the select list will set
  4. 
  5. 7 the name of the user-defined attribute containing the9 name list, that is the list of values and labels8 for the select list items, much like the template_map,& method_name and sort_name attributes
  6. 
  7. 3 the tuple size used in the name list above
  8. 
  9. 0 the index into a name list tuple for the value
  10. 
  11. : the index for the corresponding label to be displayed on the selector
  12. 
  13. 9 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
  14. 
  15. : the default label, if not an empty string, which will be7 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
  16. 


; 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 existingA 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 avoid3 having to duplicate all the numbers in the list.



C 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@ 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.



? Here is an example of its usage, which illustrates different tuple sizes and orders:


Ibuild_select_lists:     MATCH_LIST matchesperpage matches_per_page_list \hJ                                1 1 1 matches_per_page "Previous Amount" \I                RESTRICT_LIST restrict restrict_names 2 1 2 restrict "" \1F                FORMAT_LIST format template_map 3 2 1 template_name "")matches_per_page_list:  1 5 10 20 100 500eDrestrict_names: "http://www.myschool.edu/Admin/" "Admin Web Pages" \H                "http://www.myschool.edu/Faculty/" "Faculty Web Pages" \H                "http://www.myschool.edu/Student/" "Student Web Pages" \#                "" "Whole Web Site"t	
n

I The FORMAT_LIST example should give something equivalent to the FORMAT J template variable, which is already set by htsearch. It is included asH an additional example of how to specify the tuple size and indices of values and labels in a tuple.

i

t# p: Combining the format select list with template_patterns



> The addition of the = template_patterns attribute has added a new wrinkle to>? the pre-defined select list for the format parameter.A? If a document URL matches an entry in template_patterns, itsl? corresponding result template will override any template thec= user selected with the format parameter. The problem stems,= from the fact that the two were not originally intended toa< 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.

n

; However, the following example would allow user-selectedt5 templates to work together with template_patterns: 


6template_map:      Long long ${common_dir}/long.html \7                   Short short ${common_dir}/short.htmlltemplate_name:     longTEtemplate_patterns: .pdf ${common_dir}/${template_name}-pdffile.html \ D                   .ps  ${common_dir}/${template_name}-psfile.html \C                   .doc ${common_dir}/${template_name}-docfile.htmlv	


: 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 expansione< in template_patterns takes place. As long as you stick to; a template file naming convention that uses the internalw? name element of template_map (second element in a triple) asr= 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,A short-pdffile.html, short-psfile.html, and short-docfile.html,i> for the example above to work, in addition to the long.html? and short.html files, which will be used for URLs that don'ts> match any of the patterns. Of course, these patterns can be? any URL parts, and not just suffixes. Be sure to also changeuB the values for format in your initial search form, search.html,% to use your chosen internal names. 

u
I Andrew Scherpbier <andrew@contigo.com>u
t+Last modified: $Date: 2000/02/15 22:08:36 $d r˙˙eter. This is accomplished by means of theB allow_in_form attribute.C The attributes listed in the allow_in_form list will be settable> in the search form using input para