ht://Dig Copyright © 1995-2004 The ht://Dig Group
Please see the file COPYING for
license information.
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.
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 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 an input parameter. This is accomplished by means of the allow_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.
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 build_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 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 existing 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.
The addition of the 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.