ATG Page Developer’s Guide

Array Properties

To set the values in an array property, the user needs a control that allows selection of multiple values. When the user submits the form, the selected values are written to array elements.

A form can set values in an array property through a grouped set of checkboxes or a multiple-selection list box. Both controls are functionally equivalent, each possessing different layout advantages: a drop-down list typically requires less space because it uses scrollbars for long lists; while checkboxes make all choices visible.

Grouped Checkboxes

You can use a group of checkbox input tags to set an array of values. The following example creates a group of checkboxes that lists hobbies:

In this example, each checkbox is associated with the hobbies property, which is an array of Strings. When this page is displayed, any checkbox whose value attribute matches a value in the hobbies property appears as preselected. Each checkbox input tag can also set the checked attribute to true, in order to override current property settings.

Users can check or uncheck any combination of the checkboxes. On form submission, the values of all selected checkboxes are written to the array’s elements.

Given the previous example, if the array property hobbies has two elements set to climbing and fencing, the climbing and fencing checkboxes are initially checked, while the others are unchecked:

The user can change these selections—for example, deselect climbing and photography, and select swimming, biking, and fencing checkboxes:

Given these selections, on form submission the hobbies array property is set to three elements that contain the values swimming, biking, and fencing.

You can group checkboxes with the name attribute only if all tags in the group supply the same name setting. You can save a value to the array property if no checkboxes are selected by setting the default attribute to true for one checkbox in the group. Only one checkbox tag in the group can set its default attribute to true; all other checkbox tags must set their default attribute to false.

Multiple-Selection List Box

dsp:select creates a multiple-selection list box if its multiple attribute is set:

In this example, each option is associated with the hobbies property, which is an array of Strings. When this page is displayed, any option whose value attribute matches a value in the hobbies array is initially selected. You can override these initial selections and determine which options to select on initial display by qualifying each dsp:option tag with the selected attribute, set to true

The user can select any combination of options. On form submission, the values of all selected options are used to set the new elements of the array.

For example, the hobbies array property might have two elements, climbing and fencing; in that case, the climbing and fencing options are shown as selected when the form displays. If the user selects the swimming, biking, and fencing, on form submission the hobbies property is set to an array of three elements with those values.