Installation Documentation
MATCHMASTERS PRO

Preleminary Material for review

System Requirements

Preliminaries

  • Determine the path to PERL 5 on your web server host.  Note that some web hosting companies run both PERL 4 and PERL 5.  Make ABSOLUTELY sure you are not setting this up under PERL 4.  Ask your administrator if you are not sure.
  • Download the tarfile for this program and save it to your desktop. 
  • Unpack the tar archive on your desktop using a program that unpacks UNIX TAR ARCHIVES. If you don't have such a program then download WINZIP FREE from SHAREWARE.COM
  • After you have unpacked the TAR archive you will have a collection of folders and files on your desktop.  Now you have to do some basic editing of each of these files (or at least some of them).  Use a text editor such as wordpad, notepad, BBEdit, simpletext, or teachtext to edit the files.  These are NOT WORD PROCESSOR DOCUMENTS they are just simple TEXT files so don't save them as word processor documents or save them with extentions such as .txt or they will NOT WORK.   Note that there may be a some files inside of folders which are "blank".   This is normal.  If a distribution contains "blank" files please make sure you open each one and clear out any spaces, invisible characters and especially any blank lines that are contained in the files before using them.

Preparing the CGI scripts

Define Path To PERL 5

The first step is to open up each and every file that has a .cgi extention and edit line number one of each script.  Each of the cgi scripts is written in perl 5. For your scripts to run they must know where perl 5 is installed on your web server. The path to perl 5 is defined to a cgi script in the first line of the file. In each of the cgi scripts the first line of code looks something like this:

#!/usr/bin/perl

If the path to perl 5 on your web server is different from /usr/bin/perl you must edit the first line of each cgi script to reflect the correct path. If the path to perl 5 is the same no changes are necessary. If you do not know the path to perl 5 ask the webmaster or system administrator at your server site.  

Organizing the files

Create the following directory structures and upload the files from the tarball as follows below

/matchmasters/    (the default user interfaces for using matchmasters)

  • register.html    the page new members use to register their profile
  • login.html        members must login here in order to search, upload, etc
  • search.html     interface used by members to search the database
  • menu.html       member menu that links to the other pages in this directory
  • modify.html     allows members to modify any or all of their profile
  • upload.html     page used to upload member photo
  • forgot.html      page used if a member forgets their password

/matchmasters/pix/    (the default images used by the system - you can make your own if you want)

  • pic.gif
  • nopic.gif
  • mail.gif
  • matchbot.gif
  • modify.gif
  • search.gif
  • upload.gif
  • view.gif

/matchmasters/memberimages/    (nothing goes in here but chmod this directory to 777, this is where member photos are uploaded to)

/matchmasters/admin/  

  • index.html    (admin panel)

/cgi-bin/matchmasters/    (chmod everything inside to 755)

  • add.cgi                             register.html links to this (new member registration cgi)
  • configure.cgi                     configure.cgi used for the entire system
  • retrieve.cgi                        this script allows members to retrieve matches from previously entered search profiles
  • search.cgi                        search.html links to this (also creates searchprofiles for retrieve.cgi)
  • profile.cgi                         gets details of a members profile from the search results
  • modify.cgi                        used to modify members information linked to modify.html
  • login.cgi                           login script (login.html) used to access the member features
  • upload.cgi                        causes photos to be uploaded into the /matchmasters/memberimages/ folder
  • bookmark.cgi                   allows members to bookmark other members for later
  • cgi-lib.pl                           library of routines used by the system
  • deletemail.cgi                   deletes private messages from the members email list
  • viewbookmarks.cgi            view bookmarks members have created
  • deletebookmark.cgi           deletes a bookmark from the members bookmarklist
  • writemail.cgi                     brings up the "send email" screen
  • readmail.cgi                      allows members to read private messages sent to them
  • sendemail.cgi                   sends email to members (linked from the "send email" screen)
  • forgot.cgi                          linked to forgot.html (forgot password script)

/cgi-bin/matchmasters/data/       (chmod this directory to 777)

  • header.html           This is the customizable header.html that goes on all the cgi generated pages
  • footer.html             This is the customizable header.html that goes on all the cgi generated pages

/cgi-bin/matchmasters/searchprofiles/       (nothing goes inside here but chmod this directory to 777)

