HTML Goodies: PERL Primer, Part 3

…use these to jump around or read it all

     I’m starting with a guestbook script because this is an effect that can be done with a very small amount of PERL code. In addition, the script shows PERL’s ability to be modular very well.

     The script will do three things:

• Accept and delineate the information sent to it by the HTML form.
  
• Send an email letter containing the form information
  
• Post a virtual thank you page
  

     We’ll take each of the three modules in order over the next three Primers, but first let’s take a look at the effect:

     OK, it’s not that big a deal right now, but by the time we’re done with it, you’ll understand it to the point where you can make it do so much more.

The Guestbook HTML

     The easy part is the HTML. It looks like this:

     Just copy and paste it right from the page. You’ll want to make two changes to the code. The first is the path following ACTION=. You need to alter that to reflect the path to your cgi-bin and then the name of your PERL script. I called mine guestbook.cgi. You can change it to whatever you’d like, but change that here.

     It’s up to you if you want to use the full URL starting with http://. You can. It won’t hurt anything, but since you’re running this page off of the same server as the PERL script, you can eliminate the server domain by just using a starting forward slash.

     The second thing you need to change is the email address in the hidden input box. That’s the one that looks like this:

<INPUT TYPE=”hidden” NAME=”submitaddress” VALUE=”jburns@htmlgoodies.com”>

     I have it set right now to my own address. You need to change that out to reflect the email address you want the script to send mail to or else I’ll be getting all your mail. You don’t want that.

     DO NOT change any of the NAME values in the form. They must stay as they are written. You’ll see why soon.

The Script

     First off, you need to know what extension your server allows. PERL scripts will either use the extension .pl or .cgi. Every server I’ve been on wanted .cgi, a couple would take either one. My suggestion is to either ask or to simply download the script and save with both extensions. If one doesn’t work, the other will.
Try the .cgi first.

     Here’s the script. You can copy and paste it right from the page. The bold print is commented out. It won’t affect the performance.

     Now that you have the script, paste it into a text editor that does not have margins, and save it. It’s ready to go. Don’t alter its text or shape in any way.

     Save a back up just to have a clean copy. You’ll thank me later for this tip.

Post It!

     OK, we’ve got the parts. You’ve altered the HTML to reflect your path and email address. Let’s post the files.

     FTP the PERL script to your cgi-bin as text. FTP the guestbook HTML to your Web directory also as text.

     Set these permissions:

     Test it out. You should get the same guestbook effect you just saw above. If not, check the path to the CGI. If that is correct, check the PERL error log. My guess is that you altered the shape of the PERL script somewhere along the way. The log will tell you what line is messed up.

Grab the Form Data

     Now we begin tearing the script apart. We begin at the very top with the path and then the module that grabs and processes the form data.

#!/usr/bin/perl

    foreach $pair (@pairs) {

       ($name, $value) = split(/=/, $pair);

       $value =~ tr/+/ /;

       $value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack(“C”, hex($1))/eg;



    }

     That first line is the path to PERL on the server. That must correct for your server. That goes first in the script, always, no exceptions.

Comments

     I have eliminated the two comment lines shown in the script code to make the display here a little nicer. They’re printed in bold in the script display. Notice each begins with a pound sign (#). That’s PERL for a comment.

     Any line that begins with a pound sign is simply text for the
reader to view. The line will have nothing to do with the program and will be ignored by PERL.
Just be very sure that the comment only goes the one line. If the text jumps down to a line that doesn’t start with a pound sign, PERL will assume it’s part of the script, not understand it, and throw an error.

What Is This Code’s Purpose?

     This small block of code does two things. It accepts the form data and delineates it into individual pieces of data represented by the NAME on the HTML form. That’s why you can’t alter those names just yet.

     Please understand, this gets a little rough. Don’t let it throw you, stay with it and keep reading. It will all come full circle. I know how it ends – I wrote it.

     OK! Time for your first term. The first line in the code is

     That dollar sign represents what’s known as a scalar variable. It’s a single variable name that is assigned some information. We could actually write the line:

$name = “Joe Burns”

     Now the value “Joe Burns” can be called for just by using the variable.

     Keep in mind that the HTML form is first contacting the script, not the other way around. When your user sends the form by clicking the submit button, the form attempts to contact the script.

     Stay with me here, this gets a little goofy. When the form is sent, everything about that form arrives in one big block. That block is assigned to the variable $ENV. Inside that block is text that looks something like this:

     The first line is asking a question. It wants to know if the form that is contacting it is using the request method POST. The command eq means “equals”.

     Notice there is a curly bracket following the line. Those curly brackets surround all of the commands that should happen if the request method does equal POST. You see the end curly bracket after the last line of the module.

     Here is the next line:

     This line reads the CONTENT_LENGTH sent by the form and assigns it to be STandarD INput. See that above? The command STDIN represents this text as standard input text and assigns it to the variable “$buffer”

     The text that was sent from the form showed up in what I’ve heard referred to as “Webby”. Those of you who have put together a basic mailto guestbook before have probably already seen it. It looks something like this:

     The next line basically “cleans up” the text represented by $buffer:

@pairs = split(/&/, $buffer);

     The “@” before the word “pairs” means “array” in PERL. What this line is doing is breaking the line above into an array starting new lines at the & inside of “$buffer”. After this, the content that was in $buffer is now assigned to @pairs and looks like this:

NAME=Joe+Burns

EMAIL=jburns@htmlgoodies.com

COMMENT=I+like+this+page

     The next blip of code cleans the text further:

foreach $pair (@pairs) {

($name, $value) = split(/=/, $pair);

$value =~ tr/+/ /;

$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack(“C”, hex($1))/eg;

     The code states that for each (foreach) of the array lines represented by @pair, we split the line at the equals sign setting the name and the value to the variables $name and $value. See that above?

     Now we need to get rid of any plus signs or % signs inside of the text. The last two lines look for that. The operator =~ looks for elements that equal something. In this case, the plus sign. The second line does the same for % signs.

     The last line sets the variable/value relationship in stone:

$FORM{$name} = $value;

     Now, the rest of the way through the script, we can call on each of the elements from the form in this manner:

• $FORM{‘name’} – This will represent the value the user put in the HTML input box with the name “name”.

  
  

• $FORM{‘feedback’} – This will represent the information written to the textarea box.
  

     We’re done. We have gathered the data from the form and delineated it so that the FORM information is set to scalar variables named after the NAME attributes in the form itself.

     Don’t be thrown by this code. I know this one was a little rough. They get easier from here. In Primer Four, we begin to play with the email!

On to Primer Four…