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 that all of the above functions return their information in mm/dd/yyyy format. So 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 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 a year and converts it into a four-digit year. It should work well for years between 1931 and 2030. Just use the following code and convert $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 (for example) "1978."
convertMonthNameToInt() and convertIntToMonthName() are sister functions, used to convert back and forth between a month name (like "January" or "Jan") and that month's number (in this case, "1"). Use them 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. Note that the number can be negative, which means that you can subtract as well. 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');
TripodInsert.pm
The TripodInsert module makes it easier for you to include dynamic inserts into your pages. It's very similar to TripodPage, so read the TripodPage comments before using this module. The following text refers to those previous comments.
There's only one function you should need to use in TripodInsert, and that's fetchInsert(). fetchInsert() takes a text file, looks for variables, fills in the variables with the contents of a variable hash, and returns the result. This is very similar to how sendPage() from TripodPage works; indeed, fetchInsert() essentially is sendPage(), except that instead of sending its output to the Web server along with an HTTP header, it 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 are added to a log file named "my_log.txt," rather than being outputted as a Web page.
TripodMail.pm
TripodMail is a module that allows you to send out e-mail 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 e-mail headers (Reply-To:, Errors-To:, etc), but To: and From: are mandatory. You can customize your e-mail by adding variables wherever you'd like to fill something in on the fly. The sendMail method requires to 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.
Example of use:
require TripodMail;
$MAIL = new TripodMail;
$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 mails per day.
TripodPage.pm
TripodPage is a module that makes it easier for you to generate dynamic pages from your scripts. TripodPage does two big things for you:
1. It generates an HTTP header for you, so you don't have to go to the trouble of outputting a 'Content-Type: text/html\n\n' or all that other stuff. This is especially helpful if, like a lot of people, you don't know what an HTTP header is supposed to look like!
2. It 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 showed the current time, you could do that easily with TripodPage.
The functions you care about are:
- sendPage();
- sendNonCachedPage();
- printHeader();
sendPage() is the most important one. sendPage() takes an html file, in 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 do fine. Here's
the example - this one's long, with a couple of 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, but you could have different variables that get their values from other places, like random numbers, the time or date, input from a form, etc. Finally, the script calls sendPage() to take the html file and fill in the variables with the contents of the hash. sendPage() looks at the html and searches for words preceded by dollar signs. In our example file, it finds $timezone, $browser, and $ip_address. Each of these 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 Tripod - you'd see 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 a good idea if the information you are sending back changes from moment to moment, and you want to make sure that a visitor who reloads the page always gets the newest information.
printHeader() just outputs the HTTP header that tells the browser you are outputting an HTML page from your script. If your script is outputting something besides html, you can also pass it the appropriate MIME-type for your output, and it 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. You might want to use printHeader() instead of sendPage() if you are creating such a dynamic Web page that you need to write all the html from within your script, rather than using an html file as a template and filling in variables.
CGI.pm
CGI is not a Tripod-written module; rather, it's a module that sees a lot 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 adds greatly to its appeal.) Because of its wide usage, particularly in scripts offered in online script archives, we include CGI here. We're assuming, though, that you will only be using it if you already know how it works. CGI is a large module with too many functions to properly document in this guide!
Members:
help
