《.././modules_readme.html》檔案內容

View 《.././modules_readme.html》

<H3>
TRIPOD PERL MODULES README
</H3>

Table of Contents
 
1. Using Perl Modules on Tripod <A HREF="#using">[go]</A> 
2. TripodCGI.pm <A HREF="#tripodcgi">[go]</A> 
3. TripodDate.pm <A HREF="#tripoddate">[go]</A> 
4. TripodInsert.pm <A HREF="#tripodinsert">[go]</A> 
5. TripodMail.pm <A HREF="#tripodmail">[go]</A> 
6. TripodPage.pm <A HREF="#tripodpage">[go]</A> 
7. CGI.pm <A HREF="#cgi">[go]</A>

<A NAME="using"></A>
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): 
<pre>
 require TripodDate; 
</pre>
 
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: 
<pre>
 $CGI = new TripodDate; 
</pre>
 
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: 
<pre>
 $todays_date = $CGI->currentDate(); 
</pre>

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.

<A NAME="tripodcgi"></A>
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: 
<pre>
 $form_address = $CGI->param('address');
</pre>
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: 
<pre>
 @all_inputs = $CGI->param(); 
</pre>
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: 
<pre>
 $CGI->redirect('http://www.tripod.com'); <- redirects to the Tripod 
 front page
</pre>

<A NAME="tripoddate"></A>
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: 
<PRE>
 * currentDate(); * convertMonthNameToInt(); 
 * currentDay(); * convertIntToMonthName(); 
 * currentMonth(); * dateIsPast(); 
 * currentYear(); * addNMonthsToDate(); 
 * massageDate(); * addNDaysToDate(); 
 * convertYearToYYYY(); * isValidDate(); 
</PRE>

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: 
<pre>
 $todays_date = $DATE->currentDate(); 
</pre>
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: 
<pre>
 $unformatted_date = '9/6/99'; 
 $formatted_date = $DATE->massageDate($unformatted_date); 
</pre>
$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: 
<pre>
 $two_digit_year = '78'; 
 $four_digit_year = $DATE->convertYearToYYYY(); 
</pre>
 
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: 
<pre>
 $month_name = 'February'; 
 $month_number = $DATE->convertMonthNameToInt($month_name); 
 $month_name_again = $DATE->convertIntToMonthName($month_number); 
</pre>
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: 
<pre>
 $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"; 
 } 
</pre>
 
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: 
<pre>
 $moon_walk_date = '07/20/69'; 
 $five_days_later = $DATE->addNDaysToDate($moon_walk_date, '5'); 
 $ten_months_earlier = $DATE->addNMonthsToDate($moon_walk_date, '-10'); 
</pre>

<A NAME="tripodinsert"></A>
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: 
<pre>
 $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; 
</pre>
 
The 'log_template.txt' that goes with the script looks like this: 
<pre>
 ----------------------------- 
 Timezone: $timezone 
 IP: $ip_address 
 Browser: $browser 
 ----------------------------- 
</pre>
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.

<A NAME="tripodmail"></A>
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: 
<pre>
 To: $email
 From: FredFlintstone@hotmail.com
 Subject: YabbaDabbaDoo!

Hello $name,
 Congratulations! You're user number $number of this mail script!
</pre>

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:
<pre>
 require TripodMail;
 $MAIL = new TripodMail;
 $mail_template = "./flintstones_mail.txt";
 %variables = ('email' => 'Wilma@gurlmail.com',
 'name' => 'Wilma',
 'number' => '2');
 $MAIL->sendMail($mail_template, \%variables);</pre>
Note: In order to prevent spamming, you will be limited to sending out 240 
mails per day.

<A NAME="tripodpage"></A>
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: 
<pre>
 $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; 
</pre>

The 'example.html' file referred to at the beginning might look something 
like this: 
<pre>
 <HTML> 
 <HEAD><TITLE>Example Page</TITLE></HEAD> 
 <BODY BGCOLOR="#FFFFFF"> 
 <H3>Example Page</H3> 
 You are coming in from this timezone: $timezone 
 You are using the $browser browser. Your ip address is $ip_address. 
 </BODY></HTML> 
</pre>
 
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: 
<pre> 
 <HTML> 
 <HEAD><TITLE>Example Page</TITLE></HEAD> 
 <BODY BGCOLOR="#FFFFFF"> 
 <H3>Example Page</H3> 
 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. 
 </BODY></HTML> 
</pre>
 
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: 
<pre>
 $PAGE->printHeader(); 
 print "<HTML><BODY>A really simple page.</BODY></HTML>"; 
 exit; 
</pre>

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.

<A NAME="cgi"></A>
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!