Installing CGI.pm

To use this package, install it in your Perl library path. On most systems, this will be /usr/local/lib/perl5, but check with your System Administrator to be sure. Then place the following statement at the top of your Perl CGI scripts: Use CGI;

If you do not have sufficient privileges to install into /usr/local/lib/perl5, you still can use CGI.pm. Place it in a convenient place-for example, in /usr/local/etc/httpd/cgi-bin-and preface your CGI scripts with a preamble something like this: BEGIN { push(@Inc,'/usr/local/etc/httpd/cgi-bin'); } Use CGI;

Be sure to replace /usr/local/etc/httpd/cgi-bin with the location of CGI.pm on your server.

Reading Input Data

You can use two methods in the CGI.pm library to read data passed to your CGI program:

• $query = new CGI;
  This method parses the input (from both Post and Get methods) and stores it in a Perl 5 object called $query.
• $query = new CGI(FILEHANDLE);
  This method enables you to read the contents of the form from a previously opened filehandle.
  The filehandle can contain a URL-encoded query string, or it can be a series of newline delimited tag=value pairs. This method is compatible with the save() method, which enables you to save the state of a form to a file and reload it later.

Saving Your Incoming Data

Your incoming data should be saved to an object such as the $query object. The following methods are available for decoding and modifying the object data; these methods assume that you have named that object $query.

Getting a List of Keywords from the Query Object

If your CGI program was invoked as the result of an Isindex search, the parsed keywords of the Isindex input search string can be obtained with the keywords() method. This method returns the keywords as a Perl array. Use this code: @keywords = $query->keywords

Getting the Names of All Parameters Passed to Your Script

If your CGI program was invoked with a parameter list such as name1=value1&name2=value2&name3=value3"

the param() method returns the parameter names as a list. For backward compatibility, this method works even if the script was invoked as an Isindex script; in this case, a single parameter name is returned named 'keywords'. Use this code: @names = $query->param

Getting the Value(s) of a Named Parameter

You pass the param('NAME') method a single argument to fetch the value of the named parameter. If the parameter is multivalued (from multiple selections in a scrolling list, for example), you can ask to receive an array. Otherwise, the method returns a single value. Use this code: @values = $query->param('foo');

or $value = $query->param('foo');

As of version 1.50 of this library, the array of parameter names returned is in the same order in which the browser sent them. Although this is not guaranteed to be identical to the order in which the parameters were defined in the fill-out form, this is usually the case.

Setting the Value(s) of a Named Parameter

The method param('NAME' 'NEW-VALUES')

sets the value for the named parameter 'foo' to one or more values. These values are used to initialize form elements, if you so desire. Note that this is the correct way to change the value of a form field from its current setting. Use this code: $query->param('foo','an','array','of','values');

Deleting a Named Parameter

The method delete('NAME')

deletes a named parameter entirely. This is useful when you want to reset the value of the parameter so that it isn't passed down between invocations of the script. Use this code: $query->delete('foo');

Importing Parameters into a Namespace

The method import_names('NAME_SPACE')

imports all parameters into the given namespace. If there were parameters named 'foo1', 'foo2', and 'foo3', for example, after executing $query->import('R'), the variables @R::foo1, $R::foo1, @R::foo2, $R::foo2, and so on would conveniently spring into existence. Because CGI has no way of knowing whether you expect a multi- or single-valued parameter, it creates two variables for each parameter. One variable is an array and contains all the values, and the other is a scalar containing the first member of the array. Use whichever variable is appropriate. For keyword (a+b+c+d) lists, the variable @R::keywords is created. Use this code: $query->import_names('R')

If you don't specify a namespace, this method assumes namespace "Q". Use this code: $query->import_names('R'); print "Your name is $R::name\n" print "Your favorite colors are @R::colors\n";

Saving the Current State of a Form

As you have seen throughout this guide, saving the state of your CGI program is one of the harder things to do in the CGI environment. The CGI.pm library addresses that need with the following two methods. These two methods enable you to save object state information so that you can use it the next time your CGI program is called.

Saving the State to a File

The method save(FILEHANDLE)

