CGI Programming Guide - [Appendix D] CGI Lite

CGI Lite is a Perl 5 library that will decode both URL-encoded and multipart form data produced by the file upload feature present in Netscape 2.0. This module does not have all of the features of the CGI::* modules, but is lightweight and slightly easier to use. Here is a simple example that outputs all the form data:

The parse_form_data method parses the form data and stores it in an internal associative array, which can be printed out by calling the print_form_data method. Or, you can place the form data in a variable of your choice:

D.1 Multipart Forms

The file upload feature of Netscape 2.0 allows you to do just that: send files as part of a form through the network. Here is how to create a multipart form:

<HTML>
<HEAD><TITLE>CGI Lite Test</TITLE></HEAD>
<BODY>
<H1>CGI Lite Test</H1>
<HR>
<FORM ACTION="/cgi-bin/upload.pl" ENCTYPE="multipart/form-data" METHOD="POST">
What is your name? <INPUT TYPE="text" NAME="username">
<P>     
Select a <B>TEXT</B> file to send: <INPUT TYPE="file" NAME="input_file">
<P>
<INPUT TYPE="submit" VALUE="Send the Multipart Form">
<INPUT TYPE="reset"  VALUE="Clear the Information">
</FORM>
<HR>  
</BODY>
</HTML>

There are two things that are very different from what we have seen before. The first is the ENCTYPE attribute in the FORM tag. If we want the form data to be URL-encoded, then we don't have to specify ENCTYPE, in which case it defaults to application/x-www-form-urlencoded.

The other is the TYPE attribute in the INPUT tag. By specifying a TYPE of "file", Netscape will display a "Browse" button which allows you to select a file from your disk or network.

Figure D.1 shows how the form will be rendered by Netscape.

Figure D.1: Snapshot of multipart form

[Graphic: Figure D-1]

The following program decodes the form information and sends the user-uploaded file back to the browser for display. (That's the reason why we asked the user to send text files.)

#!/usr/local/bin/perl5
use CGI_Lite;
 
$cgi = new CGI_Lite ();
print "Content-type: text/plain", "\n\n";
$cgi->set_directory ("/usr/shishir") || die "Directory doesn't exist.\n";

The set_directory method allows you to store the uploaded files in a specific directory. If this method is not called, CGI_Lite defaults to /tmp.

$cgi->set_platform ("UNIX");

Since this is a text file, we can use the set_platform method to add or remove the appropriate end of line (EOL) characters. The EOL character is a linefeed ("\n") in UNIX, a carriage return ("\r") on the Macintosh, and a combination of carriage return and line feed ("\r\n") on the Windows/DOS platform.

$cgi->set_file_type ("handle");
%data = $cgi->parse_form_data ();

The set_file_type method with an argument of "handle" returns the filehandle(s) for uploaded files that are stored in the directory specified by the set_directory method.

$user = $data{'username'};
$filename = $data{'input'};
print "Welcome $user, let's see what file you uploaded...", "\n";
print "=" x 80, "\n";

Here we simply retrieve the form fields and display a welcome message. Remember, the variable $filename points to a filehandle.

if (-T $filename) {
    while (<$filename>) {
        print;
    } 
    close ($filename);
} else {
    print "Sorry! you did not upload a text file.", "\n";
}
exit (0);

If the uploaded file is a text file, we proceed to output it. If not, an error message is output.

D. CGI Lite

D.1 Multipart Forms

Figure D.1: Snapshot of multipart form