/cgi-bin/matchmasters/admin/       (chmod everything inside to 755 and password protect this directory)

  • admin.cgi                          allows admin to edit, login, or delete members
  • bulkemail.cgi                     script which runs by crontab to bulk email all members
  • configure.cgi                      exact same script used above (copied)
  • count.cgi                           counts number of members in the system
  • match.cgi                          not currently supported - will be added in next upgrade
  • quemail.cgi                        sends command to prepare bulk email message to send out
  • killmail.cgi                         cancels the bulk email scheduled
  • adminmodify.cgi                 allows admin to modify members profile information

Configure.cgi

Several variables to set inside of configure.cgi most of which should be pretty obvious (just paths and urls).  Couple worth mentioning are noted below.

  • $mailprogram = "/path/to/sendmail";
  • $yourdomain = "http://www.yourdomain.com/path/to/matchmasters";
  • $mysqldatabase= "name of your mysql database";
  • $mysqlusername = "your mysql username";
  • $mysqlpassword = "your mysql password";
  • $adminemail = "matchbot\@yourdomain.com";    DO NOT REMOVE BACKSLASH BEFORE THE @ SIGN
  • $cgi_lib'maxdata = 100000;      this is the number of bytes you will set as the maximum image size a member can upload
  • $cgidirpath = "/full/path/to/cgi-bin/matchmasters";   FULL PATH
  • $memberimagesfolderpath = "/full/path/to/html/matchmasters/memberimages";    FULL PATH
  • $datadirectory = "/full/path/to/cgi-bin/matchmasters/data";    FULL PATH
  • $searchprofiles = "//full/path/to/cgi-bin/matchmasters/searchprofiles";    FULL PATH
  • $htmlURI = "/matchmasters";     NOTE this is a U R I (not URL)
  • $cgiURI = "/cgi-bin/matchmasters";    NOTE this is a U R I (not URL)
  • $pixfolderURI = "/matchmasters/pix";    NOTE this is a U R I (not URL)
  • $memberimagesfolderURI = "/matchmasters/memberimages";    NOTE this is a U R I (not URL)

Upload Your Edited CGI and Database Files

  • Edit the configure.cgi file
  • Upload the files as described above
  • Set all .cgi files permissions to 755
  • Set all directories (searchprofiles, memberimages, data) to 777
  • Upload all the files into the /cgi-bin/matchmasters/data/ directory and chmod them all to 777 (bulkmail.txt, header.html, footer.html)
  • Password protect the /cgi-bin/matchmasters/admin/ folder so nobody can screw with the admin functions
  • Upload all the text files as ASCII but upload all the PICTURES/IMAGES as BINARY DATA
  • Upload the .sql file into your mysql database (review mysql tutorial - see above) if you do not know how, or better yet - bug your isp and get them to do it.

Edit and Upload Remaining HTML files

Edit all the html files to make sure the form action tags point to the correct cgi url.  New members start off by filling out the register.html (registration form).  After they have registered they will have to login (login.html) to use any of the features of the program. 

  • http://www.yourdomain.com/matchmasters/register.html   The newbie registration page
  • http://www.yourdomain.com/matchmasters/login.html   Where members (after registering) login to search and stuff
  • http://www.yourdomain.com/matchmasters/forgot.html   Members can have their username/password sent by email if they forget it
  • http://www.yourdomain.com/matchmasters/search.html   Search page (members must login to use)
  • http://www.yourdomain.com/matchmasters/menu.html   The menu page linking to all the features (search, upload, bookmark, etc)
  • http://www.yourdomain.com/matchmasters/upload.html   Page that allows logged in members to upload photos
  • http://www.yourdomain.com/matchmasters/modify.html   Page that allows logged in members to change their profile

http://www.yourdomain.com/matchmasters/admin/index.html   The admin panel

Send newbies wanting to register to the register.html page.  If you want to let people REGISTER for FREE but PAY to search/etc then simply password protect the rest of the html files and use your password gateway software to control access to the password file.  Matchmasters does not use a built in password system because it was designed to easily integrate into any 3rd party billing system such as mastergate/etc.  Some people like to allow FREE registrations but want to CHARGE a fee for searching/etc.  This is easily done by password protecting the directory containing the login.html, search.html, etc pages with .htaccess and using your billing software of choice to control password access to these files.