writes the current query object out to the filehandle of your choice. The filehandle already must be open and writable but, other than that, it can point to a file, a socket, a pipe, or whatever. The contents of the form are written out as tag=value pairs, which can be reloaded with the new() method later. Use this code: $query->save(FILEHANDLE)

Saving the State in a Self-Referencing URL

The method self_url()

returns a URL that, when selected, reinvokes your CGI program with all its state information intact. This is most useful when you want to jump around within a script-generated document using internal anchors but don't want to disrupt the current contents of the form(s). Use this code: $my_url=$query->self_url;

Creating the HTTP Headers

Every CGI program needs to print the correct HTTP headers. The following methods perform this task for you with a minimum amount of programming effort.

Creating the Standard Header for a Virtual Document

The header('CONTENT-TYPE/SUBTYPE') method prints the required HTTP content-type header and the requisite blank line below it. If no parameter is specified, it defaults to 'text/html'. Use this code: print $query->header('image/gif');

An extended form of this method enables you to specify a status code and a message to pass back to the browser. Use this code: print $query->header('text/html',204,'No response');

This method presents the browser with a status code of 204 (no response). Properly behaved browsers will take no action and simply remain on the current page. (This is appropriate for a script that does some processing but doesn't need to display any results, or for a script called after a user clicks on an empty part of a clickable imagemap.)

Creating the Header for a Redirection Request

The method redirect('Absolute-URI')

generates a redirection request for the remote browser. It immediately goes to the indicated URI. Your CGI program should exit soon after this. Nothing else is displayed. Use this code: print $query->redirect('http://somewhere.else/in/the/world');

Creating an HTML Header

The method start_html('TITLE', 'EMAIL-ADDRESS', 'BASE-TAG','ATTRIBUTE-LIST')

generates the header tags for your HTML page. The input parameters are the title, your e-mail address, the Base tag, and an arbitrary list of attributes, such as the background color or keywords. The method returns a canned HTML header and the opening Body tag. Use this code: print $query->start_html('Secrets of the Pyramids', 'fred@capricorn.org', 'true', 'BGCOLOR="#00A0A0"')

Table 8.1 explains the parameters of the start_html method; these are optional.

Ending an HTML Document

The end_html method ends an HTML document by printing the </BODY></HTML> tags. Use this code: print $query->end_html

Creating Forms

The CGI.pm library provides a full set of methods for creating Web fill-out forms. The various form-creating methods all return strings to the caller. These strings contain the HTML code that creates the requested form element. You are responsible for actually printing these strings. It's set up this way so that you can place formatting tags around the form elements.

The default values that you specify for the forms are used only the first time the script is invoked. If values already are present in the query string, they are used, even if blank. If you want to change the value of a field from its previous value, call the param() method to set it.

To reset the fields to their defaults, you can do this:

• Create a special <VAR>defaults</VAR> button using the defaults() method.
• Create a hypertext link that calls your script without any parameters.

The optional values of the Web fill-out form methods depend on their positions in the parameter list. You cannot leave out value two of a four-value parameter list and include values three and four, for example. If you want to include any value in a parameter list that is to the right of another optional parameter, you must include the earlier parameter, even if you want the default value from the earlier parameter.

You can put multiple forms on the same page if you want. Be warned that it isn't always easy to preserve state information for more than one form at a time, however.

By popular demand, the text and labels you provide for form elements are escaped according to HTML rules. This means that you can safely use "<CLICK ME>" as the label for a button. However, this behavior might interfere with the capability to incorporate special HTML character sequences-such as &amp;Aacute; (&Aacute;)-into your fields. If you want to turn off automatic escaping, call the autoEscape() method with a False value immediately after creating the CGI object, as outlined in this program fragment: $query = new CGI; $query->autoEscape(undef);

You can turn autoescaping back on at any time with $query->autoEscape('yes')

Creating an Isindex Tag

The isindex() method called without any arguments returns an Isindex tag that designates your CGI program as the URI to call. If you want the browser to call a different URI to handle the search, pass isindex('TGT-URI') the URI you want to be called. Use this code: print $query->isindex($action);

Starting a Form

The method startform('HTTP-METHOD', 'TGT-URI')

returns a Form tag with the optional HTTP-METHOD and TGT-URI that you specify (Post and none assumed). Use this code: print $query->startform($method,$action);

Table 8.2 explains the parameters of the startform() function.

Ending a Form

The endform() method returns a Form tag. Use this code: print $query->endform;

Creating a Text Field

The method textfield('NAME','INITIAL-VALUE','WINDOW-SIZE','MAX-chARACTERS')

returns a string that contains the HTML code for a text-input field. Use this code: print $query->textfield('foo','starting value',50,80);

Table 8.3 explains the parameters of the textfield() function.

As with all these methods, the field is initialized with its contents from earlier invocations of the script. When the form is processed, the value of the Text field can be retrieved with this code: $value = $query->param('foo');

Creating a Textarea Field

The method textarea('NAME','INITIAL-VALUE','ROWS','COLUMNS')

is just like the textfield() method, but it enables you to specify rows and columns for a multiline text-entry box. You can provide a starting value for the field, which can be long and contain multiple lines. Scrollbars for both horizontal and vertical scrolling are added automatically. Use this code: print $query->textarea('foo','starting value',50,80);

Table 8.4 explains the parameters of the textarea() function.

Creating a Password Field

The method password_field('NAME', 'INITIAL-VALUE', 'WINDOW-SIZE','MAX-chARACTERS')

is identical to textfield() except that its contents, when typed from the keyboard or from the Value field, are represented by asterisks on the Web page. Use this code: print $query->password_field('foo','starting value',50,80);

Table 8.5 explains the parameters of the password_field() function.

Creating a Pop-Up Menu

The method popup_menu('NAME', 'OPTION-NAMES', 'SELECTED-OPTION', 'OPTION-VALUES') creates a selection menu, which also is referred to as a pull-down menu. Use this code: print $query->popup_menu('menu_name',['eenie','meenie','minie'],'meenie'); or print $query->popup_menu('menu_name', ['one','two','three'],'two', {'one'=>'eenie','two'=>'meenie','three'=>'minie'});

Table 8.6 explains the parameters of the popup_menu() function.

When the form is processed, the selected value of the pop-up menu can be retrieved by using this code: $popup_menu_value = $query->param('menu_name');

Creating a Scrolling List

The method scrolling_list('NAME', 'OPTION-NAMES', 'SELECTED-OPTIONS', 'LIST-SIZE',   'MULTIPLE-SELECTIONS', 'OPTION-VALUES')

creates a scrolling list that contains the items passed in the OPTION-NAMES parameter. The list can be set to select only one item or multiple items at a time. Use this code: print $query->scrolling_list('list_name', ['eenie','meenie','minie','moe'], ['eenie','moe'],5,'true');

or print $query->scrolling_list('list_name', ['one','two','three','four'], ['one','four'],5,'true', {'one'=>'eenie','two'=>'meenie', 'three'=>'minie','four'=>'moe'});

Table 8.7 explains the parameters of the scrolling_list() function.

When this form is processed, all selected list items are returned as a list under the parameter name 'list_name'. You can retrieve the values of the selected items with this code: @selected = $query->param('list_name');

Creating a Group of Related Checkboxes

The method checkbox_group('GROUP-NAME', 'BOX-NAMES', 'SELECTED-LIST', 'VERTICAL',   'BOX-VALUES')

creates a list of checkboxes that are related by the same name, just as pop-up menus and scrolled lists are related by the same name. Use this code: print $query->checkbox_group('group_name', ['eenie','meenie','minie','moe'], ['eenie','moe'],'true');

or print $query->checkbox_group('group_name', ['one','two','three','four'], ['one','two'],'true', {'one'=>'eenie','two'=>'meenie', 'three'=>'minie','four'=>'moe'});

Table 8.8 explains the parameters of the checkbox_group().

You can retrieve the values of the enabled checkboxes (those that are turned on) with this code: @turned_on = $query->param('group_name');

Creating a Standalone Checkbox

The method checkbox('NAME', 'SELECTED', 'CGI-VALUE', 'VALUE')

is used to create an isolated checkbox that isn't logically related to any others. Use this code: print $query->checkbox('checkbox_name',1,'TURNED ON','Turn me on');

Table 8.9 explains the parameters of the checkbox() function.

You can retrieve the value of the checkbox by using this code: $turned_on = $query->param('checkbox_name');

Creating a Radio Button Group

The method radio_group('GROUP-NAME', 'BUTTON-NAMES','SELECTED','VERTICAL','BUTTON-VALUES')

creates a set of logically related radio buttons. Turning on one member of the group turns off the others. Use this code: print $query->radio_group('group_name',['eenie','meenie','minie'], 'meenie','true');

or print $query->radio_group('group_name',['one','two','three'], 'two','true', {'one'=>'eenie','two'=>'meenie'});

Table 8.10 explains the parameters of the radio_group() function.

When the form is processed, you can retrieve the selected radio button by using this code: $which_radio_button = $query->param('group_name');

Creating a Submit Button

The method submit('NAME', 'VALUE')

creates the Query Submission button. Every Web fill-out form that has more than one text-entry field or any other input type should have a Submit button. Use this code: print $query->submit('button_name','value');

Table 8.11 explains the parameters of the submit() function.

You can retrieve the value of the Submit button by using this code: $which_one = $query->param('button_name');

Creating a Reset Button

The method reset('LABEL')

creates the Reset button. It undoes whatever changes the user has recently made to the form, but it does not necessarily reset the form all the way to the defaults. (See the next section, "Creating a Defaults Button," for that.) This method takes an optional LABEL argument. If set, LABEL defines the visible name of the Reset button, which is Reset by default. Use this code: print $query->reset

Creating a Defaults Button

The defaults('LABEL') method creates a Reset to Defaults button. It takes the optional label for the button, which is Default by default. When the user clicks this button, the form is set to the defaults you specify in your script, just as it was the first time it was called. Use this code: print $query->defaults('button_label')

Creating a Hidden Field

The method hidden('NAME', VALUE(1), ... VALUE(N))

produces a text field that can't be seen by the user. It is useful for passing state variable information from one invocation of the script to the next. Use this code: print $query->hidden('hidden_name','hidden_value1','hidden_value2'...);

Table 8.12 explains the parameters of the hidden() function.

The hidden() method is a quick-and-dirty way of passing Perl arrays through forms

You can retrieve the value of a hidden field with this code: $hidden_value = $query->param('hidden_name');

Or, for values created with arrays, you can use this code: @hidden_values = $query->param('hidden_name');

Creating a Clickable Image Button

The method image_button('NAME', 'SRC', 'ALIGN')

produces an inline image that acts as a Submission button. When selected, the form is submitted and the clicked (x,y) coordinates are submitted as well. Use this code: print $query->image_button('button_name','/source/URL','MIDDLE');

Table 8.13 explains the parameters of the image_button() function.

After the image is clicked, the results are passed to your script in two parameters named "button_name.x" and "button_name.y", where "button_name" is the name of the image button: $x = $query->param('button_name.x'); $y = $query->param('button_name.y');

Controlling HTML Autoescaping

By default, if you use a special HTML character-such as >, <, or &amp-as the label or value of a button, it is escaped using the appropriate HTML escape sequence (for example, &amp;gt;). This process enables you to use anything at all for the text of a form field without worrying about breaking the HTML document. However, it also might interfere with the capability to use special characters-such as &Aacute;-as the default contents of fields. You can turn this feature on and off with the method autoEscape('ON/OFF'), as shown in this code: $query->autoEscape(undef); turns automatic HTML escaping OFF. $query->autoEscape('true'); turns automatic HTML escaping ON.

Using the CGI Library for C Programmers: cgic

cgic is an ANSI C-language library for the creation of CGI-based World Wide Web applications. cgic is included in this chapter with the permission of Thomas Boutell (<boutell@boutell.com>), and can be found at http://sunsite.unc.edu/boutell/cgic/

cgic performs these tasks:

• Parsing form data, correcting for defective or inconsistent browsers
• Transparently accepting both Get and Post form data
• Handling line breaks in form fields in a consistent manner
• Providing string, integer, floating-point, and single- and multiple-choice functions to retrieve form data
• Providing bounds-checking for numeric fields
• Loading CGI environment variables into C strings that are always non-null
• Providing a way to capture CGI situations for replay in a debugging environment
• Providing a somewhat safer form of the system() function

cgic should be compatible with any CGI-compliant server environment.