Fill-out Forms

Although the CGI module is handy for the HTML shortcuts it provides, its true strengths can best be seen in producing and processing fill-out forms. Fill-out forms work by presenting the user checkboxes, radio buttons, text fields and pop-up menus. Each object which can accept input must be given a name, and the param method of the CGI module can be used to retrieve them after the user hits the submit button in their web browser. When called with no arguments, the param method returns an array containing the names of all the form elements which have been defined; when called with one of these names, it returns the value of that element. In order to accommodate elements with more than one value (say the results of a checkbox group, or a scrolling list allowing multiple choices), the param method ``looks'' at its target and returns a single parameter value when called in scalar context, and an array when called in array context. (If you'd like to implement that functionality in your own programs, read the perl documentation for the wantarray function.)

The convenience methods provided by the CGI module to generate the necessary HTML to display the fill-out form elements all take many arguments, and there are a variety of ways to use them. One convenient technique involves calling the methods in the module with the arguments in the form ``-name => value''. Note the greater than sign (>) after the equals sign; if you omit it you'll get an error message stating:

     Can't modify constant item in scalar assignment

While you can sometimes eliminate the hyphen (-) preceding the parameter's name, it's usually a good idea to include it.

To begin a form, invoke the start_form method with the action argument. This argument provides the fully-qualified URL of the CGI script which is going to process the information from the fill-out form. As explained in Section , this URL will often be the same as the URL of the script which is generating the form. Like all of the html helper functions, you must print the returned value of the method in order for the web browser to actually see it:

print $q->start_form('http://wherever.com/cgi-bin/doit.cgi');

There is no standard suffix for perl CGI scripts; common choices are .pl or .cgi.

Since some of the CGI methods accept many arguments, any arrays or hashes which are passed to the method need to be passed with references (Section ). While the usual technique of placing a backslash before the name of an existing array or hash is perfectly acceptable, many perl programmers use what are known as anonymous arrays and hashes in place of an explicit named array or hash reference. Anonymous arrays or hashes can be used anywhere a reference to the corresponding object could be used. They often produce more readable code, and don't clutter the namespace with unneccessary names.

To create an anonymous array, separate the array values with commas, and enclose the sequence in square brackets. In some sense, this notation is not unreasonable, because square brackets are used to delimit the subscripts of arrays. Anonymous hashes, then, are produced by surrounding an alternating sequence of keys and values, separated by commas, with curly brackets. As with the anonymous array, the curly brackets are also used to delimit the subscripts of hashes. Alternatively, you can use the arrow operator (=>) to separate key/value pairs as shown in Section 6.2. Thus, a series of values separated by commas and surrounded by parentheses is a literal array, while if the series is surrounded by square brackets, it's an anonymous array, and if it's surrounded by curly braces, it's an anonymous hash.

For example, the popup_menu method produces a pop-up menu displaying a list of values, one of which the user will select. These values are provided to the method through an array reference (or an anonymous array) passed to the method as the named argument values. The selected choice will be returned through a CGI variable whose name is provided with the name argument to the method. The names of your CGI variables have nothing to do with the names of perl variables in your CGI script -- the CGI names are identifiers which allow you to retrieve values using the param method. To provide labels on the menu, a hash reference (or an anonymous hash) can be passed through the optional labels argument. This hash should contain the menu's values as its keys, with the values of the hash being the labels which should appear in the menu. Finally, the optional default argument allows you to pass the name of one of the menu's values which will be highlighted when the menu is opened. Without this argument, the first level is highlighted. So a call to the method might look like:

$q->popup_menu(-name=>'flavor',-values=>['Cchip','Straw','RumR','Van'],
  -labels=>{Straw=>'Strawberry',Cchip=>'Chocolate Chip',
  RumR=>'Rum Raisin',Van=>'Vanilla'});

Among other similar methods for CGI objects are checkbox_group, radio_group and scrolling_list. Each one takes arguments name, values, labels and default with the same meanings as for popup_menu.

The CGI module provides three methods for text input, namely textfield, textarea, and password_field. Each accepts arguments named name and default; textfield accepts arguments size and maxlength, providing the number of characters that will be visible in the field, and the maximum number of characters the user can type in the field, respectively, while textarea accepts arguments rows and columns to provide the size of the text area the user will see. password_field is identical to textfield, but its input will not be echoed to the field, but rather replaced by asterisks.

You can pass parameters back to your script through the hidden method. This method requires a name, through which the hidden values can be retrieved by the param method, and which is passed through the name argument. It also requires a default argument, which provides either a scalar value for the parameter or a reference to an array if the hidden parameter is multi-valued.

Finally, HTML text to produce a submit button, essential for any form, can be created with the submit method. This method accepts two parameters, namely name and value, both of which are optional. The name argument can be used to distinguish between different submit buttons, and will serve as a label for the button, unless a value argument is provided, in which case that argument will be used to label the button. The defaults method can be used to create text for a button that, when invoked, sets all form elements to their default value, while the reset method creates text for a button whose invocation will cause all form elements to be reset to the values they had the last time the CGI script was executed.