Perl Fishers :: CGI Tutorial

Perl Fishers
Or how to set up a simple CGI script and form to get your members' information sent direct to your inbox. A tutorial for fanlisting owners.

Introduction

Before you can add a member to your fanlisting, you need certain information from him or her. The TFL.org rules specify that you must have the member's name and country. Most fanlisting owners also require an email address and sometimes other pieces of information. The usual way of gathering this information is to put a form on your website, which the member then fills in and submits to you by clicking a button. There are several different ways of having that information sent to your inbox. This tutorial takes you step-by-step through one very simple method, using a freeware Perl CGI (Common Gateway Interface) script that is quick and easy to install.

Step 1 Gather information.

Once you can answer the following questions, you're ready to get set up. If you need to, you can have a look in your host's FAQ or help section, or contact your host and ask.

Does your host have Perl installed, so that you can run Perl (.pl) scripts?
Do you have access to your account's cgi-bin folder?
What is your path to Perl? Check with your host but often it looks like something along the lines of one of these examples.
/usr/bin/perl
/usr/local/bin/perl
What is your path to Sendmail? Check with your host but usually it looks like this example.
/usr/sbin/sendmail
What is your website's IP address? A simple way to check is to open a DOS or Unix prompt, type "ping yourdomain.com" without the quotation marks, and press enter. Your computer will contact your domain's server and the result will show you your domain's IP.

Step 2 Download the script and configure it.

Download the script from Matt's Script Archive. Save it to a folder on your hard drive.
Unzip the files.
Open formmail.pl in a plain text editor, such as Notepad or Textpad.
Search for the referers variable. Change the values it contains to match your site's domain name (with and without the 'www.' part) and IP address. For example, if your website's domain name is www.yourdomain.com and your domain's IP address is 123.123.12.3, then this line should read:
@referers = ('yourdomain.com','www.yourdomain.com','123.123.12.3');
Make sure the path to Sendmail is correct for your host.
The same goes for the path to Perl.
Upload your configured copy of formmail.pl to your cgi-bin folder. Be sure to upload it in ASCII mode.

Step 3 Set your script's permissions.

To work, the script must have the following permissions set.

Owner: Allow Read, Write, and Execute.
Group: Allow Read and Execute.
Others: Allow Read and Execute.

The manual value of the correct permissions is 755.

How you set the file permissions varies from host to host.

With some hosts, you can set the correct file permissions by logging into your file manager or control panel, clicking on the file and then clicking "Set File Permissions."

Otherwise, you can usually set the script's permission in your FTP software. In CuteFTP, for example, select the file by clicking on it once on the remote system side, right-click on the file to bring up the option menu, and select "CHMOD." (Or click "FTP" and then "CHMOD.") This should bring up a "Change File Attributes" or similar dialogue box, where you can make the changes.

Step 4 Create a New Member page.

You can use any design you like for your New Member page.

I have included basic html below for you to use if you wish. Copy and paste it into Notepad or another plain text editor. Save it with any filename you like (examples: newmember.html, join.html, form.html) and as file type Text.

It is very important to remember to edit the following sections.

Change "http://www.yourdomain.com/cgi-bin/formmail.pl" to reflect the correct url.
Change "yourname@yourdomain.com" to your email address.

Upload the New Member page to your server.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<head>
<title>FL New Member Page</title>
</head>
<body>
<form action="http://www.yourdomain.com/cgi-bin/formmail.pl" method="POST">
<input type=hidden name="recipient" value="yourname@yourdomain.com" />
<input type=hidden name="subject" value="FL New Member" />
<input type=hidden name="redirect" value="http://www.yourdomain.com/thankyou.html" />
<p>Your name: 
<br />
<input type="text" name="name" /></p>
<p>Your email address: 
<br />
<input type="text" name="email" /></p>
<p>Your country:
<br />
<input type="text" name="country" /></p>
<p>Your website (optional):
<br />
<input type="text" name="url" /></p>
<p>Choose password. (To change your details in future.)
<br />
<input type="password" name="passwordone" /></p>
<p>Repeat password:
<br />
<input type="password" name="passwordtwo" /></p>
<p><input type="submit" name="submit" value="submit" /> <input type="reset" name="resetbutton" value="reset" /></p>
</form>
</body>
</html>

