Developing Webs logo
Google
Web DW-Main DW-Photoshop
Visit the message board for solutions or post a question Check out the Classes offered for free at Developing Webs Voice Chat submit a tutorial, resources, article, font for publication consideration and earn a one way link back to your site Get more specifics about the Developing Webs Voice chat room and its room members View the current news at Developing Webs alternative sites which are resources for your d3evelopment needs Join Developing Webs Chat Link to us on your web page to help support this resource! Check out Developing Webs At yahoo groups! Developing Webs Home Adobe Photoshop Tutorials Macromedia Flash Tutorials Jasc Paint Shop Pro Tutorials Adobe Illustrator Animation basics Some Basic PHP tutorials Perl Tutorials HTML Tutorials Cascading Style Sheets javascript Front Page Tutorials Macromedia Dream Weaver Tutorials dreamweaver Publishing your site, FTP, ChMod, Promotions
RSS Newsfeed
for your site
DW News
Calendar
DW Forum
Right click on button and copy shortcut

Add to My Yahoo!

Reminder
Remember to book mark this site!



Request a Tutorial

Introduction to CGI

by pixelatedcyberdust 3/15/04

CGI is a module that is used by Perl to produce items that appear on your website; or even the entire website itself. CGI means Common Gateway Interface as it's the Perl interface to design on the web. CGI in itself is nothing more than a packaged Perl module for you to use as you wish. A module is recycled and a reusable snippet of coding we can use in our scripts so we don't have to type the same code over-and-over again.

When you downloaded Perl, it came with a number of modules to begin with: HTTP* and LWP* are just two of the classes, and in my opinion they're some of the most useful you can use.

Environment

CGI scripts can't just be executed on a computer that has Perl installed, the computer must be setup as a server as well. If you're not quite sure how to setup a server on your home computer, you can try to find a webhost that offers CGI capabilities.  Since CGI has been around for many years, the majority of web space providers will give you the option of having your own CGI-BIN, but bare in mind that many free web hosts will not support this feature for you.

The location of Perl/CGI can change from server to server, so our shebang line may be two different things on different sites.  The two most common are #!/usr/bin/perl and #!/usr/local/bin/perl, the first being most widely used and the 2nd often enough you should remember this location.


Outline of CGI usage

The first thing in all Perl scripts it the shebang line.  Then maybe a use warnings, use strict; short to follow. To make our script into a CGI script it really only takes one line of code.

use CGI;

We just told our script to load the CGI.pm module and created a CGI script.  Let's create a basic example of something we can make for our first web-based Perl script!

#!/usr/bin/perl

use warnings;
use strict;

use CGI qw/:standard/;

print header, start_html("My First CGI Script")'
print "This line will print on your website.";

print end_html;

We are invoking the standard method in our use CGI call.  More times than not, we'll be using this instead of the plain use CGI; line we talked about earlier.

The next line is print header, start_html().  The print header is printing out the HTTP headers for your website.  This instructs the browser what to load-- and how.  start_html() is where it all begins.  This is printing all of your beginning HTML codes (<HTML>, <HEAD>, <BODY>) for you.  If you only have the one un-defined value passed in the () on start_html, this will be used as your <TITLE> tag. You will see this after running the script above that the title of your page will read My First CGI Script

The next print line is something we've seen often enough to know it's printing to the screen.  You will notice we are using the same print ""; as we did for our command-line scripts you learned earlier.  So as you can see, it doesn't take much to convert your command-line script into something you can use on your website.

More detailed HEADER information

Along with the title, you may add other information as you would with raw HTML.  These may include background colors, meta tags, styles, etc.

print header, start_html(
                -title=>'title of the page',
               -style=>{'src'=>'/stylesheet/style.css'},
               -base=>'true',
                -target=>'_blank',
               -meta=>{'keywords'=>'pharaoh secret mummy', 'copyright'=>'copyright 1996 King Tut'},
               -author=>'name or email address of author',
               -BGCOLOR=>'red');

This may appear a little overwhelming at first to look at but in reality it's not much different than creating hashes.  Many of the special codes we can use are title, stile, base, meta, author and bgcolor.  That is HTML so we will not be discussing what these do or why you use them.  We are using the same print header, start_html( as we did earlier but we're using special parameters.

Parameters are on the left side of the => and the values are on the right ride. Look familiar? The parameter names are surrounded by - and => and the values with single tick marks (you can use quotes if you prefer).  Each parameter/value set is separated by a comma except the last one which ends the ).  You may use as many or as little of these extra codes as you want because that's what they are..they're optional.  You don't have to include the title tag if you don't want, just use start_html().


HTML PRINTING

CGI will take care of the HTTP header information for us, all we have to do is print the information we want to display. This means, you may not attach your own html, title or body tags as you will be adding them twice and this will very likely have consequences you weren't looking for.

If we wanted to print the color of our hair to your page, we could use:

print "The color of my hair is dark blonde\n";

