quisp: select option lists

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 `null`s 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 `null`s to appear in labels. When this occurs, and when the retrieval won't generally produce a `NULL` option list value, you can hide these `null`s 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.