j  � ht://Dig: htsearch� � 0  

htsearch



W ht://Dig Copyright © 1995-2002 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,: optionally followed by a comma and the type of list, and optional formatting codes
  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 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,A is the type of select list or input list to be created in this: template variable. Choices are select,5 multiple, radio,8 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 choicesB radio and checkbox will buildC lists of <input> tags of these types, rather than a select? list with <option> tags. The optional third and fourthA items in this comma separated list are text or formatting tagsB 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 ofc@ 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 thes? 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.e

>

C Any of the strings in an octuple may be quoted, and should be ifl@ 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 iteme? if the current input parameter value doesn't match any values? 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.

o

? If the seventh element, the configuration attribute name, ise= 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 mappedi> 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.s

e

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

d
Obuild_select_lists:     MATCH_LIST,radio matchesperpage matches_per_page_list \lJ                                1 1 1 matches_per_page "Previous Amount" \R                RESTRICT_LIST,multiple restrict restrict_names 2 1 2 restrict "" \F                FORMAT_LIST format template_map 3 2 1 template_name "")matches_per_page_list:  1 5 10 20 100 500hDrestrict_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"o	
u

I The FORMAT_LIST example should give something equivalent to the FORMATeJ 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.

C

C 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 ""	
e

= In this example, the font tag will be inserted before eachaC checkbox input tag, and the closing font tag and line break willsC be appended after each label that follows the input tag. Because"A the font tag has an embeded comma, which is also the separatoraC for the list in the first element, the whole tag (i.e. the wholee> third item in the comma separated list) is quoted, and it'sB quoted with single quotes so as not to conflict with the doubleA quotes enclosing the whole element. Finally, to embed a doublemC quote in the font tag, it must be escaped with two backslashes - A 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.a

o

b# t: Combining the format select list with template_patterns



> The addition of the = template_patterns attribute has added a new wrinkle toe? the pre-defined select list for the format parameter.i? If a document URL matches an entry in template_patterns, itst? corresponding result template will override any template theo= user selected with the format parameter. The problem stemsi= from the fact that the two were not originally intended tof< 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<5 templates to work together with template_patterns:t


6template_map:      Long long ${common_dir}/long.html \7                   Short short ${common_dir}/short.htmlhtemplate_name:     longtEtemplate_patterns: .pdf ${common_dir}/${template_name}-pdffile.html \tD                   .ps  ${common_dir}/${template_name}-psfile.html \C                   .doc ${common_dir}/${template_name}-docfile.htmle	
l

: 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 expansionh< in template_patterns takes place. As long as you stick to; a template file naming convention that uses the internale? name element of template_map (second element in a triple) asp= 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,f> 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 changemB the values for format in your initial search form, search.html,% to use your chosen internal names./


+Last modified: $Date: 2002/01/27 05:33:20 $ reÿÿ 
  • : the index for the corresponding label to be displayed on the selector
  • 
  • 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
  • 
  • : the default label,