The URL of any file located in your cgi-bin is: http://cgi.tripod.com/your_membername/cgi-bin/filename.
TRIPOD PERL MODULES README
Table of Contents
1. Using Perl Modules on Tripod [go]
2. TripodCGI.pm [go]
3. TripodDate.pm [go]
4. TripodInsert.pm [go]
5. TripodMail.pm [go]
6. TripodPage.pm [go]
7. CGI.pm [go]
USING PERL MODULES ON TRIPOD
Modules are a great way to add functionality to your scripts without having
to do all the work yourself. After all, 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, why shouldn't you benefit from their work?
Here at Tripod, we've already done the work on a few modules that we think
might be useful to you. In this document, we'll go over the general way
these modules work, so you can start using them in your scripts. You'll
also want to read the instructional comments at the beginning of any module
that you decide to use, which will give you more specifics about the functions
the module provides.
Also, you can use modules written by other people (including yourself) in
your scripts, as long as you copy them into your cgi-bin directory.
Not all modules work the same way the Tripod modules do, so you may
need to do some additional work to figure them out.
To start using one of the Tripod modules in a script, you'll first want to
add this line of code to your script (for this example, we'll use the
TripodCGI module):
require TripodDate;
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
simple way to get access to those functions). You do that like this:
$CGI = new TripodDate;
The variable $CGI is now a TripodDate object. With it, you can use
the functions in the TripodDate 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.
This should be enough to get you started using the Tripod modules in your
scripts. Remember to look at the more detailed commentary below to get
specifics on the modules you decide to use.
TRIPODCGI
TripodCGI is a module to help you deal with CGI input, which is the kind
of input your script can get from forms (as well as from specially-coded
links). When you have a form submit its information to your script,
you can use TripodCGI to grab some or all of the inputs that the form
provided, so that you can use them for your own nefarious ends ;)
Of the functions below, the only two that you are likely to need to pay
attention to are param() and redirect(). param() is the function which
lets you grab CGI input. If you specify the name of a particular input
that you want to grab, param() will grab the value associated with the
input of that name. So if I have a form with a text input box named
'address', and somebody types in '160 Water St.' and hits the submit
button, I can assign '160 Water St.' to the variable $form_address within
my form with this statement:
$form_address = $CGI->param('address');
If you just want to know all of the names of the inputs returned by
the form, don't specify an input, and the names of all the inputs will be
returned as an array - like this:
@all_inputs = $CGI->param();
The other function you might want to use is redirect(). redirect() lets
you specify the URL of a page or script that you want to move your
visitor to. You could use it like this:
$CGI->redirect('http://www.tripod.com'); <- redirects to the Tripod
front page
TRIPODDATE
TripodDate is a module for dealing with dates. You can fetch the current
date (or part of it), modify the format of a date, see which of two dates
is more recent, and so on.
The functions you may want to use are:
* currentDate(); * convertMonthNameToInt();
* currentDay(); * convertIntToMonthName();
* currentMonth(); * dateIsPast();
* currentYear(); * addNMonthsToDate();
* massageDate(); * addNDaysToDate();
* convertYearToYYYY(); * 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 that all of the above functions return their information in
mm/dd/yyyy format - so if today is July 16th, 1999, currentDate() would
return '08/16/1999', and currentMonth() would return '08'.
massageDate takes a date which may not be in mm/dd/yyyy format, and
returns it in mm/dd/yyyy format. So, you could use it like this:
$unformatted_date = '9/6/99';
$formatted_date = $DATE->massageDate($unformatted_date);
$formatted_date would then be equal to '09/06/1999'. 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 just takes a year and
converts it into a four-digit year. It should work well for years between
1931 and 2030. Just say this to convert $two_digit_year to a
$four_digit_year:
$two_digit_year = '78';
$four_digit_year = $DATE->convertYearToYYYY();
This will make $four_digit_year equal '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);
dateIsPast() 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, 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 functions are another pair: addNMonthsToDate() and
addNDaysToDate(). Both 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,
so 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
TripodInsert is a module to make it easier for you to include dynamic
inserts into your pages. It's very similar to TripodPage, and you should
read the comments for TripodPage before using this module - the comments
here will refer to it repeatedly.
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, save it as a file, etc. 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
TripodMail is a module that allows you to send out 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 (Reply-To:, Errors-To:, etc), but To:
and From: are mandatory. You can customize your email by adding variables
wherever you would like to fill something in on the fly.
The sendMail method requires 2 parameters- the location of the mail
template file, and a reference to a hash of variables.
The keys of the varaible 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
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
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 which 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
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 in 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 write all the HTML from
within your script, rather than using an HTML file as a template and
filling in variables.
CGI
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 (because it doesn't depend upon other modules
in order to do its thing). Because of it's 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
here!