You may also print variables along with this if you wanted to and the values will be displayed on your website.  The result of the following will be My favorite kind of jelly bean is red.

my $favorite_jelly_bean = "red";
print "My favorite kind of jeally bean is $favorite_jelly_bean\n";

This is fine and dandy for the hobbyist, but we need to use the power of HTML to spice up our page a little bit.  This includes font tags, tables, images, you name it!  If HTML can do it, CGI can too!  Let's begin with something simple, we'll rewrite the previous example but we'll add <p> tags around the line and we'll italicize our favorite jelly bean.

my $favorite_jelly_bean = "red";
print "<p>My favorite kind of jelly bean is <i>$favorite_jelly_bean</i></p>\n";

We use the same basic print ""; outline and we added the original HTML tags where we needed them.  We wrapped the entire line in <p></p> and included the <i> tag around our variable name so it would be italicized when it prints.  You can do the same with with underlines, bolds, brs, you name it.

With all the codes and print commands we generally use under CGI, they invented a way to simply the task at hand by creating heredocs.  A heredoc let's us print multiple lines of code together so we don't have to print line by line by line. So instead of doing something like:

print "<p>Perl is my favorite programming language because it's so powerful!</p><br>\n";
print "<p>It's also so cute!  It's so pretty, I would love to make it my wife!</p><br>\n";
print "<p>Maybe I should stop writing this tutorial now, the sun is going to be up soon :)</p>\n";

Into something which is a lot easier to read, write and maintain like this:

print <<"ALL";
<p>Perl is my favorite programming language because it's so powerful!</p><br>
<p>It's also so cute!  It's so pretty, I would love to make it my wife!</p><br>
<p>Maybe I should stop writing this tutorial now, the sun is going to be up soon :)</p>
ALL

A heredoc saves on typing print ""; over and over again, doesn't that make the code easier to read?   ALL is a filehandle that is typed in all caps, this can be pretty much any word you want as long as you end it with the same word.

print <<""END";
<p>Hello world</p>
END

print <<"ALL";
<p>Hello world</p>
ALL

EVERYTHING between your filehandle and the end tag will be printed, regardless of what's inside.  HTML codes, just text or even Perl code. This means that during a herdoc, you will not be able to manipulate or calculate data.  All you can do is print.  For an example, we will create an array and try to use it inside our heredoc.

my @array = ("one", "two", "three");

print <<"HTML";
<p>Hi there, everyone</p><br>
<p>Welcome to my site.</p><br>
my $value = pop(@array);
<p>The lonewolf wanders the night</p><br>
HTML

This will not work because everything between our HTML and HTML will be read and printed as text, nothing will be executed.  We thought we were storing a value in $value and popping our array, but instead of running as code it'll print as text. The solution to this problem is ending the herdoc, processing the needed code, then continue printing the rest.

print <<"HTML";
<p>Hi there, everyone</p><br>
<p>Welcome to my site.</p><br>
HTML

my $value = pop(@array);

print <<""HTML";
<p>The lonewolf wanders the night</p><br>
HTML

Since our my $value = pop(@array); is outside our print block, it'll execute as code and we'll achieve the result we wanted in the beginning.  Just remember, if it's inside a heredoc, it's text and will print as such.

First complete CGI script: Counter

Now that we have a better understanding of how to rewrite pre-existing and new scripts as CGI along with how to print blocks of code, we can look at a real world example.  The script below is a counter, if you have been following the Perl classes in Developing Webs this may appear familiar to you-- and that's great, we've used this code once already.

To use this file, you will need to have a web host that offers CGI access.  You will need to make a file called counter.txt and add the number 0 with no trailing characters or new lines.  When this is transferred, copy and paste the code below into a new counter.pl file and upload this into the CGI-BIN of your website.  Both the perl and the text file need to be in the same folder. Lastly, chmod both files to 755 or 777 so we're able to write to a file on the server.

#!/usr/bin/perl

use warnings;
use strict;
use CGI qw/:standard/;

my $file = "counter.txt";

open( LOG, "$file" ) or die "Cannot open file $!";
my $cnt = <LOG>;
close(LOG);

++$cnt;

open( LOG, "> $file" ) or die "Cannot open file $!";
print LOG $cnt;
close(LOG);

print "$cnt";

To see this script in action, we visit it in our web browser.  For an example, if our page was www.mypage.com and we placed the counter in the cgi-bin, we would type in www.mypage.com/cgi-bin/counter.pl as the URL.  When you click enter, it should display the number 1 the first time... and every time you refresh the page, the number should increase by a single number.

This is fine and dandy, but a counter should be included in our page rather than having to be a file you execute by itself.  We can use CGI for complete websites or we can include just a few lines of code in our html files. To include CGI files into an HTML document, we use SSI.  If you're not familiar with this term, you may want to hit this up on your favorite search index and read up on it's background and uses.  But to put shortly, SSI means Server Side Includes and it gives us the ability to run external scripts from a pre-built HTML document.

