Perl Form Builder ::Features ::Download ::Tutorial ::Examples
::Documentation ::FormBuilder Google Group ::Old List Archives ::Contribute
Note: The mailing list is has been replaced by the Google FormBuilder Group

Basic

1. Intro to FormBuilder
2. A Simple Form
3. Form Method
4. Input Validation
5. Field Options
6. Multi-Select Lists
7. Field Data
8. Field Attributes
9. HTML Formatting
10. Custom Headers
S. Summary

Intermediate

1. Trickier Forms
2. Perl References
3. Default Values
4. CGI Stickiness
5. JavaScript Actions
6. Input Validation 2
7. Multiple Submits
8. JavaScript Actions 2
9. Modules & mod_perl
10. Smartness
S. Summary

Advanced

1. Remaining Features
2. Intro to Templates
3. HTML::Template
4. HTML::Template 2
5. Template Toolkit
6. Exploiting render()
7. Multi-Screen Apps
8. Multi-Screen Apps 2
9. Multi-Screen Apps 3
10. Custom Messages
S. Summary

Basic Tutorial - Step 6: Multi-Select Lists Print

<< Field Options | Field Data >>

In the previous step, we saw how to create single-valued lists. That is, radio groups and standard select lists. Each of these allows the user to return a single value.

To allow a field to return multiple values, all you need to do is specify the multiple option to field():

$form->field(name     => 'favorite_colors',
             options  => \@colors,
             multiple => 1);
This would allow the favorite_colors field to return one or more of the items from the @colors array, which are presumably colors.

Now, what does this mean in terms of our HTML layout? Well, if there are only 4 or fewer colors, they'll be placed in a checkbox group, like so:

<input name="favorite_colors" type="checkbox" value="Red"> Red
<input name="favorite_colors" type="checkbox" value="Green"> Green
<input name="favorite_colors" type="checkbox" value="Blue"> Blue
Checkboxes will allow the user to see all the options, and choose the ones that they want. (The number 4 was actually picked in response to some user interface studies done on how many items people can remember.)

However, if there are more than 4 items, obviously checkboxes will become too cluttered, so FormBuilder automatically converts the field to a select list:

<select name="favorite_colors" multiple>
<option value="Red">Red</option>
<option value="Green">Green</option>
<option value="Blue">Blue</option>
<option value="Yellow">Yellow</option>
<option value="Orange">Orange</option>
<option value="Purple">Purple</option>
</select>
Again, all this magic can be overridden. To force a select list regardless of the number of options, all you have to do is explicitly specify the type:
$form->field(name     => 'favorite_colors',
             type     => 'select',
             options  => \@colors,
             multiple => 1);
In all situations, FormBuilder will automatically handle multiple stickiness correctly. If the person clicks multiple items and the form needs to be reloaded (as happens when validation fails), the correct items will remain selected.

Finally, since these fields can have multiple values, in order to get all the values accurately, you need to request an array from the field() function:

@favorites = $form->field('favorite_colors');
The array @favorites will contain all of the options that the user selected for that field.

<< Field Options | Field Data >>

FormBuilder is © Nate Wiger, with contributions from many people.
Nateware