Step 6 Create a Thank You page.

You can have any kind of Thank You page you like. Just make sure that it is uploaded to the url you've specified in the redirect part of your New Member page html.

I have included basic html below for you to use if you wish. Copy and paste it into Notepad or another plain text editor. Save it as thankyou.html and as file type Text.

Upload the Thank You page to your server.

Step 7 Testing.

Once you've configured your script, uploaded it to your cgi-bin folder, set your script's permissions, and uploaded your New Member and Thank You pages, go to the New Member page and test the form.

Fill in the form's fields and click the submit button. Then go to your email inbox and see if the form results are emailed to you. Depending on your mail program and your connection speed, this may or may not happen instantly.

Step 8 Troubleshooting.

Problem: The New Member form doesn't work at all.

Possible solutions:

Check that your script's permissions are set correctly. This is by far the most common problem with getting scripts to work properly.
Check that you have entered your correct email address in the New Member page html.
Check your script is uploaded to the right folder, i.e. your cgi-bin folder, and that the url you've given in the New Member page html is correct.

Problem: The New Member form seems to work, and I'm taken to the Thank You page, but I don't receive an email with the form's contents.

Possible solution:

Wait a short while and try submitting the form again. It could be your mail server or your connection speed.
Still no joy? Check that your path to Sendmail is entered correctly in the script.
If you think you may have accidentally edited something incorrectly, download a fresh copy of the script, configure it as above in Step 2, and upload it to your cgi-bin folder.

Problem: I've checked the path to Sendmail and the script's permissions, and still the New Member form doesn't work.

Possible solution:

Are you using an email address that doesn't have the same domain as your website? For example, is your website url www.yourdomain.com but your email address isn't yourname@yourdomain.com, but something like yourname@hotmail.com or yourname@yahoo.com? If so, it would be worth your while to see if you can set up your host account so that any email sent to yourname@yourdomain.com will be forwarded on to your regular email address. Then enter yourname@yourdomain.com in the recipient field of the New Member page and try again.

Problem: The New Member form is working fine, but I'm concerned about spam.

Solution:

It's pretty unlikely that a spammer will exploit your form, but as a security measure, you might like to consider renaming the script. Remember to put its new name in the New Member page html, instead of "formmail.pl".

Problem: I don't want to have so many questions on my New Member page.

Solution:

Simply delete the ones you don't want to use.

Problem: The questions on the sample New Member page irk me. I'd rather write my own.

Solution:

You can find a introductory guide to form html tags here.

Problem: I have got the form working. Now I'd like to have a form for when a member updates his or her information.

Solution:

You don't need to make any changes to your script. You just need to upload a Update form page. You can use the sample code below if you wish. Its results will be handled by your existing script. Copy and paste it into Notepad or another plain text editor. Save it with any filename you like (examples: update.html, editmember.html, refresh.html) and as file type Text.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<head>
<title>FL Update Page</title>
</head>
<body>
<form action="http://www.yourdomain.com/cgi-bin/formmail.pl" method="POST">
<input type=hidden name="recipient" value="yourname@yourdomain.com" />
<input type=hidden name="subject" value="FL Update" />
<input type=hidden name="redirect" value="http://www.yourdomain.com/thankyou.html" />
Important: Leave the fields you wish unchanged blank, and press submit when you are sure you want to change your information. You will need your old email address and password for this form.
<p>Your name: 
<br />
<input type="text" name="name" /></p>
<p>Your old email address: 
<br />
<input type="text" name="oldemail" /></p>
<p>Your email address: 
<br />
<input type="text" name="email" /></p>
<p>Your country:
<br />
<input type="text" name="country" /></p>
<p>Your website (optional):
<br />
<input type="text" name="url" /></p>
<p>Password:
<br />
<input type="password" name="passwordone" /></p>

Problem: I have a problem with the form that's not covered here.

Possible solution:

Read the Formmail FAQ at Matt's Script Archive, or contact your host's help section.

Questions? Comments? Suggestions? Email me.

yadda | home | contact