quick server pages
   
Manual page for select(option)

SELECT option lists

The HTML forms SELECT 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 #optionlist directive.

#optionlist is especially convenient in representing option lists with one or more options shown as already selected, based on a variable or database retrieval. Several examples are provided below; see also the live demo on sourceforge.


#optionlist

Build a <select> option list, either single or multiple choice. #optionlist should be used just after the opening <SELECT> tag. It usually involves multiple lines, and then terminates with the closing </SELECT> tag.

Usage:

    <select name=whatever size=whatever ... >
    #optionlist  [selected=list] [options=list]  other parameters
    #options
      value1     label words 1
      value2     label words 2
    </select>

The main things that must be supplied are the options, and which options should be shown as selected.

Options may be specified one per line, after an #options 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 #sql dumptab (see examples 4, 5) as well as #if, etc.

When values and labels are exactly the same, it may be more convenient to list the options as seen in example 3 below.

Selected options are those that will be displayed as "turned on". May be a single value or a comma-delimited list of values. Usually specified on the #optionlist line as seen in examples 1-4 below.

Occasionally it may be useful to specify selected items using a one line per selection format. This involves a #selected marker (see example 5 below).

If selected=.. and options=.. are both given on the #optionlist line, selected= must appear to the left of options=... If #selected and #options are both used, #selected must appear above the #options lines.

Other parameters:

always_selected 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.

display_only 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, #optionlist should not be within a <SELECT> </SELECT>. End is marked by special operator #endlist.

hidenulls Convert any nulls retrieved via an SQL retrieval to "". See the next section for more info.


NULL values

The special symbol NULL is used to represent a blank option. It is taken as equivalent to "". For example: #optionlist selected=@suffix options=null,Jr,III

Option lists are often filled using SQL database retrievals. Because it is possible to retrieve NULL as an option list value, the normal QUISP policy of converting NULL to "" is suspended while building an option list, to ensure that a value is always present. However this sometimes causes undesired nulls to appear in labels. When this occurs, and when the retrieval won't generally produce a NULL option list value, you can hide these nulls using the hidenulls argument.


Capturing SELECT MULTIPLE responses in the target page

When a SELECT MULTIPLE form field is captured by the target page you can convert it a comma-delimited list using #cgilistvar directive, or left as a vector using #cgimultivar. Generally the former is more convenient, but is limited by the maximum allowable length of a list (255 characters).


Examples

In ./qexamples 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 <FORM>:

Example 1. Simple demo. Choice 'B' (3 or 4) will show up as selected.

    #set question1 = "B"
    How many Alan Parsons Project albums do you own?
    <select name=question1 size=1 >
    #optionlist selected=@question1
      #options
        0	none
   	 A	1 or 2
   	 B	3 or 4
   	 C	more than 4
    </select>

Example 2. A multiple choice box initialized by a comma-delimited list.

   #set affil = "AU,RV"
   Type of affiliation:
   <select name=affil size=5 multiple>
   #optionlist selected=@affil
     #options
       AU	Author
  	RV	Reviewer
  	DC	Data contributor
  	ST	Staff
    </select>

Example 3. Option label and value the same (short).

   <select name=list_size size=1>
   #optionlist selected=@list_size options=10,20,50,100
   </select>

Example 4. Option list filled by an SQL retrieval.

   <select name=request_type size=1>
   #optionlist selected=@request_type  maxlen=80
     #options
     #sql dumptab select * from request_options order by option_name
   </select>

Example 5. Both options and selected filled by SQL retrievals.

   #set USERID = 92
   <select name=ingredients size=10 multiple>
   #optionlist  always_selected
     #options
       #sql dumptab select * from ingred_list
     #selected
       #sql dumptab 
         select ingred_name 
         from user_selections
         where userid = @USERID
       #endsql
   </selected>



quick server pages    
Copyright Steve Grubb    


Markup created by unroff 1.0,    November 04, 2004.