You will want to also provide a link to the login.html page from the main page of your website so when someone returns to the site they can easily login to search, upload photos, etc.

You can also customize the "cosmetics" of the search.html, login.html, etc pages very easily now.   Make sure you DO NOT ALTER THE FORM FIELDS OR FORM STRUCTURE THOUGH.  This will cause the system to fail. 

Mass Emailing the Database Notes

In order to mass email the entire database from the admin panel you have to setup a daily crontab file to run bulkemail.cgi.   You must also set the FULL path to the /cgi-bin/matchmasters/configure.cgi file inside of bulkemail.cgi for the crontab to work.  When you "quemail" from the admin panel it "spools" the email to be sent out to everyone.  When your crontab file executes the message is then sent out to all of the members.  You can cancel a bulk mailing by hitting the "kill mail" button.  I would recommend setting this crontab to run maybe once per day during the late hours.

CUSTOMIZATION NOTES - DO NOT READ BELOW UNLESS YOU ARE TRYING TO CHANGE THE FIELD STRUCTURES

Obviously it would take nearly an entire book to go into every single possible modification you can make to matchmasterspro.  If you are wanting to simply alter cosmetics and fieldnames you just have to

go through the cgi files and make them correlate to the changes made in the matchpro.sql file.  A professional programmer can do this in about 2 hours or so.  However, if you have the time and don't have the money

then you will definitely learn a LOT about cgi when you get through this

Changing/Adding/Deleting Fields in the Registration Form

part one - editing the .sql file

First take a look @ the matchpro.sql file.   This is where you have to begin if you want to add/delete/change your field structures.  Note the structure of the dataprofiles table below:

  • CREATE TABLE dataprofiles (
  • profilenumber char(25) DEFAULT 'profilenumber' NOT NULL,
  • AdHeadline char(35) DEFAULT 'AdHeadline' NOT NULL,
  • EmailAddress char(50) DEFAULT 'EmailAddress' NOT NULL,
  • TelephoneAreaCode char(3) DEFAULT 'TelephoneAreaCode' NOT NULL,
  • City char(50) DEFAULT 'City' NOT NULL,
  • StateProvince char(50) DEFAULT 'StateProvince' NOT NULL,
  • Zip char(6) DEFAULT 'Zip' NOT NULL,
  • Country char(50) DEFAULT 'Country' NOT NULL,
  • RelationshipPreference char(50) DEFAULT 'RelationshipPreference' NOT NULL,
  • SexualPreference char(50) DEFAULT 'SexualPreference' NOT NULL,
  • Username char(12) DEFAULT 'Username' NOT NULL,
  • Password char(12) DEFAULT 'Password' NOT NULL,
  • VerifyPassword char(12) DEFAULT 'VerifyPassword' NOT NULL,
  • SmokingPreference char(50) DEFAULT 'SmokingPreference' NOT NULL,
  • DrinkingPreference char(50) DEFAULT 'DrinkingPreference' NOT NULL,
  • MaritialStatus char(50) DEFAULT 'MaritialStatus' NOT NULL,
  • HaveChildren char(50) DEFAULT 'HaveChildren' NOT NULL,
  • BodyBuild char(50) DEFAULT 'BodyBuild' NOT NULL,
  • Height char(50) DEFAULT 'Height' NOT NULL,
  • Religion char(50) DEFAULT 'Religion' NOT NULL,
  • Race char(50) DEFAULT 'Race' NOT NULL,
  • AstrologicalSign char(50) DEFAULT 'AstrologicalSign' NOT NULL,
  • Age char(3) DEFAULT 'Age' NOT NULL,
  • Occupation char(50) DEFAULT 'Occupation' NOT NULL,
  • MiscComments char(250) DEFAULT 'MiscComments' NOT NULL,
  • PRIMARY KEY(Username,EmailAddress)
  • );

