The Input Widgets

Templating System : Widget Reference : Select

Overview

These widgets provide the single-selection and multiple-selection HTML controls; their usage is demonstrated in the acs-templating demo.

The Select Widget

This widget creates a list of choices, only one of which may be selected at any given time, using the HTML <select> control. Similarly to the button group widgets, the Select widget has one required parameter, -option option_list, which specifies all the possible choices. The option_list is a list of label-value pairs. For example,

template::element create pizza_form topping \
 -label "Pizza Topping" -datatype keyword -widget select \
 -options { 
    {Pepperoni pepperoni} 
    {Sausage sausage} 
    {{Canadian Bacon} cbacon} 
  }

will create a widget with 3 choices: "Pepperoni", "Sausage" and "Canadian Bacon". By default, the widget looks like a drop-down "picklist", however, it can be forced to look like a scrollable vertical list of n elements by using the -html { size n } parameter.

The value of the Select widget is the value of the currently selected choice. If no choice is selected, the value will be the empty string. However, if the widget happens to look like a picklist, most Web browsers automatically select the first option on the list. This behavior may be changed by supplying an extra "null" option. For example, the options for the pizza topic selection widget shown above could be changed to

template::element create pizza_form topping \
 -label "Pizza Topping" -datatype keyword -widget select \
 -options { 
    {{No Topping} {}}
    {Pepperoni pepperoni} 
    {Sausage sausage} 
    {{Canadian Bacon} cbacon} 
  }

The Multiselect Widget

This widget is similar to the Select widget, but it allows multiple values to be selected. Because of this, the Multiselect widget cannot look like a picklist. By default, the widget looks like a scrollable list of items, which grows up to 8 items in size (in other words, up to 8 items will be shown without the need to scroll). This size can be overwritten with the -html { size n } parameter.

The values (plural) property of the corresponding element contains a list of all the selected choices; the value (singular) property contains the first selected choice.

---