You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
325 lines
14 KiB
325 lines
14 KiB
3 years ago
|
<!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>
|