Let's (for example) add a new field "Annual Salary" and delete the fields "AstrologicalSign" and "Race".  We start by altering the matchpro.sql file to reflect these changes below.  Notice that I have removed both (AstrologicalSign and Race) from the database and I also ADDED a new line AnnualSalary char(50) DEFAULT 'AnnualSalary' NOT NULL,  It is VERY IMPORTANT TO NOTE that you cannot use SPACES or SINGLE QUOTES ' inside of these tables.  Also it's a good idea to keep your formats organized so I always take two word fields and capitalize the first letter of each word (i.e. AnnualSalary).  Note also that I defined this as a character which could be up to 8 characters long.  Most people dont make over 8 figure salaries so this is probably reasonable.  However you can make them up to 250 characters long.

  • CREATE TABLE dataprofiles (
  • profilenumber char(25) DEFAULT 'profilenumber' NOT NULL,
  • AdHeadline char(35) DEFAULT 'AdHeadline' NOT NULL,
  • EmailAddress char(50) DEFAULT 'EmailAddress' NOT NULL,
  • TelephoneAreaCode char(3) DEFAULT 'TelephoneAreaCode' NOT NULL,
  • City char(50) DEFAULT 'City' NOT NULL,
  • StateProvince char(50) DEFAULT 'StateProvince' NOT NULL,
  • Zip char(6) DEFAULT 'Zip' NOT NULL,
  • Country char(50) DEFAULT 'Country' NOT NULL,
  • RelationshipPreference char(50) DEFAULT 'RelationshipPreference' NOT NULL,
  • SexualPreference char(50) DEFAULT 'SexualPreference' NOT NULL,
  • Username char(12) DEFAULT 'Username' NOT NULL,
  • Password char(12) DEFAULT 'Password' NOT NULL,
  • VerifyPassword char(12) DEFAULT 'VerifyPassword' NOT NULL,
  • SmokingPreference char(50) DEFAULT 'SmokingPreference' NOT NULL,
  • DrinkingPreference char(50) DEFAULT 'DrinkingPreference' NOT NULL,
  • MaritialStatus char(50) DEFAULT 'MaritialStatus' NOT NULL,
  • HaveChildren char(50) DEFAULT 'HaveChildren' NOT NULL,
  • BodyBuild char(50) DEFAULT 'BodyBuild' NOT NULL,
  • Height char(50) DEFAULT 'Height' NOT NULL,
  • Religion char(50) DEFAULT 'Religion' NOT NULL,
  • AnnualSalary char(8) DEFAULT 'AnnualSalary' NOT NULL,
  • Age char(3) DEFAULT 'Age' NOT NULL,
  • Occupation char(50) DEFAULT 'Occupation' NOT NULL,
  • MiscComments char(250) DEFAULT 'MiscComments' NOT NULL,
  • PRIMARY KEY(Username,EmailAddress)
  • );

part two - editing the registration.html form

The key thing to remember with the forms is it does NOT make ANY difference if you use drop down menus, text fields, text areas, or whatever.  The only IMPORTANT thing is you NAME the field the EXACT SAME NAME as you used in the .sql table.  For our example I first deleted the 2 fields (astrological sign and race).  Then I create a new field for AnnualSalary like this:

  • <tr>
  • <td BGCOLOR="#FF0080" VALIGN="CENTER" width="236"><strong><font color="#FFFFFF"
  • face="Arial"><small>City</small></font></strong></td>
  • <td VALIGN="CENTER" width="363"><font color="#FFFFFF" face="Arial"><small><input
  • type="text" NAME="AnnualSalary" SIZE="8" MAXLENGTH="8"></small></font></td>
  • </tr>

Note that I set the field size and maxlength to 8 - because it is already defined this way in the .sql file.    Since we already set the maxsize inside the matchpro.sql file to 8 (AnnualSalary char(8) DEFAULT 'AnnualSalary' NOT NULL,) we have to keep it to 8 in the registration.html form too.

I could have also done this with a drop down menu like this. 

  • <tr>
  • <td BGCOLOR="#FF0080" VALIGN="CENTER" width="236"><strong><font color="#FFFFFF"
  • face="Arial"><small>Annual Salary</small></font></strong></td>
  • <td VALIGN="CENTER" width="363"><font color="#FFFFFF" face="Arial"><small><select
  • NAME="AnnualSalary" size="1">
  • <option SELECTED VALUE="">Make A Selection</option>
  • <option VALUE="$25,000">$25,000</option>
  • <option VALUE="$50,000">$50,000</option>
  • <option VALUE="$100,000">$100,000</option>
  • <option VALUE="$250,000">$250,000</option>
  • <option VALUE="$1,000,000">$1,000,000</option>
  • </select> &nbsp;</small></font></td>
  • </tr>

