AngelfireCGI is a module to help you deal with CGI input, which is the kind of input your script can collect from forms or from specially-coded links. When a user types into a form and submits information, your script can use AngelfireCGI to grab some or all of the form data, and then shuttle the data along to an email, a database, or some other destination.
Of the AngelfireCGI functions below, the two that you'll need to pay particular attention to are param() and redirect(). Param() is a function used to grab CGI input. If you specify the name of a particular field that you want to grab, param() will grab the value associated with the input field of that name. For example, let's say you have a form with an input box named "address" where users are asked to type in their home address. When a user types in "160 Water St." and hits the Submit button, you can assign the text "160 Water St." to the variable $form_address within the form. The statement looks like this:
$form_address = $CGI->param('address');
If you want to know the values of all the inputs returned by the form, don't specify an input. The names of all the inputs will then be returned as an array. The statement is:
@all_inputs = $CGI->param();
The other function of note is redirect(). redirect() lets you specify a URL or a script that the browser automatically redirects to. The user is taken there without having to do anything -- you've probably seen websites redirect your browser after they have changed their site structure or moved to a new URL. You can redirect a user anywhere by typing this:
$CGI->redirect('http://www.angelfire.com');
The script above script redirects the user to the Angelfire home page.
AngelfireDate.pm
The AngelfireDate module handles dates. You can fetch the current date (or a part of it), modify the display format of a date, see which of two dates is more recent, et cetera.
Here are some common functions to use with AngelfireDate:
- currentDate();
- currentDay();
- currentMonth();
- currentYear();
- massageDate();
- convertYearToYYYY();
- convertMonthNameToInt();
- convertIntToMonthName();
- dateIsPast();
- addNMonthsToDate();
- addNDaysToDate();
- isValidDate();
The first four functions, currentDate(), currentDay(), currentMonth(), and currentYear(), are very similar. None of them take any arguments, and each returns a single string like this:
$todays_date = $DATE->currentDate();
Note: All of the functions listed above return their information in mm/dd/yyyy format. If today is July 16, 2001, currentDate() would return "08/16/2001." and currentMonth() would return "08."
massageDate takes a date which may not be in the mm/dd/yyyy format and returns it in that format. You could use it like this:
$unformatted_date = '9/6/00'; $formatted_date = $DATE->massageDate($unformatted_date);
$formatted_date would then be equal to "09/06/2000." Note that massageDate() can handle dates using dashes or slashes, but the date needs to be numerical, and it needs to be in the standard U.S. ordering of month/day/year.
convertYearToYYYY() is another date formatter. It simply takes any year and converts it into a four-digit year. It should work for all years between 1931 and 2030. Just use the following code to convert a $two_digit_year to a $four_digit_year:
$two_digit_year = '78'; $four_digit_year = $DATE->convertYearToYYYY();
This will make $four_digit_year appear as "1978." in this example.
convertMonthNameToInt() and convertIntToMonthName() are sister functions, used to convert date data back and forth between a month name (like "January" or "Jan") and that month's number (in this case, "1"). Use these functions like this:
$month_name = 'February';
$month_number = $DATE->convertMonthNameToInt($month_name);
$month_name_again = $DATE->convertIntToMonthName($month_number);
The dateIsPast() function checks to see if a given date has already occurred. The date should be in month/day/year format. It returns "1" if the date is past, and "0" otherwise. Use it like this:
$date_in_question = '1/1/2000';
if ($DATE->dateIsPast($date_in_question)) {
print "Y2K has already occurred.\n";
} else {
print "Y2K hasn't happened yet - there's still time to prepare!\n";
}
Our last pair of functions are addNMonthsToDate() and addNDaysToDate(). Both functions require a date and a number. That number is added to the date to produce a new date. The number can be negative as well, which means that you can add or subtract days or months from any date. For example:
$moon_walk_date = '07/20/69';
$five_days_later = $DATE->addNDaysToDate($moon_walk_date, '5');
$ten_months_earlier = $DATE->addNMonthsToDate($moon_walk_date, '-10');
AngelfireInsert.pm
The AngelfireInsert module makes it easier for you to insert dynamic content into your pages. It's very similar to AngelfirePage, so read up on the AngelfirePage module before using this one. The following text refers to comments made in the AngelfirePage documentation.
There is one very important function that makes up the meat and potatoes of AngelfireInsert, and that's fetchInsert(). fetchInsert() takes a text file, looks for variables, fills in the variables with the contents of a variable hash, and then returns the result. In this regard, fetchInsert() works in a very similar way to sendPage() from the AngelfirePage module. Indeed, fetchInsert() essentially does the same work as sendPage(), except that instead of sending its output to the Web server along with an HTTP header, fetchInsert() returns the filled-in template as a value to your script. From there, you can do whatever you want with it -- print it out, combine it with other templates into a larger page, or save it as a file. Here's an example:
$template_file = 'log_template.txt';
$variable_hash{timezone} = $ENV{TZ};
$variable_hash{ip_address} = $ENV{REMOTE_HOST};
$variable_hash{browser} = $ENV{HTTP_USER_AGENT};
$log_line = $INSERT->fetchInsert($template_file);
open (LOG, '>> my_log.txt');
print LOG $log_line;
close LOG;
The "log_template.txt" that goes with the script looks like this:
-----------------------------
Timezone: $timezone
IP: $ip_address
Browser: $browser
-----------------------------
This example works like the example given for sendPage(), except that here each visitor's timezone, IP address, and browser type are added to a log file named "my_log.txt" rather than being outputted to a Web page.
AngelfireMail.pm
AngelfireMail is a module that allows you to send email messages with your scripts. In order to use it, you'll have to have a mail template in your cgi-bin directory. The mail template will need to look something like this:
To: $email
From: FredFlintstone@hotmail.com
Subject: YabbaDabbaDoo!
Hello $name,
Congratulations! You're user number $number of this mail script!
You can add other email headers such as Reply-To: or Errors-To:, but To: and From: are mandatory. You can customize your email by adding variables wherever you'd like to fill something in on the fly. The sendMail method requires two parameters, the location of the mail-template file, and a reference to a hash of variables. The keys of the variable hash should correlate with the variables in the mail template. Here's an example:
require AngelfireMail;
$MAIL = new AngelfireMail;
$mail_template = "./flintstones_mail.txt";
%variables = ('email' => 'Wilma@gurlmail.com',
'name' => 'Wilma',
'number' => '2');
$MAIL->sendMail($mail_template, \%variables);
Note: In order to prevent spamming, you will be limited to sending out 240 emails per day.
AngelfirePage.pm
AngelfirePage is a module that makes it easier for you to generate dynamic pages from your scripts. AngelfirePage does two big things for you:
First, it generates an HTTP header for you so you don't have to go to the trouble of outputting "Content-Type: text/html\n\n" or any other header information. This is especially helpful if, like a lot of people, you're not an HTTP header expert! Secondly, AngelfirePage lets you take an html template and fill in certain values that you want to be dynamic. For example, if you wanted your script to output a page that always shows the current time, you could do that easily with AngelfirePage.
The functions to look for are:
- sendPage();
- sendNonCachedPage();
- printHeader();
sendPage() is the most important function. sendPage() takes an html file, and any variables that it contains, and spits the page out to the Web server. It takes two arguments. The first is the location of the html file, and the second is a reference to a hash of variables. If you aren't familiar with hashes or with variables, just follow the example and you should catch the meaning. Here's the example -- this one is long, and has two parts to it:
$page_location = 'example.html';
$variable_hash{timezone} = $ENV{TZ};
$variable_hash{ip_address} = $ENV{REMOTE_HOST};
$variable_hash{browser} = $ENV{HTTP_USER_AGENT};
$PAGE->sendPage($page_location, \%variable_hash);
exit;
The example.html file referred to at the beginning might look something like this:
Example Page
You are coming in from this timezone: $timezone
You are using the $browser browser. Your ip address is $ip_address.
Together, this script and html file will output a page that shows the viewer's browser, IP address, and timezone. First, the script specifies the name of the html file that we will be using. Second, it creates a hash that contains all the variables contained within the page -- in this case, "timezone", "ip_address", and "browser" -- and assigns values to each of them. Note that in this case it is getting the values out of a special hash called %ENV, which contains environment variables that all CGI scripts have access to. You could also create different variables that get their values from other places, like random numbers, the time or date, or input from a form. Finally, the script calls sendPage() to fill in html file's variables with the contents of the hash. sendPage() looks at the html file and searches for words preceded by dollar signs. In our example file, it finds the variables $timezone, $browser, and $ip_address. Each of these variables then gets replaced by the values from the hash. So the output might look something like this:
Example Page
You are coming in from this timezone: US/Eastern
You are using the Mozilla/4.61 [en] (Win98; U) browser. Your ip address is 208.7.131.186.
That's what you'd see if you were using my personal computer at Angelfire -- running this script on your computer would probably produce something quite different. This is what's cool about sendPage() -- it lets you present different information on your page under different circumstances.
We can go over the last two functions quickly. sendNonCachedPage() works just like sendPage(), except that it also tells the browser not to cache the page that is sent. This is useful if the information you are sending to the user changes from moment to moment. With this function, you can ensure that a visitor who reloads the page always gets the newest information.
printHeader() just outputs an HTTP header that lets the browser know it will be displaying an HTML page generated by your script. If your script is outputting something besides HTML, you can also pass it the appropriate MIME-type for your output. The function will change the header accordingly. You can use it like this:
$PAGE->printHeader();
print "A really simple page.
";
exit;
That will output a page which says "A really simple page." and nothing else. If you are creating such a dynamic Web page that you need to write all the HTML from within your script, you might want to use printHeader() instead of sendPage(). If you are just using an HTML file as a template and filling in variables, then printHeader() works perfectly.
CGI.pm
CGI.pm is not an Angelfire-written module. It's a module that sees a great deal of use among Perl programmers on the Web because it's very useful and easy to install. It doesn't depend upon other modules in order to do its thing, which also adds to its appeal. Because of its wide usage, particularly by scripts offered in free online script archives, we include CGI here. We assume, however, that you will only be using the CGI module if you already know how it works. CGI is a large module with too many functions to properly document in this guide! To read extensive documentation on CGI.pm, read the pages written by the developers of the module.