The Input Widgets

Templating System : Widget Reference : Input

Overview

These widgets provide a variety of HTML controls, all of which are based on <input type="...">. In particular, the hidden, text, radio and checkbox widgets are currently implemented; their use is demonstrated in the acs-templating demo.

The Hidden Widget

This is simply an <input type=hidden> widget, which is used for passing pre-set variables along with the form.

The Text Widget

This widget allows the user to enter one line of text. It is completely identical to the <input type=text>. The -html parameter can be used to set its properties (such as size, maxlength, etc.), as described in the general widgets reference. The value of this widget is the text string.

The Radio Group Widget

This widget actually represents a group of radio buttons, at most one of which can be selected at any given time. The widget has one required parameter, -option option_list, which specifies the radio buttons to display. The option_list is a list of label-value pairs. For example, 

template::element create test_form cost \
 -label "Car Cost" -datatype number -widget radio \
 -options { {Cheap 1000} {Medium 50000} {Expensive 999999} }
will create a radio button group with 3 options: "Cheap", whose value is 1000, "Medium", whose value is 50000, and "Expensive", whose value is 999999. The value of the entire widget is either the empty string (if the user did not select any of the radio buttons), or a the value of the currently selected radio button. For instance, if the user selects "Medium" in the example above, the value of cost will be 50000.

The default form template renders the Radio Group widget as a column of radio buttons. Since the Radio Group can consist of many HTML controls, the usual formwidget tag cannot be used to position the widget; instead, the formgroup tag must be used.

The Checkbox Group Widget

This widget is identical in use to the Radio Group widget, but instead of radio buttons it generates a group of checkboxes, any number of which can be checked at any given time. The values (plural) property of the corresponding element contains a list of all the checked values; the value (singular) property contains the first element in the list.

templating@arsdigita.com