part two - editing the modify.html form

The modify.html form is pretty much the same deal as editing the registration.html form.  In fact, it is the same form except it requires someone to first login (login.html) before it actually does anything.  So make the same changes to modify.html as you did with registration.html

part three - editing the search.html form

Again, this will be very similar to editing the registration.html and modify.html forms.  Only a couple of differences.   With any field that uses what is called an "OPTIONAL FORM SELECTION DEVICE" (eg:  drop down menus, radio buttons, etc) you have to set a DEFAULT value (or SELECTED VALUE) of NULL.  For our example I first deleted the two search fields for astrological sign and race and then I added a new search option (text field) for annual salary

  • <tr>
  • <td BGCOLOR="#FF0080" VALIGN="CENTER" width="236"><strong><font color="#FFFFFF"
  • face="Arial"><small>Annual Salary</small></font></strong></td>
  • <td VALIGN="CENTER" width="363"><font color="#FFFFFF" face="Arial"><small><select
  • NAME="AnnualSalary" size="1">
  • <option SELECTED VALUE="">No Preference</option>
  • <option VALUE="$25,000">$25,000</option>
  • <option VALUE="$50,000">$50,000</option>
  • <option VALUE="$100,000">$100,000</option>
  • <option VALUE="$250,000">$250,000</option>
  • <option VALUE="$1,000,000">$1,000,000</option>
  • </select> &nbsp;</small></font></td>
  • </tr>

These are the only forms that must be modified.  Now we move on to editing the cgi.

part four - editing add.cgi

Under the form_parse routine redefine your variables (note I deleted again astrologicalsign and race, then added annualsalary)

  • $AdHeadline = $FORM{'AdHeadline'};
  • $EmailAddress = $FORM{'EmailAddress'};
  • $TelephoneAreaCode = $FORM{'TelephoneAreaCode'};
  • $City = $FORM{'City'};
  • $StateProvince = $FORM{'StateProvince'};
  • $Zip = $FORM{'Zip'};
  • $Country = $FORM{'Country'};
  • $RelationshipPreference = $FORM{'RelationshipPreference'};
  • $SexualPreference = $FORM{'SexualPreference'};
  • $Username = $FORM{'Username'};
  • $Password = $FORM{'Password'};
  • $VerifyPassword = $FORM{'VerifyPassword'};
  • $SmokingPreference = $FORM{'SmokingPreference'};
  • $DrinkingPreference = $FORM{'DrinkingPreference'};
  • $MaritialStatus = $FORM{'MaritialStatus'};
  • $HaveChildren = $FORM{'HaveChildren'};
  • $BodyBuild = $FORM{'BodyBuild'};
  • $Height = $FORM{'Height'};
  • $Religion = $FORM{'Religion'};
  • $AnnualSalary = $FORM{'AnnualSalary'};
  • $Occupation = $FORM{'Occupation'};
  • $MiscComments = $FORM{'MiscComments'};
  • $MiscComments =~ s/ /\|/g;
  • $MiscComments =~ s/\s/\|/g;
  • $MiscComments =~ s/\|+/ /g;

Also take note that if you are adding new "TEXTAREA FIELDS" you need to add the extra parsing routines like are used for "MiscComments".  Otherwise it screws up your database with a bunch of carraige returns and garbage.  For example if I had added yet another new field and called it "YourLifeStory", when I edited add.cgi I would have also added

  • $YourLifeStory = $FORM{'YourLifeStory '};
  • $YourLifeStory  =~ s/ /\|/g;
  • $YourLifeStory  =~ s/\s/\|/g;
  • $YourLifeStory  =~ s/\|+/ /g;

This extra parsing is only required for TEXTAREAS.

