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)