|
this is the print friendly version of the CGI field guide Tripod's CGI Support Field Guide You can do a lot of cool stuff on your site with HTML; display basic pages, add images, play music, link to other sites ... the list goes on. But at some point, you'll probably want your page to be able to do even more. That's why Tripod offers a CGI service, with which you can easily add Perl scripts that will make your pages more dynamic. Want to gather information from your viewers or open a guestbook? Perhaps you'd like to write a game or set cookies. CGI scripts can do some pretty amazing things. We're here to help you learn how to use CGI on Tripod. New to CGI scripts? Don't despair; Tripod's got you covered. We've written some useful scripts that you can plug directly into your page with no programming! You'll find them in our Script Library. Tripod has ready-made scripts for forms, random content, site search, and timely content. You'll be able to customize the script and then cut and paste it into your HTML pages. Couldn't be simpler. You can access the Script Library through the FreeForm Editor by clicking on the "Cool Page Features" pull-down menu. Or stop right here and go to the Library! Still with us? Then you must know something about CGI. If you're itching to use your own CGI scripts (whether you wrote them yourself or carped them from someplace else), you'll need to be initiated, for CGI is bit different on Tripod! But it still boils down to a basic five-step process:
Step 1: Use your cgi-bin now. So you know CGI — we don't need to tell you what it is. Still, there are a few things you need to know about how CGI works on Tripod. You must put all your CGI scripts and associated files and modules into a specially designated directory on your Web server, which on Tripod is called "cgi-bin." Tripod differs from other CGI services in that all member-CGI scripts run on a special server named "cgi.tripod.com." While your scripts are running, the CGI server doesn't contact any other server on Tripod. This means a few things: Since the CGI server won't contact any other servers on Tripod, any HTML or other file your script needs to access must be in your cgi-bin. You don't need to create the bin, we've done it for you. You can find it in your FileManager. While a CGI script is running, Tripod's CGI server considers your cgi-bin to be the root directory. The sorts of things you can expect to find in a standard member's cgi-bin would be:
Step 2: Upload Tripod's Perl modules First, we've put together a few standard Perl modules (packages of functions) that will make your scripts work. You'll need to put them in the cgi-bin in your Tripod member directory along with your CGI scripts in order for the scripts to work. (Remember, all scripts, modules, and associated files need to be in your cgi-bin, or our servers won't find them!) You can use this collection of Perl modules, along with your cgi-bin, to make scripts work on any of your Tripod pages. These modules will allow you to do the following tasks:
All Tripod modules are written in Perl. Perl allows you to use modules to encapsulate commonly used functions. Tripod's cgi-bin fully supports modules — just put them into your cgi-bin directory and your scripts will find them. In addition to the modules, you'll find a file called "modules_readme.html." This file contains detailed instructions on how to use modules in your scripts, and lets you know what each module can do. You'll need to read it to effectively enable your scripts!
You will upload the following modules: Load the modules directly to your cgi-bin on this page. Whether you've written it yourself or picked it up someplace else, the only way to make a script work on your Tripod page is to dump it into your cgi-bin. Get a copy of your script and move onto Step 4. Step 4: Put your script and associated files in the CGI bin. There are three ways to get scripts into your Tripod cgi-bin. Any CGI scripts you put in your cgi-bin must have either a .pl or a .cgi file extension, or they won't work. Write your own scripts here. Or: Get a copy of your script and then go to the FileManager. Under the "File — Options" drop-down menu, select "New Script." Paste your script code into the input box and save it. Or: Upload your scripts to your Tripod cgi-bin using a stand-alone FTP program. Step 5: Use your scripts on your Tripod pages. The page or pages on which you use your script must live on Tripod servers. Those pages don't need to be in your cgi-bin, but they do need to be in your directory somewhere! Tripod does not provide troubleshooting support for your CGI scripts. However, there are lots of valuable resources available for programming assistance:
Webmonkey: Programming CGI/Perl |
|
An abbreviation for Common Gateway Interface, CGI refers to the way in which most Web servers communicate with scripts or programs. CGI is most commonly used in forms requiring the user to input information. This data is put into an HTML form by a script and can be utilized by the programmer in various ways. Perl is the language most commonly used to write CGI scripts; all of the scripts in the CGI Library are written in Perl. CGI is not itself a programming language; it's more of a protocol for communication between the Web server and a script. 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 his or her work? Here at Tripod, we've already done the work on a few modules that we think might be useful to you. Simply click on the module name to learn the general way these modules work, and 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, as they will give you more specifics about the functions the module provides. You can use modules written by other people (including yourself) in your scripts, as long as you copy them into your cgi-bin directory. Be aware that not all modules work the same way Tripod modules do, so you may need to do some additional work to figure them out. For starters, all modules used on Tripod must be written in Perl. If modules contain code other than Perl, they simply won't work on Tripod. A Good Example of how Tripod modules differ from others: In this case, "$template" is the name of the template file, and "%hash" is a hash of variable mentioned in the template. The hash for the template about should include a recipient, sender, subject, body, and signature in the hash of variables. That hash would be built elsewhere in the script that's calling the TripodMail module. For example, if this bit of code were in a guestbook script, that script would collect information from a form (where the visitor actually signed the book). Along with building a new entry in your guestbook, the script would also store the visitor's e-mail address in your hash as "recipient," and your e-mail address as "sender." One important thing to note is that TripodMail is not the same thing as a mail program; any ready-made script that uses a mail program will have to be significantly altered before it will work. If you're writing your own scripts and are planning to use TripodMail, keep this information in mind. The TripodMail.pm module also includes information about how it works and how to call the methods. 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 create an object 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(); system We've also limited how many system resources are available to each script. For example, a script can only use up to one second of CPU time before it is deemed to be causing problems and is terminated. This ensures that users don't accidentally -- or intentionally -- write scripts that run endlessly and eat up all of the server's resources. It's unlikely that you'll run into system-resource constraints unless you're running a script which requires an exceptional amount of processing time or memory. |
|
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, and use them for your own needs. 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 that 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 you have a form with a text input box named "address," and somebody types in "160 Water St." and hits the Submit button, you 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. The names of all the inputs will then 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 to which you want to move your visitor. You could use it like this: $CGI->redirect('http://www.tripod.com');
The TripodDate module deals 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: | |
|
|
|
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();
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';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'; 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'; 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';The "log_template.txt" that goes with the script looks like this: ----------------------------- 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 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 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: 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! The functions you care about are:
$page_location = 'example.html';The 'example.html' file referred to at the beginning might look something like this: Example PageTogether, 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 PageThat'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();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 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! |