#set TITLE = "select option lists"
#include top

.SH SELECT option lists
The HTML forms \fCSELECT\fR tag creates picklists that allow a user to select
one or sometimes multiple choices.  The list of choices is called an "option list",
and for each choice contains a short tag, a longer descriptive label, and an indication
that the option is selected or not.
QUISP supports dynamic building of option lists through the \fC#optionlist\fR
directive.  
.LP
\fC#optionlist\fR is especially convenient in representing option lists with one or more
options shown as already selected, based on a variable or database retrieval.  Several 
#set FILE = "#examples"
#set TAG = "examples"
#include link
are provided below; see also the
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index"
#set TAG = "live demo on sourceforge."
#include link

#include space

.SH #optionlist
Build a \fC<select>\fR option list, either single or multiple choice.
\fC#optionlist\fR should be used just after the opening \fC<SELECT>\fR tag.
It usually involves multiple lines, and
then terminates with the closing \fC</SELECT>\fR tag.
.LP
Usage:
.nf
  \0 <select name=whatever size=whatever ... >
  \0 #optionlist  [selected=\fIlist\fR] [options=\fIlist\fR]  \fIother parameters\fR
  \0 #options
  \0   \fIvalue1     label words 1\fR
  \0   \fIvalue2     label words 2\fR
  \0 </select>
.fi
.LP
\fBThe main things that must be supplied\fR are the \fBoptions\fR, and which options should be shown as \fBselected\fR. 
.LP
\fBOptions\fR may be specified one per line, after an \fC#options\fR marker.  Within each line
the first whitespace-delimited token is taken as the value (values cannot have embedded whitespace).  
The second token and everything following on the
line are taken as the label.
This set of options can be filled dynamically using other directives, such as
#set FILE = "sql.html"
#set TAG = "#sql dumptab"
#include link
(see examples 4, 5) as well as \fC#if\fR, etc.
.LP
When values and labels are exactly the same, it may be more convenient to list the options as seen in example 3 below.
.LP
\fBSelected\fR options are those that will be displayed as "turned on".
May be a single value or a
#set FILE = "commalist.html"
#set TAG = "comma-delimited list"
#include link
of values.
Usually specified on the #optionlist line as seen in examples 1-4 below.
.LP
Occasionally it may be useful to specify selected items using a one line per selection format.
This involves a \fC#selected\fR marker (see example 5 below).
.LP
If \fCselected=..\fR  and \fCoptions=..\fR are both given on the \fC#optionlist\fR line, \fCselected=\fR
must appear to the left of \fCoptions=..\fR.  If \fC#selected\fR and \fC#options\fR are both used, \fC#selected\fR
must appear above the \fC#options\fR lines.

.LP
\fBOther parameters:\fR

// .LP
// \fBmaxlen=\fIn\fR may be specified to limit the length of a label to \fIn\fR characters, 
// sometimes handy when the the option list is being filled dynamically.
.LP
\fBalways_selected\fR   If no selections are specified, the topmost 
option is shown as selected by default.  This provides a default and avoids the 
stupidity of requiring a user to select a choice when a dynamically filled option list 
has only one choice shown.
.LP
\fBdisplay_only\fR If specified, the overall result is not an option list at all, 
but a simple HTML displayable list of selected choices.  If this is done, 
\fC#optionlist\fR should not be within a \fC<SELECT> </SELECT>\fR.  End is marked by 
special operator \fC#endlist\fR.
.LP
\fBhidenulls\fR  Convert any \fCnull\fRs retrieved via an SQL retrieval to \fC""\fR.
See the next section for more info.

#include space
.SH NULL values
The special symbol \fCNULL\fR is used to represent a blank option.
It is taken as equivalent to \fC""\fR.
For example: \fC #optionlist selected=@suffix options=null,Jr,III\fR
.LP
Option lists are often filled using SQL database retrievals.  
Because it is possible to retrieve \fCNULL\fR as an option list value,
the normal QUISP policy of converting \fCNULL\fR to \fC""\fR is suspended
while building an option list, to ensure that a value is always present.  
However this sometimes causes undesired \fCnull\fRs to appear in labels.  
When this occurs, and when the retrieval won't generally produce a \fCNULL\fR option 
list value, you can hide these \fCnull\fRs using the \fChidenulls\fR argument.


#include space
.SH Capturing SELECT MULTIPLE responses in the target page
When a \fCSELECT MULTIPLE\fR form field is captured by the
#set FILE = "forms.html"
#set TAG = "target page"
#include link
you can convert it a 
#set FILE = "commalist.html"
#set TAG = "comma-delimited list"
#include link
using 
#set FILE = "cgivar.html"
#set TAG = "#cgilistvar"
#include link
directive, or left as a vector using
#set FILE = "cgivar.html"
#set TAG = "#cgimultivar."
#include link
Generally the former is more convenient, but is 
limited by the maximum allowable length of a list (255 characters).


#include space
.ig >>
<a name=examples></a>
.>>

.SH Examples
In \fC./qexamples\fR are a number of examples that do various things, see the README file there.
All of the following examples are assumed to be within an HTML \fC<FORM>\fR:


.LP
\fBExample 1. Simple demo.
Choice 'B' (3 or 4) will show up as selected.\fR
.nf
  \0 #set question1 = "B"
  \0 How many Alan Parsons Project albums do you own?
  \0 <select name=question1 size=1 >
  \0 #optionlist selected=@@question1
  \0   #options
  \0     0	none
  \0	 A	1 or 2
  \0	 B	3 or 4
  \0	 C	more than 4
  \0 </select>
.fi

.LP
\fBExample 2. A multiple choice box initialized by a comma-delimited list.\fR
.nf
 \0 #set affil = "AU,RV"
 \0 Type of affiliation:
 \0 <select name=affil size=5 multiple>
 \0 #optionlist selected=@@affil
 \0   #options
 \0     AU	Author
 \0	RV	Reviewer
 \0	DC	Data contributor
 \0	ST	Staff
 \0  </select>
.fi

.LP
\fBExample 3. Option label and value the same (short).\fR
.nf
 \0 <select name=list_size size=1>
 \0 #optionlist selected=@@list_size options=10,20,50,100
 \0 </select>
.fi

.LP
\fBExample 4. Option list filled by an SQL retrieval.\fR
.nf 
 \0 <select name=request_type size=1>
 \0 #optionlist selected=@@request_type  maxlen=80
 \0   #options
 \0   #sql dumptab select * from request_options order by option_name
 \0 </select>
.fi

.LP
\fBExample 5. Both options and selected filled by SQL retrievals.\fR
.nf
 \0 #set USERID = 92
 \0 <select name=ingredients size=10 multiple>
 \0 #optionlist  always_selected
 \0   #options
 \0     #sql dumptab select * from ingred_list
 \0   #selected
 \0     #sql dumptab 
 \0       select ingred_name 
 \0       from user_selections
 \0       where userid = @@USERID
 \0     #endsql
 \0 </selected>
.fi

#include bottom
