NAME

       HTMLDocument::addSelectElement - Adds a selection box

SYNOPSIS

       ElementTree  addSelectElement(  ElementTree  block,  String name, Int ssize, [Pair<String,
       [SelectOption]> ] optgroups )

ARGUMENTS

       parent The parent element

       name The name of the input. Remember that names starting with "kaya_" may be used  by  the
       Kaya standard library and should not be used directly by applications.

       ssize  The size of the select element. If this is zero, the select element will only allow
       one option to be selected at any one time. If this is one or more, the select element will
       allow  multiple  options to be selected, and suggest to the browser that this many options
       be displayed simultaneously.

       optgroups The options to select from

DESCRIPTION

       Adds a selection box to a form. The optgroups parameter is a  list  of  pairs.  The  first
       element  of  the  pair  is the 'heading' for the option group, and the second element is a
       list of options in that group. For most simple selectors, a single option  group  with  no
       heading (the empty string) is sufficient.

    options = [
        SelectOption("Express delivery","1",true),
        SelectOption("Standard delivery","2",false),
        SelectOption("Slow delivery","3",false)
    ];
    sel = addSelectElement(fieldset,"choice",0,[("",options)]);
    /* // produces
    <select>
      <option value='1' selected='selected'>Express delivery</option>
      <option value='2'>Standard delivery</option>
      <option value='3'>Slow delivery</option>
    </select>
    */

       Using  multiple  groups of options is useful for larger select elements, where it can make
       the form clearer.

    singles = ["A1","A2","B5"];
    twins = ["A4","C2"];
    doubles = ["A7","C1","C3"];
    sopts = [];
    topts = [];
    dopts = [];
    for s in singles {
        push(sopts,SelectOption(s,s,false);
    }
    for t in twins {
        push(topts,SelectOption(s,s,false);
    }
    for d in doubles {
        push(dopts,SelectOption(s,s,false);
    }
    options = [
        ("Single rooms",sopts),
        ("Twin rooms",topts),
        ("Double rooms",dopts)
    ];
    sel = addSelectElement(roombooker,"room",0,options);

       Select elements allowing multiple options to be selected have very bad usability  in  most
       browsers  - it is often better to use HTMLDocument.addOptionList (3kaya) to generate a set
       of checkboxes instead. Whichever method you use for multiple selection, remember that  you
       need  to  use WebCommon.incomingData (3kaya) to correctly retrieve the selections from the
       user's form submission.

AUTHORS

       Kaya standard library by Edwin Brady, Chris Morris  and  others  (kaya@kayalang.org).  For
       further information see http://kayalang.org/

LICENSE

       The Kaya standard library is free software; you can redistribute it and/or modify it under
       the terms of the GNU Lesser General Public License (version 2.1 or any later  version)  as
       published by the Free Software Foundation.

RELATED

       HTMLDocument.SelectOption (3kaya)
       HTMLDocument.addFieldset (3kaya)
       HTMLDocument.addLabelledSelect (3kaya)
       HTMLDocument.addLazySelect (3kaya)
       HTMLDocument.addOptionList (3kaya)
       HTMLDocument.addTextarea (3kaya)
       HTMLDocument.addTextInput (3kaya)