CGI, short for Common Gateway Interface, refers to the way in which most Web servers communicate with scripts or programs. CGI is most commonly used in forms that require the user to input information. Once the user submits data via an HTML form, a CGI script can be utilized by the programmer to use the data in various ways. Perl is the language most commonly used to write CGI scripts; all of the scripts in the CGI Library are written in Perl. CGI is not itself a programming language. It's more of a protocol for communication between the Web server and a script.
Modules Definition
Modules are packages of functions that you can access with CGI scripts in order to serve dynamic content to your users in various ways. Since they are commonly shared among programmers, modules are a great way to add functionality to your scripts without having to do all the work yourself. If somebody else has done the job of figuring out how to read CGI input from a form, or calculate which of two dates is the earlier one, they can package these functions into modules so that you can benefit from their work.
Here at Angelfire, we've already assembled a few modules that we think might be useful to you. Simply click on the module name on the first page of this guide to learn the general way these modules work. Once you're familiar with the basics, you can start using them in conjunction with your own scripts. You'll also want to read the instructional comments at the beginning of any module that you decide to use. All of Angelfire's modules are annotated to give you more specific information about the functions the module provides.
You can use modules written by other people in your scripts, or you can go ahead and write your own. All you need to do is copy the modules you want to use into your site's cgi-bin directory. Be aware that not all modules work the same way our Angelfire modules do, so you may need to dig in a little deeper to figure them out. For starters, all modules used on Angelfire must be written in Perl. If modules are written in a language other than Perl, they simply won't work on your Angelfire site!
A Good Example of how Angelfire modules differ from others:
CGI is frequently used to manage automated email communication between Web administrators and site visitors, whether it be a site manager automatically sending email to visitors, or information compiled from a site's forms being mailed to the site's owner. In order to do either task, a script needs access to an email program. Angelfire has provided its users with a module called AngelfireMail.pm. However, Angelfire's mail module doesn't function exactly like the mail programs you may have used before. You need to have a mail template in your directory which defines the common fields in an email, such as "To," "From," and "Subject." You can include variables in that template. There is a method of the AngelfireMail.pm module called "sendMail." This method needs two bits of information: the name of the mail template in your directory, and a hash (a collection of variables). These are the same variables that are referred to in your template. Say you had a template that looked a bit like this:
To: $recipient
From: $sender
Subject: $subject
$body
$signature
You could then use the AngelfireMail module to send e-mail by creating a new instance:
require AngelfireMail;
$mail= new AngelfireMail;
$mail->sendMail($template, /%hash);
In this case, "$template" is the name of the template file, and "%hash" is a hash of variables mentioned in the template. The hash for the template should include a recipient, sender, subject, body, and signature in the hash of variables. That hash would be put together elsewhere in the script that's calling the AngelfireMail module. For example, if this bit of code were in a guestbook script, the script would collect information from the form that the user fills out when he or she actually signs the book. Along with building a new entry in your guestbook, the script would also store the visitor's email address in your hash as "recipient," and your email address as "sender."
One important thing to note is that AngelfireMail is not the same thing as a mail program; any ready-made script that uses a mail program will have to be significantly altered before it will work. If you're writing your own scripts and are planning to use AngelfireMail, keep this information in mind. The AngelfireMail.pm module also includes information about how it works and how to call the methods.
To start using one of the Angelfire modules in a script, you'll first want to add this line of code to your script (for this example, we'll use the AngelfireCGI module):
require AngelfireDate;
This lets the Perl interpreter know that you want to have access to the functions in the module. Next, you can create an "object" that will let you access those functions. If you know any object-oriented programming, this should sound familiar. Otherwise, just think of the object as a way to get access to the functions you want to utilize. You create an object by adding this to your script:
$CGI = new AngelfireDate;
The variable $CGI is now a AngelfireDate object. With it, you can use the functions in the AngelfireDate module. For example, you can use the currentDate() function, which returns today's date, like this:
$todays_date = $CGI->currentDate();
This would assign the date to the $todays_date variable. Whenever you want to print the current date on the page, you would simply call the $todays_date variable.
Limitations of Angelfire's CGI
There are some important limitations to consider when running CGI scripts on Angelfire. For instance, certain Perl commands have been disabled for security reasons. This prevents people from performing such malicious acts as reading information stored in your private directories. Programmers who perform normal dynamic content functions like sending email and storing form data very rarely use the disabled commands, but there are a few disabled commands that you might want to take note of. These are:
system
exec
fork
chown
chmod
sleep
unlink
kill
eval
All commands involving sockets
We've also limited how many system resources are available to each script. For example, a script can only use up to one second of CPU time before it is deemed to be causing problems and is terminated. This ensures that users don't accidentally -- or intentionally -- write scripts that run endlessly and eat up all of the server's resources. It's unlikely that you'll run into system-resource constraints unless you're running a script which requires an exceptional amount of processing time or memory.