Now we have to edit some of the other subroutines - hopefully this should be pretty obvious.  Same example as before.   Note again I removed astrological sign and race and added a routine to check that they entered a value for AnnualSalary

  • ############################################################
  • # CHECK FOR MISSING FIELDS
  • ############################################################
  • sub errcheck {
  • if ($AnnualSalary eq ""){
  • print "Error! Annual Salary is required!";
  • exit;
  • }
  • if ($AdHeadline eq ""){
  • print "Error! Ad headline is required!";
  • exit;
  • }
  • if ($EmailAddress eq ""){
  • print "Error! Email address is required!";
  • exit;
  • }
  • if ($TelephoneAreaCode eq ""){
  • print "Error! Area code is required!";
  • exit;
  • }
  • if ($City eq ""){
  • print "Error! City is required!";
  • exit;
  • }
  • if ($StateProvince eq ""){
  • print "Error! State/Province is required!";
  • exit;
  • }
  • if ($Zip eq ""){
  • print "Error! Zipcode is required!";
  • exit;
  • }
  • if ($Country eq ""){
  • print "Error! Country is required!";
  • exit;
  • }
  • if ($RelationshipPreference eq ""){
  • print "Error! Relationship profile is required!";
  • exit;
  • }
  • if ($SexualPreference eq ""){
  • print "Error! Sexual profile is required!";
  • exit;
  • }
  • if ($Username eq ""){
  • print "Error! Username is required!";
  • exit;
  • }
  • if ($Password eq ""){
  • print "Error! Password is required!";
  • exit;
  • }
  • if ($VerifyPassword eq ""){
  • print "Error! Please verify your password!";
  • exit;
  • }
  • if ($SmokingPreference eq ""){
  • print "Error! Smoking profile is required!";
  • exit;
  • }
  • if ($DrinkingPreference eq ""){
  • print "Error! Drinking profile is required!";
  • exit;
  • }
  • if ($MaritialStatus eq ""){
  • print "Error! Maritial Status is required!";
  • exit;
  • }
  • if ($HaveChildren eq ""){
  • print "Error! Have children is required!";
  • exit;
  • }
  • if ($BodyBuild eq ""){
  • print "Error! Body build is required!";
  • exit;
  • }
  • if ($Height eq ""){
  • print "Error! Height is required!";
  • exit;
  • }
  • if ($Religion eq ""){
  • print "Error! Religion is required!";
  • exit;
  • }
  • if ($Age eq ""){
  • print "Error! Age is required!";
  • exit;
  • }
  • if ($Occupation eq ""){
  • print "Error! Occupation is required!";
  • exit;
  • }
  • if ($MiscComments eq ""){
  • print "Error! Comments are required!";
  • exit;
  • }
  • if ($Password ne $VerifyPassword){
  • print "Error. Passwords do not match.";
  • exit;
  • }
  • }

Now we have to edit the savedata subroutine.  Same as before I delete the astrological sign and race, and add annual salary.  Note here that it is of VITAL IMPORTANCE that the ORDER OF THE FIELDS IN THIS STRING MATCH EXACTLY THE ORDER AS THEY APPEAR IN YOUR matchpro.sql file

  • ############################################################
  • # SAVE DATA
  • ############################################################
  • sub savedata {
  • $query = "INSERT INTO dataprofiles values('$profilenumber','$AdHeadline','$EmailAddress','$TelephoneAreaCode','$City','$StateProvince','$Zip','$Country','$RelationshipPreference','$SexualPreference','$Username','$Password','$VerifyPassword','$SmokingPreference','$DrinkingPreference','$MaritialStatus','$HaveChildren','$BodyBuild','$Height','$Religion','$AnnualSalary','$Age','$Occupation','$MiscComments')";
  • $dbh->do($query);
  • }

Ok, well that was the hard part.  The only other thing you will want to do is edit the subroutine "printconfirmation" so it prints the new variable and doesn't print the deleted ones.  You can also customize the look of this page by simply pasting extra html in between the

print <<ENDCONFIRMATIONPAGE;

PASTE HTML IN BETWEEN HERE

ENDCONFIRMATIONPAGE

part four - editing search.cgi and retrieve.cgi

The basic routines that you HAVE to edit are "sub getdata".  It should be pretty obvious what needs to be done.   Make sure that you match the row orders correctly.  If you want to get really creative you can also alter the printheader/printfooter, and dumpdata routines to change the look of the search results even more.

If you have become completely confused by this point then I would suggest paying a programmer that can do this entire project you are spending days on in about 2 hours.  Otherwise... read on.

Other notes

Don't forget - this is a mysql application so you have to do the usual (create a mysql database and upload the matchmasters.sql file) before any of this will work.  If you don't understand what that meant then you are going to have to get some professional help installing this system or you can contact your isp and email them the .sql file and they can probably set that part up for you.