Introduction and Preparation
You have made a site in FrontPage and you are happy - for a while. Then there are things you want to add and you discover that FrontPage cannot help. People keep telling you about this script and that one that will do what you want but Perl...cgi...FTP...SSI... these are foreign terms. Where on earth do you start?
Right here.
In this tutorial we are going to guide you through the steps involved in setting up a cgi script and integrating it into your site. Not in theory, but in practice using a script that will automate the running of polls at your site. Even if you already have some sort of a utility that does this you can still follow along and add this to a test page in your site. This installation will involve you in all of the basic steps needed to install any script, once you have successfully completed this one there will be no problem moving on to other and more complex scripts.
A Few words about Perl and CGI
First the good news: you do not need to know anything at all about Perl or CGI to begin installing and using scripts. These tutorials will assume you know absolutely nothing. However it is no harm to have at least a basic understanding of what is going on when you use Perl/CGI on your site.
Perl and CGI, though the terms are often used interchangeably, are not the same thing. CGI stands for 'Common Gateway Interface' and describes a method by which data is passed from a user to some program for processing and then back again to the user. To put it simply let's look at the example of a user poll on a web page.
A user of the page votes in the poll
The user's input is passed to a program
The program records the vote and adds it to all previous votes
A page is served which shows the user the result of the poll so far.
The interaction between the user, the program and back to the user again is handled using CGI.
The program that does the work could be written in any of a number of languages but the most commonly used one is Perl. Perl and CGI work very well together and there are a huge number of ready-made scripts, or programs, available which make use of this Perl and CGI to provide a range of utilities for use on websites.
And that, really, is about it. So, lets begin.
The first thing you need to do is ensure that you have everything you need for an installation and that your host provides support for this sort of script.
What you need to use Perl scripts
One of the advantages of Perl scripts is that they need very little in the way of specialized features on your server. Just about everyone on a Unix type server will be able to use them, and many scripts (including our sample script) will also run happily on NT servers. However a quick review of what is required before you begin will avoid problems later.
What you need on your computer
1. An unzipping utility - eg WinZip
Most cgi scripts in fact consist of a number of interlinked scripts and configuration files and often HTML and text files also. They are usually made available for download as a zip file and you will need a way of unzipping them.
You can download an evaluation copy of WinZip here: http://www.winzip.com/ddchomea.htm
A single user license costs $29
2. An FTP client - eg WS_FTP
Files that are part of a cgi script should never be published from within FP, they need to be uploaded using FTP. To do this you will require an FTP client.
You can download an evaluation copy of WS_FTP here: http://www.ipswitch.com/cgi/download_eval.pl?product=WS-0000
There is a shareware version available free to educational users, government employees (U.S. local, state, federal and military) or to non-business home users only. A single user license for the pro version costs $39.95
During this tutorial we will refer to WS_FTP but if you already have another FTP client the procedures will be pretty much the same. If you have not used an FTP client before please take some time this week to have a look around at it and become familiar with its basic interface. There are good introductory tutorials about installing and using WS_FTP here: http://www.ftpplanet.com/tutorial/
3. A text Editor
Notepad will do fine or you can use whatever text editor is your favorite. Scripts should not be opened and altered in FrontPage.
CGI/Perl scripts run on most Unix servers, though the one we have chosen is suitable for use on NT servers also. However these instructions refer to Unix type servers.
You need to find out the following about your server:
1. Can you run Perl Scripts?
Most hosts allow scripts to be run, a few do not. You should be able to find this information on your hosts support pages.
2. Where should your scripts be uploaded?
Most hosts require that scripts be placed in a specific directory, usually called either cgi-bin or cgi-local. This directory will probably have been created for you when your site was set up initially, you can FTP in to your site to see if it is there and what it is called or ask your host if you are unsure.
Please note:
3. What is the Path to Perl on your sever?
In order to function your script will need to know where to find Perl, the set of code instructions that allow it to function.
The first line of all scripts is something like this:
#!/usr/bin/perl
or
#!/usr/local/bin/perl
This line is vital and it tells the script where to find Perl on the server. Your host support pages will probably tell you which is appropriate on your server, if not, contact them and ask them what the 'path to Perl' is.
4. Your Server File paths
There is often confusion between file paths and URLs so we will deal with that here in some detail and give you a chance to get familiar with the concept. One of the biggest causes of problems when uploading CGI scripts is getting the server paths wrong, so if this is new to you read and reread this section until it starts to make some sense to you!
We are all familiar with the structure of URLs, for example:
http://www.thesite.com/directory/subdirectory/file.htm
A browser will use this information to find the page file.htm and display it. However the server sees things rather differently in its internal functioning and finds files using the server path. The server path consists of two parts:
a. The path to the root directory of your site on the server.
The exact path will vary from server to server but will look something like this:
/usr/www/yoursite/
Again the exact paths may be available on your hosts support pages or you can email them and ask. Another way to find out is to FTP in to your site. Once your site opens in the FTP client you will see the server path displayed in the location window.
b. The path to the actual file or directory within your site.
This will be the same as whatever comes after your base URL - so using the example URL above the full path would be something like:
/usr/www/yoursite/directory/subdirectory/file.htm
It is very important to understand the difference between URLs and paths. When we come to configure the script we will need to use server file paths to tell it where to find files on your server.
Please note that forward slashes are used, not back slashes as in the file system on your computer.
5. Acceptable file extensions
Perl files use the extensions .pl or .cgi, often interchangeably. While most servers allow either to be used, some insist on one or the other. Again you need to know if this is the case on yours.
Often the extensions are interchangeable, so if a script is called script.cgi you can rename it script.pl and no harm done. However you will need to record this somewhere during the configuration of the script (next week!) so find out about it now.
I know that much of this will seem like double Dutch to those of you who have not worked with scripts before but please do not panic, as we work through installing our script over the next couple of weeks it will all become clear. In the meantime you might like to copy this short email (or whatever parts of it are appropriate) to your host and get all the information you need in one place.
<---Begin email----->
Please could you give me the following information about my site: http://www.yoursite.com.
1. Am I allowed to run Perl Scripts?
2. What is the name of the directory in which they should be installed?
3. What is the path to Perl?
4. What is the file path to my root directory?
5. What file extensions are allowed: .pl or .cgi or both?
<---End email----->
In the next part of this tutorial we will look at how to find, select and evaluate scripts, we will download one and then configure it for and upload it to your server.
Finding and Evaluating a Script
There are a vast number of sites out there offering Perl scripts, free and otherwise, that will do pretty much anything that you could imagine on your site. Many are very good, functional, reliable and secure but there are also some poor quality scripts available that will give you nothing but grief and may even represent a security threat to your site or its users. How do you sort the wheat from the chaff?
When you go to a site that supplies a script you like there are a few ways of satisfying yourself that it is a good one from a reliable source.
There should really be a working demo available or links to examples of the script running on an actual site, if you cannot see the script in action hesitate to pay for it, though it may be worth downloading and trying a free one.
Is there any support available at the site? Read whatever FAQs are there or visit the forum if there is one. Some of these forums are active and useful, others are full of lost souls struggling with scripts and failing to get any answers.
Is there free email support with the script? This is a little much to expect with a free script but if you are paying you should get some level of support after buying.
Is there an installation service? Not of course that you will need it by the time we are finished here, but it is a good indication of there being live support if such a service is offered. Some sites even offer free installation with their scripts but remember this will involve you giving FTP access to your site to strangers, so it is always best to install yourself if possible.
Does the script actually do what you want? Check out its features carefully, email for further information if you are unsure. There should be some form of money back guarantee or the ability to download and install a trial version before paying if the script is not a free one.
Finally, and perhaps most importantly, get recommendations. You can always post at OutFront to see if anyone has experience with a script you are considering or contact the owners and ask for references from other users.
Some good places to look for scripts
http://www.hotscripts.com/
http://cgi.resourceindex.com/
http://www.cgi-world.com - source of our sample script and some other really great scripts
Downloading the Script
The script chosen for our installation is a user poll script from http://www.cgi-world.com/. We used all of these criteria in above when looking for a script for this tutorial and came up with this one.
This one was chosen partly because it is free and compatible with older versions of Perl, so everyone can have a go at installing it, but also because it has wide appeal and is from a very reliable source of quality scripts. CGI World are creators of a range of very useful and high quality scripts, several of which I have personally used, and they provide excellent, prompt and helpful support.
Before you download
Make a new folder in My Documents, or wherever else suits you, and call it Poll Script. Unzip the script to this folder when you have downloaded. Also take a few minutes to read about the script at the CGI World site.
You can read about and download the script from here:
In the next part of this tutorial we will take a look at the script and configure it for your server.
Configuring and Installing Your Script
Most scripts comprise a number of files in addition to the actual Perl scripts, image files, text files, html files and so on, that work with the script to display your pages. In this case you have in the main folder the following files (the ones we will be uploading and working with are in red):
image.gif
INSTALL_Poll_It_v2.05
LICENSE_Poll_It
Poll_It_SSI_v2.05.cgi
Poll_It_v2.05.cgi
pollit_files Folder
The text files are used to store information about your polls and display it to users. If you open them now they will be blank, this is as it should be.
The HTML files control how your polls will look on your site. When we come, next week, to customizing your script for your site we will look at the possibilities of editing some of these but for now just leave all the files in this folder as they are.
Configuring the Script
The only file you need to configure is the Poll_It_v2.05.cgi, so open this in Notepad or whatever text editor you will use. NOT in FrontPage!
I will be installing on my server at http://www.inkkdesign.com so will use that as the sample for the configuration steps below. Obviously you will replace your URL for mine.
Configuration Steps
1. The Path to Perl
This is the very first line of the script and reads:
#!/usr/local/bin/perl
You should know the path to perl on your server after last weeks article, if this is it no change is needed. If your path is:
#!/usr/bin/perl
edit this line carefully to read correctly.
2. Editing Variables
These variables tell the script about things that are specific to your server, your site or which are dictated by your own preferences. Variable names in Perl are indicated by the $ sign - never edit names these in any way. The only bits you edit are after the = sign. You must also be careful to retain the parentheses and the semi colons in the variables intact. There are just a few to specify here:
a. $admin_password = "protection";
Choose whatever password you like, but do change it from the default. Make sure you leave the parentheses intact and use only letters and numbers. Maybe I used the password below, maybe I didn't!
$admin_password = "abbeyvet";
b. $image_url = "http://www.your-url/image.gif";
This is where you need to specify where on your site the image that came with the script will be placed. The easiest thing to do is place it in the main images folder at your site. So you would amend this variable to read (in my case):
$image_url = "http://www.inkkdesign.com/images/image.gif";
c. $vote_text = "Rock the Vote!";
Simply the text that will appear on the button to allow people to vote.
$vote_text = "Vote Now!";
d. The final three variables are just for text that will appear in your poll pages:
$last_poll_text = "<LI>View our Previous Polls Results";
$results_not_available = "<BR>The results will be posted soon...";
$poll_not_available = "<BR>Currently there is no opinion poll available...<P>Check back soon for another poll...";
When a variable contains some HTML tags, as these do, you should be very careful not to disturb it when you edit the variable. You can add additional HTML but do not do so for now. I did not edit these variables at all; you can change the wording if you wish.
That's the configuration taken care of - now lets get it up there and working!
Uploading your Script
These instructions assume you are using WS_FTP, if you are using another FTP client the procedure will be much the same.
1. Fire up WS_FTP
In the Local System window - on the left - navigate to your script files on your local computer.
2. In the Remote System window - on the right - navigate first to your images folder. Making sure you have Binary mode selected (below the two file windows) select the files image.gif from your computer and upload to your images folder.
3. IMPORTANT: Change the upload method to ASCII once this is done. Perl scripts MUST be uploaded in ASCII format.
4. Navigate to your cgi-bin directory, whatever it is called. In my case it is called cgi-local. Make a new directory in the cgi bin by selecting 'Mk Dir' on the right of your screen and call it 'poll' - note lower case. Double click on this new directory to open it.
5. Upload the file Poll_It_v2.05.cgi to the 'poll' directory.
6. Inside the 'poll' directory make a new directory, as above, and call it 'pollit_files'. Open it.
7. Upload all the files in the 'pollit_files' directory on your computer to the new one of the same name on the server.
That's it - your script is on your server. Now you need to set permissions for it. Oh no! I hear you say - this is the tricky bit! Well, tricky perhaps if you have not done it before but it is not difficult if you just take a few minutes out to learn how it works.
Setting Permissions and About CHMOD
This is the part of installing scripts that causes most angst for Newbies, so we will take a moment to look at the whole issue of file permissions before doing anything to our script.
You can give three levels of access to any file:
Read access: The file can be read.
Write access: The file can be written to
Execute access: The file can be executed.
In the chmod system these levels of access are given numerical values as below:
Read access = 4
Write access = 2
Execute access = 1
The levels of access allowed to any file is expressed as the sum of these values. Eg:
Read and Write: 4 + 2 = 6
Read Write and Execute: 4+2+1=7
Read and Execute: 4+1=5
... and so on.
You can also allow different types of user different levels of access. The three types of users are
Owner
Group
Other
In general Group and Other can be taken to mean the world in general, the Owner is you - the person running the script and your server.
A permission of 755 would mean:
Owner: Read, Write and Execute (4+2+1=7)
Group: Read and Execute (4+1=5)
Other: Read and Execute (4+1=5)
A permission of 644 would mean:
Owner: Read and Write(4+2=6)
Group: Read (4)
Other: Read (4)
644 is in fact the default for HTML files - you can read them and write to them, your users can just read them.
Setting permissions for our Script
Setting permissions in WS_FTP is simple, just right click the file and you are presented with a dialogue box which allows you to tick off the relevant permissions.
Do this for each of the following files and directories in our script.
Poll_It_v2.05.cgi
Chmod 755, that is:
Owner: Read, write and Execute
Group and Other: Read and Execute
Files in the pollit_files directory
1. All files ending in .html:
The moment of truth!
If you have followed along until this point your script should now be installed and functional.
Open this URL - replacing your own sites details obviously, or check out the poll running at my site first if you would like to see the script in action!:
http://www.inkkdesign.com/cgi-local/poll/Poll_It_v2.05.cgi
and you should see a message telling you there is no poll available. Open this URL and login using the password you specified to start creating one!
http://www.inkkdesign.com/cgi-local/poll/Poll_It_v2.05.cgi?load=login
Having Problems?
If you have any problems along the way with this installing this particular script please use the forums to ask questions, a thread was started specifically to deal with any issues that arose while following this tutorial, you may find the answer to your problem there.
For general script problems it is best to look first at the site where you got the script, perhaps they have a forum or an FAQ page, or they may provide email support.
Having said that the most common problems that arise in relation to scripts are:
Incorrect file names or file paths.
Remember that Unix servers are case sensitive - make sure you have named all files and folders properly.Incorrect Permissions
Read the section on setting permissions above and double check that you have everything rightIncorrect Path to Perl
Are you sure you configured this correctly for your server?
In the final part of this tutorial we will have a look at customizing this script to suit the appearance and structure of your site.
Customizing your User Poll
The poll is installed and it looks fine, it just doesn't look like your site. Generally you will want to alter the poll's appearance so that it fits seamlessly with your existing design. Fortunately this is very easy to do, but there are a few little things to look out for.
You have two options for integrating the poll.
1. Non-SSI
In this case the poll will have its own page, which you can customize to look exactly like any other page in your site. This is a good option for anyone who cannot use SSI or .shtml extensions on their server.
There is a sample of my customized installation here: http://www.inkkdesign.com/cgi-local/poll/Poll_It_v2.05.cgi
2. Using SSI (Server Side Includes)
Using this option the poll is fully integrated within another page on your site. This is probably the method preferred by most.
There is a sample of an poll integrated using SSI here:
http://www.inkkdesign.com/pollit.shtml
Note that there is nothing to stop you using both methods on the same site and with the same poll. For example you might want to have the poll included by SSI on your home page but also put a link elsewhere in your site that allows users to go to a specific page to vote.
Customizing a Non-SSI Poll Installation
This script uses HTML templates to display the poll and the poll results so we will need to edit both of these template files so that they look more like your site.
The files are both in the pollit_files directory wherever you unzipped the script to. The two we need are:
_poll.htm
_last_poll.htm
There are many ways to go about editing these but this is the way I find quickest and easiest. It may seem like an involved process but it really does not take very long.
1. In your web do File>Import and import both files to your web.
2. Right click each and rename it so that the underscore at the start of the name is removed. If you do not do this you wil be unable to open the file.
3. Open poll.htm. What you have is a pretty standard, if plain html file. You can edit the colors, table widths, fonts etc here in the same way as you would any other file, but you need to be careful.
It is essential than none of the markers - eg the words surrounded by $ signs - are deleted, they are what make the page work. You can resize the $marker$ text, change its color, its font or its alignment but do not delete it.
4. When you are happy save the file. Repeat steps 1-3 for _last_poll.htm
5. Now open any page in your site and save as a template - call it perltemplate.htm. What we are going to do is set up this page so that we can past the actual poll tables into it. The first thing you need to do is remove any text on the page so that you have a fully styled template with no content. There are a few things you need to do to make sure this page will work.
a. This will not be a FrontPage file - it will be part of a script and will be FTPed, not uploaded. Therefore you must remove all FP features such as include pages or navigation components and replace them with none FP alternatives - eg plain text or a JavaScript navigation.
b. You need to change all the urls in the HTML from relative to absolute. Links, image paths and so on must all be changed.
For example if you have a link to your home page that reads <a href=index.html> this must be changed to <a href=http://www.yoursite.com/index.html>
Similarly if you have an image called using <img src=/images/image.gif> it needs to be amended to <img src=http://www.yoursite.com/images/image.gif>
This is a bit tricky if you are unused to editing HTML, but stick with it, it is not that bad! Just go carefully through your html replacing the urls one by one.
6. When you are satisfied that step 5 is complete save the page.
7. Open poll.htm again. If you go to html view you will see that between the <body> and </body> tags there is just one large table. Highlight it and copy it. Close the file.
8. Back at your template, decide where you want the poll to go and type the word 'Here'. Highlight 'Here' and switch to HTML view. Replace the word 'Here' with the table you copied to your clipboard.
9. When you go back to normal view your poll should be neatly integrated into the page. Make any final edits you like to it - you may need to alter the table widths for example. When you are happy do File>Save As and save the file as _poll.htm
10. Open your perltemplate.htm file again and repeat steps 6-9 to create a using the table in last_poll.htm and saving the file as _last_poll.htm
11. Fire up your FTP connection and upload your new _poll.htm and _last_poll.htm files replacing those on your server and you are done.
Housekeeping note: You can either delete all the files left hanging around your site on your local computer after doing all this or place them in a folder marked not for publication. Otherwise they will all be published next time you publish your site, not a problem but messy! I find it handy to keep the perltemplate.htm file - you never know when you will be using another script that will need something similar.
Customizing an SSI Poll Installation
There are three stages in this process, uploading an additional script, editing a template and placing the poll on your page.
Configure and Upload the Perl Script
The first thing you need to do here is configure and upload the poll_it_SSI_v2.05.pl file.
1. Open the file in Notepad or the text editor of your choice. Edit the path to perl and the two variables; this should be easy after last week!
2. Upload to the main poll directory and chmod 755 (Owner: read, write and execute, Group and Other: read and execute)
Ok, that's that bit, now the customization.
Edit the Template
1. Import the file _ssi_poll.htm (in the pollit_files directory) into your web. Rename to ssi_poll.htm so that you can open it. Once open change the styles, table width, colors and so on as you wish again being careful not to delete any of the markers.
2. When you are happy save the file, rename back to _ssi_poll.htm and upload to your server replacing the file of the same name there.
Finally, getting the poll into your page.
Include the Poll in a Web Page
Quite often you will want the poll on a home page, but if you have not used SSI before it might be a good idea to test it on another page first. Your call.
1. Open the file you wish to place the poll in, decide where you want the poll to appear, type the word 'here' and highlight it.
2. Switch to HTML view and replace the word 'here' with
<!--#exec cgi="path/to/Poll_It_SSI_v2.05.cgi" -->
You need to edit this bit:
"path/to/Poll_It_SSI_v2.05.cgi"
to reflect the location of your cgi bin. In may case the result was:
If you started this series never having installed a Perl script and you now have one working then well done! You have passed through a door to a world of possibilities. Anyone spending a few minutes browsing the Perl scripts somewhere like http://www.hotscripts.com is sure to find at least a couple of scripts they could use right now.
What are you waiting for - go get 'em!
<!--#exec cgi="cgi-local/poll/Poll_It_SSI.cgi" -->Note: You will see nothing when you switch to normal view - the page must be read from the server for the include to appear, so don't panic!
3. Now save your file with an .shtml extension. So if it was previously file.htm, rename to file.shtml.
4. Publish your web to see if it is all working.
Problems?
If the poll is not appearing on your page you will see instead an error message [An error has occurred while processing this directive]
This is almost invariably because the path to the file in
<!--#exec cgi="cgi-local/poll/Poll_It_SSI.cgi" -->
was incorrect. Double check this.
So there you are, a fully integrated poll for your site. chmod 644, ie
Owner: Read and Write
Group and Other: Read
2. All files ending in .txt:
chmod 666, ie
Owner, Group and Other: Read and Write This is an image that is used to display your user votes in an attractive manner. This is a text file containing installation instructions. For the moment ignore this - use our installation instructions instead, especially if this is your first installation. The license, which you should read. If you are having problems opening this choose to open it in Notepad. A Perl script file that allows you to include your poll in an existing page using Server Side Includes. Since we are not going to do that, initially anyway, you can ignore this one for the moment. This is the script that will make it all happen! There is also a folder called pollit_files containing a mixture of HTML files and text files. Once you have downloaded and unzipped the script take a few minutes to look at the files you received, which should now be in your Poll Script folder.This directory will not exist in your FP web on your own computer and you do NOT need to create it.
What you need to know about your server
discuss this topic to forum