To use SSI, your server must allow it.  Not all web hosts do, but most of them will.  If you named the script above as counter.pl as you were asked and we wanted this to be included on our main page at www.mypage.com/index.html, our SSI would appear as: <!--#include file="/cgi-bin/counter.pl" --> .  You may place SSI tags anywhere between your <BODY> and </BODY> tags and you need to make sure the path is accurate.  We placed our counter.pl in the cgi-bin, so this would work.  If we made a folder counter inside the cgi-bin, we would be required to use: <!--#include file="/cgi-bin/counter/counter.pl" -->.

So try this SSI out and put it in one of your favorite pages on your site then load that page in the browser, it should print the number wherever you included the SSI tag.  Pretty neat, isn't it?

Counter script, explained

#!/usr/bin/perl
#This is the location to perl itself on your server

use warnings;
use strict;
# Warnings and Strict are both security modules to help protect your script. They will
# warn you if it 'thinks' you're doing something you didn't mean to or it'll flat out
# die and hopefully give you a reason or an idea on what's wrong.

my $file = "counter.txt";
# Since we're using Strict, we have to globalize the variable with 'my'. All new non-special
# system variables will have to be my'd. This is the location of the text file you want to
# read and write to. It can have folder names such as /cgi-bin/counter.txt but be sure the
# file already exists otherwise Warnings will kick in.

use CGI qw/:standard/;
# Since this is a web script (one to be used and run on a web server), we're going to need to
# use the CGI module. This module makes it easier for us to print HTML to a web page.

open( LOG, "$file" ) or die "Cannot open file $!";
# we now begin by opening a file for read-only. We open it, give it a filehandle then give it
# a file location. LOG is our filehandle, but in reality it can be any word you want: COUNTER,
# NEW or even DOG, but it's best to keep descriptive filenames.

# The location of $file near the beginning of the script. If for some reason the file cannot
# be found or opened, "or die" will kick in, crash the script and give you a reason.

my $cnt = <LOG>;
# Now that LOG is opened, we have to save its contents to a variable. Your variable name
# must be assigned to the same 'filehandle' as you called it when you opened it on the
# previous line.

close(LOG);
# The data is stored in a variable so we no longer have a need to read the file. Close it
# by closing it's filehandle.

++$cnt;
# $cnt holds whatever was contained in $file, hopefully it was a number so we can increment it.
# We are pre-incrementing (++ before the variable) so it calculates its new value before you print it
# back to the LOG file. ++ will increase the number by 1.

open( LOG, "> $file" );
# We now have to reopen the file, this time for WRITE only. We do this by adding ">" before the $file
# location. We are using the same LOG filehandle for simplicity.

print LOG $cnt;
# Printing to a file or database is a little different than printing to the screen. For the $cnt
# to be written to our text file, we have to print to the LOG filehandle. We just printed the new
# value of $cnt to file.

close(LOG);
# Since we've written the data we needed, we close the file.

print "$cnt";
# If you pay close attention, you'll see we're not printing to a filehandle. That means $cnt is going to
# be printed directly to your web page. A counter wouldn't do any good if the visitor (or you) can't have
# a visual look at the counter. This prints the current count number to your screen.

Overview

CGI is a very large module and this doesn't begin to scratch the real capabilities of it. There are two types of CGI programming, OOP (Object Orientated) and FOP (Function Orientated), I will teach the later as I've never seen the purpose to complicate code.  We learned how to setup a CGI file and print lines of text or full blocks of HTML to our browser window.  We also learned how to set a few advanced header attributes such as background colors, images, CSS sheets, etc.

Then we moved onto a real example to use; a counter, where we discussed how to install it on your site and how to use SSI to access the script from any document on your site.  You should now have a better understanding of web-based Perl programming, better known as CGI. There is so much more to learn, but hopefully this serves as a good introduction.

If you wish to continue your ventures on CGI, you may want to look at the actual documentation for it found here.

Challenge Questions

1) What do CGI and SSI stand for?

To view the solution, highlight between the lines below:

------------------------------------------------------------------------
CGI- COmmon Gateway Interface
SSI- Server Side Include

------------------------------------------------------------------------

2) What is wrong with the following code?

my $favorite_number = 11;

print <<"ALL";
<p>  My favorite number in the whole world is the number $favorite_number.<br>
It's such a great number, it's the day I was born and some people find the number<br>
$favorite_number to be very lucky.

my $results = $favorite_number * 3;

<p>Did you know that if you multiply this number by three, you get $results??

ALL

To view the solution, highlight between the lines below:
------------------------------------------------------------------------
You are trying to process/execute information while inside of a heredoc statement.  Anything found in a heredoc will print as text, so running this script won't crash on us.. but my $results never gets calculated
------------------------------------------------------------------------

 



"Building The Web Into a Nicer Place -- One Site At A Time"
Developing Webs Group Copyright © 2001-2024 All Rights Reserved
Privacy and Legal