diff options
Diffstat (limited to 'debian/htdig/htdig-3.2.0b6/htdoc/hts_selectors.html')
| -rw-r--r-- | debian/htdig/htdig-3.2.0b6/htdoc/hts_selectors.html | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/debian/htdig/htdig-3.2.0b6/htdoc/hts_selectors.html b/debian/htdig/htdig-3.2.0b6/htdoc/hts_selectors.html new file mode 100644 index 00000000..e05037f9 --- /dev/null +++ b/debian/htdig/htdig-3.2.0b6/htdoc/hts_selectors.html @@ -0,0 +1,324 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> +<html> + <head> + <title> + ht://Dig: htsearch + </title> + </head> + <body bgcolor="#eef7ff"> + <h1> + htsearch + </h1> + <p> + ht://Dig Copyright © 1995-2004 <a href="THANKS.html">The ht://Dig Group</a><br> + Please see the file <a href="COPYING">COPYING</a> for + license information. + </p> + <hr size="4" noshade> + <h2> + Input parameter select lists + </h2> + <p> + The primary interface to htsearch is through an HTML + <a href="hts_form.html">form</a>. + The input fields in this form can be defined as any type that + HTML allows, but some of these are best handled through HTML + <em>select</em> lists. + </p> + <h3> + <a name="predefined"></a> + Pre-defined template select lists + </h3> + <p> + In order to propagate these select lists to the search form + in the results template, so that the default <em>selected</em> + value will be the one the user last selected, htsearch defines + a few of these select lists as + <a href="hts_templates.html">template variables</a>. + These variables are: + </p> + <ul> + <li> + <strong>FORMAT</strong>, which selects the <b>format</b> input parameter + for follow-up searches, with the current value being the + default. The current value is taken from the <strong>format</strong> + input parameter, if one was provided, or from the + <a href="attrs.html#template_name">template_name</a> + attribute otherwise, and this value will also be given in + the <strong>SELECTED_FORMAT</strong> template variable. + The various parameter values, and their corresponding + labels for the select list, are taken from the + <a href="attrs.html#template_map">template_map</a> + attribute. + </li> + <li> + <strong>METHOD</strong>, which selects the <b>method</b> input parameter + for follow-up searches, with the current value being the + default. The current value is taken from the <strong>method</strong> + input parameter, if one was provided, or from the + <a href="attrs.html#match_method">match_method</a> + attribute otherwise, and this value will also be given in + the <strong>SELECTED_METHOD</strong> template variable. + The various parameter values, and their corresponding + labels for the select list, are taken from the + <a href="attrs.html#method_names">method_names</a> + attribute. + </li> + <li> + <strong>SORT</strong>, which selects the <b>sort</b> input parameter + for follow-up searches, with the current value being the + default. The current value is taken from the <strong>sort</strong> + input parameter, if one was provided, or from the + <a href="attrs.html#sort">sort</a> + attribute otherwise, and this value will also be given in + the <strong>SELECTED_SORT</strong> template variable. + The various parameter values, and their corresponding + labels for the select list, are taken from the + <a href="attrs.html#sort_names">sort_names</a> + attribute. + </li> + </ul> + <p> + 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 <a href="attrs.html">configuration + attribute</a> that's not already automatically handled by an + input parameter. This is accomplished by means of the + <a href="attrs.html#allow_in_form">allow_in_form</a> 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. + </p> + <h3> + <a name="custom"></a> + Custom template select lists + </h3> + <p> + 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. + </p> + <p> + To overcome this drawback, you must use the + <a href="attrs.html#build_select_lists">build_select_lists</a> + 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. + </p> + <p> + The entries in this list each consist of an <em>octuple</em>, 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: + </p> + <ol> + <li> + 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 + </li> + <li> + the input parameter name that the select list will set + </li> + <li> + the name of the user-defined attribute containing the + <em>name list</em>, that is the list of values and labels + for the select list items, much like the template_map, + method_name and sort_name attributes + </li> + <li> + the <em>tuple</em> size used in the name list above + </li> + <li> + the index into a name list tuple for the value + </li> + <li> + the index for the corresponding label to be displayed on + the selector + </li> + <li> + 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 + </li> + <li> + 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 + </li> + </ol> + <p> + 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 <strong>select</strong>, + <strong>multiple</strong>, <strong>radio</strong>, + and <strong>checkbox</strong>, with the default being + <strong>select</strong>. The word <strong>multiple</strong> + refers to a <select multiple> type of select list, + where more than one option can be selected. The choices + <strong>radio</strong> and <strong>checkbox</strong> 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. + </p> + <p> + 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 <a href="attrs.html">existing + attributes</a>. 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. + </p> + <p> + 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 <em>selected</em> 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. + </p> + <p> + 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. + </p> + <p> + Here is an example of its usage, which illustrates different + tuple sizes and orders: + </p> + <pre> +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" + </pre> + <p> + 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. + </p> + <p> + Here is an example which illustrates additional formatting tags, + and the quoting that may be required: + </p> + <pre> +build_select_lists: "RESTRICT_LIST,checkbox,'<font face=\\"Arial,Helvetica\\" size=\\"+2\\">',</font><br>" \ + restrict restrict_names 2 1 2 restrict "" + </pre> + <p> + 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. + </p> + <h3> + <a name="template_patterns"></a> + Combining the format select list with template_patterns + </h3> + <p> + The addition of the <a href="attrs.html#template_patterns"> + template_patterns</a> attribute has added a new wrinkle to + the pre-defined select list for the <strong>format</strong> 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. + </p> + <p> + However, the following example would allow user-selected + templates to work together with template_patterns: + </p> + <pre> +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 + </pre> + <p> + This works because the template_name attribute gets set + internally in htsearch, to the user-selected value of the + <strong>format</strong> 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. + </p> + + <hr size="4" noshade> + + Last modified: $Date: 2004/05/28 13:15:18 $ + + </body> +</html> |