Example Page

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!