<!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>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
8dd3144bd884120842950371516fa49e
>
files
>
185
